Přejít k obsahu

Komponenty

Blockstudio obsahuje v každé sestavě 59 UI komponent. Registrují se automaticky, stylují pomocí návrhových tokenů a zapisují stejnou syntaxí značek jako každý jiný blok.

Blockstudio 7.3 obsahuje sadu bezhlavých bloků UI poháněných WordPress Interactivity API. Jsou registrovány pod jmenným prostorem bsui/* a lze je skládat do šablon, stránek založených na souborech, vzorů a obsahu příspěvků.

Poznámka

Komponenty UI jsou v beta verzi, během níž shromažďujeme zpětnou vazbu k sadě komponent, jejich pojmenování, chování a způsobům použití v projektech. Ve verzi 7.3 je můžete vyzkoušet, ale rozhraní API se může před označením za stabilní ještě upravit.

Povolení komponent UI

Komponenty UI jsou součástí balíčku a jejich použití je třeba výslovně povolit. Zapněte je v souboru blockstudio.json své šablony:

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

Nebo je povolte pomocí filtru:

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

Po povolení zaregistruje Blockstudio knihovnu komponent obsaženou v includes/ui/blocks.

Veřejný přehled a ukázky

Bloky implementace dodávané v balíčku zůstávají běžnými registracemi bsui/*, ale při vytváření galerie komponent by uživatelé měli používat veřejný přehled skupin:

PHP
use Blockstudio\Ui;

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

Ui::inventory() sdružuje všechny složené komponenty pod jejich veřejným kořenovým blokem a uvádí registrace implementace, které daná skupina vyžaduje. Ui::examples() přidává deterministickou normalizovanou deklaraci s výchozími a názornými daty. Zachovává požadované vztahy mezi kořenovými a podřízenými bloky, takže výsledek lze předat přímo do Blockstudio\Render::document().

Veřejný přehled plátna zpřístupňuje tyto ukázky pod typem ui a vynechává registrace implementace dodávané v balíčku z běžného typu blocks. Výsledkem je jedna úplná ukázka pro každou veřejnou skupinu komponent namísto galerie interních částí kořenových bloků, spouštěčů, vyskakovacích oken a vrstev.

Při sestavování již vykresleného dokumentu vrátí Ui::global_assets($block_names, $html) přesný globální styl a skript dodávaný v balíčku pouze tehdy, pokud výběr výstupu skutečně používá komponentu UI.

Vykreslování

Použijte běžnou syntaxi značek bloků:

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

Funguje i kratší syntaxe <bs:>:

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

V šablonách Blockstudio se značky bloků vykreslují automaticky. Na souborových stránkách a ve vzorech se synchronizují jako nativní bloky WordPress. Pokud chcete vykreslovat komponenty UI přímo z obsahu příspěvků nebo oblastí widgetů, povolte značky bloků pro jednotlivé stránky:

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

Základní komponenty

Jednoduché komponenty se vykreslí jako jediný 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>

Atributy se přímo mapují na atributy block.json jednotlivých komponent. Například komponenta bsui/button podporuje label, icon, iconPosition, href, variant, size a disabled.

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

Složené komponenty

Mnohé komponenty UI se skládají z více bloků. Kořenový blok spravuje stav a podřízené bloky uvádějí svůj nadřazený blok.

Záložky

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>

Výběrové pole

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>

Pole formuláře

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>

Dostupné bloky

Knihovna komponent UI dodávaná v balíčku zahrnuje:

Oblast Bloky
Rozvržení bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
Akce bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
Vstupy 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
Překryvné vrstvy bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
Navigace bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs
Zpětná vazba bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast
Formuláře bsui/field, bsui/field-group, bsui/form

Složené komponenty zpřístupňují také podřízené bloky, například bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup a bsui/select-option.

Styly

Komponenty UI se dodávají s vlastními vlastními vlastnostmi CSS s předponou --bs-ui-*. Můžete je přepsat ve své šabloně CSS:

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

Chování komponent je bezhlavé, ale jejich názory na výchozí podobu stačí k použití ihned po instalaci. Nejprve přepište tokeny a podle potřeby pak přidejte specifická pravidla CSS pro jednotlivé komponenty.

CSS komponent dodávaných v balíčku se vydává v pojmenované kaskádové vrstvě bsui. Pravidla CSS šablony mimo vrstvy mohou přepsat pravidla komponent bez !important:

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

Chcete-li přidat vlastní variantu bsui/button, připojte možnost výběru pomocí existujícího filtru atributů a zadejte variantě CSS hodnotu 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;
}';
});

Všechny komponenty

Rozbalovací seznam Vrstvené sekce, které postupně rozbalují vždy jeden panel. Upozorňovací dialog Modální okno, které přeruší pracovní postup a vyžaduje odpověď, než se zavře. Poměr stran Uzamkne obsah do pevného poměru šířky a výšky. avatar Uživatelský obrázek, který se při neúspěšném načtení nahradí iniciálami. Odznak Malý štítek pro stav, počty a kategorie. Drobečková navigace Zobrazuje pozici aktuální stránky v hierarchii. Tlačítko Spouští akci a nabízí varianty pro různé úrovně zvýraznění. Skupina tlačítek Spojuje související tlačítka do jednoho segmentovaného ovládacího prvku. Kalendář Kalendářní mřížka pro výběr jednoho dne. Karta Plocha, která sdružuje záhlaví, tělo a zápatí. Karusel Posuvný pás snímků s podporou klávesnice. Zaškrtávací políčko Binární volba, která podporuje také neurčitý stav. Sbalitelný Skrývá a zobrazuje jednu oblast obsahu. Výběr barvy Vybere barvu a odešle ji spolu s okolním formulářem. Kombinovaný seznam Textové pole, které při psaní filtruje seznam možností. Kontextová nabídka Akce zobrazené po kliknutí pravým tlačítkem a ukotvené k ukazateli. Vstupní pole data Maskované pole pro zadávání data bez výběrového kalendáře. Dialog Modální vrstva pro soustředěné úkoly a potvrzení. Výsuvný panel Panel, který se vysune z libovolného okraje obrazovky. Pole Sdružuje jeden ovládací prvek se štítkem, popisem a chybovou zprávou. Skupina polí Sdružuje související pole pod společným názvem. Nahrávání souboru Zóna pro přetažení a výběr souborů s podporou více souborů. Formulář Odesílá pole formuláře a hlásí úspěch bez opětovného načtení stránky. Vstup Jednořádkové textové pole pro všechny běžné typy vstupu. Klávesová zkratka Zobrazí klávesovou zkratku v samostatné klávese. Popisek Popisek ovládacího prvku sdílený všemi označenými komponentami. Nabídka Rozbalovací seznam akcí ukotvený k aktivátoru. Panel nabídek Vodorovný pruh nabídek jako v desktopové aplikaci. Měřidlo Zobrazuje měření v rámci známého rozsahu. Navigační nabídka Navigace webu s vnořenými odkazy a panely při najetí. Číselné pole Číselné pole se šipkami a omezeným rozsahem. Vstup pro jednorázové heslo Oddělená políčka pro zadání jednorázového hesla. Stránkování Odkazy na stránky s předchozí a následující stránkou a vynechanými položkami. Pole pro heslo Pole pro heslo s přepínačem zobrazení. Pole pro telefonní číslo Pole pro telefonní číslo s výběrem země a formátováním. Vyskakovací nabídka Formátovaný obsah ukotvený k aktivátoru, který se zavře kliknutím mimo něj. Karta náhledu Karta při najetí, která zobrazí náhled cíle odkazu. Průběh Zobrazuje, jak daleko je úkol rozpracovaný. Skupina přepínačů Sada možností, z níž lze vybrat právě jednu. Hodnocení Ovládací prvek s hvězdičkami pro zadání hodnocení. Oblast posouvání Kontejner s posuvníkem a stylovanými překryvnými posuvníky. Vyberte Rozbalovací nabídka pro výběr ze seznamu možností. Oddělovač Čára, která odděluje obsah nebo skupiny ovládacích prvků. Kostra Zástupný tvar, který se zobrazí během načítání obsahu. Posuvník Výběr hodnoty nebo rozsahu tažením po dráze. Mezera Pevný svislý rozestup ze škály mezer. Točítko Označuje probíhající práci bez známé doby trvání. Hromádka Uspořádá potomky do řádku nebo sloupce s rovnoměrnými rozestupy. Přepínač Přepíná nastavení, které se projeví okamžitě. Tabulka Tabulková data s volitelným řazením a střídavým stínováním řádků. Karty Přepíná mezi panely, které zabírají stejné místo. Text Vykresluje text v próze zvolené velikosti a sémantické značky. Textové pole Víceřádkové textové pole, které se zvětšuje podle počtu řádků. Výběr času Výběr denního času s nastavitelným krokem. Poskytovatel oznámení toast Zobrazuje dočasná oznámení v rohu obrazovky. Přepínač Tlačítko, které zůstane stisknuté a představuje zapnutý stav. Skupina přepínačů Sada přepínačů pro výběr jedné nebo více možností. panel nástrojů Řada ovládacích prvků s přesouváním fokusu mezi nimi. nápověda Krátká nápověda zobrazená při najetí nebo zaměření.