Lewati ke konten

Komponen

Blockstudio menyertakan 59 komponen UI di setiap build. Komponen ini didaftarkan secara otomatis, ditata dengan token desain, dan ditulis menggunakan sintaks tag yang sama seperti blok lainnya.

Blockstudio 7.3 menyertakan kumpulan blok UI tanpa antarmuka yang didukung oleh Interactivity WordPress API. Blok-blok ini terdaftar dalam namespace bsui/* dan dapat dirangkai dalam templat, halaman berbasis file, pola, dan konten pos.

Catatan

Komponen UI masih dalam versi beta selagi kami mengumpulkan masukan tentang kumpulan komponen, penamaan, perilaku, dan pola penggunaan proyek. Komponen ini siap dicoba di 7.3, tetapi antarmuka API masih dapat disempurnakan sebelum dinyatakan stabil.

Aktifkan Komponen UI

Komponen UI yang disertakan harus diaktifkan secara eksplisit. Aktifkan di blockstudio.json tema Anda:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

Atau aktifkan menggunakan filter:

PHP
add_filter('blockstudio/settings/ui/enabled', '__return_true');

Setelah diaktifkan, Blockstudio mendaftarkan pustaka komponen bawaan dari includes/ui/blocks.

Inventaris Publik dan Contoh

Blok implementasi bawaan tetap berupa pendaftaran bsui/* biasa, tetapi pengguna sebaiknya memakai inventaris keluarga publik saat membuat galeri komponen:

PHP
use Blockstudio\Ui;

$families = Ui::inventory();
$examples = Ui::examples();

Ui::inventory() mengelompokkan setiap komponen majemuk di bawah akar publiknya dan mencantumkan pendaftaran implementasi yang diperlukan oleh keluarga tersebut. Ui::examples() menambahkan deklarasi ternormalisasi deterministik dengan data default dan contoh. Hasilnya mempertahankan hubungan akar/anak yang diwajibkan, sehingga dapat langsung diteruskan ke Blockstudio\Render::document().

Inventaris Canvas publik menampilkan contoh-contoh ini berdasarkan jenis ui-nya dan menghilangkan pendaftaran implementasi bawaan dari jenis blocks biasa. Hasilnya adalah satu contoh lengkap untuk setiap keluarga komponen publik, bukan galeri berisi fragmen internal akar, pemicu, popup, dan lapisan.

Saat merangkai dokumen yang sudah dirender, Ui::global_assets($block_names, $html) hanya mengembalikan gaya dan skrip global bawaan yang persis sama jika output terpilih benar-benar menggunakan komponen UI.

Rendering

Gunakan sintaks tag blok biasa:

HTML
<block name="bsui/button" label="Save" variant="default"></block>

Sintaks <bs:> yang lebih singkat juga dapat digunakan:

HTML
<bs:bsui-button label="Save" variant="default" />

Dalam templat Blockstudio, tag blok dirender secara otomatis. Pada halaman dan pola berbasis file, tag tersebut disinkronkan sebagai blok native WordPress. Untuk merender komponen UI langsung dari konten pos atau area widget, aktifkan tag blok tingkat halaman:

JSON
{
  "ui": {
    "enabled": true
  },
  "blockTags": {
    "enabled": true,
    "allow": ["bsui/*", "app/*"]
  }
}

Komponen Dasar

Komponen sederhana dirender sebagai satu blok:

HTML
<block name="bsui/button" label="Continue" variant="default"></block>
<block name="bsui/badge" label="Beta"></block>
<block
  name="bsui/input"
  nameAlt="email"
  type="email"
  placeholder="Email"
></block>
<block name="bsui/textarea" name="message" placeholder="Message"></block>
<block name="bsui/spinner"></block>

Atribut dipetakan langsung ke atribut block.json setiap komponen. Misalnya, bsui/button mendukung label, icon, iconPosition, href, variant, size, dan disabled.

PHP
bs_render_block([
  'name' => 'bsui/button',
  'data' => [
    'label' => 'Continue',
    'icon' => [
      'set' => 'heroicons',
      'subSet' => 'outline',
      'icon' => 'arrow-right',
    ],
    'iconPosition' => 'right',
  ],
]);

Komponen Majemuk

Banyak komponen UI merupakan blok majemuk. Blok akar mengelola status, sedangkan blok anak mendeklarasikan induknya.

Tab

HTML
<block name="bsui/tabs" defaultValue="tab1">
  <block name="bsui/tabs-list">
    <block name="bsui/tabs-trigger" value="tab1" title="Features"></block>
    <block name="bsui/tabs-trigger" value="tab2" title="Pricing"></block>
    <block name="bsui/tabs-trigger" value="tab3" title="FAQ"></block>
  </block>
  <block name="bsui/tabs-panel" value="tab1">
    <p>Features content.</p>
  </block>
  <block name="bsui/tabs-panel" value="tab2">
    <p>Pricing content.</p>
  </block>
  <block name="bsui/tabs-panel" value="tab3">
    <p>FAQ content.</p>
  </block>
</block>

Dialog

HTML
<block name="bsui/dialog">
  <block name="bsui/dialog-trigger" label="Open Dialog"></block>
  <block name="bsui/dialog-backdrop"></block>
  <block name="bsui/dialog-popup">
    <p>Dialog content.</p>
    <block name="bsui/dialog-close" label="Close"></block>
  </block>
</block>

Select

HTML
<block name="bsui/select" placeholder="Choose a fruit" nameAlt="fruit">
  <block name="bsui/select-trigger"></block>
  <block name="bsui/select-popup">
    <block name="bsui/select-option" value="apple" label="Apple"></block>
    <block name="bsui/select-option" value="banana" label="Banana"></block>
    <block name="bsui/select-option" value="cherry" label="Cherry"></block>
  </block>
</block>

Field Formulir

HTML
<block name="bsui/form" block="contact/form" successMessage="Thank you!">
  <block name="bsui/field">
    <block name="bsui/field-label" text="Email"></block>
    <block name="bsui/input" nameAlt="email" type="email"></block>
    <block name="bsui/field-error"></block>
  </block>
</block>

Blok yang Tersedia

Pustaka UI bawaan mencakup:

Area Blok
Tata letak bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
Tindakan bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
Input bsui/checkbox, bsui/color-picker, bsui/date-input, bsui/file-upload, bsui/input, bsui/number-field, bsui/otp-input, bsui/password-input, bsui/phone-input, bsui/radio-group, bsui/rating, bsui/select, bsui/slider, bsui/switch, bsui/textarea, bsui/time-picker
Overlay bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
Navigasi bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs
Umpan balik bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast
Formulir bsui/field, bsui/field-group, bsui/form

Komponen majemuk juga menyediakan blok anak, seperti bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup, dan bsui/select-option.

Gaya

Komponen UI menyertakan properti kustom CSS sendiri menggunakan prefiks --bs-ui-*. Anda dapat menggantinya dari CSS tema Anda:

CSS
:root {
  --bs-ui-radius: 0.5rem;
  --bs-ui-primary: oklch(0.45 0.18 260);
  --bs-ui-primary-foreground: white;
}

Perilaku komponen tidak dikendalikan oleh antarmuka, tetapi cukup memiliki pendapat agar langsung dapat digunakan. Ganti token terlebih dahulu, lalu tambahkan CSS khusus komponen jika diperlukan.

CSS komponen bawaan dikeluarkan dalam lapisan cascade bsui bernama. CSS tema yang tidak berlapis dapat mengganti aturan komponen tanpa !important:

CSS
.button-brand {
  background: var(--brand-primary);
}

Untuk menambahkan varian bsui/button kustom, tambahkan opsi select dengan filter atribut yang sudah ada, lalu sediakan varian CSS dengan blockstudio/ui/button/variants-style:

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (($block['name'] ?? '') === 'bsui/button' && ($attribute['id'] ?? '') === 'variant') {
    $attribute['options'][] = [
      'label' => 'Brand',
      'value' => 'brand',
    ];
  }

  return $attribute;
}, 10, 2);

add_filter('blockstudio/ui/button/variants-style', function($css) {
  return $css . '
[data-bsui-button][data-variant="brand"] {
  background: var(--brand-primary);
  color: white;
}';
});

Semua komponen

Akordeon Bagian bertumpuk yang membuka satu panel setiap kali. Dialog Peringatan Modal yang menghentikan alur dan memerlukan jawaban sebelum ditutup. Rasio Aspek Mengunci konten ke rasio lebar dan tinggi tetap. Avatar Gambar pengguna yang beralih ke inisial saat gagal dimuat. Lencana Label kecil untuk status, jumlah, dan kategori. Breadcrumb Menunjukkan posisi halaman saat ini dalam hierarki. Tombol Memicu tindakan, dengan varian untuk setiap tingkat penekanan. Grup Tombol Menggabungkan tombol terkait menjadi satu kontrol bersegmen. Kalender Kisi tanggal untuk memilih satu hari. Kartu Permukaan yang mengelompokkan header, isi, dan footer. Karusel Jalur slide yang dapat digeser dengan dukungan keyboard. Kotak Centang Pilihan biner yang juga mendukung status tak tentu. Dapat Dilipat Menyembunyikan dan menampilkan satu area konten. Pemilih Warna Memilih warna dan mengirimkannya bersama formulir di sekitarnya. Combobox Input teks yang memfilter daftar opsi saat Anda mengetik. Menu Konteks Tindakan yang muncul saat klik kanan dan ditambatkan ke pointer. Input Tanggal Kolom bertopeng untuk mengetik tanggal tanpa pemilih tanggal. Dialog Lapisan modal untuk tugas terfokus dan konfirmasi. Drawer Panel yang meluncur masuk dari tepi layar mana pun. Field Membungkus satu kontrol dengan label, deskripsi, dan pesan kesalahannya. Grup Bidang Mengelompokkan kolom terkait di bawah judul yang sama. Unggah File Zona drop dan pemilih file dengan dukungan banyak file. Formulir Mengirim kolom dan melaporkan keberhasilan tanpa memuat ulang halaman. Input Kolom teks satu baris untuk semua jenis input umum. Pintasan Keyboard Menampilkan pintasan keyboard pada tombolnya sendiri. Label Keterangan untuk kontrol yang digunakan bersama oleh setiap komponen berlabel. Menu Daftar tarik-turun tindakan yang ditambatkan ke pemicu. Menubar Bilah menu horizontal seperti pada aplikasi desktop. Meter Menunjukkan pengukuran dalam rentang yang diketahui. Menu Navigasi Navigasi situs dengan tautan bertingkat dan panel saat diarahkan. Kolom Angka Input numerik dengan tombol pengatur dan rentang terbatas. Input OTP Kotak terpisah untuk memasukkan kode sandi sekali pakai. Paginasi Tautan halaman dengan opsi sebelumnya, berikutnya, dan pemangkasan. Input Kata Sandi Kolom kata sandi dengan tombol untuk menampilkannya. Input Nomor Telepon Kolom telepon dengan pilihan negara dan pemformatan. Popover Konten kaya yang ditambatkan ke pemicu dan ditutup saat klik di luar. Kartu Pratinjau Kartu saat diarahkan yang menampilkan pratinjau tujuan tautan. Progres Menunjukkan kemajuan suatu tugas. Grup Radio Kumpulan opsi yang hanya mengizinkan satu pilihan. Penilaian Kontrol bintang untuk memasukkan skor. Area Gulir Kontainer gulir dengan scrollbar overlay yang diberi gaya. Pilih Menu tarik-turun untuk memilih dari daftar opsi. Pemisah Garis yang memisahkan konten atau mengelompokkan kontrol. Kerangka Bentuk placeholder yang ditampilkan sementara konten dimuat. Slider Memilih nilai atau rentang dengan menyeret sepanjang jalur. Ruang Langkah tetap ritme vertikal dari skala jarak. Pemintal Menandakan pekerjaan yang sedang berlangsung tanpa durasi yang diketahui. Tumpukan Menyusun elemen anak dalam baris atau kolom dengan jarak yang konsisten. Sakelar Mengaktifkan atau menonaktifkan setelan yang langsung diterapkan. Tabel Data tabel dengan opsi pengurutan dan pola belang. Tab Beralih di antara panel yang menempati ruang yang sama. Text Merender prosa dengan ukuran dan tag semantik yang dipilih. Area Teks Kolom teks multibaris yang bertambah tinggi sesuai jumlah barisnya. Pemilih Waktu Memilih waktu dalam sehari dengan interval tertentu. Penyedia Toast Menampung notifikasi sementara di sudut layar. Toggle Tombol yang tetap tertekan untuk menunjukkan status aktif. Grup Toggle Kumpulan tombol alih yang berfungsi sebagai pilihan tunggal atau jamak. Toolbar Baris kontrol dengan fokus yang berpindah di antaranya. Tooltip Petunjuk singkat yang ditampilkan saat diarahkan atau difokuskan.