Hoppa till innehåll

Komponenter

Sammansättning

De paketerade UI-komponenterna är utformade för att sättas samman, inte användas en i taget. En väljare öppnas inuti en dialogruta, ett formulär valideras inuti en sidopanel och en meny placeras i en tabellrad. Den här sidan förklarar hur dessa delar samverkar: hur sammansatta komponentfamiljer är strukturerade, hur utlösare skickar vidare knappens egenskaper, vad Interactivity API gör under huven och hur lagerhanteringen håller staplade ytor sammanhängande.

Sammansatta komponentfamiljer

En sammansatt komponent består av ett rotblock och underordnade block. Roten äger tillståndet, och varje underordnat block anger sin plats i familjen genom parent och usesContext i sin block.json:

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

Rötter exponerar ett område med InnerBlocks, en lista med allowedBlocks och en inledande template, så att en dialogruta infogas med sin utlösare, bakgrund och popup i redigeraren. Familjen fungerar likadant oavsett om den sätts samman i redigeraren, på en filbaserad sida eller i taggar:

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>

Popupfönster och paneler är riktiga InnerBlocks-områden, inte platshållare med särskild syntax. En bsui/dialog-popup accepterar nästlade block på samma sätt som ett gruppblock, vilket gör det enkelt att placera ett formulär, en väljare eller en annan dialogruta inuti den.

Platta data eller sammansatta underordnade delar

Vissa familjer tar emot innehållet som data i stället för underordnade delar. Väljaren återger sin egen utlösare och listbox när du skickar in en options-array med JSON, vilket passar alternativ som kommer från 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'],
    ]),
  ],
]);

Båda formerna ger samma markupavtal och samma beteende vid körning. Använd underordnade delar när strukturen skapas manuellt och options när den beräknas.

Vidarebefordran från utlösare

Överlagringskomponenter öppnas från en knapp, och den knappen ska vara systemknappen. I stället för att varje utlösare implementerar en egen knapp bäddar utlösarblocken för bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible och bsui/tooltip in bsui/button via ett blockfält:

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

idStructure för över knappens fält till utlösaren med prefixet trigger_. Alla knappens egenskaper är tillgängliga: 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" />

I utlösarens mall är $a['trigger'] den fullständigt återgivna knappen, så knappens stilmall och framtida förbättringar följer med. Vid körning skickar en gemensam hjälpfunktion omslagets ARIA-kopplingar (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) vidare till den inre knappen och håller den synkroniserad via en MutationObserver, så hjälpmedel ser en enhetlig kontroll.

Interactivity API under huven

Varje interaktiv familj är en WordPress Interactivity API-lagring som har fått namn efter sitt rotblock: bsui/dialog, bsui/select, bsui/form, bsui/tabs och så vidare. Det får tre följder.

Tillståndet initieras på serversidan. Rotmallen skriver ut sitt ursprungliga tillstånd som data-wp-context, direkt från blockets attribut:

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

Den första återgivningen är korrekt HTML utan en synlig återfuktning från klientsidan, popupfönster börjar som hidden och samma markup fungerar på redigerarens arbetsyta eftersom kontexten inte är beroende av ett tillståndssteg som bara körs på frontend.

Beteendet kopplas med direktiv, inte med din JavaScript. Mallarna kopplar deklarativt markup till lagringar. Väljarens utlösare, utan sin PHP, består enbart av direktiv:

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 skickar händelser till åtgärder, data-wp-bind håller attribut synkroniserade med härlett tillstånd, data-wp-text återger tillstånd som text och data-wp-on-document--click låter rötter stängas när ett klick sker utanför. När du sätter samman komponenter behöver du aldrig skriva en händelsehanterare; lagringen följer med blocket som en inbäddad modul.

Dina lagringar kan kopplas in i komponenternas skarvar. Formulärkontroller accepterar direktivuttryck som attribut, och Interactivity APIs namnområdessyntax kopplar dem till valfri lagring. onChange skickar ändringshanteringen till en av dina åtgärder, checked kopplar kontrollens tillstånd till ditt tillstånd och bindText återger en etikett som ett data-wp-text-element kopplat till valfri tillståndssökväg:

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 är tillgängligt för objekten bsui/label, bsui/checkbox, bsui/switch, bsui/toggle och bsui/radio-group. För kryssrutor, växlingsknappar och alternativknappar förs det vidare till den gemensamma etikettprimitiven, så att text som styrs av tillståndet använder exakt samma typografi som systemets etiketter. Väljare och andra inmatningsfält skickar dessutom en bubblande change-händelse från roten, med det nya värdet i detail, för grövre integreringar.

