Gå til indhold

Komponenter

Sammensætning

De medfølgende UI-komponenter er designet til at blive sat sammen, ikke brugt én ad gangen. En vælger åbner i en dialogboks, en formular valideres i et sidepanel, og en menu vises i en tabelrække. Denne side forklarer mekanikken, der får delene til at fungere sammen: hvordan sammensatte komponentfamilier er struktureret, hvordan udløsere videresender knapegenskaber, hvad Interactivity API gør i baggrunden, og hvilken lagdelingsmodel der får stablede flader til at hænge sammen.

Sammensatte komponentfamilier

En sammensat komponent består af en rodblok og underordnede blokke. Roden ejer tilstanden; hvert barn angiver sin plads i familien via parent og usesContext i sin block.json:

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

Rødder viser et område for InnerBlocks med en liste over allowedBlocks og en start-template, så når du indsætter en dialogboks i editoren, oprettes dens udløser, baggrund og popup automatisk, og familien fungerer ens, uanset om den sammensættes i editoren, på en filbaseret side eller i 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>

Popups og paneler er rigtige InnerBlocks-områder, ikke slots med særlig syntaks. En bsui/dialog-popup accepterer indlejrede blokke på samme måde som en gruppeblok, så det er helt almindeligt at placere en formular, en vælger eller en anden dialogboks i den.

Flade data eller sammensatte underordnede elementer

Nogle familier modtager indholdet som data i stedet for underordnede elementer. Vælgeren opretter sin egen udløser og listeboks, når du giver den en options JSON-liste, hvilket passer til valgmuligheder fra 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'],
    ]),
  ],
]);

Begge former giver samme markup-kontrakt og samme funktionsmåde ved kørsel. Brug underordnede elementer, når strukturen er skrevet direkte, og options, når den beregnes.

Videresendelse af udløser

Overlejringskomponenter åbnes med en knap, og den knap bør være systemknappen. I stedet for at hver udløser genimplementerer den, indlejrer udløserblokkene i bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible og bsui/tooltip bsui/button via et blokfelt:

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

idStructure udfolder knappens felter på udløseren med præfikset trigger_. Alle knappens egenskaber er tilgængelige: 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 udløserens skabelon er $a['trigger'] den fuldt gengivne knap, så knappens typografiark og fremtidige forbedringer følger med. Ved kørsel videresender en fælles hjælpefunktion wrapperens ARIA-koblinger (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) til den indre knap og holder dem synkroniseret via en MutationObserver, så hjælpeteknologi ser én sammenhængende kontrol.

Interactivity API i baggrunden

Hver interaktiv familie er et WordPress Interactivity API-lager med navn efter sin rodblok: bsui/dialog, bsui/select, bsui/form, bsui/tabs osv. Det har tre konsekvenser.

Tilstanden etableres på serversiden. Rodens skabelon udskriver sin indledende tilstand som data-wp-context direkte fra blokkens attributter:

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

Første visning er korrekt HTML uden et glimt af hydrering på klientsiden, popups starter hidden, og den samme markup fungerer i editorens lærred, fordi konteksten ikke afhænger af en tilstandspassage, der kun kører på frontend.

Adfærden forbindes med direktiver, ikke med din JavaScript. Skabelonerne forbinder markup med lagre på en deklarativ måde. Vælgerens udløser uden sin PHP består udelukkende af direktiver:

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 sender hændelser videre til handlinger, data-wp-bind holder attributter synkroniseret med afledt tilstand, data-wp-text gengiver tilstand som tekst, og data-wp-on-document--click giver rødder mulighed for at lukke ved klik udenfor. Du behøver aldrig skrive en hændelseshåndtering for at sammensætte komponenter; lageret følger med blokken som et indlejret modul.

Dine lagre kan tilsluttes ved forbindelsespunkterne. Formularfelter accepterer direktivudtryk som attributter, og den navneområdeforsynede syntaks i Interactivity API peger dem mod ethvert lager. onChange sender ændringshåndteringen videre til en af dine handlinger, checked knytter feltets tilstand til din tilstand, og bindText gengiver en etiket som et data-wp-text-span-element knyttet til en vilkårlig tilstandssti:

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 er tilgængelig på elementerne bsui/label, bsui/checkbox, bsui/switch, bsui/toggle og bsui/radio-group. På afkrydsningsfelter, omskiftere og radioknapper føres den videre til det fælles primitiv for etiketter, så tilstandsbaseret tekst bevarer systemets nøjagtige etikette typografi. Vælgere og andre inputfelter udsender desuden en boblende change-hændelse fra deres rod med den nye værdi i detail til grovere integrationer.

