Pular para o conteúdo

Componentes

Composição

Os componentes incluídos em UI foram projetados para serem combinados, e não usados um de cada vez. Um seletor abre dentro de uma caixa de diálogo, um formulário valida dados dentro de um painel deslizante e um menu fica em uma linha de tabela. Esta página explica como esses elementos se encaixam: como as famílias compostas são estruturadas, como os gatilhos encaminham as propriedades dos botões, o que a API Interactivity faz por baixo dos panos e como o modelo de camadas mantém coerentes as superfícies empilhadas.

Famílias compostas

Um componente composto consiste em um bloco raiz e blocos filhos. A raiz controla o estado; cada filho declara seu lugar na família por meio de parent e usesContext no seu block.json:

JSON
{
  "name": "bsui/select-option",
  "parent": ["bsui/select-popup"],
  "usesContext": ["bsui/select"]
}

As raízes expõem uma área InnerBlocks com uma lista allowedBlocks e um template inicial. Assim, ao inserir uma caixa de diálogo no editor, são criados seu gatilho, plano de fundo e janela pop-up; além disso, uma família se comporta da mesma forma quando composta no editor, em uma página baseada em arquivos ou em tags:

HTML
<bs:bsui-select name="role" placeholder="Pick a role">
  <bs:bsui-select-trigger />
  <bs:bsui-select-popup>
    <bs:bsui-select-option value="viewer" label="Viewer" />
    <bs:bsui-select-option value="editor" label="Editor" />
  </bs:bsui-select-popup>
</bs:bsui-select>

Janelas pop-up e painéis são áreas InnerBlocks reais, não espaços reservados com sintaxe especial. Um bsui/dialog-popup aceita blocos aninhados da mesma forma que um bloco de grupo, permitindo compor normalmente um formulário, um seletor ou outra caixa de diálogo dentro dele.

Dados planos ou filhos compostos

Algumas famílias aceitam conteúdo como dados em vez de filhos. Ao receber uma lista options JSON, o seletor renderiza seu próprio gatilho e lista de opções, o que é adequado para opções provenientes de PHP:

PHP
bs_render_block([
  'name' => 'bsui/select',
  'data' => [
    'name' => 'role',
    'placeholder' => 'Pick a role',
    'options' => wp_json_encode([
      ['value' => 'viewer', 'label' => 'Viewer'],
      ['value' => 'editor', 'label' => 'Editor'],
    ]),
  ],
]);

As duas formas produzem o mesmo contrato de marcação e o mesmo comportamento em tempo de execução. Use filhos quando a estrutura for definida manualmente e options quando for calculada.

Encaminhamento de gatilhos

Os componentes de sobreposição são abertos por um botão, que deve ser o botão do sistema. Em vez de cada gatilho reimplementar um, os blocos de gatilho de bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible e bsui/tooltip incorporam bsui/button por meio de um campo de bloco bloco:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "trigger",
        "type": "block",
        "block": "bsui/button",
        "idStructure": "trigger_{id}"
      }
    ]
  }
}

O idStructure expande os campos do botão no gatilho usando o prefixo trigger_. Todas as propriedades do botão ficam disponíveis: trigger_label, trigger_variant, trigger_size, trigger_icon, trigger_iconPosition, trigger_href, trigger_disabled.

HTML
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />

No modelo do gatilho, $a['trigger'] é o botão totalmente renderizado, então a folha de estilos do botão e futuros refinamentos acompanham esse botão. Em tempo de execução, um auxiliar compartilhado encaminha ao botão interno a configuração ARIA do contêiner (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) e mantém tudo sincronizado por meio de um MutationObserver, para que a tecnologia assistiva reconheça um único controle coerente.

O funcionamento interno de API Interactivity

Cada família interativa é um armazenamento Interactivity WordPress API, cujo nome corresponde ao bloco raiz: bsui/dialog, bsui/select, bsui/form, bsui/tabs e assim por diante. Isso traz três consequências.

O estado é definido no lado do servidor. O modelo raiz imprime seu estado inicial como data-wp-context, diretamente dos atributos do bloco:

HTML
<div
  data-wp-interactive="bsui/select"
  data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
  data-bsui-select-root
>

A primeira renderização já está correta HTML, sem lampejo de hidratação no lado do cliente; as janelas pop-up começam hidden; e a mesma marcação funciona na tela do editor porque o contexto não depende de uma etapa de estado exclusiva do frontend.

