Komponen
Komposisi
Komponen UI yang disertakan dirancang untuk dirangkai, bukan digunakan satu per satu. Pilihan terbuka di dalam dialog, formulir divalidasi di dalam drawer, dan menu berada di baris tabel. Halaman ini menjelaskan mekanisme yang menyatukan bagian-bagian tersebut: struktur keluarga komponen majemuk, cara pemicu meneruskan properti tombol, fungsi Interactivity API di baliknya, serta model pelapisan yang menjaga permukaan bertumpuk tetap selaras.
Keluarga komponen majemuk
Komponen majemuk terdiri dari blok akar dan blok anak. Akar memiliki status; setiap anak menyatakan posisinya dalam keluarga melalui parent dan usesContext di block.json-nya:
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
Akar menyediakan area InnerBlocks dengan daftar allowedBlocks dan template awal, sehingga saat dialog disisipkan di editor, pemicu, backdrop, dan popup-nya dibuat sebagai kerangka. Keluarga komponen berperilaku sama saat dirangkai di editor, halaman berbasis file, atau tag:
<bs:bsui-select name="role" placeholder="Pick a role">
<bs:bsui-select-trigger />
<bs:bsui-select-popup>
<bs:bsui-select-option value="viewer" label="Viewer" />
<bs:bsui-select-option value="editor" label="Editor" />
</bs:bsui-select-popup>
</bs:bsui-select>
Popup dan panel adalah area InnerBlocks sungguhan, bukan slot dengan sintaks khusus. bsui/dialog-popup menerima blok bersarang seperti blok grup, sehingga formulir, pilihan, atau dialog lain dapat ditempatkan di dalamnya sebagai komposisi biasa.
Data datar atau anak yang dirangkai
Sebagian keluarga menerima konten sebagai data, bukan anak. Pilihan akan merender pemicu dan listbox-nya sendiri jika Anda memberinya array options JSON, cocok untuk opsi yang berasal dari PHP:
bs_render_block([
'name' => 'bsui/select',
'data' => [
'name' => 'role',
'placeholder' => 'Pick a role',
'options' => wp_json_encode([
['value' => 'viewer', 'label' => 'Viewer'],
['value' => 'editor', 'label' => 'Editor'],
]),
],
]);
Kedua bentuk menghasilkan kontrak markup dan perilaku runtime yang sama. Gunakan anak jika strukturnya ditulis langsung, options jika strukturnya dihitung.
Penerusan pemicu
Komponen overlay dibuka melalui tombol, dan tombol itu seharusnya tombol sistem. Agar setiap pemicu tidak perlu membuat ulang tombolnya sendiri, blok pemicu bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible, dan bsui/tooltip menyematkan bsui/button melalui bidang bidang blok:
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
idStructure memperluas bidang tombol ke pemicu dengan prefiks trigger_. Semua properti tombol tersedia: trigger_label, trigger_variant, trigger_size, trigger_icon, trigger_iconPosition, trigger_href, trigger_disabled.
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
Dalam templat pemicu, $a['trigger'] adalah tombol yang dirender sepenuhnya, sehingga stylesheet tombol dan penyempurnaan mendatang ikut terbawa. Saat runtime, helper bersama meneruskan pengaitan ARIA milik wrapper (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) ke tombol di dalamnya dan menjaganya tetap selaras melalui MutationObserver, sehingga teknologi bantu melihat satu kontrol yang terpadu.
Mekanisme Interactivity API
Setiap keluarga interaktif adalah store Interactivity WordPressAPI bernama sesuai blok akarnya: bsui/dialog, bsui/select, bsui/form, bsui/tabs, dan seterusnya. Ada tiga konsekuensinya.
Status diinisialisasi di sisi server. Templat akar mencetak status awalnya sebagai data-wp-context, langsung dari atribut blok:
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
Tampilan awal sudah benar HTML tanpa kedipan hidrasi sisi klien, popup dimulai dalam keadaan hidden, dan markup yang sama berfungsi di kanvas editor karena konteks tidak bergantung pada tahap status khusus frontend.
Perilaku dihubungkan dengan direktif, bukan dengan JavaScript Anda. Templat menghubungkan markup ke store secara deklaratif. Pemicu pilihan, setelah PHP-nya dihapus, hanya berisi direktif:
<button
data-wp-interactive="bsui/select"
data-wp-on--click="actions.toggle"
data-wp-on--keydown="actions.handleTriggerKeyDown"
data-wp-bind--aria-expanded="state.ariaExpanded"
data-wp-text="state.displayValue"
data-bsui-select-trigger
aria-haspopup="listbox"
>
data-wp-on mengarahkan peristiwa ke aksi, data-wp-bind menjaga atribut tetap selaras dengan status turunan, data-wp-text merender status sebagai teks, dan data-wp-on-document--click membuat akar menutup saat klik di luar. Merangkai komponen tidak pernah memerlukan penulisan penangan peristiwa; store disertakan bersama blok sebagai modul sebaris.
Toko Anda dapat terhubung melalui bagian-bagian ini. Kontrol formulir menerima ekspresi direktif sebagai atribut, dan sintaks namespaced Interactivity API mengarahkannya ke store mana pun. onChange mengarahkan penanganan perubahan ke salah satu aksi Anda, checked mengikat status kontrol ke status Anda, dan bindText menampilkan label sebagai span data-wp-text yang terikat ke jalur status mana pun:
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />
bindText tersedia pada item bsui/label, bsui/checkbox, bsui/switch, bsui/toggle, dan bsui/radio-group. Pada item checkbox, switch, dan radio, nilai ini mengalir ke primitif label bersama, sehingga teks yang digerakkan oleh status mempertahankan tipografi label sistem yang persis sama. Select dan input lainnya juga mengirimkan event change yang menggelembung dari elemen root-nya, dengan nilai baru di detail, untuk integrasi yang lebih sederhana.
Nilai terkontrol
Biarkan value atau checked tidak diatur untuk kontrol yang mengelola nilainya sendiri. Gunakan defaultValue, defaultChecked, atau defaultPressed milik Toggle untuk memilih nilai awal. Toggle mandiri menangani input pointer dan keyboard tanpa store konsumen.
Untuk mengontrol field dari store Anda sendiri, sediakan binding-nya beserta tindakan onChange yang memperbarui nilai terikat. value adalah jalur direktif, bukan nilai default literal. Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating, dan Time Picker mendukung value. Checkbox, Switch, dan Toggle menggunakan checked.
Awali jalur dengan namespace pemiliknya, misalnya my/settings::context.quantity atau my/settings::state.quantity. Kontrol majemuk memiliki namespace sendiri; jalur tanpa kualifikasi merujuk ke kontrol tersebut, bukan otomatis ke store induk Anda. Binding nilai kontrol majemuk mendukung jalur bertitik ke dalam context atau state, termasuk kunci array numerik, tetapi tidak mendukung ekspresi JavaScript atau pemanggilan fungsi.
Berikut binding Number Field lengkap dalam blok kustom dengan dukungan Interactivity API yang diaktifkan:
<div
data-wp-interactive="my/settings"
data-wp-context='<?php echo esc_attr(wp_json_encode(['quantity' => 2])); ?>'
>
<bs:bsui-number-field
nameAlt="quantity"
defaultValue="2"
value="my/settings::context.quantity"
onChange="my/settings::actions.setQuantity"
/>
<output data-wp-text="context.quantity"></output>
</div>
import { getContext, store } from '@wordpress/interactivity';
store('my/settings', {
actions: {
setQuantity(event) {
// Compound controls publish their normalized value in a custom change event.
if (event.detail?.value !== undefined) {
getContext().quantity = event.detail.value;
}
},
},
});
Atur nilai default yang sesuai untuk nilai awal yang dirender di server. Setelah dihidrasi, perubahan pada induk memperbarui setiap instance yang terikat, termasuk nilai nol, false, dan kosong. Input formulir tersembunyi milik Checkbox dan Switch juga mengikuti binding checked. Nilai Time Picker menggunakan HH:MM dalam format 24 jam atau string kosong.
Untuk handler Input, Textarea, dan Password Input native, baca event.target.value; kontrol nilai majemuk menerbitkan event.detail.value.
Batas Number Field bersifat opsional: jika min dan max tidak disertakan, nilainya tidak dibatasi, sedangkan nol yang ditetapkan secara eksplisit tetap menjadi batas yang valid.
Select, Date Input, Phone Input, dan OTP Input menerbitkan perubahan melalui onChange, tetapi tidak menyediakan binding value terkontrol ini. Gunakan properti default yang didokumentasikan untuk nilai awal.
Menyusun dari blok Anda sendiri
Komposisi tidak terbatas pada halaman. Tag blok dirender secara otomatis di dalam templat blok, sehingga blok proyek dapat menghasilkan komponen bsui secara langsung dan membungkusnya dalam strukturnya sendiri:
<div useBlockProps class="settings-panel">
<bs:bsui-switch label="Public profile" name="public" />
<bs:bsui-space size="4" />
<bs:bsui-button label="Save" variant="default" />
</div>
Hal yang sama juga berlaku dari PHP dengan bs_block(), termasuk penyarangan melalui kunci content, seperti yang dijelaskan pada bagian perenderan terprogram. Bagaimanapun caranya, stylesheet dan store komponen akan dimuat bersamanya, dan blok Anda tetap menjadi lapisan tipis yang menyusun bagian-bagian sistem.
Untuk menyusun komponen berdampingan, bsui/stack adalah baris atau kolom flex generik: direction, gap pada skala jarak, align, justify, dan toggle wrap. Secara default, anak mempertahankan ukuran alaminya; toggle grow merenggangkannya agar berbagi panjang tumpukan secara merata. Dengan cara ini, dua tombol pada footer membagi lebarnya, alih-alih berkumpul di salah satu ujung.
Grup field dan kartu
bsui/field-group merender fieldset. Varian default mengelompokkan field terkait tanpa menambahkan permukaan. Gunakan variant="card" untuk bingkai luar yang redup, lalu tempatkan field di dalam bsui/field-group-content agar kontennya memiliki permukaan inset. Letakkan judul dan deskripsi di luar blok konten tersebut:
<bs:bsui-field-group variant="card">
<bs:bsui-field-group-title text="Account settings" />
<bs:bsui-field-group-description text="Manage your account preferences." />
<bs:bsui-field-group-content>
<bs:bsui-field>
<bs:bsui-field-label text="Display name" />
<bs:bsui-input nameAlt="display_name" placeholder="Enter display name" />
</bs:bsui-field>
<bs:bsui-field>
<bs:bsui-field-label text="Email" />
<bs:bsui-input nameAlt="email" type="email" placeholder="Enter email" />
</bs:bsui-field>
</bs:bsui-field-group-content>
</bs:bsui-field-group>
disabled="true" pada grup menggunakan perilaku fieldset bawaan untuk menonaktifkan kontrol formulirnya. Gaya kartu tidak mengubah varian default.
Pemisah toolbar
Tempatkan bsui/toolbar-separator di antara item toolbar. Elemen ini mengikuti orientation toolbar induk: toolbar horizontal memiliki pemisah vertikal setinggi penuh, sedangkan toolbar vertikal memiliki pemisah horizontal selebar penuh. Pemisah membentang hingga tepi dalam bingkai toolbar tanpa mengubah tinggi kontrol. Toolbar horizontal akan bergulir saat isinya melebihi lebar yang tersedia.
Model lapisan
Permukaan yang bertumpuk biasanya menjadi titik lemah pustaka komponen. Komponen yang disertakan mengikuti seperangkat aturan sederhana, yang ditulis untuk orang-orang yang membangun UI sungguhan.
Modal dipindahkan ke body
Saat dialog, dialog peringatan, atau panel samping dibuka, popup dan backdrop-nya dipindahkan ke document.body, dengan komentar placeholder yang menandai tempat untuk mengembalikannya saat ditutup. Pemindahan ke portal membebaskan modal dari overflow, transform, atau konteks penumpukan milik ancestor mana pun. Membukanya juga mengunci gulir halaman: penguncian dihitung berdasarkan jumlah komponen overlay yang terbuka, dan lebar scrollbar diperhitungkan agar halaman tidak bergeser. Backdrop berada di z-index: 50, popup di 51, fokus berpindah ke dalam popup, Tab terperangkap di dalamnya, dan saat ditutup fokus kembali ke pemicunya.
Modal ditumpuk. Membuka dialog dari dalam dialog akan menambahkannya ke satu tumpukan bersama: hanya dialog terluar yang menampilkan backdrop, sementara dialog di belakang dialog teratas mengecil dan terlihat sedikit dari belakangnya. Tumpukan ini mengatur properti kustom --bs-ui-nested-dialogs pada setiap popup latar belakang, sehingga offset dan skala yang terlihat makin besar di setiap tingkat, dan tinggi induk menyesuaikan dengan tinggi anak agar setiap lapisan terlihat merata. Saat ditutup, semuanya dipulihkan dengan urutan terbalik, satu lapisan setiap kali ditutup.
Saat modal ditutup, fokus kembali ke pemicunya dan kembali ke elemen yang tepat. Helper bersama getAnchor mengarahkan pembungkus pemicu ke tombol sistem di dalamnya, sehingga kontrol yang terlihat mendapatkan fokus kembali, bukan pembungkus yang tidak terlihat.
Modal teratas tidak pernah ditransformasi
Efek mengintip itu hanya mentransformasi dialog latar belakang. Modal teratas sengaja dibiarkan tanpa transformasi, karena elemen yang ditransformasi menjadi blok penampung bagi descendant position: fixed, yang akan merusak setiap popup mengambang yang dibuka di dalamnya.
Inilah aturan yang membuat seluruh model pelapisan dapat dirangkai. Semua lapisan mengambang memosisikan diri menggunakan koordinat tetap, yang hanya merujuk ke viewport selama tidak ada leluhur yang ditransformasi:
- Menu dan combobox menghitung posisinya terhadap pemicu menggunakan strategi
fixeddari Floating UI, menempatkannya di bawah pemicu dan membalik atau menggeser posisinya saat ruang viewport tidak cukup. - Select melakukan hal yang sama saat belum ada pilihan. Jika sudah ada pilihan, popup-nya justru disejajarkan agar opsi yang dipilih tepat berada di atas pemicu, dengan posisi dibatasi oleh viewport, seperti perilaku select bawaan di macOS.
- Menu konteks terbuka pada koordinat
clientX/clientYpenunjuk.
Karena modal teratas tidak ditransformasi, semuanya tertambat dengan benar ke pemicunya di dalam dialog, dialog peringatan, atau laci, pada tingkat bersarang apa pun. Popup tidak mengetahui bahwa dirinya berada di dalam modal, dan tidak perlu mengetahuinya.
Escape menutup lapisan terdalam terlebih dahulu
Satu kali menekan Escape menutup tepat satu lapisan, dari bagian terdalam ke luar:
- Lapisan mengambang yang terbuka (listbox select, menu, popover, popup tanggal atau telepon) ditutup terlebih dahulu dan fokus kembali ke pemicunya. Select menghentikan perambatan peristiwa, dan handler modal juga tidak bertindak saat ada lapisan mengambang yang terbuka, sehingga dialog di bawahnya tidak menerima penekanan tersebut.
- Modal teratas ditutup berikutnya.
- Jika ada modal yang ditumpuk, setiap penekanan Escape berikutnya mengeluarkan satu modal lagi dari tumpukan.
Penutupan mengikuti kebijakan, bukan terjadi secara kebetulan. Dialog yang dirender dengan dismissable="false" mengabaikan Escape maupun klik backdrop. Sementara bsui/alert-dialog merespons Escape seperti modal lainnya, tetapi sengaja mengabaikan klik backdrop: pola ini mengharuskan pilihan dibuat secara sadar, bukan ditutup secara tidak sengaja. Klik backdrop pada dialog biasa akan menutupnya karena dismissable secara default bernilai true.
Formulir di dalam dialog
Pola yang menguji semua aturan di atas sekaligus: pemicu membuka modal, modal berisi formulir dengan validasi, dan formulir berisi select mengambang.
<bs:bsui-dialog>
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
<bs:bsui-dialog-backdrop />
<bs:bsui-dialog-popup>
<bs:bsui-dialog-header>
<bs:bsui-dialog-title content="Invite a teammate" />
<bs:bsui-dialog-description content="They receive an email with a join link." />
</bs:bsui-dialog-header>
<bs:bsui-dialog-content>
<bs:bsui-form block="team/invite" successMessage="Invitation sent.">
<bs:bsui-field name="email">
<bs:bsui-field-label text="Email" />
<bs:bsui-input name="email" type="email" placeholder="colleague@example.com" required="true" />
<bs:bsui-field-error />
</bs:bsui-field>
<bs:bsui-field name="role">
<bs:bsui-field-label text="Role" />
<bs:bsui-select name="role" defaultValue="editor" placeholder="Pick a role">
<bs:bsui-select-trigger />
<bs:bsui-select-popup>
<bs:bsui-select-option value="viewer" label="Viewer" />
<bs:bsui-select-option value="editor" label="Editor" />
<bs:bsui-select-option value="admin" label="Admin" />
</bs:bsui-select-popup>
</bs:bsui-select>
</bs:bsui-field>
<bs:bsui-space size="2" />
<bs:bsui-button label="Send invite" />
</bs:bsui-form>
</bs:bsui-dialog-content>
<bs:bsui-dialog-footer>
<bs:bsui-dialog-close label="Cancel" />
</bs:bsui-dialog-footer>
</bs:bsui-dialog-popup>
</bs:bsui-dialog>
Setiap tag dan atribut di atas berperan penting: pemicu meneruskan ke tombol sistem, judul dan deskripsi menerima content, field membawa nama yang diserialisasi oleh formulir, dan required="true" dikonversi menjadi boolean sungguhan oleh parser tag.
Fungsi setiap store saat runtime
bsui/dialog memasukkan {"open":false,"dismissable":true} ke dalam konteks di server. Klik pada pemicu menjalankan actions.open: popup dan backdrop dipindahkan melalui portal ke body, scroll dikunci dengan kompensasi scrollbar, popup dianimasikan masuk selama 150ms, fokus berpindah ke elemen pertama yang dapat difokuskan, dan Tab berputar di dalamnya. Area header, konten, dan footer mengatur jaraknya sendiri menggunakan token celah modal.
bsui/select menunggu di dalam formulir bersama listbox-nya hidden. Mengeklik pemicu akan mengubah context.open, memosisikan listbox menggunakan koordinat viewport tetap, dan karena defaultValue="editor" sudah dipilih, menyejajarkan popup agar Editor tepat berada di atas pemicu. Tombol panah, Home, End, dan pengetikan cepat memindahkan opsi aktif; Enter atau klik memilih opsi; Tab dan klik di luar menutupnya tanpa memilih. Teks yang terlihat pada pemicu diperbarui melalui data-wp-text="state.displayValue", dan <input name="role"> tersembunyi melacak nilainya melalui data-wp-bind--value="state.selectedValue", yang kemudian diserialisasi oleh formulir. Semua ini tertambat dengan benar di dalam dialog karena modal teratas tidak ditransformasi.
bsui/form menangani submit. bsui/button di akhir formulir merender elemen button biasa tanpa atribut type, sehingga secara default menjadi kontrol submit formulir berdasarkan HTML; tombol Batal berada di footer, di luar elemen form, sehingga tidak dapat mengirimkan apa pun. Saat dikirim, store menserialisasi FormData formulir dan mengirimkannya melalui API data dari blok yang disebutkan dalam block, yang dalam contoh ini membuat baris pada skema database milik blok team/invite. Kesalahan validasi dikembalikan untuk setiap kolom: setiap bsui/field membawa name-nya, ditandai tidak valid, mengubah warna cincin fokus menjadi warna destruktif, dan menampilkan pesan dalam peringatan bsui/field-error. Jika berhasil, isi formulir disembunyikan dan successMessage ditampilkan, keduanya melalui data-wp-bind--hidden.
Lapisan ditutup sesuai urutan. Saat listbox terbuka, Escape menutup listbox dan mengembalikan fokus ke pemicu select; Escape berikutnya menutup dialog dan mengembalikan fokus ke Undang rekan tim. Klik backdrop menutup dialog karena dismissable dibiarkan pada nilai default-nya. Saat ditutup, scroll dibuka kembali dan popup dipindahkan dari portal ke tempatnya semula di dokumen.
Markup yang sama saat ditempelkan ke halaman berbasis file akan disinkronkan sebagai blok native, dan komposisi yang sama saat dirangkai di editor akan ditampilkan secara interaktif di kanvas, karena semua perilaku di atas berada dalam direktif dan store yang dimuat di kedua konteks.
Hal yang menjaga agar titik-titik pertemuan ini berfungsi
Titik-titik pertemuan di atas bukan sekadar konvensi; semuanya merupakan invarian yang dipertahankan pustaka di mana pun ia merender: setiap label menggunakan tipografi yang sama, setiap popup modal berbagi satu permukaan dan meredupkan halaman di belakangnya, popup mengambang tetap tertambat pada pemicunya saat halaman digulir, dan Escape menutup tepat satu lapisan setiap kali, dari bagian terdalam ke luar. Jaminan ini berlaku di frontend dan kanvas editor, baik menggunakan token default maupun token tema Anda, sehingga komposisi yang berperilaku dengan benar di satu konteks akan berperilaku sama di konteks lainnya.
Contoh langsung
Komposisi di halaman ini adalah tata bahasanya; /ui/examples adalah buku frasanya. Halaman itu mengumpulkan komposisi yang dirender langsung dalam tiga tingkatan: pasangan yang membuktikan satu titik pertemuan antara dua atau tiga komponen, pola produk yang mudah dikenali dan dibuat dari beberapa komponen, serta aplikasi mini lengkap yang dirangkai seperti komponen dalam produk nyata. Setiap halaman komponen di /ui juga menyertakan contoh penerapan, mulai dari field berlabel hingga kalender di balik popover.
Model direktif dan store yang menjadi dasar komponen UI, serta cara menggunakannya di blok Anda sendiri.