Ga naar de inhoud

Componenten

Compositie

De meegeleverde UI-componenten zijn ontworpen om samen te worden gebruikt, niet één voor één. Een selectievak opent in een dialoogvenster, een formulier wordt gevalideerd in een lade en een menu staat in een tabelrij. Op deze pagina leest u hoe dit samenspel werkt: hoe samengestelde families zijn opgebouwd, hoe triggers knopprops doorgeven, wat de Interactivity-API onder de motorkap doet en hoe het lagenmodel gestapelde oppervlakken op elkaar afstemt.

Samengestelde families

Een samengestelde component bestaat uit een hoofdblok en onderliggende blokken. Het hoofdblok beheert de status; elk onderliggend blok geeft via parent en usesContext in zijn block.json aan waar het in de familie thuishoort:

JSON
{
  "name": "bsui/select-option",
  "parent": ["bsui/select-popup"],
  "usesContext": ["bsui/select"]
}

Hoofdblokken bieden een InnerBlocks-gebied met een lijst van allowedBlocks en een startende template. Als u dus een dialoogvenster invoegt in de editor, worden de trigger, achtergrond en pop-up automatisch aangemaakt. Een familie werkt hetzelfde, of deze nu is samengesteld in de editor, op een pagina op basis van bestanden of met tags:

HTML
<bs:bsui-select name="role" placeholder="Pick a role">
  <bs:bsui-select-trigger />
  <bs:bsui-select-popup>
    <bs:bsui-select-option value="viewer" label="Viewer" />
    <bs:bsui-select-option value="editor" label="Editor" />
  </bs:bsui-select-popup>
</bs:bsui-select>

Pop-ups en panelen zijn echte InnerBlocks-gebieden, geen slots met speciale syntaxis. In een bsui/dialog-popup kunnen onderliggende blokken worden geplaatst, net als in een groepsblok. Daardoor kunt u er gewoon een formulier, selectievak of ander dialoogvenster in samenstellen.

Platte gegevens of samengestelde onderliggende elementen

Sommige families accepteren hun inhoud als gegevens in plaats van als onderliggende elementen. Het selectievak genereert zelf de trigger en lijst wanneer u een array met options JSON aanlevert. Dit is geschikt voor opties uit PHP:

PHP
bs_render_block([
  'name' => 'bsui/select',
  'data' => [
    'name' => 'role',
    'placeholder' => 'Pick a role',
    'options' => wp_json_encode([
      ['value' => 'viewer', 'label' => 'Viewer'],
      ['value' => 'editor', 'label' => 'Editor'],
    ]),
  ],
]);

Beide vormen leveren hetzelfde markupcontract en hetzelfde runtimegedrag op. Gebruik onderliggende elementen wanneer de structuur wordt geschreven, en options wanneer deze wordt berekend.

Triggers doorgeven

Overlays worden geopend met een knop, en dat hoort de systeemknop te zijn. In plaats van die knop telkens opnieuw te implementeren, voegen de triggerblokken van bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible en bsui/tooltip bsui/button in via een blokveld:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "trigger",
        "type": "block",
        "block": "bsui/button",
        "idStructure": "trigger_{id}"
      }
    ]
  }
}

De idStructure voegt de velden van de knop met het voorvoegsel trigger_ toe aan de trigger. Alle knopprops zijn beschikbaar: trigger_label, trigger_variant, trigger_size, trigger_icon, trigger_iconPosition, trigger_href, trigger_disabled.

HTML
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />

In de template van de trigger is $a['trigger'] de volledig gerenderde knop, zodat de stylesheet en toekomstige verbeteringen van de knop behouden blijven. Tijdens runtime geeft een gedeelde helper de ARIA-koppelingen van de wrapper (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) door aan de binnenste knop en houdt deze via een MutationObserver synchroon, zodat hulptechnologie één samenhangend bedieningselement ziet.

De Interactivity-API onder de motorkap

