Pular para o conteúdo

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:

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

Ou habilite-os com um filtro:

PHP
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:

PHP
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:

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

A sintaxe mais curta <bs:> também funciona:

HTML
<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:

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

Componentes básicos

Componentes simples são renderizados como um único bloco:

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>

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.

PHP
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

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>

Caixa de diálogo

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>

Seletor

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>

Campos de formulário

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>

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:

CSS
: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:

CSS
.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:

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

Todos os componentes

Acordeão Seções empilhadas que expandem um painel por vez. Caixa de diálogo de alerta Uma janela modal que interrompe o fluxo e exige uma resposta antes de fechar. Proporção da tela Mantém o conteúdo em uma proporção fixa entre largura e altura. Avatar Uma imagem de usuário que exibe as iniciais caso não carregue. Selo Um rótulo pequeno para status, contagens e categorias. Trilha de navegação Mostra a posição da página atual na hierarquia. Botão Aciona uma ação, com variantes para cada nível de destaque. Grupo de botões Agrupa botões relacionados em um único controle segmentado. Calendário Uma grade de datas para selecionar um único dia. Cartão Uma superfície que agrupa cabeçalho, corpo e rodapé. Carrossel Uma sequência deslizável de slides com suporte ao teclado. Caixa de seleção Uma escolha binária que também aceita um estado indeterminado. Recolhível Oculta e revela uma única região de conteúdo. Seletor de cores Seleciona uma cor e a envia com o formulário ao redor. Caixa de combinação Um campo de texto que filtra uma lista de opções à medida que você digita. Menu de contexto Ações exibidas ao clicar com o botão direito, ancoradas no ponteiro. Campo de entrada de data Um campo mascarado para digitar datas sem um seletor. Caixa de diálogo Uma camada modal para tarefas focadas e confirmações. Painel deslizante Um painel que desliza de qualquer borda da tela. Campo Envolve um controle com rótulo, descrição e erro. Grupo de campos Agrupa campos relacionados sob um título comum. Envio de arquivo Uma área para soltar arquivos e um seletor com suporte a vários arquivos. Formulário Envia os campos e informa o sucesso sem recarregar a página. Entrada Um campo de texto de linha única para todos os tipos de entrada comuns. Atalho de teclado Exibe um atalho de teclado em sua própria tecla. Rótulo Uma legenda para um controle, compartilhada por todos os componentes com rótulo. Menu Uma lista suspensa de ações ancorada em um acionador. Barra de menus Uma barra horizontal de menus, como em um aplicativo de desktop. Medidor Mostra uma medida dentro de um intervalo conhecido. Menu de navegação Navegação do site com links aninhados e painéis exibidos ao passar o cursor. Campo numérico Uma entrada numérica com controles de incremento e um intervalo limitado. Campo de entrada OTP Campos separados para inserir um código de uso único. Paginação Links de página com opções anterior, próxima e de truncamento. Campo de senha Um campo de senha com opção para revelar o conteúdo. Campo de telefone Um campo de telefone com seleção de país e formatação. Janela pop-up Conteúdo rico ancorado em um acionador, fechado ao clicar fora. Cartão de pré-visualização Um cartão exibido ao passar o cursor que pré-visualiza o destino de um link. Progresso Mostra o progresso de uma tarefa. Grupo de botões de opção Um conjunto de opções no qual é possível selecionar exatamente uma. Avaliação Um controle de estrelas para registrar uma avaliação. Área de rolagem Um contêiner de rolagem com barras de rolagem sobrepostas e estilizadas. Selecione Uma lista suspensa para escolher entre várias opções. Separador Uma linha que divide conteúdo ou grupos de controles. Esqueleto Uma forma de espaço reservado exibida enquanto o conteúdo carrega. Controle deslizante Seleciona um valor ou intervalo arrastando ao longo de uma trilha. Espaço Um passo fixo de ritmo vertical da escala de espaçamento. Indicador giratório Indica trabalho em andamento sem duração conhecida. Pilha Organiza os elementos filhos em uma linha ou coluna com espaçamento uniforme. Interruptor Alterna uma configuração que é aplicada imediatamente. Tabela Dados tabulares com opções de ordenação e linhas alternadas. Abas Alterna entre painéis que ocupam o mesmo espaço. Text Renderiza texto em prosa com tamanho e tag semântica definidos. Área de texto Um campo de texto com várias linhas que cresce conforme elas aumentam. Seletor de horário Seleciona um horário do dia com um intervalo definido. Provedor de notificações toast Exibe notificações temporárias em um canto da tela. Alternância Um botão que permanece pressionado para representar o estado ativado. Grupo de alternância Um conjunto de alternadores que funciona como escolha única ou múltipla. Barra de ferramentas Uma linha de controles com foco móvel entre eles. Dica de ferramenta Uma dica breve exibida ao passar o cursor ou receber foco.