Menggunakan pembolehubah CSS untuk mencipta tema dinamik dalam Puck

Puck ialah editor visual sumber terbuka untuk React, memperkasakan generasi pembina halaman dan produk tanpa kod generasi seterusnya. Beri kami bintang di GitHub! ⭐️

---

Apabila menyepadukan Puck ke dalam produk pembinaan halaman anda, keperluan biasa ialah membenarkan pengguna anda mengurus tema halaman secara berpusat tanpa perlu membuat pelarasan pada setiap komponen.

Contohnya: pengguna memerlukan cara untuk mengurus gaya fon secara global—walaupun untuk komponen yang telah ditambahkan pada halaman. Begini bagaimana ia boleh kelihatan dalam tindakan:

Memandangkan Puck hanyalah komponen React, terdapat banyak cara untuk menyelesaikan masalah ini (serta menguruskan keadaan lain yang lebih kompleks). Untuk artikel ini, saya akan menumpukan pada salah satu pendekatan yang paling mudah lagi berkuasa—sifat CSS. Mari selami!

Untuk tutorial ini, saya akan menganggap anda mempunyai pemahaman asas tentang Puck dan fungsinya. Jika anda baru menggunakan Puck, jangan risau—anda masih dialu-alukan untuk mengikuti! Walau bagaimanapun, saya syorkan anda menyemak panduan permulaan untuk membiasakan diri anda dengan asasnya.

Persediaan Projek menggunakan Vite

Saya akan mulakan dengan menyediakan projek menggunakan skrip perancah Vite. Anda dialu-alukan untuk mengikuti atau melangkau bahagian ini jika anda sudah mempunyai projek dengan Puck.

Jika anda menggunakan Next.js atau Remix anda juga boleh menggunakan salah satu resipi Puck rasmi untuk menyediakan projek anda.

Mencipta Projek

Untuk bermula, buka terminal anda dan jalankan arahan berikut untuk mencipta projek Vite baharu:

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

Memasang Puck

Seterusnya, pasang pakej Puck:

npm i @measured/puck --save

Memadamkan gaya bercanggah

Apabila anda memulakan projek baharu dengan Vite, ia akan disertakan dengan beberapa gaya lalai yang akan bertembung dengan Puck's. Untuk membetulkannya, padamkan src/index.css dan src/App.css, kemudian alih keluar importnya daripada src/main.jsx dan src/App.jsx:

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

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

Memaparkan editor Puck

Dengan struktur projek asas sedia, pergi ke fail src/App.jsx anda dan gantikan kandungannya dengan kod di bawah. Ini akan menyediakan Puck dengan konfigurasi asas untuk menyeret dan menjatuhkan komponen Tajuk dan Perenggan:

Perhatikan bahawa, demi kesederhanaan saya menggunakan penggayaan sebaris dalam contoh ini

// 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

Hebat! Memandangkan anda mempunyai asas untuk dibina, mari tambahkan tema untuk pengguna anda.

Menambah tema

Seperti yang saya nyatakan sebelum ini, sifat tersuai CSS ialah pilihan terbaik untuk menambahkan tema interaktif pada editor anda. Mengapa ini pendekatan yang hebat? Kerana ia ringan, tidak memerlukan kebergantungan luaran dan (sebahagian besarnya) dikendalikan secara asli oleh penyemak imbas.

Persediaan

Untuk menambah tema dinamik dengan sifat CSS, anda perlu menentukan pembolehubah tema anda sebagai sifat pada beberapa induk komponen yang memerlukannya. Ini boleh jadi komponen akar Puck atau mana-mana komponen induk lain dalam hierarki editor anda, tidak mengapa asalkan anda mentakrifkannya dan kemudian membacanya di tempat yang anda perlukan menggunakan fungsi var CSS.

Untuk tutorial ini, saya akan menumpukan pada menggunakan komponen akar Puck supaya pengguna dapat menetapkan saiz fon dan warna untuk tajuk dan perenggan di satu tempat di peringkat atas editor:

Langkah 1: Tentukan Pembolehubah

Mulakan dengan mentakrifkan objek untuk memusatkan semua nama pembolehubah CSS. Ini akan meningkatkan ketekalan dan menyelamatkan anda daripada masalah penyahpepijatan yang disebabkan oleh nama harta yang salah taip dalam CSS.

Petua Pro: Jika anda menggunakan TypeScript anda boleh menggunakan enum dan bukannya objek untuk mendapatkan keselamatan jenis tambahan

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

Langkah 2: Tambahkan Pembolehubah pada Komponen Induk

Seterusnya, kemas kini konfigurasi akar untuk memasukkan prop dan medan untuk pembolehubah tema. Ini akan membolehkan pengguna mengemas kini sifat tersuai secara langsung dari dalam medan akar editor.

Untuk melakukan ini, anda perlu menentukan medan untuk prop akar baharu dan nilai lalainya:

npm i @measured/puck --save

Selepas itu, dalam fungsi pemaparan akar, baca sifat tersuai daripada prop dan hantarkannya kepada elemen akar sebagai pembolehubah CSS.