Kontrollerede værdier

Lad value eller checked være udefineret for en kontrol, der administrerer sin egen værdi. Brug defaultValue, defaultChecked eller Toggle's defaultPressed til dens indledende valg. En selvstændig Toggle håndterer input fra mus og tastatur uden et forbrugerlager.

Hvis du vil styre et felt fra dit eget lager, skal du angive både dets binding og en onChange-handling, der opdaterer den bundne værdi. value er en direktivsti, ikke en bogstavelig standardværdi. Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating og Time Picker understøtter value. Checkbox, Switch og Toggle bruger i stedet checked.

Kvalificér stier med det tilhørende navnerum, for eksempel my/settings::context.quantity eller my/settings::state.quantity. Sammensatte kontroller har deres eget navnerum; en ukvalificeret sti henviser til den kontrol, ikke automatisk til dit overordnede lager. Sammensatte værdibindinger understøtter punktstier ind i kontekst eller tilstand, herunder numeriske arraynøgler, men ikke JavaScript-udtryk eller funktionskald.

Her er en komplet binding for Number Field i en brugerdefineret blok med understøttelse af Interactivity API aktiveret:

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

Angiv den tilsvarende standardværdi for den indledende værdi, der gengives på serveren. Når overordnet indhold er hydreret, opdateres alle bundne instanser ved ændringer, også med værdierne nul, falsk og tom. Skjulte formularinput i Checkbox og Switch følger også deres checked-binding. Time Picker-værdier bruger HH:MM i 24-timersformat eller en tom streng. For indbyggede handlere i Input, Textarea og Password Input skal du læse event.target.value; sammensatte værdikontroller udsender event.detail.value. Grænser for Number Field er valgfrie: Hvis min og max udelades, har feltet ingen grænser, mens et eksplicit nul stadig er en gyldig grænse.

Select, Date Input, Phone Input og OTP Input udsender ændringer via onChange, men viser ikke denne kontrollerede binding for value. Brug deres dokumenterede standardegenskaber til indledende værdier.

Sammensætning fra dine egne blokke

Sammensætning er ikke begrænset til sider. Bloktags gengives automatisk i blokskabeloner, så en projektblok kan udskrive bsui-komponenter direkte og omslutte 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>

Det samme fungerer fra PHP med bs_block(), også med indlejring via nøglen content, som beskrevet under programmatisk gengivelse. Uanset fremgangsmåden indlæses komponentens typografiark og lager sammen med den, og din blok forbliver et tyndt lag, der arrangerer systemets dele.

Når komponenter skal arrangeres side om side, er bsui/stack den generiske flexrække eller -kolonne: direction, gap på afstandsskalaen, align, justify og en wrap-omskifter. Som standard bevarer underordnede elementer deres naturlige størrelse; grow-omskifteren strækker dem, så de deler stakkens længde ligeligt. Sådan får en sidefod to knapper til at dele dens bredde i stedet for at samle sig i den ene ende.

Feltgrupper og kort

bsui/field-group gengiver et fieldset. Standardvarianten grupperer relaterede felter uden at tilføje en overflade. Brug variant="card" til en dæmpet ydre ramme, og placér derefter felter i bsui/field-group-content for at få en indrykket indholdsoverflade. Hold titlen og beskrivelsen uden for denne indholdsblok:

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" på gruppen bruger den indbyggede fieldset-adfærd til at deaktivere dens formularkontroller. Kortformatering ændrer ikke standardvarianten.

Adskillere i værktøjslinjen

Placér bsui/toolbar-separator mellem elementer i værktøjslinjen. Den følger den overordnede værktøjslinjes orientation: En vandret værktøjslinje får en lodret adskiller i fuld højde, og en lodret værktøjslinje får en vandret adskiller i fuld bredde. Adskillerne strækker sig til værktøjslinjens indvendige kanter uden at ændre kontrolhøjden. En vandret værktøjslinje ruller, når indholdet overskrider den tilgængelige bredde.