Elke interactieve familie is een WordPress-Interactivity-API met de naam van het hoofdblok: bsui/dialog, bsui/select, bsui/form, bsui/tabs enzovoort. Dit heeft drie gevolgen.

De status wordt aan de serverzijde ingesteld. De template van het hoofdblok drukt de initiële status af als data-wp-context, rechtstreeks vanuit de blokattributen:

HTML
<div
  data-wp-interactive="bsui/select"
  data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
  data-bsui-select-root
>

De eerste weergave klopt HTML zonder flits tijdens client-side hydratatie, pop-ups beginnen hidden en dezelfde markup werkt in het editorcanvas, omdat de context niet afhankelijk is van een statusverwerking die alleen aan de frontend plaatsvindt.

Het gedrag wordt gekoppeld met directives, niet met uw JavaScript. De templates verbinden markup declaratief met stores. De trigger van het selectievak bestaat, zonder zijn PHP, alleen uit directives:

HTML
<button
  data-wp-interactive="bsui/select"
  data-wp-on--click="actions.toggle"
  data-wp-on--keydown="actions.handleTriggerKeyDown"
  data-wp-bind--aria-expanded="state.ariaExpanded"
  data-wp-text="state.displayValue"
  data-bsui-select-trigger
  aria-haspopup="listbox"
>

data-wp-on stuurt gebeurtenissen naar acties, data-wp-bind houdt attributen synchroon met afgeleide status, data-wp-text geeft status weer als tekst en data-wp-on-document--click zorgt ervoor dat hoofdblokken worden gesloten wanneer u erbuiten klikt. Voor het samenstellen van componenten hoeft u nooit een gebeurtenishandler te schrijven; de store wordt als inline-module met het blok meegeleverd.

Uw stores kunnen op deze koppelpunten aansluiten. Formulierbedieningselementen accepteren directive-expressies als attributen, en de namespaced syntaxis van de Interactivity-API verwijst ze naar elke store. onChange stuurt de wijzigingsafhandeling naar een van uw acties, checked koppelt de status van het bedieningselement aan uw status en bindText geeft een label weer als een data-wp-text-span die aan elk statuspad is gekoppeld:

HTML
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />

bindText is beschikbaar op items van bsui/label, bsui/checkbox, bsui/switch, bsui/toggle en bsui/radio-group. Bij checkbox-, switch- en radio-items wordt deze doorgegeven aan het gedeelde labelprimitief, zodat tekst die door de status wordt aangestuurd exact de typografie van systeemlabels behoudt. Selectievakken en andere invoervelden sturen bovendien vanaf hun hoofdblok een doorbellende gebeurtenis change uit, met de nieuwe waarde in detail, voor integraties op een hoger niveau.

Gecontroleerde waarden

Laat value of checked niet ingesteld voor een besturingselement dat zijn eigen waarde beheert. Gebruik defaultValue, defaultChecked of Toggle's defaultPressed voor de beginselectie. Een zelfstandige Toggle verwerkt invoer via muis en toetsenbord zonder consumer-store.

Als je een veld vanuit je eigen store wilt beheren, geef dan zowel de binding als een onChange-actie op die de gebonden waarde bijwerkt. value is een directive-pad, geen letterlijke standaardwaarde. Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating en Time Picker ondersteunen value. Checkbox, Switch en Toggle gebruiken in plaats daarvan checked.

Voorzie paden van de namespace waartoe ze behoren, bijvoorbeeld my/settings::context.quantity of my/settings::state.quantity. Samengestelde besturingselementen hebben hun eigen namespace; een pad zonder namespace verwijst naar dat besturingselement en niet automatisch naar de bovenliggende store. Samengestelde waardebindingen ondersteunen puntnotatiepaden naar context of state, waaronder numerieke array-sleutels, maar geen JavaScript-expressies of functieaanroepen.

Hier volgt een volledige binding voor Number Field in een aangepast blok met ingeschakelde ondersteuning voor Interactivity API:

PHP
<div
  data-wp-interactive="my/settings"
  data-wp-context='<?php echo esc_attr(wp_json_encode(['quantity' => 2])); ?>'
>
  <bs:bsui-number-field
    nameAlt="quantity"
    defaultValue="2"
    value="my/settings::context.quantity"
    onChange="my/settings::actions.setQuantity"
  />
  <output data-wp-text="context.quantity"></output>
</div>
JavaScript
import { getContext, store } from '@wordpress/interactivity';

store('my/settings', {
  actions: {
    setQuantity(event) {
      // Compound controls publish their normalized value in a custom change event.
      if (event.detail?.value !== undefined) {
        getContext().quantity = event.detail.value;
      }
    },
  },
});

Stel dezelfde standaardwaarde in voor de initiële servergerenderde waarde. Na het hydrateren worden wijzigingen in de bovenliggende waarde doorgegeven aan elke gebonden instantie, ook bij nul, false en lege waarden. Ook de verborgen formulierinvoer van Checkbox en Switch volgt hun checked-binding. Waarden voor Time Picker gebruiken HH:MM in 24-uursnotatie of een lege string. Lees bij native handlers van Input, Textarea en Password Input event.target.value; samengestelde waardevelden geven event.detail.value door. De grenzen van Number Field zijn optioneel: als min en max ontbreken, is er geen begrenzing; een expliciete nul blijft een geldige grens.

Select, Date Input, Phone Input en OTP Input geven wijzigingen door via onChange, maar bieden deze gecontroleerde value-binding niet aan. Gebruik hun gedocumenteerde standaardwaarden voor beginwaarden.

Samenstellen vanuit uw eigen blokken

Samenstellen is niet beperkt tot pagina's. Bloktags worden automatisch weergegeven in bloktemplates, zodat een projectblok rechtstreeks bsui-componenten kan genereren en deze in een eigen structuur kan opnemen:

PHP
<div useBlockProps class="settings-panel">
  <bs:bsui-switch label="Public profile" name="public" />
  <bs:bsui-space size="4" />
  <bs:bsui-button label="Save" variant="default" />
</div>

Hetzelfde werkt vanuit PHP met bs_block(), waaronder geneste samenstelling via de sleutel content, zoals beschreven onder programmatisch weergeven. In beide gevallen worden de stylesheet en store van de component mee geladen, en blijft uw blok een dunne indelingslaag rond systeemonderdelen.

Om componenten naast elkaar te plaatsen, is bsui/stack de algemene flexrij of -kolom: direction, gap op de afstandsschaal, align, justify en een wrap-schakelaar. Onderliggende elementen behouden standaard hun natuurlijke grootte; met de schakelaar grow worden ze uitgerekt zodat ze de lengte van de stapel gelijk verdelen. Zo kunnen twee knoppen in een voettekst de breedte delen in plaats van aan één kant bij elkaar te staan.

Veldgroepen en kaarten

bsui/field-group rendert een fieldset. De standaardvariant groepeert verwante velden zonder een oppervlak toe te voegen. Gebruik variant="card" voor een gedempt buitenkader en plaats de velden vervolgens in bsui/field-group-content voor een verdiept inhoudsoppervlak. Houd de titel en beschrijving buiten dit inhoudsblok:

HTML
<bs:bsui-field-group variant="card">
  <bs:bsui-field-group-title text="Account settings" />
  <bs:bsui-field-group-description text="Manage your account preferences." />
  <bs:bsui-field-group-content>
    <bs:bsui-field>
      <bs:bsui-field-label text="Display name" />
      <bs:bsui-input nameAlt="display_name" placeholder="Enter display name" />
    </bs:bsui-field>
    <bs:bsui-field>
      <bs:bsui-field-label text="Email" />
      <bs:bsui-input nameAlt="email" type="email" placeholder="Enter email" />
    </bs:bsui-field>
  </bs:bsui-field-group-content>
</bs:bsui-field-group>

