Simpan token reka bentuk bersama dalam CSS halaman, dedahkan pemboleh ubah khusus komponen sebagai API penggayaan, dan hubungkannya dengan pemetaan ringkas yang dimiliki halaman. Tutorial ini membina demo Mac setempat yang memisahkan tanggungjawab tersebut.

Apakah yang dimiliki oleh halaman dan apakah yang dimiliki oleh komponen?

Bagi seseorang yang mengedit halaman web yang ditulis sendiri pada Mac, tugas khususnya ialah menyesuaikan tema komponen boleh guna semula tanpa menjadikan pelaksanaannya bergantung pada nama token halaman. Contoh di bawah menggunakan komponen orbit-tile rekaan yang mengandungi bentuk abstrak dan label ringkas.

Token reka bentuk dan pemboleh ubah komponen awam kedua-duanya boleh berupa sifat tersuai CSS. Perbezaannya terletak pada kontrak yang anda dokumentasikan. Sifat tersuai biasa yang tidak didaftarkan mengambil bahagian dalam lata dan diwarisi; mengisytiharkannya pada :root menjadikannya tersedia melalui pewarisan merentas dokumen. Tiada kata kunci CSS khas yang menjadikan sesuatu sifat sebagai token reka bentuk. Menggunakan sifat tersuai CSS (pemboleh ubah)

Gunakan jadual pemilikan ini untuk menentukan tempat sesuatu pengisytiharan patut diletakkan. Nama-nama ini sekadar contoh dan khusus untuk contoh ini.

Lapisan Contoh Tanggungjawab
Token reka bentuk halaman --scene-accent, --scene-rounding Pilihan visual bersama untuk halaman yang ditulis sendiri
Peraturan penyepaduan halaman Peraturan yang menyasarkan orbit-tile Menterjemahkan pilihan halaman kepada API komponen
Pemboleh ubah komponen awam --orbit-tile-fill, --orbit-tile-radius Kawalan terdokumen yang tersedia kepada pengguna
Pelaksanaan komponen .shape, peraturan susun atur, nilai lalai literal Memaparkan komponen tanpa memerlukan token halaman

Ujian yang berguna ialah keboleh alihan: bolehkah halaman lain membekalkan nama token yang berbeza sambil menggunakan komponen yang sama tanpa sebarang perubahan? Dengan pemetaan milik halaman, boleh. Halaman baharu itu akan memetakan tokennya sendiri kepada pemboleh ubah komponen awam yang sama.

Bagaimanakah kontrak penggayaan merentasi Shadow DOM?

Shadow DOM memisahkan padanan pemilih daripada pewarisan. Pemilih halaman biasanya tidak dapat memilih bentuk dalaman merentasi sempadan shadow. Nilai sifat yang diwarisi masih boleh sampai kepadanya melalui hos. Spesifikasi CSS Shadow menerangkan pepohon elemen terhampar yang digunakan untuk hubungan ini; pepohon pemilih yang berasingan tidak menghapuskan pewarisan. Modul CSS Shadow Tahap 1