Styrda värden

Lämna value eller checked utan värde för ett reglage som hanterar sitt eget värde. Använd defaultValue, defaultChecked eller Toggles defaultPressed för dess initiala val. En fristående Toggle hanterar pekar- och tangentbordsinmatning utan en konsumentlagring.

Om du vill styra ett fält från din egen lagring anger du både dess bindning och en åtgärd onChange som uppdaterar det bundna värdet. value är en direktivväg, inte ett bokstavligt standardvärde. Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating och Time Picker stöder value. Checkbox, Switch och Toggle använder i stället checked.

Kvalificera sökvägar med det ägande namnområdet, till exempel my/settings::context.quantity eller my/settings::state.quantity. Sammansatta reglage har ett eget namnområde; en okvalificerad sökväg syftar på reglaget, inte automatiskt på den överordnade lagringen. Sammansatta värdebindningar stöder punktnotation för sökvägar in i kontext eller tillstånd, inklusive numeriska arraynycklar, men inte JavaScript uttryck eller funktionsanrop.

Här är en fullständig bindning för Number Field i ett anpassat block med stöd för Interactivity API aktiverat:

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

Ange motsvarande standardvärde för det initiala värdet som renderas på servern. När värdena har hydratiserats uppdaterar ändringar i den överordnade komponenten varje bunden instans, även med värdena noll, falskt och tomt. Checkbox och Switch dolda formulärfält följer också sin bindning checked. Time Picker-värden använder HH:MM i 24-timmarsformat eller en tom sträng. För hanterare för inbyggda Input, Textarea och Password Input läser du event.target.value; sammansatta värdereglage skickar event.detail.value. Gränser för Number Field är valfria: om min och max utelämnas saknar fältet gränser, medan en uttrycklig nolla fortfarande är en giltig gräns.

Select, Date Input, Phone Input och OTP Input skickar ändringar via onChange, men har inte den här styrda bindningen för value. Använd deras dokumenterade standardegenskaper för initiala värden.

Sammansättning från egna block

Sammansättning är inte begränsad till sidor. Blocktaggar återges automatiskt inuti blockmallar, så ett projektblock kan skriva ut bsui-komponenter direkt och omsluta dem i sin egen struktur:

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>

Samma sak fungerar med PHP och bs_block(), även med nästling via nyckeln content, enligt beskrivningen under programmatisk återgivning. Oavsett metod laddas komponentens stilmall och lagring med den, och ditt block förblir ett tunt lager som ordnar systemdelarna.

För att placera komponenter sida vid sida är bsui/stack den generiska flexraden eller -kolumnen: direction, gap på avståndsskalan, align, justify och en wrap-växling. Underordnade element behåller sin naturliga storlek som standard. Växlingen grow sträcker ut dem så att de delar stapelns längd lika, vilket gör att en sidfot kan låta två knappar dela på bredden i stället för att klumpa ihop sig vid ena kanten.

Fältgrupper och kort

bsui/field-group renderar en fältgrupp. Standardvarianten grupperar relaterade fält utan att lägga till en yta. Använd variant="card" för en nedtonad yttre ram och placera sedan fält inuti bsui/field-group-content för att få en infälld yta för innehållet. Håll rubriken och beskrivningen utanför det här innehållsblocket:

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" i gruppen använder det inbyggda fieldset-beteendet för att inaktivera dess formulärkontroller. Kortets utformning ändrar inte standardvarianten.

Verktygsfältsavgränsare

Placera bsui/toolbar-separator mellan objekt i verktygsfältet. Den följer den överordnade verktygsfältets orientation: ett horisontellt verktygsfält får en lodrät avgränsare i full höjd, och ett lodrätt verktygsfält får en vågrät avgränsare i full bredd. Avgränsarna sträcker sig till verktygsfältets kant på insidan utan att ändra kontrollernas höjd. Ett horisontellt verktygsfält rullar när innehållet överskrider den tillgängliga bredden.

Lagerhanteringsmodellen

