使用 CSS 变量在 Puck 中创建动态主题

Puck 是 React 的开源可视化编辑器，为下一代页面构建器和无代码产品提供支持。在 GitHub 上给我们一颗星！ ⭐️

---

将 Puck 集成到您的页面构建产品中时，一个常见的需求是让您的用户能够集中管理页面主题，而无需对每个组件进行调整。

例如：用户需要一种全局管理字体样式的方法 - 即使对于已添加到页面的组件也是如此。以下是实际效果：

由于 Puck 只是一个 React 组件，因此有很多方法可以解决这个问题（以及管理其他更复杂的状态）。在本文中，我将重点讨论最简单但最强大的方法之一——CSS 属性。让我们开始吧！

对于本教程，我假设您对 Puck 及其功能有基本的了解。如果您是 Puck 的新手，请不要担心 — 我们仍然欢迎您继续学习！不过，我建议您查看入门指南以熟悉基础知识。

使用 Vite 设置项目

我将首先使用 Vite 的脚手架脚本建立一个项目。如果您已经有 Puck 的项目，欢迎您继续阅读或跳过本节。

如果您使用 Next.js 或 Remix，您还可以使用官方 Puck 配方之一来设置您的项目。

创建项目

首先，打开终端并运行以下命令来创建一个新的 Vite 项目：

npm create vite@latest puck-global-themes -- --template react
cd puck-global-themes
npm install

安装冰球

接下来，安装 Puck 软件包：

npm i @measured/puck --save

删除冲突的样式

当您使用 Vite 开始一个新项目时，它会附带一些默认样式，这些样式会与 Puck 的冲突。要解决此问题，请删除 src/index.css 和 src/App.css，然后从 src/main.jsx 和 src/App.jsx 中删除它们的导入：

// main.jsx
import "./index.css"; // Remove this line

// App.jsx
import "./App.css"; // Remove this line

渲染 Puck 编辑器

准备好基本的项目结构后，转到 src/App.jsx 文件并将其内容替换为以下代码。这将为 Puck 设置一个用于拖放标题和段落组件的基本配置：

请注意，为了简单起见，我在本例中使用内联样式

// App.jsx
import { Puck } from "@measured/puck";
import "@measured/puck/puck.css";

// The configs for each of your draggable components
// Ideally you would pull each of these to their own files

const headingConfig = {
  defaultProps: {
    title: "Title",
  },
  fields: {
    title: {
      type: "text",
    },
  },
  render: ({ title }) => {
    return (
      <div>
        <h1 id="title">{title}</h1>
      </div>
    );
  },
};

const paragraphConfig = {
  defaultProps: {
    content: "This is a paragraph...",
  },
  fields: {
    content: {
      type: "textarea",
    },
  },
  render: ({ content }) => {
    return (
      <div>
        <p>{content}</p>
      </div>
    );
  },
};