O comportamento é conectado por diretivas, não pelo seu JavaScript. Os modelos conectam a marcação aos armazenamentos de forma declarativa. Sem o PHP do gatilho do seletor, ele contém apenas diretivas:

HTML
<button
  data-wp-interactive="bsui/select"
  data-wp-on--click="actions.toggle"
  data-wp-on--keydown="actions.handleTriggerKeyDown"
  data-wp-bind--aria-expanded="state.ariaExpanded"
  data-wp-text="state.displayValue"
  data-bsui-select-trigger
  aria-haspopup="listbox"
>

data-wp-on encaminha eventos para ações, data-wp-bind mantém atributos sincronizados com o estado derivado, data-wp-text renderiza o estado como texto e data-wp-on-document--click permite que as raízes fechem ao clicar fora. A composição de componentes nunca exige escrever um manipulador de eventos; o armazenamento vem com o bloco como módulo incorporado.

Seus armazenamentos podem se integrar aos pontos de conexão. Os controles de formulário aceitam expressões de diretiva como atributos, e a sintaxe com namespace de API Interactivity permite direcioná-los a qualquer armazenamento. onChange encaminha o tratamento de alterações para uma das suas ações, checked vincula o estado do controle ao seu estado e bindText renderiza um rótulo como um elemento data-wp-text vinculado a qualquer caminho de estado:

HTML
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />

bindText está disponível nos itens bsui/label, bsui/checkbox, bsui/switch, bsui/toggle e bsui/radio-group. Nos itens de caixa de seleção, chave e opção de rádio, ele passa pelo primitivo de rótulo compartilhado, mantendo a tipografia exata do rótulo do sistema para o texto controlado pelo estado. Seletores e outras entradas também emitem um evento change propagado a partir da raiz, levando o novo valor em detail, para integrações mais abrangentes.

Valores controlados

Deixe value ou checked sem definir para um controle que gerencia o próprio valor. Use defaultValue, defaultChecked ou defaultPressed do Toggle para a seleção inicial. Um Toggle independente lida com entradas de ponteiro e teclado sem um armazenamento consumidor.

Para controlar um campo a partir do seu próprio armazenamento, forneça tanto sua vinculação quanto uma ação onChange que atualize o valor vinculado. value é um caminho de diretiva, não um valor padrão literal. Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating e Time Picker aceitam value. Checkbox, Switch e Toggle usam checked.

Qualifique os caminhos com o namespace proprietário, por exemplo, my/settings::context.quantity ou my/settings::state.quantity. Controles compostos têm seu próprio namespace; um caminho sem qualificação se refere àquele controle, e não automaticamente ao armazenamento pai. As vinculações de valores compostos aceitam caminhos com pontos para acessar contexto ou estado, incluindo chaves numéricas de array, mas não expressões JavaScript nem chamadas de função.

Veja uma vinculação completa de Number Field em um bloco personalizado com suporte a Interactivity API habilitado:

PHP
<div
  data-wp-interactive="my/settings"
  data-wp-context='<?php echo esc_attr(wp_json_encode(['quantity' => 2])); ?>'
>
  <bs:bsui-number-field
    nameAlt="quantity"
    defaultValue="2"
    value="my/settings::context.quantity"
    onChange="my/settings::actions.setQuantity"
  />
  <output data-wp-text="context.quantity"></output>
</div>
JavaScript
import { getContext, store } from '@wordpress/interactivity';

store('my/settings', {
  actions: {
    setQuantity(event) {
      // Compound controls publish their normalized value in a custom change event.
      if (event.detail?.value !== undefined) {
        getContext().quantity = event.detail.value;
      }
    },
  },
});

Defina o padrão correspondente para o valor inicial renderizado no servidor. Após a hidratação, as alterações no pai atualizam todas as instâncias vinculadas, inclusive valores zero, false e vazios. Os campos de formulário ocultos de Checkbox e Switch também seguem a vinculação checked. Os valores de Time Picker usam HH:MM no formato de 24 horas ou uma string vazia. Para os manipuladores nativos de Input, Textarea e Password Input, leia event.target.value; os controles de valor compostos publicam event.detail.value. Os limites de Number Field são opcionais: se min e max forem omitidos, o campo não terá limites; zero explícito continua sendo um limite válido.

Select, Date Input, Phone Input e OTP Input publicam alterações por meio de onChange, mas não expõem essa vinculação controlada de value. Use as propriedades padrão documentadas para definir valores iniciais.