Det är ofta staplade ytor som får komponentbibliotek att fallera. De paketerade komponenterna följer en liten uppsättning regler för dig som bygger riktiga gränssnitt.

Modaler flyttas till dokumentkroppen

När en dialogruta, en varningsdialogruta eller en sidopanel öppnas flyttas popupfönstret och bakgrunden till document.body, med en platshållarkommentar som markerar vägen tillbaka när den stängs. Genom att flytta ut modalen slipper den begränsningarna från överordnade elements overflow, transformering eller staplingskontext. När den öppnas låses även sidans rullning: låset räknas gemensamt för alla överlagringskomponenter och kompenserar för rullningslistens bredd så att sidan inte förskjuts. Bakgrunden placeras på z-index: 50, popupfönstret på 51, fokus flyttas in i popupfönstret, Tab låses där och när det stängs återgår fokus till utlösaren.

Modala dialoger staplas. När en dialog öppnas inifrån en annan läggs den till i en gemensam stack: endast den yttersta dialogen visar sin bakgrund, och dialogerna bakom den översta skalas ned och skymtar fram bakom den. Stacken styr en --bs-ui-nested-dialogs-egenskap på varje popup i bakgrunden, så förskjutningen och skalningen ökar för varje nivå, och den överordnade dialogen anpassar sin höjd efter den underordnade så att lagren skymtar jämnt. När dialogerna stängs återställs allt i omvänd ordning, ett lager i taget.

När en modal stängs återgår fokus till dess utlösare, och det hamnar på rätt element. En gemensam hjälpfunktion getAnchor löser upp en utlösares omslag till systemknappen inuti det, så att det synliga reglaget återfår fokus i stället för ett osynligt omslag.

Den översta modalen transformeras aldrig

Den här skymtande effekten transformerar bara dialogerna i bakgrunden. Den översta modalen förblir medvetet otransformerad, eftersom ett transformerat element blir den innehållande blockbehållaren för position: fixed-underordnade element, vilket skulle göra att alla flytande popup-fönster som öppnas inuti den slutar fungera.

Det här är regeln som gör att hela lagerstrukturen fungerar tillsammans. De flytande lagren positionerar sig alla med fasta koordinater, som bara avser visningsområdet så länge ingen transformerad förfader ligger emellan:

  • Menyn och kombinationsrutan beräknar sin position i förhållande till utlösaren med strategin UI för Floating fixed. De placeras under den och vänds eller förskjuts när visningsområdet inte räcker till.
  • Select-komponenten gör samma sak när inget är valt. När det redan finns ett val justeras popup-fönstret i stället så att det valda alternativet hamnar precis ovanför utlösaren, begränsat till visningsområdet, på samma sätt som inbyggda select-element fungerar på macOS.
  • Kontextmenyn öppnas vid pekarens clientX/clientY.

Eftersom den översta modalen är otransformerad förankras alla dessa element korrekt vid sina utlösare inuti en dialog, en varningsdialog eller en sidopanel, oavsett nästlingsdjup. Popup-fönstren behöver inte veta att de befinner sig i en modal, och det behövs inte heller.

Escape stänger det innersta lagret först

Ett tryck på Escape stänger exakt ett lager, inifrån och ut:

  1. Ett öppet flytande lager (en listbox för select, en meny, en popover, en datum- eller telefonpopup) stängs först och fokus återgår till dess utlösare. Select-komponenten stoppar händelsens spridning, och modalernas händelsehanterare avvaktar dessutom när ett flytande lager är öppet, så dialogen under det märker aldrig det trycket.
  2. Den översta modalen stängs härnäst.
  3. Med staplade modaler tar varje ytterligare tryck på Escape bort ytterligare ett lager från stacken.

Avstängning styrs av en policy, inte av en slump. En dialog som renderas med dismissable="false" ignorerar både Escape och klick på bakgrunden. Och bsui/alert-dialog hanterar Escape som vilken modal som helst men ignorerar medvetet klick på bakgrunden: poängen med mönstret är att valet måste göras, i stället för att dialogen avfärdas av misstag. Klick på bakgrunden stänger en vanlig dialog, eftersom dismissable som standard är true.

Ett formulär i en dialog

Mönstret som tillämpar alla regler ovan samtidigt: en utlösare öppnar en modal, modalen innehåller ett formulär med validering, och formuläret innehåller en flytande select-komponent.

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>

