Ga naar de inhoud

Componenten

Blockstudio bevat bij elke build 59 UI componenten. Ze worden automatisch geregistreerd, opgemaakt met ontwerptokens en geschreven met dezelfde tagsyntaxis als elk ander blok.

Blockstudio 7.3 bevat een meegeleverde set headless UI-blokken die worden aangedreven door de WordPress Interactivity API. Ze zijn geregistreerd onder de namespace bsui/* en kunnen worden samengesteld in templates, pagina's met bestandsstructuur, patronen en berichtinhoud.

Opmerking

UI-componenten zijn in bèta terwijl we feedback verzamelen over de componentenset, de naamgeving, het gedrag en gebruikspatronen in projecten. Je kunt ze uitproberen in 7.3, maar de API-interface kan nog worden aangepast voordat deze stabiel wordt verklaard.

UI-componenten inschakelen

Meegeleverde UI-componenten zijn optioneel. Schakel ze in via blockstudio.json van je thema:

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

Of schakel ze in met een filter:

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

Als ze zijn ingeschakeld, registreert Blockstudio de meegeleverde componentenbibliotheek vanuit includes/ui/blocks.

Openbare inventaris en voorbeelden

De meegeleverde implementatieblokken blijven gewone bsui/*-registraties, maar consumenten kunnen bij het samenstellen van een componentengalerij beter de openbare inventaris van componentfamilies gebruiken:

PHP
use Blockstudio\Ui;

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

Ui::inventory() groepeert elke samengestelde component onder de openbare hoofdcomponent en vermeldt de implementatieregistraties die voor die familie nodig zijn. Ui::examples() voegt een deterministische, genormaliseerde declaratie met standaard- en voorbeeldgegevens toe. De vereiste relaties tussen hoofd- en onderliggende componenten blijven behouden, zodat het resultaat direct aan Blockstudio\Render::document() kan worden doorgegeven.

De openbare Canvas-inventaris toont deze voorbeelden onder het type ui en laat meegeleverde implementatieregistraties weg uit het gewone type blocks. Zo ontstaat één compleet voorbeeld per openbare componentfamilie, in plaats van een galerij met interne fragmenten voor hoofdcomponenten, triggers, popups en lagen.

Bij het samenstellen van een al weergegeven document geeft Ui::global_assets($block_names, $html) de exacte meegeleverde globale stijl en het script alleen terug wanneer de geselecteerde uitvoer daadwerkelijk een UI-component gebruikt.

Renderen

Gebruik de gewone syntaxis voor bloktags:

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

De kortere syntaxis <bs:> werkt ook:

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

In templates van Blockstudio worden bloktags automatisch weergegeven. Op pagina's met bestandsstructuur en in patronen worden ze gesynchroniseerd als native WordPress-blokken. Als je UI-componenten rechtstreeks uit berichtinhoud of widgetgebieden wilt weergeven, schakel dan bloktags op paginaniveau in:

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

Basiscomponenten

Eenvoudige componenten worden als één blok weergegeven:

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>

Attributen komen rechtstreeks overeen met de block.json-attributen van elke component. Zo ondersteunt bsui/button label, icon, iconPosition, href, variant, size en disabled.

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

Samengestelde componenten

Veel UI-componenten bestaan uit meerdere blokken. Het hoofdblok beheert de status en onderliggende blokken geven hun bovenliggende blok op.

Tabbladen

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>

Dialoogvenster

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>

Formuliervelden

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>

Beschikbare blokken

De meegeleverde UI-bibliotheek bevat:

Gebied Blokken
Indeling bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
Acties bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
Invoer 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
Overlays bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
Navigatie bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs
Feedback bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast
Formulieren bsui/field, bsui/field-group, bsui/form

Samengestelde componenten bevatten ook onderliggende blokken, zoals bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup en bsui/select-option.

Vormgeving

UI-componenten worden geleverd met eigen CSS-custom properties met het voorvoegsel --bs-ui-*. Je kunt deze overschrijven vanuit CSS van je thema:

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

De componenten hebben geen ingebouwd gedrag, maar bieden genoeg houvast om meteen bruikbaar te zijn. Overschrijf eerst de tokens en voeg daarna waar nodig componentspecifieke CSS toe.

De gebundelde component CSS wordt uitgegeven in de benoemde bsui-cascadelaag. Een thema CSS zonder laag kan componentregels overschrijven zonder !important:

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

Als je een aangepaste variant van bsui/button wilt toevoegen, voeg dan de selectoptie toe met het bestaande attributenfilter en geef de variant-CSS op met 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;
}';
});

Alle componenten

Accordeon Gestapelde secties waarvan telkens één paneel wordt uitgevouwen. Waarschuwingsdialoog Een modal die de workflow onderbreekt en een antwoord vereist voordat deze sluit. Beeldverhouding Beperkt inhoud tot een vaste breedte-hoogteverhouding. Avatar Een gebruikersafbeelding die bij een laadfout wordt vervangen door initialen. Badge Een klein label voor status, aantallen en categorieën. Kruimelpad Toont de plek van de huidige pagina in de hiërarchie. Knop Voert een actie uit, met varianten voor elk nadrukniveau. Knopgroep Voegt verwante knoppen samen tot één gesegmenteerde bediening. Agenda Een datumraster om één dag te kiezen. Kaart Een oppervlak met een koptekst, inhoud en voettekst. Carrousel Een versleepbare reeks dia's met toetsenbordondersteuning. Selectievakje Een binaire keuze die ook een onbepaalde status ondersteunt. Inklapbaar Verbergt en toont één inhoudsgebied. Kleurkiezer Kiest een kleur en verstuurt deze met het bijbehorende formulier. Combobox Een tekstinvoer die tijdens het typen een lijst met opties filtert. Contextmenu Acties die bij rechtsklikken verschijnen en aan de aanwijzer zijn verankerd. Datumveld Een gemaskeerd veld om datums in te voeren zonder kiezer. Dialoog Een modale laag voor taken die focus vereisen en voor bevestigingen. Zijpaneel Een paneel dat vanaf elke schermrand naar binnen schuift. Veld Groepeert een bedieningselement met het label, de beschrijving en de foutmelding. Veldgroep Groepeert verwante velden onder een gedeelde titel. Bestand uploaden Een dropzone en bestandskiezer met ondersteuning voor meerdere bestanden. Formulier Verstuurt de velden en meldt succes zonder de pagina opnieuw te laden. Invoer Een tekstveld van één regel voor alle gangbare invoertypen. Sneltoets Toont een sneltoets in een eigen toetskapje. Label Een bijschrift voor een bedieningselement, gedeeld door alle componenten met een label. Menu Een vervolgkeuzelijst met acties, verankerd aan een trigger. Menubalk Een horizontale menubalk, zoals in een desktopapplicatie. Meter Toont een meting binnen een bekend bereik. Navigatiemenu Sitenavigatie met geneste links en panelen die bij hover verschijnen. Getalveld Een numerieke invoer met stapknoppen en een begrensd bereik. OTP-invoer Gescheiden vakjes voor het invoeren van een eenmalige toegangscode. Paginering Paginakoppelingen met vorige, volgende en afgekorte vermeldingen. Wachtwoordinvoer Een wachtwoordveld met een schakelaar om het wachtwoord te tonen. Telefoonnummerinvoer Een telefoonnummerveld met landkeuze en opmaak. Pop-over Uitgebreide inhoud die aan een trigger is verankerd en bij een klik buiten het element sluit. Voorbeeldkaart Een kaart die bij hover een voorbeeld toont van waar een link naartoe leidt. Voortgang Toont hoever een taak is gevorderd. Groep keuzerondjes Een reeks opties waaruit precies één optie kan worden geselecteerd. Beoordeling Een bediening met sterren om een score vast te leggen. Scrollgebied Een scrollcontainer met opgemaakte overlay-scrollbalken. Selecteer Een vervolgkeuzelijst om een optie uit een lijst te kiezen. Scheidingsteken Een lijn die inhoud of groepen bedieningselementen scheidt. Skelet Een placeholdervorm die wordt weergegeven terwijl inhoud wordt geladen. Schuifregelaar Kiest een waarde of bereik door langs een spoor te slepen. Ruimte Een vaste stap in de verticale ritmiek van de afstandsschaal. Draaier Geeft aan dat er werk wordt uitgevoerd zonder bekende duur. Stapel Rangschikt onderliggende elementen in een rij of kolom met gelijkmatige tussenruimte. Schakelaar Schakelt een instelling om die direct wordt toegepast. Tabel Tabelgegevens met optioneel sorteren en afwisselende rijkleuren. Tabbladen Schakelt tussen panelen die dezelfde ruimte innemen. Text Toont lopende tekst met een gekozen grootte en semantische tag. Tekstvak Een tekstveld met meerdere regels dat meegroeit met het aantal regels. Tijdkiezer Kiest een tijdstip met een gekozen interval. Toast-provider Toont tijdelijke meldingen in een hoek van het scherm. Schakelaar Een knop die ingedrukt blijft om een ingeschakelde status weer te geven. Schakelaargroep Een reeks schakelaars voor één keuze of meerdere keuzes. Werkbalk Een rij bedieningselementen met roving focus ertussen. Tooltip Een korte hint die bij hover of focus verschijnt.