Compor a partir dos seus próprios blocos

A composição não se limita a páginas. As tags de bloco são renderizadas automaticamente dentro dos modelos de bloco, então um bloco de projeto pode emitir componentes bsui diretamente e envolvê-los na sua própria estrutura:

PHP
<div useBlockProps class="settings-panel">
  <bs:bsui-switch label="Public profile" name="public" />
  <bs:bsui-space size="4" />
  <bs:bsui-button label="Save" variant="default" />
</div>

O mesmo funciona a partir de PHP com bs_block(), inclusive com aninhamento pela chave content, conforme descrito em renderização programática. Em ambos os casos, a folha de estilos e o armazenamento do componente são carregados junto com ele, e seu bloco continua sendo uma camada fina de organização sobre as partes do sistema.

Para dispor componentes lado a lado, bsui/stack é a linha ou coluna flexível genérica: direction, gap na escala de espaçamento, align, justify e uma opção wrap. Por padrão, os filhos mantêm seu tamanho natural; a opção grow faz com que se estiquem para dividir igualmente o comprimento do conjunto, como quando um rodapé faz dois botões dividirem sua largura em vez de ficarem juntos em uma das extremidades.

Grupos de campos e cartões

bsui/field-group renderiza um conjunto de campos. A variante padrão agrupa campos relacionados sem adicionar uma superfície. Use variant="card" para criar uma moldura externa discreta e, em seguida, coloque os campos dentro de bsui/field-group-content para obter a superfície de conteúdo recuada. Mantenha o título e a descrição fora desse bloco de conteúdo:

HTML
<bs:bsui-field-group variant="card">
  <bs:bsui-field-group-title text="Account settings" />
  <bs:bsui-field-group-description text="Manage your account preferences." />
  <bs:bsui-field-group-content>
    <bs:bsui-field>
      <bs:bsui-field-label text="Display name" />
      <bs:bsui-input nameAlt="display_name" placeholder="Enter display name" />
    </bs:bsui-field>
    <bs:bsui-field>
      <bs:bsui-field-label text="Email" />
      <bs:bsui-input nameAlt="email" type="email" placeholder="Enter email" />
    </bs:bsui-field>
  </bs:bsui-field-group-content>
</bs:bsui-field-group>

disabled="true" no grupo usa o comportamento nativo de fieldset para desativar seus controles de formulário. O estilo do cartão não altera a variante padrão.

Separadores da barra de ferramentas

Coloque bsui/toolbar-separator entre os itens da barra de ferramentas. Ele segue a orientation do contêiner: uma barra de ferramentas horizontal recebe um separador vertical de altura total, e uma barra vertical recebe um separador horizontal de largura total. Os separadores se estendem até as bordas internas da borda da barra de ferramentas sem alterar a altura dos controles. Uma barra de ferramentas horizontal rola quando o conteúdo excede a largura disponível.

O modelo de camadas

É comum que bibliotecas de componentes falhem ao lidar com superfícies empilhadas. Os componentes incluídos seguem um pequeno conjunto de regras, pensado para quem cria UIs reais.

Modais são enviados ao body

Quando uma caixa de diálogo, caixa de diálogo de alerta ou painel deslizante é aberta, a janela pop-up e o plano de fundo são movidos para document.body, com um comentário marcador indicando onde retornar ao fechar. O envio para outro local libera o modal do overflow, da transformação ou do contexto de empilhamento de qualquer ancestral. Ao abrir, a rolagem da página também é bloqueada: o bloqueio é contado entre todos os componentes de sobreposição e compensa a largura da barra de rolagem para que a página não se desloque. O plano de fundo fica em z-index: 50, a janela pop-up em 51, o foco passa para a janela pop-up, a tecla Tab fica restrita a ela e, ao fechar, o foco retorna ao gatilho.

Modais se empilham. Abrir uma caixa de diálogo de dentro de outra adiciona uma camada a uma pilha compartilhada: apenas a caixa de diálogo mais externa exibe seu fundo escurecido, e as caixas atrás da que está no topo diminuem e aparecem parcialmente por trás dela. A pilha controla uma propriedade personalizada --bs-ui-nested-dialogs em cada popup de fundo, fazendo com que o deslocamento e a escala aumentem a cada nível, enquanto a caixa de diálogo pai ajusta sua altura à da filha para que as camadas apareçam de maneira uniforme. Ao fechar, tudo é restaurado na ordem inversa, uma camada por vez.