Lagdelingsmodellen

Det er ofte i stablede flader, at komponentbiblioteker begynder at falde fra hinanden. De medfølgende komponenter følger et lille sæt regler, som er skrevet til folk, der bygger rigtige UI'er.

Modaler flyttes til body

Når en dialogboks, alarmdialogboks eller et sidepanel åbnes, flyttes dets popup og baggrund til document.body, og en pladsholderkommentar markerer, hvor det skal tilbage, når det lukkes. Flytningen frigør modalen fra enhver forfæders overflow, transformering eller stablingskontekst. Åbning låser også sidescrollning: Låsen tælles på tværs af alle overlejringskomponenter, og scrollbarens bredde kompenseres, så siden ikke flytter sig. Baggrunden ligger på z-index: 50, popuppen på 51, fokus flyttes ind i popuppen, Tab holdes indenfor, og når den lukkes, flyttes fokus tilbage til udløseren.

Modaler stables. Når en dialog åbnes inde i en anden dialog, lægges den på én fælles stak: Kun den yderste dialog viser sin baggrund, og dialogerne bag den øverste skaleres ned og titter frem bag den. Stakken styrer en --bs-ui-nested-dialogs-brugerdefineret egenskab på hver bagvedliggende popup, så forskydningen og skaleringen bliver større for hvert niveau, og forælderen tilpasser sin højde til barnet, så lagene titter lige meget frem. Når dialogerne lukkes, gendannes alt i omvendt rækkefølge, ét lag ad gangen.

Når en modal lukkes, føres fokus tilbage til dens udløser og det rigtige element. En fælles hjælper, getAnchor, finder systemknappen inde i en udløser-wrapper, så det synlige kontrolfelt får fokus igen i stedet for en usynlig wrapper.

Den øverste modal transformeres aldrig

Denne effekt, hvor lagene titter frem, transformerer kun dialogerne i baggrunden. Den øverste modal forbliver bevidst utransformeret, fordi et transformeret element bliver den indeholdende blok for position: fixed-descendants, hvilket ville ødelægge alle flydende popups, der åbnes inde i den.

Det er denne regel, der får hele lagmodellen til at fungere sammen. De flydende lag positionerer sig alle med faste koordinater, som kun er i forhold til viewporten, så længe ingen transformeret forfader griber ind:

  • Menuen og kombinationsfeltet beregner deres position i forhold til udløseren med Floating UIs fixed-strategi, placerer sig under den og vender eller forskydes, når der ikke er plads i viewporten.
  • Det gør vælgeren også, når intet er valgt. Hvis der allerede er valgt noget, justerer den i stedet sin popup, så den valgte mulighed ligger direkte over udløseren, afgrænset til viewporten, ligesom indbyggede vælgere på macOS.
  • Kontekstmenuen åbnes ved markørens clientX/clientY.

Fordi den øverste modal er utransformeret, forankres alt dette korrekt til sine udløsere inde i en dialog, en alarmdialog eller en skuffe, uanset indlejringsdybde. Popupperne behøver ikke vide, at de er inde i en modal, og det er heller ikke nødvendigt.

Escape lukker det inderste lag først

Ét tryk på Escape lukker præcis ét lag, indefra og ud:

  1. Et åbent flydende lag (en vælgerliste, en menu, en popover, en dato- eller telefonpopup) lukkes først, og fokus føres tilbage til udløseren. Vælgeren stopper hændelsens viderespredning, og modalens hændelseshåndteringer træder også tilbage, når et flydende lag er åbent, så dialogen nedenunder aldrig registrerer det tryk.
  2. Den øverste modal lukkes derefter.
  3. Hvis der er flere modaler, fjerner hvert efterfølgende tryk på Escape endnu en fra stakken.

Lukning er en politik, ikke et tilfælde. En dialog, der gengives med dismissable="false", ignorerer både Escape og klik på baggrunden. Og bsui/alert-dialog reagerer på Escape som enhver anden modal, men ignorerer bevidst klik på baggrunden: Formålet med mønstret er, at valget skal træffes bevidst, så dialogen ikke lukkes ved et uheld. Klik på baggrunden lukker en almindelig dialog, da dismissable som standard er true.

En formular i en dialog

Mønstret, der afprøver alle reglerne ovenfor på én gang: En udløser åbner en modal, modalen indeholder en formular med validering, og formularen indeholder en flydende vælger.

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>