disabled="true" in de groep gebruikt het native fieldset-gedrag om de formulierbesturingselementen uit te schakelen. De kaartstijl verandert de standaardvariant niet.

Scheidingstekens voor de werkbalk

Plaats bsui/toolbar-separator tussen werkbalkitems. Het volgt de orientation van de bovenliggende werkbalk: een horizontale werkbalk krijgt een verticale scheidingslijn over de volledige hoogte, en een verticale werkbalk krijgt een horizontale scheidingslijn over de volledige breedte. Scheidingslijnen lopen door tot aan de binnenranden van de werkbalkrand zonder de hoogte van bedieningselementen te veranderen. Een horizontale werkbalk kan scrollen wanneer de inhoud breder is dan de beschikbare ruimte.

Het lagenmodel

Gestapelde oppervlakken zijn vaak het punt waarop componentbibliotheken misgaan. De meegeleverde componenten volgen een kleine reeks regels voor mensen die echte UI's bouwen.

Modale vensters worden naar de body verplaatst

Wanneer een dialoogvenster, waarschuwingsdialoogvenster of lade wordt geopend, worden de pop-up en achtergrond naar document.body verplaatst, met een tijdelijke reactie die aangeeft waar ze moeten terugkeren wanneer ze worden gesloten. Door deze portaalconstructie vallen modale vensters buiten de overflow, transformaties en stapelcontext van bovenliggende elementen. Bij het openen wordt ook de paginaschuif vergrendeld: de vergrendeling wordt bijgehouden voor alle overlaycomponenten samen en compenseert de breedte van de schuifbalk, zodat de pagina niet verschuift. De achtergrond staat op z-index: 50, de pop-up op 51, de focus gaat naar de pop-up, Tab blijft erin gevangen en bij het sluiten keert de focus terug naar de trigger.

Modals worden gestapeld. Als je vanuit een dialoogvenster een ander opent, komt dat op één gedeelde stapel: alleen het buitenste dialoogvenster toont de achtergrond, en de dialoogvensters achter het bovenste worden kleiner en steken erachteruit. De stapel bepaalt een --bs-ui-nested-dialogs-custom property op elke achtergrondpopup, zodat de uitspringende afstand en schaal met elk niveau toenemen. Het bovenliggende venster past zijn hoogte aan die van het onderliggende aan, zodat de lagen gelijkmatig uitsteken. Bij het sluiten wordt alles in omgekeerde volgorde hersteld, één laag per keer.

Wanneer een modaal venster sluit, keert de focus terug naar het element dat het heeft geopend, en wel naar het juiste element. Een gedeelde helper getAnchor herkent in een trigger-wrapper de systeembutton, zodat de zichtbare bedieningselementen weer focus krijgen in plaats van een onzichtbare wrapper.

Het bovenste modale venster wordt nooit getransformeerd

Dat uitspringende effect transformeert alleen de dialoogvensters op de achtergrond. Het bovenste modale venster blijft bewust ongetransformeerd, omdat een getransformeerd element het bevattende blok wordt voor position: fixed-afstammelingen. Daardoor zouden alle zwevende popups die erin worden geopend niet meer werken.

Dit is de regel die ervoor zorgt dat het volledige lagenmodel goed samenwerkt. De zwevende lagen positioneren zichzelf allemaal met vaste coördinaten, die alleen naar de viewport verwijzen zolang er geen getransformeerde voorouder tussen zit:

  • Het menu en de combobox bepalen hun positie ten opzichte van de trigger met de strategie fixed van Floating UI. Ze verschijnen eronder en worden omgeklapt of verschoven als de viewport te weinig ruimte biedt.
  • De select doet hetzelfde als er niets is geselecteerd. Is er al een selectie, dan wordt de popup zo uitgelijnd dat de geselecteerde optie precies boven de trigger staat, begrensd door de viewport, zoals native selects zich gedragen op macOS.
  • Het contextmenu opent op de clientX/clientY-coördinaten van de aanwijzer.

