使用 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>