Quando um modal é fechado, o foco volta ao elemento que o acionou, e retorna ao elemento correto. Um helper compartilhado getAnchor resolve um contêiner do acionador para encontrar o botão do sistema dentro dele, para que o controle visível recupere o foco em vez de um contêiner invisível.

O modal do topo nunca é transformado

Esse efeito de aparecer parcialmente transforma apenas as caixas de diálogo ao fundo. O modal do topo permanece deliberadamente sem transformação, pois um elemento transformado se torna o bloco de referência para descendentes position: fixed, o que quebraria todos os popups flutuantes abertos dentro dele.

Essa é a regra que permite compor todo o modelo de camadas. Todas as camadas flutuantes se posicionam usando coordenadas fixas, que só correspondem à janela de visualização se não houver um ancestral transformado:

  • O menu e a caixa de combinação calculam sua posição em relação ao acionador com a estratégia fixed de Floating UI; aparecem abaixo dele e mudam de lado ou de posição quando falta espaço na janela de visualização.
  • O seletor faz o mesmo quando nada está selecionado. Quando já há uma seleção, ele alinha o popup de modo que a opção selecionada fique diretamente sobre o acionador, limitada à janela de visualização, como acontece com seletores nativos em macOS.
  • O menu de contexto abre nas coordenadas clientX/clientY do ponteiro.

Como o modal do topo não é transformado, todos esses elementos se ancoram corretamente aos seus acionadores dentro de uma caixa de diálogo, de uma caixa de diálogo de alerta ou de uma gaveta, em qualquer nível de aninhamento. Os popups não sabem que estão dentro de um modal, e não precisam saber.

Escape fecha primeiro a camada mais interna

Um toque em Escape fecha exatamente uma camada, de dentro para fora:

  1. Uma camada flutuante aberta (uma listbox de seletor, um menu, um popover, um popup de data ou telefone) fecha primeiro e devolve o foco ao seu acionador. O seletor interrompe a propagação do evento, e os manipuladores do modal também não agem quando há qualquer camada flutuante aberta, então a caixa de diálogo abaixo nunca recebe esse toque.
  2. Em seguida, o modal do topo fecha.
  3. Com modais empilhados, cada novo toque em Escape remove mais uma camada da pilha.

O fechamento é uma política, não um acaso. Uma caixa de diálogo renderizada com dismissable="false" ignora tanto Escape quanto cliques no fundo escurecido. E bsui/alert-dialog responde a Escape como qualquer modal, mas ignora deliberadamente os cliques no fundo escurecido: o objetivo desse padrão é que a escolha seja feita, em vez de permitir um fechamento acidental. Cliques no fundo escurecido fecham uma caixa de diálogo comum, pois dismissable tem o valor true por padrão.

Um formulário em uma caixa de diálogo

O padrão que exercita todas as regras acima ao mesmo tempo: um acionador abre um modal, o modal contém um formulário com validação, e o formulário contém um seletor flutuante.

HTML
<bs:bsui-dialog>
  <bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
  <bs:bsui-dialog-backdrop />
  <bs:bsui-dialog-popup>
    <bs:bsui-dialog-header>
      <bs:bsui-dialog-title content="Invite a teammate" />
      <bs:bsui-dialog-description content="They receive an email with a join link." />
    </bs:bsui-dialog-header>
    <bs:bsui-dialog-content>
      <bs:bsui-form block="team/invite" successMessage="Invitation sent.">
        <bs:bsui-field name="email">
          <bs:bsui-field-label text="Email" />
          <bs:bsui-input name="email" type="email" placeholder="colleague@example.com" required="true" />
          <bs:bsui-field-error />
        </bs:bsui-field>
        <bs:bsui-field name="role">
          <bs:bsui-field-label text="Role" />
          <bs:bsui-select name="role" defaultValue="editor" placeholder="Pick a role">
            <bs:bsui-select-trigger />
            <bs:bsui-select-popup>
              <bs:bsui-select-option value="viewer" label="Viewer" />
              <bs:bsui-select-option value="editor" label="Editor" />
              <bs:bsui-select-option value="admin" label="Admin" />
            </bs:bsui-select-popup>
          </bs:bsui-select>
        </bs:bsui-field>
        <bs:bsui-space size="2" />
        <bs:bsui-button label="Send invite" />
      </bs:bsui-form>
    </bs:bsui-dialog-content>
    <bs:bsui-dialog-footer>
      <bs:bsui-dialog-close label="Cancel" />
    </bs:bsui-dialog-footer>
  </bs:bsui-dialog-popup>