Doordat het bovenste modale venster ongetransformeerd blijft, worden al deze elementen correct verankerd aan hun triggers in een dialoogvenster, waarschuwingsdialoogvenster of drawer, ongeacht de nestdiepte. De popups hoeven niet te weten dat ze in een modaal venster staan; dat hoeft ook niet.

Escape sluit eerst de binnenste laag

Eén druk op Escape sluit precies één laag, van binnen naar buiten:

  1. Een geopende zwevende laag (een select-listbox, menu, popover, datum- of telefoonpopup) sluit als eerste en geeft de focus terug aan de trigger. De select stopt de gebeurtenispropagatie. Ook houden de modalhandlers zich afzijdig zolang er een zwevende laag openstaat, zodat het onderliggende dialoogvenster die toetsaanslag niet opvangt.
  2. Vervolgens sluit het bovenste modale venster.
  3. Bij gestapelde modale vensters verwijdert elke volgende druk op Escape er nog één van de stapel.

Sluiten gebeurt volgens beleid, niet per ongeluk. Een dialoogvenster dat met dismissable="false" wordt weergegeven, negeert zowel Escape als klikken op de achtergrond. En bsui/alert-dialog reageert op Escape zoals elk modaal venster, maar negeert bewust klikken op de achtergrond: het idee van dit patroon is dat de keuze bewust moet worden gemaakt en niet per ongeluk kan worden gesloten. Klikken op de achtergrond sluit een gewoon dialoogvenster wel, omdat dismissable standaard op true staat.

Een formulier in een dialoogvenster

Dit patroon toetst alle bovenstaande regels tegelijk: een trigger opent een modaal venster, daarin staat een formulier met validatie en dat formulier bevat een zwevende select.

HTML
<bs:bsui-dialog>
  <bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
  <bs:bsui-dialog-backdrop />
  <bs:bsui-dialog-popup>
    <bs:bsui-dialog-header>
      <bs:bsui-dialog-title content="Invite a teammate" />
      <bs:bsui-dialog-description content="They receive an email with a join link." />
    </bs:bsui-dialog-header>
    <bs:bsui-dialog-content>
      <bs:bsui-form block="team/invite" successMessage="Invitation sent.">
        <bs:bsui-field name="email">
          <bs:bsui-field-label text="Email" />
          <bs:bsui-input name="email" type="email" placeholder="colleague@example.com" required="true" />
          <bs:bsui-field-error />
        </bs:bsui-field>
        <bs:bsui-field name="role">
          <bs:bsui-field-label text="Role" />
          <bs:bsui-select name="role" defaultValue="editor" placeholder="Pick a role">
            <bs:bsui-select-trigger />
            <bs:bsui-select-popup>
              <bs:bsui-select-option value="viewer" label="Viewer" />
              <bs:bsui-select-option value="editor" label="Editor" />
              <bs:bsui-select-option value="admin" label="Admin" />
            </bs:bsui-select-popup>
          </bs:bsui-select>
        </bs:bsui-field>
        <bs:bsui-space size="2" />
        <bs:bsui-button label="Send invite" />
      </bs:bsui-form>
    </bs:bsui-dialog-content>
    <bs:bsui-dialog-footer>
      <bs:bsui-dialog-close label="Cancel" />
    </bs:bsui-dialog-footer>
  </bs:bsui-dialog-popup>
</bs:bsui-dialog>

Elk tag en attribuut hierboven is essentieel: de trigger verwijst naar de systeembutton, titel en beschrijving gebruiken content, de velden bevatten de namen die het formulier serialiseert en required="true" wordt in de tagparser omgezet naar een echte boolean.

Wat elke store tijdens runtime doet

bsui/dialog zet {"open":false,"dismissable":true} op de server in de context. De klik op de trigger voert actions.open uit: de popup en achtergrond worden naar de body geportald, scrollen wordt vergrendeld met compensatie voor de scrollbar, de popup animeert in 150 ms, de focus gaat naar het eerste focusbare element en Tab blijft binnen de popup. De header-, content- en footerregio's gebruiken de tokens voor de ruimte tussen modale elementen.

