Componentes
Blockstudio inclui 59 UI componentes em cada compilação. Eles são registrados automaticamente, estilizados com tokens de design e criados com a mesma sintaxe de tags de qualquer outro bloco.
Blockstudio 7.3 inclui um conjunto integrado de blocos UI sem interface visual, habilitados pela WordPress Interactivity API. Eles são registrados no namespace bsui/* e podem ser compostos em templates, páginas baseadas em arquivos, padrões e conteúdo de posts.
Observação
Os componentes UI estão em versão beta enquanto coletamos feedback sobre o conjunto de componentes, os nomes, o comportamento e os padrões de uso nos projetos. Eles já podem ser testados na versão 7.3, mas a interface API ainda pode ser aprimorada antes de ser considerada estável.
Habilitar componentes UI
Os componentes integrados UI são opcionais. Habilite-os no arquivo blockstudio.json do seu tema:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
Ou habilite-os com um filtro:
add_filter('blockstudio/settings/ui/enabled', '__return_true');
Quando habilitado, Blockstudio registra a biblioteca de componentes integrada de includes/ui/blocks.
Inventário público e exemplos
Os blocos de implementação integrados continuam sendo registros bsui/* comuns, mas
os consumidores devem usar o inventário público de famílias ao criar uma galeria de componentes:
use Blockstudio\Ui;
$families = Ui::inventory();
$examples = Ui::examples();
Ui::inventory() agrupa cada componente composto sob sua raiz pública e
lista os registros de implementação exigidos por essa família.
Ui::examples() adiciona uma declaração normalizada determinística com dados padrão e
ilustrativos. Ela preserva as relações obrigatórias entre raiz e filhos, para que o
resultado possa ser passado diretamente para Blockstudio\Render::document().
O inventário público do Canvas expõe esses exemplos sob seu tipo ui e
omite os registros de implementação integrados do tipo blocks comum. Isso
produz um exemplo completo por família de componentes pública, em vez de uma galeria
de fragmentos internos de raiz, acionador, popup e camada.
Ao montar um documento já renderizado, Ui::global_assets($block_names, $html) retorna o estilo global e o script integrados exatos somente quando a saída selecionada realmente usa um componente UI.
Renderização
Use a sintaxe normal de tag de bloco:
<block name="bsui/button" label="Save" variant="default"></block>
A sintaxe mais curta <bs:> também funciona:
<bs:bsui-button label="Save" variant="default" />
Nos templates Blockstudio, as tags de bloco são renderizadas automaticamente. Em páginas baseadas em arquivos e padrões, elas são sincronizadas como blocos nativos WordPress. Se quiser renderizar componentes UI diretamente do conteúdo de posts ou de áreas de widgets, habilite as tags de bloco no nível da página:
{
"ui": {
"enabled": true
},
"blockTags": {
"enabled": true,
"allow": ["bsui/*", "app/*"]
}
}
Componentes básicos
Componentes simples são renderizados como um único bloco:
<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>
Os atributos são mapeados diretamente para os atributos block.json de cada componente. Por exemplo, bsui/button aceita label, icon, iconPosition, href, variant, size e disabled.
bs_render_block([
'name' => 'bsui/button',
'data' => [
'label' => 'Continue',
'icon' => [
'set' => 'heroicons',
'subSet' => 'outline',
'icon' => 'arrow-right',
],
'iconPosition' => 'right',
],
]);
Componentes compostos
Muitos componentes UI são blocos compostos. O bloco raiz controla o estado, e os blocos filhos declaram seu bloco pai.
Guias
<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>
Caixa de diálogo
<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>
Seletor
<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>
Campos de formulário
<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>
Blocos disponíveis
A biblioteca integrada UI inclui:
| Área | Blocos |
|---|---|
| Layout | bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table |
| Ações | bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar |
| Entradas | 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 |
| Sobreposições | bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip |
| Navegação | 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 |
| Formulários | bsui/field, bsui/field-group, bsui/form |
Os componentes compostos também expõem blocos filhos, como 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.
Estilo
Os componentes UI vêm com suas próprias propriedades personalizadas CSS usando o prefixo --bs-ui-*. Você pode substituí-las no arquivo CSS do seu tema:
:root {
--bs-ui-radius: 0.5rem;
--bs-ui-primary: oklch(0.45 0.18 260);
--bs-ui-primary-foreground: white;
}
Os componentes não têm interface visual definida em seu comportamento, mas são opinativos o suficiente para serem usados assim que instalados. Primeiro substitua os tokens e depois adicione CSS específicos do componente quando necessário.
O CSS dos componentes integrados é emitido na camada de cascata nomeada bsui. O CSS do tema, sem camada, pode substituir as regras dos componentes sem !important:
.button-brand {
background: var(--brand-primary);
}
Para adicionar uma variante personalizada de bsui/button, acrescente a opção ao seletor usando o filtro de atributos
existente e forneça o CSS da variante com
blockstudio/ui/button/variants-style:
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;
}';
});
Relacionados
- UI Composição, incluindo campos controlados, cartões de campo e separadores da barra de ferramentas
- Renderização programática
- Componentes
- Interatividade API