Zum Inhalt springen

Komponenten

Blockstudio liefert 59 UI Komponenten mit jedem Build aus. Sie werden automatisch registriert, mit Design-Tokens gestaltet und mit derselben Tag-Syntax wie jeder andere Block erstellt.

Blockstudio 7.3 enthält eine gebündelte Sammlung zustandsloser UI-Blöcke, die auf dem Interactivity-API WordPress basieren. Sie sind unter dem Namespace bsui/* registriert und lassen sich in Templates, dateibasierten Seiten, Mustern und Beitragsinhalten kombinieren.

Hinweis

UI-Komponenten sind in der Beta-Phase, während wir Feedback zum Komponentensatz, zu den Namen, zum Verhalten und zu Nutzungsmustern in Projekten sammeln. Du kannst sie in 7.3 ausprobieren, aber die API-Oberfläche kann noch überarbeitet werden, bevor sie als stabil gilt.

UI-Komponenten aktivieren

Die gebündelten UI-Komponenten sind optional. Aktiviere sie in der blockstudio.json deines Themes:

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

Oder aktiviere sie mit einem Filter:

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

Nach der Aktivierung registriert Blockstudio die gebündelte Komponentenbibliothek aus includes/ui/blocks.

Öffentliches Verzeichnis und Beispiele

Die gebündelten Implementierungsblöcke bleiben normale bsui/*-Registrierungen. Für Komponentengalerien sollten Nutzer jedoch das öffentliche Verzeichnis der Komponentenfamilien verwenden:

PHP
use Blockstudio\Ui;

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

Ui::inventory() gruppiert alle zusammengesetzten Komponenten unter ihrem öffentlichen Stamm und listet die benötigten Implementierungsregistrierungen für jede Familie auf. Ui::examples() ergänzt eine deterministische, normalisierte Deklaration mit Standard- und Beispieldaten. Dabei bleiben erforderliche Beziehungen zwischen Stamm und Unterelementen erhalten, sodass sich das Ergebnis direkt an Blockstudio\Render::document() übergeben lässt.

Das öffentliche Canvas-Verzeichnis führt diese Beispiele unter seinem Typ ui auf und lässt gebündelte Implementierungsregistrierungen aus dem normalen Typ blocks aus. So entsteht ein vollständiges Beispiel pro öffentlicher Komponentenfamilie statt einer Galerie interner Stamm-, Auslöser-, Popup- und Ebenenfragmente.

Beim Zusammenstellen eines bereits gerenderten Dokuments gibt Ui::global_assets($block_names, $html) das genaue gebündelte globale Stylesheet und Skript nur dann aus, wenn die ausgewählte Ausgabe tatsächlich eine UI-Komponente verwendet.

Rendering

Verwende die übliche Syntax für Block-Tags:

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

Auch die kürzere Syntax <bs:> funktioniert:

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

In Blockstudio-Templates werden Block-Tags automatisch gerendert. In dateibasierten Seiten und Mustern werden sie als native WordPress-Blöcke synchronisiert. Wenn du UI-Komponenten direkt aus Beitragsinhalten oder Widget-Bereichen rendern möchtest, aktiviere Block-Tags auf Seitenebene:

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

Einfache Komponenten

Einfache Komponenten werden als einzelner Block gerendert:

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>

Attribute werden direkt den block.json-Attributen der jeweiligen Komponente zugeordnet. bsui/button unterstützt zum Beispiel label, icon, iconPosition, href, variant, size und disabled.

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

Zusammengesetzte Komponenten

Viele UI-Komponenten bestehen aus mehreren Blöcken. Der Stammblock verwaltet den Zustand, und die untergeordneten Blöcke geben ihren übergeordneten Block an.

Tabs

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>

Auswahl

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>

Formularfelder

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>

Verfügbare Blöcke

Die gebündelte UI-Bibliothek enthält:

Bereich Blöcke
Layout bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
Aktionen bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
Eingaben 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
Einblendungen bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
Navigation bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs
Rückmeldungen bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast
Formulare bsui/field, bsui/field-group, bsui/form

Zusammengesetzte Komponenten bieten auch untergeordnete Blöcke wie bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup und bsui/select-option.

Gestaltung

UI-Komponenten enthalten eigene benutzerdefinierte CSS-Eigenschaften mit dem Präfix --bs-ui-*. Du kannst sie in deinem Theme mit CSS überschreiben:

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

Die Komponenten sind in ihrem Verhalten zustandslos, aber konkret genug gestaltet, um direkt einsatzbereit zu sein. Überschreibe zuerst die Tokens und füge bei Bedarf komponentenspezifische CSS hinzu.

Das CSS der gebündelten Komponenten wird in der benannten Kaskadenebene bsui ausgegeben. Nicht eingebettete Theme-CSS können Komponentenregeln ohne !important überschreiben:

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

Um eine benutzerdefinierte Variante von bsui/button hinzuzufügen, ergänze die Auswahloption mit dem vorhandenen Attributfilter und gib die Varianten-CSS mit blockstudio/ui/button/variants-style an:

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;
}';
});

Alle Komponenten

Akkordeon Gestapelte Bereiche, von denen jeweils ein Panel ausgeklappt wird. Hinweisdialog Ein modaler Dialog, der den Ablauf unterbricht und eine Antwort erfordert, bevor er sich schließt. Seitenverhältnis Hält Inhalte in einem festen Verhältnis von Breite zu Höhe. Avatar Ein Benutzerbild, das bei einem Ladefehler durch Initialen ersetzt wird. Abzeichen Eine kurze Beschriftung für Status, Anzahl und Kategorien. Breadcrumb Zeigt, an welcher Stelle der Hierarchie sich die aktuelle Seite befindet. Schaltfläche Löst eine Aktion aus und bietet Varianten für jede Gewichtungsstufe. Schaltflächengruppe Fasst zusammengehörige Buttons zu einer segmentierten Steuerung zusammen. Kalender Ein Kalender zum Auswählen eines einzelnen Tages. Karte Eine Fläche, die Kopfzeile, Inhalt und Fußzeile gruppiert. Karussell Eine wischbare Folienleiste mit Tastaturunterstützung. Kontrollkästchen Eine binäre Auswahl, die auch einen unbestimmten Zustand unterstützt. Einklappbar Blendet einen einzelnen Inhaltsbereich ein und aus. Farbauswahl Wählt eine Farbe aus und übermittelt sie mit dem umgebenden Formular. Combobox Ein Texteingabefeld, das während der Eingabe eine Optionsliste filtert. Kontextmenü Aktionen, die per Rechtsklick am Mauszeiger angezeigt werden. Datumseingabe Ein maskiertes Feld zur Eingabe von Datumsangaben ohne Auswahlkalender. Dialog Eine modale Ebene für Aufgaben und Bestätigungen, die volle Aufmerksamkeit erfordern. Drawer Ein Panel, das von jeder Bildschirmkante hereingleitet. Feld Umschließt ein Steuerelement mit Beschriftung, Beschreibung und Fehlermeldung. Feldgruppe Gruppiert zusammengehörige Felder unter einem gemeinsamen Titel. Datei-Upload Eine Dropzone und Dateiauswahl mit Unterstützung für mehrere Dateien. Formular Übermittelt die Felder und meldet den Erfolg ohne Neuladen. Eingabe Ein einzeiliges Textfeld für alle gängigen Eingabetypen. Tastenkombination Zeigt eine Tastenkombination in einer eigenen Tastenkappe an. Beschriftung Eine Beschriftung für ein Steuerelement, die alle beschrifteten Komponenten verwenden können. Menü Eine Dropdown-Liste mit Aktionen, die an einem Auslöser verankert ist. Menüleiste Eine horizontale Menüleiste wie in einer Desktop-Anwendung. Messgerät Zeigt einen Messwert innerhalb eines bekannten Bereichs an. Navigationsmenü Website-Navigation mit verschachtelten Links und Hover-Panels. Zahlenfeld Eine Zahleneingabe mit Schrittsteuerung und begrenztem Wertebereich. OTP-Eingabe Getrennte Felder zur Eingabe eines Einmalcodes. Seitennummerierung Seitenlinks mit Zurück, Weiter und Auslassung. Passworteingabe Ein Passwortfeld mit Schalter zum Einblenden. Telefoneingabe Ein Telefonnummernfeld mit Länderauswahl und Formatierung. Popover Formatierter Inhalt an einem Auslöser verankert, der per Klick außerhalb geschlossen wird. Vorschaukarte Eine Hover-Karte mit Vorschau auf das Linkziel. Fortschritt Zeigt an, wie weit eine Aufgabe fortgeschritten ist. Optionsfeldgruppe Eine Optionsgruppe, in der genau eine Option ausgewählt werden kann. Bewertung Eine Sternbewertung zum Erfassen einer Bewertung. Scrollbereich Ein Scroll-Container mit gestalteten, überlagerten Scrollleisten. Auswählen Ein Dropdown zur Auswahl aus einer Optionsliste. Trennlinie Eine Linie, die Inhalte oder Gruppen von Steuerelementen trennt. Skelett Eine Platzhalterform, die während des Ladens Inhalte ersetzt. Schieberegler Wählt durch Ziehen entlang einer Leiste einen Wert oder Wertebereich aus. Abstand Ein fester Schritt im vertikalen Rhythmus des Abstandsrasters. Spinner Zeigt laufende Arbeit ohne bekannte Dauer an. Stapel Ordnet untergeordnete Elemente mit gleichmäßigen Abständen in einer Zeile oder Spalte an. Schalter Schaltet eine Einstellung um, die sofort angewendet wird. Tabelle Tabellarische Daten mit optionaler Sortierung und abwechselnder Zeilenfärbung. Tabs Wechselt zwischen Panels, die denselben Platz einnehmen. Text Zeigt Fließtext in einer gewählten Größe und mit einem semantischen Tag an. Textbereich Ein mehrzeiliges Textfeld, das mit der Zeilenanzahl wächst. Zeitauswahl Wählt eine Uhrzeit in einem festgelegten Intervall aus. Toast-Anbieter Zeigt vorübergehende Benachrichtigungen in einer Bildschirmecke an. Umschalter Ein Button, der gedrückt bleibt, um den eingeschalteten Zustand darzustellen. Umschaltgruppe Eine Gruppe von Umschaltern für eine einfache oder Mehrfachauswahl. Werkzeugleiste Eine Reihe von Steuerelementen, zwischen denen der Fokus weiterwandert. Tooltip Ein kurzer Hinweis, der beim Darüberfahren oder Fokussieren erscheint.