Przejdź do treści

Komponenty

Blockstudio dostarcza 59 UI komponentów z każdą kompilacją. Są one rejestrowane automatycznie, stylizowane za pomocą tokenów projektu i tworzone przy użyciu tej samej składni znaczników co każdy inny blok.

Blockstudio 7.3 zawiera zestaw bezgłowych bloków UI obsługiwanych przez WordPress Interactivity API. Są rejestrowane w przestrzeni nazw bsui/* i można je łączyć w szablonach, stronach opartych na plikach, wzorcach i treści wpisów.

Uwaga

Komponenty UI są w wersji beta, ponieważ zbieramy opinie o zestawie komponentów, nazewnictwie, działaniu i sposobach użycia w projektach. Można je wypróbować w wersji 7.3, ale interfejs API może jeszcze zostać dopracowany przed uznaniem go za stabilny.

Włącz komponenty UI

Dołączone komponenty UI są opcjonalne. Włącz je w pliku blockstudio.json motywu:

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

Możesz też je włączyć za pomocą filtra:

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

Po włączeniu Blockstudio rejestruje dołączoną bibliotekę komponentów z includes/ui/blocks.

Publiczny wykaz i przykłady

Dołączone bloki implementacyjne pozostają zwykłymi rejestracjami bsui/*, ale podczas tworzenia galerii komponentów należy korzystać z publicznego wykazu rodzin:

PHP
use Blockstudio\Ui;

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

Ui::inventory() grupuje wszystkie komponenty złożone pod ich publicznym elementem głównym i wymienia rejestracje implementacyjne wymagane przez daną rodzinę. Ui::examples() dodaje deterministyczną, znormalizowaną deklarację z danymi domyślnymi i przykładowymi. Zachowuje wymagane relacje między elementami głównymi i podrzędnymi, dzięki czemu wynik można przekazać bezpośrednio do Blockstudio\Render::document().

Publiczny wykaz Canvas udostępnia te przykłady w typie ui, a z normalnego typu blocks pomija rejestracje dołączonych bloków implementacyjnych. Dzięki temu powstaje po jednym kompletnym przykładzie na każdą publiczną rodzinę komponentów, zamiast galerii wewnętrznych fragmentów: elementów głównych, wyzwalaczy, popupów i warstw.

Podczas składania już wyrenderowanego dokumentu Ui::global_assets($block_names, $html) zwraca dokładny zestaw globalnych stylów i skryptów tylko wtedy, gdy wybrane dane wyjściowe rzeczywiście używają komponentu UI.

Renderowanie

Użyj standardowej składni tagów bloków:

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

Działa też krótsza składnia <bs:>:

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

W szablonach Blockstudio tagi bloków są renderowane automatycznie. Na stronach opartych na plikach i we wzorcach synchronizują się jako natywne bloki WordPress. Aby renderować komponenty UI bezpośrednio z treści wpisów lub obszarów widżetów, włącz tagi bloków na poziomie strony:

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

Podstawowe komponenty

Proste komponenty renderują się jako pojedynczy 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>

Atrybuty bezpośrednio odpowiadają atrybutom block.json każdego komponentu. Na przykład bsui/button obsługuje label, icon, iconPosition, href, variant, size i disabled.

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

Komponenty złożone

Wiele komponentów UI składa się z kilku bloków. Blok główny zarządza stanem, a bloki podrzędne deklarują swój element nadrzędny.

Karty

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>

Okno dialogowe

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>

Lista wyboru

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>

Pola formularza

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>

Dostępne bloki

Dołączona biblioteka UI obejmuje:

Obszar Bloki
Układ bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
Działania bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
Pola wejściowe 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
Nakładki bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
Nawigacja bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs
Informacje zwrotne bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast
Formularze bsui/field, bsui/field-group, bsui/form

Komponenty złożone udostępniają też bloki podrzędne, takie jak bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup i bsui/select-option.

Stylowanie

Komponenty UI są dostarczane z własnymi właściwościami niestandardowymi CSS używającymi prefiksu --bs-ui-*. Możesz je nadpisać w arkuszu stylów CSS motywu:

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

Komponenty nie narzucają zachowania, ale mają wystarczająco określone ustawienia, by działać od razu po instalacji. Najpierw nadpisz tokeny, a następnie dodaj w razie potrzeby reguły CSS specyficzne dla komponentu.

Dołączone reguły CSS komponentu są emitowane w nazwanej warstwie kaskady bsui. Nienależące do warstw reguły CSS motywu mogą nadpisywać reguły komponentu bez !important:

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

Aby dodać niestandardowy wariant bsui/button, dopisz opcję listy wyboru za pomocą istniejącego filtra atrybutów i podaj wariant CSS przez 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;
}';
});

Wszystkie komponenty

Akordeon Sekcje ułożone jedna nad drugą, w których można rozwijać jeden panel naraz. Okno alertu Okno modalne przerywające bieżące działanie i wymagające odpowiedzi przed zamknięciem. Proporcje obrazu Utrzymuje stałe proporcje szerokości do wysokości zawartości. Awatar Obraz użytkownika, który w razie niepowodzenia ładowania zastępują inicjały. Odznaka Mała etykieta stanu, liczby lub kategorii. Okruszki nawigacyjne Pokazuje położenie bieżącej strony w hierarchii. Przycisk Uruchamia działanie i oferuje warianty o różnym stopniu wyróżnienia. Grupa przycisków Łączy powiązane przyciski w jeden segmentowy element sterujący. Kalendarz Siatka dat do wyboru jednego dnia. Karta Obszar grupujący nagłówek, treść i stopkę. Karuzela Przesuwany zestaw slajdów z obsługą klawiatury. Pole wyboru Wybór binarny obsługujący również stan nieokreślony. Zwijany Ukrywa i pokazuje pojedynczy obszar treści. Wybór koloru Wybiera kolor i przesyła go wraz z otaczającym formularzem. Pole kombinowane Pole tekstowe filtrujące listę opcji podczas pisania. Menu kontekstowe Działania wyświetlane po kliknięciu prawym przyciskiem i zakotwiczone przy wskaźniku. Pole daty Maskowane pole do wpisywania dat bez selektora. Okno dialogowe Warstwa modalna do zadań wymagających skupienia i potwierdzeń. Wysuwany panel Panel wysuwany z dowolnej krawędzi ekranu. Pole Łączy kontrolkę z etykietą, opisem i komunikatem o błędzie. Grupa pól Grupuje powiązane pola pod wspólnym tytułem. Przesyłanie pliku Obszar upuszczania i selektor plików z obsługą wielu plików. Formularz Wysyła dane pól i informuje o powodzeniu bez ponownego ładowania strony. Dane wejściowe Jednowierszowe pole tekstowe do wszystkich typowych rodzajów danych wejściowych. Skrót klawiszowy Wyświetla skrót klawiaturowy we własnym polu klawisza. Etykieta Podpis kontrolki, wspólny dla wszystkich komponentów z etykietą. Menu Lista rozwijana z działaniami zakotwiczona przy elemencie wyzwalającym. Pasek menu Poziomy pasek menu, jak w aplikacji komputerowej. Miernik Pokazuje pomiar w określonym zakresie. Menu nawigacyjne Nawigacja witryny z zagnieżdżonymi odnośnikami i panelami rozwijanymi po najechaniu. Pole liczbowe Pole liczbowe ze strzałkami i ograniczonym zakresem wartości. Pole kodu OTP Oddzielne pola do wpisania jednorazowego kodu dostępu. Paginacja Odnośniki do stron z opcjami poprzedniej, następnej i skróconej listy. Pole hasła Pole hasła z przełącznikiem jego widoczności. Pole numeru telefonu Pole numeru telefonu z wyborem kraju i formatowaniem. Wyskakujące okienko Treść sformatowana, zakotwiczona przy elemencie wyzwalającym i zamykana kliknięciem poza nią. Karta podglądu Karta podglądu po najechaniu, pokazująca cel odnośnika. Postęp Pokazuje postęp wykonywania zadania. Grupa przycisków opcji Zestaw opcji, z którego można wybrać dokładnie jedną. Ocena Gwiazdki do wystawiania oceny. Obszar przewijania Kontener przewijania ze stylizowanymi paskami przewijania nakładanymi na treść. Wybierz Lista rozwijana do wyboru jednej z dostępnych opcji. Separator Linia oddzielająca treść lub grupy kontrolek. Szkielet Kształt zastępczy wyświetlany podczas ładowania treści. Suwak Wybiera wartość lub zakres przez przeciąganie wzdłuż toru. Odstęp Stały odstęp pionowy ze skali odstępów. Pokrętło Sygnalizuje trwającą pracę o nieznanym czasie trwania. Stos Układa elementy podrzędne w wierszu lub kolumnie, zachowując równe odstępy. Przełącznik Przełącza ustawienie, które zaczyna obowiązywać od razu. Tabela Dane tabelaryczne z opcjonalnym sortowaniem i naprzemiennym cieniowaniem wierszy. Karty Przełącza między panelami zajmującymi to samo miejsce. Text Wyświetla tekst z wybranym rozmiarem i znacznikiem semantycznym. Pole tekstowe Wielowierszowe pole tekstowe, które rozszerza się wraz z liczbą wierszy. Selektor czasu Wybiera porę dnia z określonym krokiem. Dostawca powiadomień toast Wyświetla tymczasowe powiadomienia w rogu ekranu. Przełącznik Przycisk pozostający wciśnięty, aby sygnalizować włączony stan. Grupa przełączników Zestaw przełączników działających jak wybór jednej lub wielu opcji. Pasek narzędzi Wiersz kontrolek, między którymi można przemieszczać fokus. Podpowiedź Krótka podpowiedź wyświetlana po najechaniu lub uzyskaniu fokusu.