Hvert tag og hver attribut ovenfor er afgørende: Udløseren videresender til systemknappen, titlen og beskrivelsen får content, felterne har de navne, som formularen serialiserer, og required="true" konverteres til en rigtig boolean i tagparseren.

Hvad hver store gør under kørsel

bsui/dialog lægger {"open":false,"dismissable":true} i konteksten på serveren. Udløserens klik kører actions.open: Popup'en og baggrunden portaleres til body, scroll låses med kompensation for scrollbar, popup'en animeres ind over 150ms, fokus flyttes til det første fokuserbare element, og Tab gennemløber elementerne i den. Områderne til sidehoved, indhold og sidefod placerer sig med modalens afstandstokens.

bsui/select venter inde i formularen med sin listeboks hidden. Når der klikkes på udløseren, skifter context.open, og listeboksen placeres med faste koordinater i viewporten. Da defaultValue="editor" allerede er valgt, justeres popup'en, så Editor ligger direkte over udløseren. Piletasterne, Home, End og indtastning flytter den aktive mulighed; Enter eller et klik vælger en mulighed; Tab og klik udenfor lukker uden at vælge. Udløserens synlige tekst opdateres gennem data-wp-text="state.displayValue", og det skjulte <input name="role"> følger værdien gennem data-wp-bind--value="state.selectedValue", som formularen senere serialiserer. Alt dette forankres korrekt inde i dialogen, fordi den øverste modal er utransformeret.

bsui/form opfanger indsendelsen. bsui/button til sidst i formularen gengiver et almindeligt button-element uden attributten type, så det er formularens indsendelseskontrol som standard ifølge HTML; knappen Annuller ligger i sidefoden uden for elementet form og kan ikke indsende noget. Ved indsendelse serialiserer store formularens FormData og sender dem gennem dataenes API for blokken, der er navngivet i block. Her oprettes en række i team/invite-blokkens databaseskema. Valideringsfejl returneres for hvert felt: Hvert bsui/field får sit name, markeres som ugyldigt, fokusrammen skifter til advarselsfarven, og meddelelsen vises i dets bsui/field-error-alarm. Når det lykkes, skjules formularens indhold, og successMessage vises, begge dele gennem data-wp-bind--hidden.

Lagene lukkes i rækkefølge. Når listeboksen er åben, lukker Escape listeboksen og flytter fokus tilbage til vælgerens udløser; næste tryk på Escape lukker dialogen og flytter fokus tilbage til Inviter teammedlem. Et klik på baggrunden lukker dialogen, fordi dismissable beholdt sin standardværdi. Når dialogen lukkes, låses scroll op, og popup'en flyttes tilbage til sin plads i dokumentet.

Den samme markup indsat på en filbaseret side synkroniseres som indbyggede blokke, og den samme sammensætning, der bygges i editoren, kan forhåndsvises interaktivt på lærredet, fordi al adfærden ovenfor ligger i direktiver og stores, der indlæses i begge sammenhænge.

Det, der får disse grænseflader til at fungere

Grænsefladerne ovenfor er ikke konventioner, men invariants, som biblioteket opretholder, uanset hvor det gengiver: Alle etiketter bruger den samme typografi, alle modale popupper deler den samme overflade og dæmper siden bagved, flydende popupper bevarer deres forankring til udløseren, mens siden ruller, og Escape lukker præcis ét lag ad gangen, indefra og ud. Garantierne gælder både på frontend og på editorens lærred, med standardtokens og dit temas tokens, så en sammensætning, der fungerer i én sammenhæng, fungerer på samme måde i de andre.

Liveeksempler

Sammensætningerne på denne side er grammatikken; /ui/examples er parløren. Den samler levende, gengivne sammensætninger i tre niveauer: par, der demonstrerer én grænseflade mellem to eller tre komponenter, genkendelige produktmønstre bygget af en håndfuld komponenter og komplette miniapps sammensat, som komponenterne leveres i rigtige produkter. Hver komponentside på /ui tilføjer sine egne gennemarbejdede eksempler, fra et mærket felt til en kalender bag en popover.

Interaktivitet

Direktivet og store-modellen, som UI-komponenterne bygger på, og hvordan du bruger den i dine egne blokke.