Aller au contenu

Composants

Blockstudio fournit 59 UI composants à chaque compilation. Ils sont enregistrés automatiquement, stylisés avec des jetons de conception et rédigés avec la même syntaxe de balises que tout autre bloc.

Blockstudio 7.3 inclut un ensemble intégré de blocs headless UI propulsés par WordPress Interactivity API. Ils sont enregistrés dans l’espace de noms bsui/* et peuvent être composés dans des modèles, des pages basées sur des fichiers, des compositions et du contenu de publication.

Remarque

Les composants UI sont en version bêta, tandis que nous recueillons des retours sur l'ensemble des composants, leur nommage, leur comportement et les usages du projet. Vous pouvez les essayer dans la version 7.3, mais l'interface API pourra encore être affinée avant d'être déclarée stable.

Activer les composants UI

Les composants UI inclus sont désactivés par défaut. Activez-les dans le fichier blockstudio.json de votre thème :

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

Vous pouvez aussi les activer avec un filtre :

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

Une fois activé, Blockstudio enregistre la bibliothèque de composants incluse depuis includes/ui/blocks.

Inventaire public et exemples

Les blocs d'implémentation inclus restent des enregistrements bsui/* ordinaires, mais les utilisateurs doivent consulter l'inventaire public des familles pour créer une galerie de composants :

PHP
use Blockstudio\Ui;

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

Ui::inventory() regroupe chaque composant composite sous sa racine publique et répertorie les enregistrements d'implémentation requis pour cette famille. Ui::examples() ajoute une déclaration normalisée déterministe avec des données par défaut et des données illustratives. Elle préserve les relations requises entre racine et enfants, afin que le résultat puisse être transmis directement à Blockstudio\Render::document().

L'inventaire public Canvas présente ces exemples sous son type ui et omet les enregistrements d'implémentation inclus du type blocks habituel. On obtient ainsi un exemple complet par famille de composants publique, plutôt qu'une galerie de fragments internes de racines, de déclencheurs, de popups et de couches.

Lors de l'assemblage d'un document déjà rendu, Ui::global_assets($block_names, $html) renvoie la feuille de style globale et le script inclus exacts uniquement si le résultat sélectionné utilise réellement un composant UI.

Rendu

Utilisez la syntaxe habituelle des balises de bloc :

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

La syntaxe abrégée <bs:> fonctionne aussi :

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

Dans les modèles Blockstudio, les balises de bloc effectuent le rendu automatiquement. Dans les pages basées sur des fichiers et les compositions, elles sont synchronisées sous forme de blocs natifs WordPress. Pour effectuer le rendu direct de composants UI depuis le contenu de publication ou des zones de widgets, activez les balises de bloc au niveau de la page :

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

Composants de base

Les composants simples sont rendus sous forme d'un seul bloc :

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>

Les attributs correspondent directement aux attributs block.json de chaque composant. Par exemple, bsui/button prend en charge label, icon, iconPosition, href, variant, size et disabled.

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

Composants composites

De nombreux composants UI sont des blocs composites. Le bloc racine gère l'état, et les blocs enfants déclarent leur parent.

Onglets

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>

Boîte de dialogue

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>

Sélecteur

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>

Champs de formulaire

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>

Blocs disponibles

La bibliothèque UI incluse comprend :

Domaine Blocs
Mise en page bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
Actions bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
Champs 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
Superpositions bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
Navigation bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs
Retours bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast
Formulaires bsui/field, bsui/field-group, bsui/form

Les composants composites exposent également des blocs enfants tels que bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup et bsui/select-option.

Styles

Les composants UI sont fournis avec leurs propres propriétés personnalisées CSS, qui utilisent le préfixe --bs-ui-*. Vous pouvez les remplacer depuis le CSS de votre thème :

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

Le comportement des composants est sans interface prédéfinie, mais ils sont assez directifs pour être utilisables tels quels. Remplacez d'abord les tokens, puis ajoutez des règles CSS propres aux composants si nécessaire.

La CSS des composants inclus est émise dans la couche de cascade nommée bsui. Les règles CSS non placées dans une couche peuvent remplacer les règles des composants sans !important :

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

Pour ajouter une variante bsui/button personnalisée, ajoutez l'option du sélecteur au moyen du filtre d'attributs existant, puis fournissez la variante CSS avec 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;
}';
});

Tous les composants

Accordéon Sections empilées qui déploient un panneau à la fois. Boîte de dialogue d'alerte Une fenêtre modale qui interrompt le déroulement et exige une réponse avant de se fermer. Proportions Contraint le contenu à un rapport largeur/hauteur fixe. Avatar Une image d’utilisateur remplacée par ses initiales en cas d’échec du chargement. Badge Une petite étiquette pour un état, un décompte ou une catégorie. Fil d’Ariane Indique la place de la page actuelle dans la hiérarchie. Bouton Déclenche une action, avec des variantes pour chaque niveau d’importance. Groupe de boutons Regroupe des boutons associés dans un seul contrôle segmenté. Calendrier Une grille de dates pour choisir un seul jour. Carte Un conteneur regroupant un en-tête, un corps et un pied de page. Carrousel Un carrousel de diapositives navigable par balayage et au clavier. Case à cocher Un choix binaire qui prend aussi en charge un état indéterminé. Rétractable Masque et affiche une seule zone de contenu. Sélecteur de couleur Choisit une couleur et l’envoie avec le formulaire associé. Liste déroulante Un champ texte qui filtre une liste d’options pendant la saisie. Menu contextuel Des actions affichées au clic droit et ancrées au pointeur. Champ de saisie de date Un champ masqué pour saisir des dates sans sélecteur. Boîte de dialogue Une couche modale pour les tâches ciblées et les confirmations. Panneau coulissant Un panneau qui glisse depuis n’importe quel bord de l’écran. Champ Associe une étiquette, une description et une erreur à un contrôle. Groupe de champs Regroupe des champs associés sous un titre commun. Téléversement de fichier Une zone de dépôt et un sélecteur de fichiers prenant en charge plusieurs fichiers. Formulaire Envoie ses champs et signale la réussite sans rechargement. Entrée Un champ texte sur une ligne pour les types de saisie courants. Raccourci clavier Affiche un raccourci clavier dans une touche dédiée. Libellé Une légende pour un contrôle, commune à tous les composants avec étiquette. Menu Une liste déroulante d’actions ancrée à un déclencheur. Barre de menus Une barre horizontale de menus, comme dans une application de bureau. Jauge Affiche une mesure dans une plage connue. Menu de navigation Navigation du site avec liens imbriqués et panneaux au survol. Champ numérique Un champ numérique avec boutons d’incrémentation et plage limitée. Saisie de code OTP Des cases séparées pour saisir un code à usage unique. Pagination Des liens de page avec précédent, suivant et troncature. Champ de mot de passe Un champ de mot de passe avec un bouton d’affichage. Champ de numéro de téléphone Un champ téléphonique avec sélection du pays et formatage. Fenêtre contextuelle Un contenu enrichi ancré à un déclencheur et fermé par un clic à l’extérieur. Carte d’aperçu Une carte au survol qui affiche un aperçu de la destination d’un lien. Progression Indique l’avancement d’une tâche. Groupe de boutons radio Un ensemble d’options dont une seule peut être sélectionnée. Évaluation Un contrôle à étoiles pour attribuer une note. Zone de défilement Un conteneur défilant avec des barres de défilement superposées et stylisées. Sélectionner Une liste déroulante pour choisir parmi plusieurs options. Séparateur Une ligne qui sépare du contenu ou des groupes de contrôles. Squelette Une forme de remplacement affichée pendant le chargement du contenu. Curseur Choisit une valeur ou une plage en faisant glisser le curseur. Espace Un intervalle fixe de rythme vertical issu de l’échelle d’espacement. Indicateur circulaire Indique un travail en cours dont la durée est inconnue. Pile Dispose les éléments enfants en ligne ou en colonne avec un espacement régulier. Interrupteur Active ou désactive un réglage qui s’applique immédiatement. Tableau Des données tabulaires avec tri et bandes alternées facultatifs. Onglets Bascule entre des panneaux qui occupent le même espace. Text Affiche du texte avec une taille et une balise sémantique choisies. Zone de texte Un champ texte multiligne qui s’agrandit selon le nombre de lignes. Sélecteur d’heure Choisit une heure selon un intervalle défini. Fournisseur de notifications toast Héberge des notifications temporaires dans un coin de l’écran. Basculer Un bouton qui reste enfoncé pour représenter l’état activé. Groupe de bascules Un ensemble de boutons bascule permettant un ou plusieurs choix. Barre d’outils Une rangée de contrôles où le focus passe de l’un à l’autre. Info-bulle Une courte indication affichée au survol ou à la prise de focus.