bsui/select wacht in het formulier met de listbox hidden. Een klik op de trigger schakelt context.open om en positioneert de listbox met vaste viewportcoördinaten. Omdat defaultValue="editor" al is geselecteerd, wordt de popup zo uitgelijnd dat Editor precies boven de trigger staat. Pijltoetsen, Home, End en typen om te zoeken verplaatsen de actieve optie; Enter of een klik selecteert die. Tab en klikken buiten de popup sluiten deze zonder iets te selecteren. De zichtbare tekst van de trigger wordt bijgewerkt via data-wp-text="state.displayValue". Het verborgen <input name="role"> volgt de waarde via data-wp-bind--value="state.selectedValue", die het formulier later serialiseert. Dit alles wordt correct in het dialoogvenster verankerd doordat het bovenste modale venster ongetransformeerd blijft.

bsui/form onderschept het indienen. De bsui/button aan het einde van het formulier geeft een gewoon button-element weer zonder attribuut type, zodat dit standaard het verzendbesturingselement van het formulier is volgens HTML. De knop Annuleren staat in de footer, buiten het element form, en kan dus niets indienen. Bij het indienen serialiseert de store de FormData van het formulier en stuurt die via de data-API van het blok dat in block wordt genoemd. Hier maakt dat een rij aan in het schema voor de database van het blok team/invitedatabaseschema. Validatiefouten worden per veld teruggegeven: elk bsui/field bevat zijn name, wordt als ongeldig gemarkeerd, verandert de focusring naar de waarschuwingskleur en toont het bericht in de bsui/field-error-melding. Bij succes wordt de formulierinhoud verborgen en verschijnt de successMessage, beide via data-wp-bind--hidden.

De lagen worden in volgorde afgebouwd. Als de listbox openstaat, sluit Escape die en keert de focus terug naar de trigger van de select. De volgende druk op Escape sluit het dialoogvenster en zet de focus terug op Uitnodigen. Een klik op de achtergrond sluit het dialoogvenster omdat dismissable op de standaardwaarde stond. Bij het sluiten wordt scrollen weer ontgrendeld en wordt de popup teruggeplaatst in het document.

Dezelfde markup die in een pagina met bestandsstructuur wordt geplakt, wordt gesynchroniseerd als native blokken. Dezelfde compositie die in de editor wordt samengesteld, wordt interactief weergegeven op het canvas, omdat al het bovenstaande gedrag is ondergebracht in directives en stores die in beide contexten worden geladen.

Wat deze naadloze samenwerking mogelijk maakt

De naadloze samenwerking hierboven berust niet op conventies, maar op invarianten die de bibliotheek bij elke weergave handhaaft: elk label gebruikt dezelfde typografie, elke modale popup deelt één oppervlak en dimt de pagina erachter, zwevende popups blijven aan hun trigger verankerd terwijl de pagina scrolt, en Escape sluit telkens precies één laag, van binnen naar buiten. Deze garanties gelden op de frontend en op het editorcanvas, met de standaardtokens of die van je thema. Een compositie die in de ene context werkt, werkt dus ook hetzelfde in de andere.

Livevoorbeelden

De composities op deze pagina vormen de grammatica; /ui/examples is het zinnenboek. Het bevat live weergegeven composities in drie categorieën: paren die één naadloze samenwerking tussen twee of drie componenten aantonen, herkenbare productpatronen die uit enkele componenten zijn opgebouwd en complete mini-apps zoals de componenten in echte producten worden gebruikt. De pagina van elke component op /ui bevat eigen uitgewerkte voorbeelden, van een gelabeld veld tot een kalender achter een popover.

Interactiviteit

Het model met directives en stores waarop de componenten van UI zijn gebouwd, en hoe je het in je eigen blokken gebruikt.