// Objek konfigurasi Puck
konfigurasi const = {
  komponen: {
    //... komponen sedia ada
  },
  akar: {
    //... konfigurasi medan akar

    render: ({ children, fontColor, headingFontSize, paragraphFontSize}) => {
      kembali (
        <utama>



<p>Jika anda kini pergi ke editor, anda seharusnya melihat medan baharu pada peringkat akar untuk setiap satu prop. Belum ada maklum balas visual lagi, tetapi jika anda memeriksa gaya akar editor, anda akan melihat pembolehubah ditetapkan dengan setiap perubahan yang anda buat pada medan.</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>
  
  
  Langkah 3: Akses Pembolehubah Dikongsi dalam Komponen Kanak-kanak
</h3>

<p>Akhir sekali, akses pembolehubah tema dalam komponen yang anda perlukan dengan menggunakan fungsi var CSS dalam gaya anda.</p>

<p>Dalam contoh kami, anda akan menambahkannya dalam headingConfig dan paragraphConfig:<br>
</p>

<pre class="brush:php;toolbar:false">const headingConfig = {
  //... Konfigurasi medan tajuk

  render: ({ tajuk }) => {
    kembali (
      <div>
        <h1>



</h1>
<p>Jika anda kembali ke editor, seret dan lepaskan beberapa tajuk dan perenggan, kemudian ubah suai medan pada peringkat akar, anda akan perasan bahawa semua tajuk dan perenggan dikemas kini untuk mencerminkan perubahan tersebut:</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>? Dan itu sahaja! Pengguna anda kini boleh mentakrifkan tema yang digunakan dengan lancar merentas komponen berbeza dalam halaman mereka.</p>

<h3>
  
  
  Kebaikan & Keburukan menggunakan sifat CSS
</h3>

<p>✅ Kelebihan:</p>

<ul>
<li>Persediaan yang mudah dan intuitif</li>
<li>Fungsi lata dan timpa terbina dalam dalam hierarki halaman, membolehkan pengurusan mudah gaya dikongsi dan keupayaan untuk menyesuaikan komponen individu</li>
<li>Sifar kebergantungan luaran dan jejak ringan—sifat tersuai CSS disokong secara asli oleh penyemak imbas</li>
<li>Kurang plat dandang dan kerumitan penyelenggaraan berbanding pilihan lain</li>
</ul>

<p>❌ Keburukan:</p>

<ul>
<li>Hanya sesuai untuk penggayaan ringkas—tidak boleh mengendalikan data atau logik yang kompleks</li>
<li>Penyahpepijatan boleh menjadi sukar apabila menyusun berbilang peringkat penggantian sifat CSS</li>
</ul>

<h2>
  
  
  Membawanya lebih jauh
</h2>

<p>Bergantung pada kes penggunaan khusus anda, terdapat banyak cara untuk membawa tema editor anda lebih jauh:</p>
<ul>
<li>
<strong>Gunakan tema pratakrif</strong> - Dalam sesetengah aplikasi, anda mungkin perlu menyediakan pilihan tema lalai—seperti Gelap, Terang atau Minimum. Untuk ini, anda boleh menggunakan medan pilihan dengan berbilang objek tema. 
Objek ini boleh mengumpulkan semua sifat CSS sebagai satu unit, membolehkan pengguna bertukar-tukar dengan mudah antara tema yang berbeza untuk halaman mereka tanpa perlu mengisi satu medan.</li>
<li>
<strong>Sepadukan perpustakaan penggayaan</strong> – Untuk editor yang lebih besar, mungkin lebih baik menggunakan perpustakaan penggayaan untuk memanfaatkan gaya pra-bina, memperkemas takrifan anda dan mengurangkan boilerplate. Perpustakaan seperti Tailwind atau Emotion boleh disepadukan dengan mudah dengan Puck, memberikan anda fleksibiliti dan kecekapan sambil mengekalkan rupa yang digilap. Malah, Puck juga menawarkan pemalam Emosi yang memudahkan proses penyepaduan untuk anda!</li>
<li>
<strong>Tambah penggantian tema peringkat komponen</strong> – Kadangkala pengguna mungkin perlu menyesuaikan komponen individu dalam halaman mereka supaya mereka menonjol daripada tema yang lain. Memandangkan kami menggunakan sifat CSS, ini boleh dicapai dengan mudah dengan mengatasi pembolehubah tema peringkat induk pada peringkat komponen. Sebagai contoh, anda boleh menambah medan warna fon pilihan dalam komponen Tajuk anda yang, jika disediakan, akan mentakrifkan semula sifat CSS khusus untuk elemen h1 tersebut.</li>
</ul>

<h2>
  
  
  Kekal Berhubung dan Teruskan Membina?
</h2>

<p>Saya harap tutorial ini telah memperkasakan anda untuk memanfaatkan pembolehubah CSS untuk tema dinamik dalam pembina halaman berkuasa Puck. Komuniti pembangun sumber terbuka adalah nadi kepada evolusi Puck dan saya tidak sabar untuk melihat apl inovatif yang anda cipta!</p>

<p>Kami berdedikasi untuk meningkatkan lagi keupayaan Puck, dengan aliran berterusan ciri baharu, termasuk enjin drag-and-drop revolusioner untuk grid kompleks dan reka letak yang dilancarkan tidak lama lagi, dan set pemalam baharu di kaki langit.</p>

<p>Jadi, jika Puck telah memberi inspirasi kepada anda atau jika anda ingin mengikuti perkembangan terkini dengan ciri terkini, berikut ialah cara anda boleh terlibat:</p>

<ul>
<li>
<strong>⭐ Bintangi kami di GitHub</strong> untuk menyokong projek dan memberi inspirasi kepada orang lain untuk meneroka potensinya.</li>
<li>
<strong>? Sertai komuniti Discord kami</strong> untuk berkongsi projek anda, bertanya soalan dan bekerjasama.</li>
<li>
<strong>? Ikuti kami di X dan Bluesky</strong> untuk mendapatkan kemas kini terbaharu, intipan dan pengumuman ciri.</li>
<li>
<strong>? Selami dengan lebih mendalam dokumentasi rasmi</strong> untuk mendapatkan teknik dan cerapan lanjutan yang boleh membawa aliran kerja tanpa kod anda ke peringkat seterusnya.</li>
</ul>


          </div>