Varje tagg och attribut ovan fyller en viktig funktion: utlösaren vidarebefordrar till systemknappen, titeln och beskrivningen får content, fälten har de namn som formuläret serialiserar, och required="true" omvandlas till ett riktigt booleskt värde i taggparsern.

Vad varje store gör vid körning

bsui/dialog lägger in {"open":false,"dismissable":true} i kontexten på servern. När utlösaren klickas körs actions.open: popup-fönstret och bakgrunden portalas till body, rullningen låses med kompensation för rullningslisten, popup-fönstret animeras in under 150 ms, fokus flyttas till det första fokuserbara elementet och Tab cirkulerar inom det. Sidhuvudet, innehållet och sidfoten får mellanrum med modalens avståndstoken.

bsui/select väntar inne i formuläret med sin listbox hidden. När utlösaren klickas ändras context.open, listboxen positioneras med fasta koordinater i visningsområdet, och eftersom defaultValue="editor" redan är valt justeras popup-fönstret så att Editor hamnar precis ovanför utlösaren. Piltangenterna, Home, End och tangentbordssökning flyttar det aktiva alternativet; Enter eller ett klick väljer det; Tab och klick utanför stänger utan att välja. Utlösarens synliga text uppdateras via data-wp-text="state.displayValue", och det dolda <input name="role"> håller reda på värdet via data-wp-bind--value="state.selectedValue", som formuläret senare serialiserar. Allt detta förankras korrekt inuti dialogen eftersom den översta modalen är otransformerad.

bsui/form fångar upp formulärets inskickning. bsui/button i slutet av formuläret återger ett vanligt button-element utan attributet type, så det fungerar som formulärets skickaknapp enligt standarden för HTML; knappen Avbryt finns i sidfoten utanför elementet form och kan inte skicka något. När formuläret skickas serialiserar lagret formulärets FormData och skickar det via data-API för blocket som anges i block. Här skapas en rad i blockets team/invite databasschema. Valideringsfel returneras per fält: varje bsui/field får sitt name, markeras som ogiltigt, fokusringen får den destruktiva färgen och meddelandet visas i dess bsui/field-error-avisering. När det lyckas döljs formulärets innehåll och successMessage visas, båda via data-wp-bind--hidden.

Lagren stängs i tur och ordning. När listboxen är öppen stänger Escape listboxen och flyttar tillbaka fokus till select-utlösaren; nästa tryck på Escape stänger dialogen och flyttar tillbaka fokus till Invite teammate. Ett klick på bakgrunden stänger dialogen eftersom dismissable lämnades på standardvärdet. När dialogen stängs låses rullningen upp och popup-fönstret flyttas tillbaka till sin plats i dokumentet.

Samma markup som klistras in på en filbaserad sida synkroniseras som inbyggda block, och samma komposition som sätts ihop i redigeraren förhandsvisas interaktivt i arbetsytan, eftersom allt beteende ovan styrs av direktiv och stores som laddas i båda sammanhangen.

Det här håller gränssnitten fungerande

Gränssnitten ovan är inte konventioner, utan invarianta egenskaper som biblioteket upprätthåller överallt där det renderar: varje etikett motsvarar en och samma typografi, alla modala popup-fönster delar samma yta och tonar ned sidan bakom sig, flytande popup-fönster förblir förankrade vid utlösaren medan sidan rullas, och Escape stänger exakt ett lager åt gången, inifrån och ut. Garantierna gäller både i frontend och på redigerarens arbetsyta, med standardtoken eller ditt temas token. Därför fungerar en komposition som beter sig på ett visst sätt i ett sammanhang likadant i de andra.

Liveexempel

Kompositionerna på den här sidan är grammatiken; /ui/examples är parlören. Den samlar renderade kompositioner i tre nivåer: par som visar hur två eller tre komponenter fungerar tillsammans, välbekanta produktmönster som byggs av några få komponenter och kompletta miniappar sammansatta så som komponenterna levereras i riktiga produkter. Varje komponentsida på /ui innehåller egna genomarbetade exempel, från ett märkt fält till en kalender bakom en popover.

Interaktivitet

Direktivet och store modellerar grunden för komponenterna UI och visar hur du använder den i dina egna block.