</bs:bsui-dialog>

Cada tag e atributo acima é essencial: o acionador encaminha para o botão do sistema, o título e a descrição recebem content, os campos têm os nomes que o formulário serializa, e required="true" é convertido em um booleano real pelo analisador de tags.

O que cada store faz em tempo de execução

bsui/dialog insere {"open":false,"dismissable":true} no contexto do servidor. O clique no acionador executa actions.open: o popup e o fundo escurecido são enviados para o body, a rolagem é bloqueada com compensação da barra de rolagem, o popup aparece com uma animação de 150ms, o foco vai para o primeiro elemento focalizável, e a tecla Tab percorre os elementos dentro dele. As regiões de cabeçalho, conteúdo e rodapé se espaçam usando os tokens de espaçamento do modal.

bsui/select aguarda dentro do formulário com sua listbox hidden. Clicar no acionador alterna context.open, posiciona a listbox usando coordenadas fixas da janela de visualização e, como defaultValue="editor" já está selecionado, alinha o popup para que Editor fique diretamente sobre o acionador. As teclas de seta, Home, End e a digitação antecipada movem a opção ativa; Enter ou um clique seleciona; Tab e cliques fora fecham sem selecionar. O texto visível do acionador é atualizado por meio de data-wp-text="state.displayValue", e o campo oculto <input name="role"> acompanha o valor por meio de data-wp-bind--value="state.selectedValue", que é o que o formulário serializa depois. Tudo isso se ancora corretamente dentro da caixa de diálogo porque o modal do topo não é transformado.

bsui/form intercepta o envio. O bsui/button no final do formulário renderiza um elemento simples button sem atributo type, então ele é o controle de envio do formulário por padrão HTML; o botão Cancelar fica no rodapé, fora do elemento form, e não pode enviar nada. Ao enviar, o armazenamento serializa o formulário FormData e o envia pelo API de dados do bloco indicado em block, criando aqui uma linha no esquema de banco de dados database schema do bloco team/invite. Os erros de validação retornam por campo: cada bsui/field recebe seu name, é marcado como inválido, redireciona o anel de foco para a cor destrutiva e exibe a mensagem em seu alerta bsui/field-error. Em caso de sucesso, o corpo do formulário é ocultado e o successMessage é exibido, ambos por meio de data-wp-bind--hidden.

As camadas se fecham na ordem. Com a listbox aberta, Escape a fecha e devolve o foco ao acionador do seletor; o próximo Escape fecha a caixa de diálogo e devolve o foco a Convidar colega. Um clique no fundo escurecido fecha a caixa de diálogo porque dismissable manteve seu valor padrão. Ao fechar, a rolagem é desbloqueada e o popup volta ao seu lugar no documento.

A mesma marcação colada em uma página baseada em arquivos é sincronizada como blocos nativos, e a mesma composição montada no editor pode ser visualizada de forma interativa na tela, pois todos os comportamentos acima ficam em diretivas e stores carregados nos dois contextos.

O que mantém essas conexões funcionando

As conexões acima não são convenções; são invariantes que a biblioteca mantém onde quer que renderize: cada rótulo corresponde à mesma tipografia, cada popup modal compartilha uma superfície e escurece a página ao fundo, os popups flutuantes mantêm sua âncora no acionador enquanto a página rola, e Escape fecha exatamente uma camada por vez, de dentro para fora. Essas garantias valem no frontend e na tela do editor, com os tokens padrão ou os do seu tema, então uma composição que funciona em um contexto funciona da mesma forma nos outros.

Exemplos ao vivo

As composições desta página são a gramática; /ui/examples é o guia de expressões. Ele reúne composições renderizadas ao vivo em três níveis: pares que demonstram uma conexão entre dois ou três componentes, padrões de produto reconhecíveis criados com alguns deles e miniaplicativos completos montados da maneira como os componentes são distribuídos em produtos reais. A página de cada componente em /ui traz exemplos práticos próprios, desde um campo com rótulo até um calendário atrás de um popover.

Interatividade

O modelo de diretivas e stores sobre o qual os componentes UI são construídos e como usá-lo nos seus próprios blocos.