Vai al contenuto

Componenti

Blockstudio include 59 UI componenti a ogni build. Vengono registrati automaticamente, stilizzati con token di design e creati con la stessa sintassi dei tag di qualsiasi altro blocco.

Blockstudio 7.3 include una raccolta di blocchi UI senza interfaccia predefinita, basati su WordPress Interactivity API. Sono registrati nello spazio dei nomi bsui/* e possono essere composti nei template, nelle pagine basate su file, nei pattern e nei contenuti degli articoli.

Nota

I componenti UI sono in beta mentre raccogliamo commenti sulla raccolta, sui nomi, sul comportamento e sugli schemi d'uso nei progetti. Potete provarli nella versione 7.3, ma la superficie API potrebbe ancora essere perfezionata prima di essere dichiarata stabile.

Attivare i componenti UI

I componenti UI inclusi sono facoltativi. Attivateli nel file blockstudio.json del tema:

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

Oppure attivateli con un filtro:

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

Una volta attivati, Blockstudio registra la libreria di componenti inclusa da includes/ui/blocks.

Inventario pubblico ed esempi

I blocchi di implementazione inclusi restano normali registrazioni bsui/*, ma per creare una raccolta di componenti, chi li usa dovrebbe consultare l'inventario pubblico delle famiglie:

PHP
use Blockstudio\Ui;

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

Ui::inventory() raggruppa ogni componente composto sotto la propria radice pubblica e elenca le registrazioni di implementazione richieste dalla relativa famiglia. Ui::examples() aggiunge una dichiarazione normalizzata deterministica con dati predefiniti e illustrativi. Mantiene le relazioni richieste tra radice e figli, così il risultato può essere passato direttamente a Blockstudio\Render::document().

L'inventario Canvas pubblico espone questi esempi con il tipo ui e omettere le registrazioni di implementazione incluse dal normale tipo blocks. In questo modo si ottiene un esempio completo per ogni famiglia di componenti pubblica, invece di una raccolta di frammenti interni di radice, trigger, popup e livelli.

Quando si assembla un documento già visualizzato, Ui::global_assets($block_names, $html) restituisce gli esatti stili globali e script inclusi solo se l'output selezionato usa effettivamente un componente UI.

Rendering

Usate la normale sintassi dei tag dei blocchi:

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

Funziona anche la sintassi abbreviata <bs:>:

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

Nei template Blockstudio, i tag dei blocchi vengono visualizzati automaticamente. Nelle pagine basate su file e nei pattern, vengono sincronizzati come blocchi WordPress nativi. Per visualizzare i componenti UI direttamente nei contenuti degli articoli o nelle aree widget, attivate i tag dei blocchi a livello di pagina:

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

Componenti di base

I componenti semplici vengono visualizzati come un singolo blocco:

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>

Gli attributi corrispondono direttamente agli attributi block.json di ciascun componente. Per esempio, bsui/button supporta label, icon, iconPosition, href, variant, size e disabled.

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

Componenti composti

Molti componenti UI sono composti da più blocchi. Il blocco radice gestisce lo stato, mentre i blocchi figli dichiarano il rispettivo elemento padre.

Schede

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>

Finestra di dialogo

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>

Selettore

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>

Campi del modulo

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>

Blocchi disponibili

La libreria UI inclusa comprende:

Area Blocchi
Layout bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
Azioni bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
Input 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
Sovrapposizioni bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
Navigazione 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
Moduli bsui/field, bsui/field-group, bsui/form

I componenti composti espongono anche blocchi figli come bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup e bsui/select-option.

Stili

I componenti UI includono proprietà personalizzate CSS con il prefisso --bs-ui-*. Potete sovrascriverle dal file CSS del tema:

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

I componenti non impongono uno stile comportamentale, ma offrono indicazioni sufficienti per essere usabili fin da subito. Sovrascrivete prima i token, poi aggiungete le regole CSS specifiche del componente dove necessario.

I componenti CSS inclusi vengono generati nel livello nominato bsui della cascata. Le regole CSS del tema non inserite in un livello possono sovrascrivere quelle dei componenti senza !important:

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

Per aggiungere una variante bsui/button personalizzata, aggiungete l'opzione del selettore usando il filtro degli attributi esistente e fornite il CSS della variante con 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;
}';
});

Tutti i componenti

Fisarmonica Sezioni sovrapposte che espandono un pannello alla volta. Finestra di dialogo di avviso Una finestra modale che interrompe il flusso e richiede una risposta prima di chiudersi. Proporzioni Vincola il contenuto a un rapporto fisso tra larghezza e altezza. Avatar Un'immagine utente che, se non si carica, viene sostituita dalle iniziali. Badge Una piccola etichetta per stati, conteggi e categorie. Percorso di navigazione Mostra la posizione della pagina corrente nella gerarchia. Pulsante Avvia un'azione, con varianti per ogni livello di enfasi. Gruppo di pulsanti Raggruppa pulsanti correlati in un unico controllo segmentato. Calendario Una griglia di date per selezionare un singolo giorno. Scheda Una superficie che raggruppa intestazione, corpo e piè di pagina. Carosello Una sequenza di diapositive scorrevole con supporto per la tastiera. Casella di controllo Una scelta binaria che supporta anche uno stato indeterminato. Espandibile Nasconde e mostra una singola area di contenuto. Selettore di colore Seleziona un colore e lo invia insieme al modulo. Casella combinata Un campo di testo che filtra un elenco di opzioni mentre digitate. Menu contestuale Azioni visualizzate al clic destro e ancorate al puntatore. Campo di inserimento della data Un campo con maschera per inserire date senza un selettore. Finestra di dialogo Un livello modale per attività e conferme che richiedono attenzione. Pannello a scomparsa Un pannello che scorre da qualsiasi bordo dello schermo. Campo Raggruppa un controllo con etichetta, descrizione ed errore. Gruppo di campi Raggruppa campi correlati sotto un titolo comune. Caricamento di file Un'area di rilascio e selezione file con supporto per più file. Modulo Invia i campi e segnala l'esito positivo senza ricaricare la pagina. Input Un campo di testo su una sola riga per tutti i tipi di input più comuni. Scorciatoia da tastiera Visualizza una scorciatoia da tastiera nel proprio tasto. Etichetta Una didascalia per un controllo, condivisa da tutti i componenti con etichetta. Menu Un elenco a discesa di azioni ancorato a un elemento di attivazione. Barra dei menu Una barra orizzontale di menu, come in un'applicazione desktop. Indicatore Mostra una misura all'interno di un intervallo noto. Menu di navigazione Navigazione del sito con link annidati e pannelli al passaggio del mouse. Campo numerico Un input numerico con controlli incrementali e intervallo limitato. Campo di immissione OTP Caselle separate per inserire un codice monouso. Paginazione Link alle pagine precedenti e successive, con troncamento. Campo password Un campo per la password con un interruttore per mostrarla. Campo del numero di telefono Un campo telefonico con selezione del paese e formattazione. Popover Contenuto avanzato ancorato a un elemento di attivazione, che si chiude facendo clic all'esterno. Scheda di anteprima Una scheda al passaggio del mouse che mostra un'anteprima della destinazione di un link. Avanzamento Mostra a che punto è un'attività. Gruppo di pulsanti di opzione Un insieme di opzioni di cui se ne può selezionare esattamente una. Valutazione Un controllo a stelle per assegnare un punteggio. Area di scorrimento Un contenitore scorrevole con barre di scorrimento sovrapposte e personalizzate. Selezionare Un menu a discesa per scegliere da un elenco di opzioni. Separatore Una linea che divide i contenuti o raggruppa i controlli. Scheletro Una forma segnaposto visualizzata durante il caricamento dei contenuti. Cursore Seleziona un valore o un intervallo trascinando lungo una traccia. Spazio Un'unità fissa di ritmo verticale della scala di spaziatura. Indicatore circolare Indica un'attività in corso di durata sconosciuta. Pila Dispone i componenti figli in riga o colonna con spaziatura uniforme. Interruttore Attiva o disattiva un'impostazione applicata immediatamente. Tabella Dati tabulari con ordinamento e righe alternate facoltativi. Schede Alterna tra pannelli che occupano lo stesso spazio. Text Visualizza il testo con una dimensione e un tag semantico scelti. Area di testo Un campo di testo su più righe che si espande in base al numero di righe. Selettore dell'ora Seleziona un orario con un intervallo scelto. Fornitore di notifiche toast Ospita notifiche temporanee in un angolo dello schermo. Alternanza Un pulsante che resta premuto per rappresentare lo stato attivo. Gruppo di attivazione Un insieme di interruttori per la selezione singola o multipla. Barra degli strumenti Una riga di controlli tra cui spostare il focus. Descrizione comando Un breve suggerimento mostrato al passaggio del mouse o quando l'elemento riceve il focus.