// The Puck configuration object
const config = {
  components: {
    Heading: headingConfig,
    Paragraph: paragraphConfig,
  },
  root: {
    render: ({ children }) => {
      return (
        <main>



<p>Finally, run the application in development mode, navigate to http://localhost:5173, and check that everything is working as expected:<br>
</p>

<pre class="brush:php;toolbar:false">npm run dev

太棒了！现在您已经有了基础，让我们为您的用户添加主题。

添加主题

正如我之前提到的，CSS 自定义属性是向编辑器添加交互式主题的绝佳选择。为什么这是一个很好的方法？因为它是轻量级的，不需要外部依赖项，并且（大部分）由浏览器本地处理。

设置

要使用 CSS 属性添加动态主题，您需要将主题变量定义为需要它们的组件的某些父级的属性。这可能是 Puck 的根组件或编辑器层次结构中的任何其他父组件，只要您定义它们，然后使用 var CSS 函数在需要的地方读取它们，这并不重要。

在本教程中，我将重点使用 Puck 的根组件，以便用户能够在编辑器顶层的一个位置设置标题和段落的字体大小和颜色：

第 1 步：定义变量

首先定义一个对象来集中所有 CSS 变量名称。这将提高一致性，并使您免于因 CSS 中属性名称输入错误而导致的调试问题。

专业提示：如果您使用 TypeScript，您可以使用枚举而不是对象来获得额外的类型安全性

npm create vite@latest puck-global-themes -- --template react
cd puck-global-themes
npm install

第 2 步：将变量添加到父组件

接下来，更新根配置以包含主题变量的道具和字段。这将允许用户直接从编辑器的根字段内更新自定义属性。

为此，您需要定义新根 props 的字段及其默认值：

npm i @measured/puck --save

之后，在根的渲染函数中，从 props 中读取自定义属性并将它们作为 CSS 变量传递给根元素。

// Puck 配置对象
常量配置= {
  成分： {
    //...现有组件
  },
  根： {
    //...根字段配置

    渲染：({children,fontColor,headingFontSize,paragraphFontSize})=> {
      返回 （
        



<p>如果您现在转到编辑器，您应该会在根级别看到每个道具的新字段。目前还没有视觉反馈，但如果您检查编辑器根目录的样式，您将看到对字段所做的每次更改都设置了变量。</p>

<p><img src="/static/imghwm/default1.png" data-src="https://img.php.cn/upload/article/000/000/000/173634396450671.jpg?x-oss-process=image/resize,p_40" class="lazy" alt="Using CSS variables to create dynamic themes in Puck"></p><h3>
  
  
  第三步：访问子组件中的共享变量
</h3>

<p>最后，通过在样式中使用 var CSS 函数来访问所需组件中的主题变量。</p>

<p>在我们的示例中，您将它们添加到 headerConfig 和 paragraphConfig 中：<br>
</p>

<pre class="brush:php;toolbar:false">const headerConfig = {
  //... 标题字段配置

  渲染：({ 标题 }) => {
    返回 （
      <div>
        <h1>



</h1>
<p>如果您返回编辑器，拖放一些标题和段落，然后修改根级别的字段，您会注意到所有标题和段落都会更新以反映这些更改：</p>

<p><img src="/static/imghwm/default1.png" data-src="https://img.php.cn/upload/article/000/000/000/173634396650466.jpg?x-oss-process=image/resize,p_40" class="lazy" alt="Using CSS variables to create dynamic themes in Puck"></p>

<p>？就是这样！您的用户现在可以定义无缝应用于其页面中不同组件的主题。</p>

<h3>
  
  
  使用 CSS 属性的优点和缺点
</h3>

<p>✅ 优点：</p>

<ul>
<li>简单直观的设置</li>
<li>页面层次结构中的内置级联和覆盖功能，可以轻松管理共享样式并能够自定义各个组件</li>
<li>零外部依赖和轻量化——浏览器原生支持 CSS 自定义属性</li>
<li>比其他选项更少的样板和维护复杂性</li>
</ul>

<p>❌缺点：</p>

<ul>
<li>仅适合简单的样式——无法处理复杂的数据或逻辑</li>
<li>嵌套多层 CSS 属性覆盖时，调试可能会很困难</li>
</ul>

<h2>
  
  
  更进一步
</h2>

<p>根据您的具体用例，有很多方法可以进一步完善您的编辑器主题：</p>
<ul>
<li>
<strong>使用预定义主题</strong> - 在某些应用程序中，您可能需要提供默认主题选项，例如深色、浅色或最小主题。为此，您可以使用具有多个主题对象的选择字段。 
这些对象可以将所有 CSS 属性分组为一个单元，允许用户轻松地在页面的不同主题之间切换，而无需填写单个字段。</li>
<li>
<strong>集成样式库</strong> – 对于较大的编辑器，最好使用样式库来利用预构建的样式、简化定义并减少样板文件。 Tailwind 或 Emotion 等库可以轻松与 Puck 集成，为您提供灵活性和效率，同时保持精美的外观。事实上，Puck 甚至提供了一个 Emotion 插件，可以为您简化集成过程！</li>
<li>
<strong>添加组件级主题覆盖</strong> – 有时用户可能需要自定义页面中的各个组件，以便它们从主题的其余部分中脱颖而出。由于我们使用的是 CSS 属性，因此可以通过在组件级别覆盖父级主题变量来轻松实现这一点。例如，您可以在 Heading 组件中添加一个可选的字体颜色字段，如果提供的话，将专门为该 h1 元素重新定义 CSS 属性。</li>
</ul>

<h2>
  
  
  保持联系并继续建设？
</h2>

<p>我希望本教程能够帮助您在 Puck 支持的页面构建器中利用 CSS 变量实现动态主题。开源开发者社区是 Puck 发展的核心，我迫不及待地想看到您创建的创新应用程序！</p>

<p>我们致力于进一步推动 Puck 的功能，不断推出新功能，包括即将推出的用于复杂网格和布局的革命性拖放引擎，以及即将推出的一套新插件。</p>

<p>所以，如果 Puck 给了您启发或者您想了解最新功能，您可以通过以下方式参与其中：</p>

<ul>
<li>
<strong>⭐ 在 GitHub 上给我们加星标</strong> 以支持该项目并激励其他人探索其潜力。</li>
<li>
<strong>？加入我们的 Discord 社区</strong> 分享您的项目、提出问题并进行协作。</li>
<li>
<strong>？在 X 和 Bluesky</strong> 上关注我们，了解最新更新、先睹为快和功能公告。</li>
<li>
<strong>？深入研究官方文档</strong>以获取先进的技术和见解，可以将您的无代码工作流程提升到一个新的水平。</li>
</ul>


          </div>