Biarkan pemboleh ubah awam tidak ditetapkan dalam komponen dan bekalkan nilai lalai di tempat pemboleh ubah itu digunakan. Contohnya, background-color: var(--orbit-tile-fill, #667085) menerima nilai diwarisi daripada pengguna sambil menyediakan nilai lalai kendiri. Jika --orbit-tile-fill: #667085 diisytiharkan pada :host, hos akan mempunyai nilainya sendiri dan menyekat nilai yang diwarisi daripada leluhur. Pengguna masih boleh menyasarkan hos secara langsung. Menggayakan Komponen Web

Untuk contoh ini, dokumentasikan dua kawalan awam sahaja:

Pemboleh ubah awam Nilai yang diterima untuk contoh ini Nilai lalai jika tiada Kesan
--orbit-tile-fill Warna CSS yang sah #667085 Warna latar belakang bentuk
--orbit-tile-radius Satu panjang atau peratusan bukan negatif 1rem Jejari sudut bentuk

Nilai yang diterima ini ialah persetujuan API. Pelaksanaan asas tidak mendaftarkan atau mengesahkannya secara automatik. Nama kelas dalaman ialah butiran pelaksanaan, jadi pengarang halaman patut menyesuaikan pemboleh ubah awam dan bukannya bergantung pada .shape.

Bina contoh setempat yang lengkap pada Mac anda

Gunakan editor teks biasa dan pelayar yang menyokong sifat tersuai CSS, Shadow DOM dan elemen tersuai autonomi. Contoh ini menggunakan elemen autonomi yang memanjangkan HTMLElement; MDN membezakan pendekatan ini daripada elemen terbina dalam tersuai, yang tidak dirancang untuk disokong oleh Safari. Menggunakan elemen tersuai

Dalam TextEdit, pilih File > New, kemudian Format > Make Plain Text. Tampal dokumen lengkap di bawah dan simpan sebagai token-demo.html. Jika diminta, pilih Use .html. Apabila membukanya semula untuk diedit, pilih Ignore rich text commands dalam dialog buka, atau dayakan Display HTML files as HTML code instead of formatted text dalam tetapan. Bekerja dengan dokumen HTML dalam TextEdit pada Mac

Lembaran gaya pertama dokumen memiliki token, peraturan penyepaduan dan susun atur halaman. Komponen mencipta lembaran gaya berasingan di dalam akar shadow-nya. HTML mentakrifkan elemen style sebagai cara untuk membenamkan CSS; meletakkan semua sumber dalam satu fail menjadikan persediaan sumber contoh ini jelas. Piawaian HTML: Elemen style

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Orbit tile token demo</title>
  <style>
    /* Page-owned shared tokens */
    :root {
      --scene-accent: #4058b8;
      --scene-rounding: 12px;
    }

    /* Page-owned integration mapping */
    orbit-tile {
      --orbit-tile-fill: var(--scene-accent);
      --orbit-tile-radius: var(--scene-rounding);
    }

    /* A local page theme */
    .alternate {
      --scene-accent: #276f64;
      --scene-rounding: 24px;
    }

    /* An intentional override for one component instance */
    orbit-tile.special {
      --orbit-tile-fill: #a65b20;
      --orbit-tile-radius: 50%;
    }

    body {
      max-width: 36rem;
      margin: 3rem auto;
      padding: 0 1rem;
      font: 1rem/1.5 system-ui, sans-serif;
    }
    main { display: grid; gap: 1rem; }
  </style>
</head>
<body>
  <main>
    <orbit-tile>Sample A</orbit-tile>
    <section class="alternate" aria-label="Alternate samples">
      <orbit-tile>Sample B</orbit-tile>
    </section>
    <orbit-tile class="special">Sample C</orbit-tile>
  </main>

  <script>
    class OrbitTile extends HTMLElement {
      constructor() {
        super();
        const root = this.attachShadow({ mode: 'open' });
        const style = document.createElement('style');
        style.textContent = `
          :host { display: block; }
          .tile {
            display: flex;
            align-items: center;
            gap: 1rem;
            padding: 1rem;
            background: #f2f4f6;
            color: #202630;
          }
          .shape {
            display: block;
            width: 4rem;
            height: 4rem;
            flex: 0 0 4rem;
            background-color: var(--orbit-tile-fill, #667085);
            border-radius: var(--orbit-tile-radius, 1rem);
          }
        `;
        const tile = document.createElement('div');
        tile.className = 'tile';
        const shape = document.createElement('span');
        shape.className = 'shape';
        shape.setAttribute('aria-hidden', 'true');
        tile.append(shape, document.createElement('slot'));
        root.append(style, tile);
      }
    }
    customElements.define('orbit-tile', OrbitTile);
  </script>
</body>
</html>

Buka fail yang disimpan dalam Safari, Chrome atau Firefox. Contoh ini tidak mempunyai skrip, fon, imej atau lembaran gaya luaran. JavaScript telah lulus semakan sintaks; hasil visual berikut ialah hasil yang dijangka berdasarkan pengisytiharan, bukannya laporan pelaksanaan dalam pelayar.

Instans Bentuk yang dijangka Laluan nilai
Sample A Biru, dengan bucu 12px Token akar → pemetaan hos → komponen
Sample B Hijau, dengan bucu 24px Token seksyen → pemetaan hos → komponen
Sample C Bulatan jingga Penggantian instans → komponen

Perhatikan bahawa JavaScript komponen tidak mengandungi rujukan --scene-*. Lembaran gayanya hanya menggunakan nama awam --orbit-tile-*. Halaman boleh menyusun semula kosa kata temanya tanpa mengubah komponen.

Di manakah pemetaan token kepada komponen patut dilakukan?

Petakan nilai di tempat tema yang dimaksudkan tersedia. Dalam demo ini, peraturan orbit-tile berjalan pada setiap hos. Ini membolehkan hos kedua menyelesaikan --scene-accent selepas mewarisi nilai hijau daripada seksyen.

Elakkan memindahkan pemetaan itu ke :root tanpa mempertimbangkan masa penyelesaian. Jika --orbit-tile-fill: var(--scene-accent) dikira di situ, keturunan akan mewarisi nilainya yang telah diselesaikan. Mengubah --scene-accent sahaja pada seksyen kemudian tidak membina semula alias yang diwarisi itu. Rujukan var() dalam sifat tersuai diselesaikan sebelum nilai terkiranya diwarisi. Sifat Tersuai CSS untuk Modul Pemboleh Ubah Berantaian Tahap 1

Keputusan praktikal bergantung pada skop: gunakan pemetaan pada hos apabila setiap instans patut mengikut token halaman di sekelilingnya. Jika seluruh rantau memang berkongsi satu nilai komponen awam, mengisytiharkan pemboleh ubah awam itu pada rantau tersebut boleh jadi sesuai—tetapi buang pemetaan hos bagi pemboleh ubah itu supaya nilai diwarisi tidak digantikannya.

Untuk penggunaan dalaman yang berulang, alias pelaksanaan boleh mengumpulkan pengisytiharan sandaran. Nama seperti --_orbit-tile-fill boleh menandakan konvensyen dalaman, tetapi garis bawah tidak mewujudkan privasi yang dikuatkuasakan. Penggunaan secara langsung, seperti yang ditunjukkan dalam contoh lengkap, lebih mudah diikuti apabila setiap nilai digunakan sekali. Menggayakan Komponen Web

Bagaimanakah anda boleh mendiagnosis penggantian yang tidak berfungsi?

Gunakan tiga instans itu sebagai ujian kontrak ringkas. Ubah satu pengisytiharan pada satu masa, simpan dan muat semula. Pemeriksaan ini membantu membezakan sumber yang tiada, masalah pewarisan dan nilai yang tidak sah.

  1. Tukar aksen akar kepada #7251a1. Jangkakan hanya Sample A menggunakannya; seksyen dan instans mempunyai pilihan masing-masing.
  2. Tukar aksen seksyen kepada #32758a. Jangkakan Sample B berubah tanpa mengedit kod komponen.
  3. Buang seluruh pemetaan penyepaduan. Jangkakan Sample A dan Sample B menggunakan isian kelabu dan jejari 1rem daripada komponen; Sample C mengekalkan penggantian awam yang dinyatakan secara jelas.
  4. Pulihkan pemetaan sebelum meneruskan eksperimen lain.

Jika semua bentuk hilang, mula-mula pastikan dokumen disimpan sebagai HTML dan skripnya masih utuh. Jika label kelihatan tetapi bentuk tidak digayakan, periksa lembaran gaya komponen. Lembaran gaya dokumen sahaja tidak menggayakan keturunan shadow menggunakan pemilih biasa; pelaksanaan perlu melampirkan gaya dalaman pada pepohon shadow. MDN mendokumentasikan gaya terbenam dan lembaran gaya terbina untuk tujuan itu. Menggunakan shadow DOM

Jika hanya penggantian leluhur yang gagal, cari pengisytiharan pemboleh ubah awam secara langsung pada hos. Dalam contoh ini, pemetaan penyepaduan ialah pengisytiharan sedemikian. Sama ada ubah token halaman yang membekalkannya, gantikan pemboleh ubah awam pada instans, atau buang pemetaan apabila tema awam pada peringkat leluhur ialah kontrak yang dimaksudkan.

Jika bentuk menjadi lut sinar selepas menetapkan --orbit-tile-fill: 12px, nilai sandaran tidak akan membaikinya. Pemboleh ubah itu wujud, tetapi nilai gantinya tidak sah untuk background-color. Pengisytiharan itu menjadi tidak sah pada masa nilai terhitung; ia tidak kembali kepada pengisytiharan latar belakang yang terdahulu. Buang penetapan itu atau berikan warna yang sah. Sifat Tersuai CSS untuk Modul Pemboleh Ubah Berantaian Tahap 1

Patutkah pemboleh ubah awam menggunakan @property?

Pendaftaran ialah pilihan untuk kontrak ini. @property menambah kekangan sintaks, nilai awal dan tingkah laku pewarisan yang jelas. MDN menandainya sebagai Baseline 2024, tersedia pada pelayar semasa sejak Julai 2024, sambil memberi amaran bahawa pelayar lama mungkin tidak menyokongnya. Contoh lengkap ini tidak menjadikan pendaftaran sebagai prasyarat. Peraturan CSS @property

Jika anda memperkenalkan pendaftaran, selaraskannya pada peringkat dokumen. Dokumentasi pelaksanaan Chrome melaporkan bahawa pendaftaran di dalam akar shadow diabaikan; laporannya bertarikh Ogos 2024, jadi anggapnya sebagai sempadan kebolehoperasian yang didokumenkan dan bukannya bukti ujian pelayar baharu. Laluan yang disokong dan diterangkan di situ ialah pendaftaran pada skop dokumen, dengan komponen menggunakan sifat tersebut merentasi sempadan. Nama CSS yang ditakrifkan pengarang dan shadow DOM: Dalam spesifikasi dan dalam amalan

Pendaftaran juga mengubah tingkah laku. Menetapkan inherits: false akan memutuskan pewarisan hos kepada bentuk dalam contoh ini. Warna awal yang didaftarkan bermaksud sifat yang tidak ditetapkan akan menggunakan warna itu, jadi sandaran var() pada tempat penggunaan tidak lagi menjadi nilai lalai apabila nilai tiada. Kekalkan inherits: true untuk reka bentuk ini dan tentukan dengan sengaja mekanisme yang mengawal nilai lalai. Peraturan CSS @property

Kontrak yang siap sepatutnya membolehkan pengarang halaman menerangkan laluan setiap nilai: pilihan halaman bersama, pemetaan kepada kawalan komponen yang didokumenkan dan nilai sandaran milik komponen. Letakkan pemetaan dekat dengan skop tema yang dimaksudkan, biarkan input awam yang diwarisi tidak ditetapkan secara dalaman, dan kekalkan contoh tiga instans setiap kali anda menyemak semula API.

Sumber