Siirry sisältöön

Komponentit

Blockstudio toimittaa jokaisessa koontiversiossa 59 UI-komponenttia. Ne rekisteröidään automaattisesti, tyylitellään suunnittelutunnisteilla ja kirjoitetaan samalla tunnistesyntaksilla kuin muutkin lohkot.

Blockstudio 7.3 sisältää valmiina joukon headless-UI-lohkoja, jotka toimivat WordPress Interactivity API-ominaisuuden avulla. Ne rekisteröidään bsui/*-nimiavaruuteen, ja niitä voi käyttää malleissa, tiedostopohjaisilla sivuilla, kuvioissa ja artikkelien sisällössä.

Huomautus

UI-komponentit ovat beta-vaiheessa, sillä keräämme palautetta komponenttijoukosta, nimeämisestä, toiminnasta ja projektien käyttötavoista. Niitä voi kokeilla versiossa 7.3, mutta API-rajapintaa voidaan vielä hioa ennen kuin se merkitään vakaaksi.

Ota UI-komponentit käyttöön

Mukana toimitettavat UI-komponentit eivät ole oletusarvoisesti käytössä. Ota ne käyttöön teemasi tiedostossa blockstudio.json:

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

Tai ota ne käyttöön suodattimella:

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

Kun Blockstudio on otettu käyttöön, se rekisteröi mukana toimitettavan komponenttikirjaston lähteestä includes/ui/blocks.

Julkinen luettelo ja esimerkit

Mukana toimitettavat toteutuslohkot rekisteröidään tavalliseen tapaan bsui/*-lohkoina, mutta kuluttajien tulee käyttää julkista komponenttiperheiden luetteloa komponenttigalleriaa kootessaan:

PHP
use Blockstudio\Ui;

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

Ui::inventory() ryhmittelee kaikki yhdistelmäkomponentit julkisen juurielementtinsä alle ja luettelee kyseisen perheen tarvitsemat toteutusrekisteröinnit. Ui::examples() lisää deterministisen normalisoidun määrityksen, joka sisältää oletusarvot ja havainnollistavat tiedot. Se säilyttää vaaditut juuri- ja lapsielementtien suhteet, joten tuloksen voi välittää suoraan kohteelle Blockstudio\Render::document().

Julkinen Canvas-luettelo tarjoaa nämä esimerkit ui-tyypissä ja jättää mukana toimitettavat toteutusrekisteröinnit pois tavallisesta blocks-tyypistä. Näin jokaisesta julkisesta komponenttiperheestä syntyy yksi täydellinen esimerkki sisäisten juuri-, laukaisin-, ponnahdusikkuna- ja tasofragmenttien gallerian sijaan.

Kun kootaan jo renderöityä dokumenttia, Ui::global_assets($block_names, $html) palauttaa mukana toimitettavan globaalin tyylin ja komentosarjan täsmälleen vain, kun valittu tuloste todella käyttää UI-komponenttia.

Renderöinti

Käytä tavallista lohkon tagisyntaksia:

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

Myös lyhyempi <bs:>-syntaksi toimii:

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

Blockstudio-malleissa lohkojen tagit renderöityvät automaattisesti. Tiedostopohjaisilla sivuilla ja kuvioissa ne synkronoidaan natiiveiksi WordPress-lohkoiksi. Jos haluat renderöidä UI-komponentteja suoraan artikkelien sisällöstä tai vimpaimen alueilta, ota sivukohtaiset lohkotagit käyttöön:

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

Peruskomponentit

Yksinkertaiset komponentit renderöityvät yhtenä lohkona:

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>

Attribuutit yhdistyvät suoraan kunkin komponentin block.json-attribuutteihin. Esimerkiksi bsui/button tukee ominaisuuksia label, icon, iconPosition, href, variant, size ja disabled.

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

Yhdistelmäkomponentit

Monet UI-komponentit koostuvat useista lohkoista. Juurilohko hallitsee tilaa, ja lapsilohkot ilmoittavat oman ylälohkoonsa.

Välilehdet

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>

Valintaikkuna

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>

Valintaluettelo

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>

Lomakekentät

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>

Saatavilla olevat lohkot

Mukana toimitettava UI-kirjasto sisältää seuraavat lohkot:

Alue Lohkot
Asettelu bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
Toiminnot bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
Syötteet 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
Peittokerrokset bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
Navigointi bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs
Palaute bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast
Lomakkeet bsui/field, bsui/field-group, bsui/form

Yhdistelmäkomponenteissa on myös lapsilohkoja, kuten bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup ja bsui/select-option.

Tyylit

UI-komponenttien mukana toimitetaan niiden omat CSS-mukautetut ominaisuudet, jotka käyttävät --bs-ui-*-etuliitettä. Voit ohittaa niiden arvot teemassasi tiedostossa CSS:

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

Komponenttien toiminta on headless, mutta niiden oletusratkaisut tekevät niistä käyttövalmiita. Ohita ensin tokenit ja lisää sitten tarvittaessa komponenttikohtaiset CSS-määritykset.

Mukana toimitettavan komponentin CSS sisällytetään nimettyyn bsui-kaskadikerrokseen. Teeman kerrostamaton CSS voi ohittaa komponentin säännöt ilman !important-määritystä:

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

Voit lisätä mukautetun bsui/button-version lisäämällä valintavaihtoehdon olemassa olevalla attribuuttisuodattimella ja antamalla versiolle CSS-määrityksen käyttäen 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;
}';
});

Kaikki komponentit

Haitari Päällekkäin pinotut osiot, joista avautuu yksi paneeli kerrallaan. Hälytysikkuna Modaali, joka keskeyttää työnkulun ja vaatii vastauksen ennen sulkeutumista. Kuvasuhde Lukitsee sisällön kiinteään leveys-korkeussuhteeseen. avatar Käyttäjän kuva, jonka tilalla näytetään nimikirjaimet, jos lataus epäonnistuu. Ilmoitusmerkki Pieni tunniste tilaa, lukumääriä ja luokkia varten. Murupolku Näyttää nykyisen sivun sijainnin hierarkiassa. Painike Käynnistää toiminnon, ja korostustasoille on omat varianttinsa. Painikeryhmä Yhdistää toisiinsa liittyvät painikkeet yhdeksi ositetuksi ohjaimeksi. Kalenteri Päivämääräruudukko yksittäisen päivän valintaan. Kortti Pinta, joka kokoaa otsakkeen, sisällön ja alatunnisteen. Karuselli Pyyhkäistävä diojen rata, jota voi käyttää näppäimistöllä. Valintaruutu Kahden vaihtoehdon valinta, joka tukee myös määrittelemätöntä tilaa. Avattava Piilottaa ja näyttää yhden sisältöalueen. Värinvalitsin Valitsee värin ja lähettää sen ympäröivän lomakkeen mukana. Yhdistelmäkenttä Tekstikenttä, joka suodattaa vaihtoehtoluetteloa kirjoittamisen aikana. Kontekstivalikko Hiiren kakkospainikkeella avautuvat toiminnot, jotka ankkuroidaan osoittimeen. Päivämääräkenttä Maskattu kenttä päivämäärän kirjoittamiseen ilman valitsinta. Valintaikkuna Modaali tehtäville, jotka vaativat keskittymistä, ja vahvistuksille. Lokero Paneeli, joka liukuu esiin mistä tahansa näytön reunasta. Kenttä Kokoaa yhden ohjaimen ja sen tunnisteen, kuvauksen sekä virheilmoituksen. Kenttäryhmä Ryhmittelee toisiinsa liittyvät kentät yhteisen otsikon alle. Tiedoston lataus Pudotusalue ja tiedostonvalitsin, joka tukee useita tiedostoja. Lomake Lähettää kenttien tiedot ja ilmoittaa onnistumisesta lataamatta sivua uudelleen. Syöte Yksirivinen tekstikenttä kaikkiin yleisiin syöttötyyppeihin. Pikanäppäin Näyttää pikanäppäimen omassa näppäinhatussaan. Nimike Ohjaimen kuvateksti, jota kaikki tunnisteelliset komponentit käyttävät. Valikko Avattava toimintoluettelo, joka ankkuroidaan avauspainikkeeseen. Valikkopalkki Vaakasuora valikkopalkki työpöytäsovelluksen tapaan. Mittari Näyttää mitta-arvon tunnetulla vaihteluvälillä. Navigointivalikko Sivustonavigaatio sisäkkäisine linkkeineen ja osoittimen päälle avautuvine paneeleineen. Numerokenttä Numeerinen syöttökenttä askelpainikkeilla ja rajatulla vaihteluvälillä. Kertakäyttöisen salasanan syöttökenttä Erilliset ruudut kertakäyttöisen pääsykoodin syöttämiseen. Sivutus Sivulinkit: edellinen, seuraava ja väliin jätettävät sivut. Salasanakenttä Salasanakenttä, jossa on näyttökytkin. Puhelinnumerokenttä Puhelinnumerokenttä, jossa on maavalinta ja numeron muotoilu. Ponnahdusvalikko Monipuolinen sisältö avauspainikkeeseen ankkuroituna, suljetaan napsauttamalla ulkopuolelle. Esikatselukortti Osoittimen päälle avautuva kortti näyttää linkin kohteen esikatselun. Edistyminen Näyttää, kuinka pitkällä tehtävä on. Radiopainikeryhmä Vaihtoehtojoukko, josta voi valita täsmälleen yhden. Arvio Tähtiohjain arvosanan antamiseen. Vieritysalue Vierityssäilö, jossa on tyylitellyt ja sisällön päälle piirtyvät vierityspalkit. Valitse Avattava luettelo, josta valitaan vaihtoehto. Erotin Viiva, joka erottaa sisältöalueita tai ohjainryhmiä. Luuranko Paikkamerkin muoto, joka näkyy sisällön latautuessa. Liukusäädin Valitsee arvon tai vaihteluvälin vetämällä liukusäädintä. Väli Välistysasteikosta tuleva kiinteä pystysuuntainen väliaskel. Latausympyrä Ilmaisee käynnissä olevan työn, jonka kestoa ei tiedetä. Pino Asettaa lapset riviin tai sarakkeeseen tasaisin välein. Kytkin Kytkee asetuksen päälle tai pois; muutos astuu voimaan heti. Taulukko Taulukkomuotoista tietoa, jossa voi olla lajittelu ja vuorottelevat rivivärit. Välilehdet Vaihtaa samassa tilassa olevien paneelien välillä. Text Näyttää tekstin valitulla koolla ja semanttisella tunnisteella. Tekstialue Monirivinen tekstikenttä, joka kasvaa rivimäärän mukaan. Ajanvalitsin Valitsee kellonajan valitulla aikavälillä. Ilmoituksen tarjoaja Näyttää tilapäiset ilmoitukset näytön kulmassa. Vaihtokytkin Painike, joka pysyy painettuna ja ilmaisee päällä olevaa tilaa. Vaihtoryhmä Kytkinjoukko, joka toimii yhden tai usean vaihtoehdon valintana. työkalupalkki Ohjainrivi, jossa kohdistus siirtyy niiden välillä. työkaluvihje Lyhyt vihje, joka näytetään osoittimen ollessa päällä tai kohdistuksen aikana.