Pular para o conteúdo

Como criar componentes interativos

WordPress blocos são estáticos por padrão. O editor salva HTML no banco de dados, o frontend o renderiza e a história termina aí. Para muitos blocos, isso é exatamente o que se espera. Mas alguns componentes precisam responder à interação do usuário: alternar conteúdo, trocar abas, abrir diálogos e atualizar contadores.

A WordPress Interactivity API adiciona comportamento reativo no lado do cliente aos blocos usando atributos HTML chamados diretivas. Você escreve data-wp-on--click em vez de addEventListener, data-wp-bind--hidden em vez de element.hidden = true. A API cuida automaticamente da reatividade, do isolamento de contexto e da hidratação.

Blockstudio cuida da configuração. Defina "interactivity": true no seu block.json, e Blockstudio gera o importmap, carrega o API tanto no editor quanto no frontend e resolve as importações dos seus módulos ES. Sem etapa de compilação, sem empacotador e sem configuração do webpack. Consulte a Referência de Interactivity para ver os detalhes de configuração.

Este guia apresenta quatro componentes completos, cada um introduzindo novos conceitos. Ao final, você terá padrões funcionais para os elementos interativos de UI uso mais comuns.

Como funciona

Diretivas

Diretivas são atributos data-wp-* que declaram comportamento reativo diretamente no seu HTML. As mais usadas:

Diretiva Finalidade Exemplo
data-wp-interactive Define o namespace do armazenamento data-wp-interactive="myBlock"
data-wp-context Estado reativo local por instância data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Manipulador de eventos data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Vincula um atributo HTML data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Alterna uma classe CSS data-wp-class--is-active="context.isActive"
data-wp-text Define o conteúdo do texto data-wp-text="state.count"
data-wp-style--[prop] Define um estilo em linha data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Evento global do documento data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Executa um callback quando o estado muda data-wp-watch="callbacks.log"
data-wp-each Percorre um array data-wp-each="state.items"

O armazenamento

Todo bloco interativo tem um armazenamento, criado ao chamar store() com um namespace e um objeto que contém actions, callbacks e, opcionalmente, state:

JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myBlock', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

Dentro das ações, getContext() retorna o objeto data-wp-context mais próximo na árvore DOM. getElement() retorna uma referência ao elemento DOM que acionou a ação, útil para ler atributos data-*.

Contexto vs. estado

Contexto (data-wp-context) é local a cada instância de bloco. Se você colocar três acordeões em uma página, cada um terá seu próprio valor isOpen. Alternar um não afeta os outros.

Estado (wp_interactivity_state()) é global e compartilhado entre todas as instâncias de um bloco. Use-o para dados vindos do servidor (como a contagem de comentários) ou valores que devem ser iguais em todos os lugares.

O contexto funciona tanto no editor quanto no frontend. O estado funciona apenas no frontend porque WordPress o serializa em uma tag de script que não é incluída nas respostas REST API do editor.

Acordeão

O padrão interativo mais simples: clique em um botão para alternar um conteúdo. Este exemplo precisa de apenas três diretivas e algumas linhas de JavaScript.

JSON
{
  "name": "my-theme/accordion",
  "title": "Accordion",
  "category": "text",
  "icon": "arrow-down-alt2",
  "description": "Expandable content section.",
  "blockstudio": {
    "interactivity": true,
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "Accordion heading" },
      { "id": "body", "type": "textarea", "label": "Body", "default": "Accordion content goes here." }
    ]
  }
}
PHP
<div useBlockProps
     data-wp-interactive="myTheme/accordion"
     data-wp-context='{ "isOpen": false }'>
  <button
    data-wp-on--click="actions.toggle"
    data-wp-bind--aria-expanded="context.isOpen"
    aria-controls="accordion-panel"
    style="all: unset; cursor: pointer; display: flex; justify-content: space-between; align-items: center; width: 100%; padding: 1rem; font-weight: 600; font-size: 1.125rem;">
    <?php echo esc_html( $a['heading'] ); ?>
    <span aria-hidden="true" data-wp-text="context.isOpen ? '−' : '+'">+</span>
  </button>
  <div
    id="accordion-panel"
    role="region"
    data-wp-bind--hidden="!context.isOpen"
    style="padding: 0 1rem 1rem;">
    <p><?php echo esc_html( $a['body'] ); ?></p>
  </div>
</div>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myTheme/accordion', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

Como funciona:

  1. data-wp-context='{ "isOpen": false }' cria um booleano local para esta instância.
  2. Clicar no botão chama actions.toggle, que inverte context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" oculta ou mostra o painel.
  4. data-wp-bind--aria-expanded e data-wp-text atualizam o estado do botão para acessibilidade e o indicador visual.

Como cada instância do bloco recebe seu próprio contexto, é possível inserir vários acordeões em uma página sem configuração adicional. Eles funcionam de forma independente.

Abas

As abas introduzem dois novos conceitos: data-wp-class--* para alternar classes CSS e getElement() para ler atributos de dados do elemento que acionou uma ação.

Este exemplo usa um campo repetidor para que editores possam adicionar quantas abas precisarem.

JSON
{
  "name": "my-theme/tabs",
  "title": "Tabs",
  "category": "text",
  "icon": "table-row-after",
  "description": "Tabbed content switcher.",
  "blockstudio": {
    "interactivity": true,
    "attributes": [
      {
        "id": "tabs",
        "type": "repeater",
        "label": "Tabs",
        "min": 1,
        "max": 8,
        "attributes": [
          { "id": "label", "type": "text", "label": "Tab Label", "default": "Tab" },
          { "id": "content", "type": "textarea", "label": "Content", "default": "Tab content goes here." }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps
     data-wp-interactive="myTheme/tabs"
     data-wp-context='{ "activeTab": 0 }'>
  <div role="tablist" style="display: flex; gap: 0; border-bottom: 2px solid #e5e7eb;">
    <?php foreach ( $a['tabs'] as $i => $tab ) : ?>
      <button
        role="tab"
        data-index="<?php echo esc_attr( $i ); ?>"
        data-wp-on--click="actions.selectTab"
        data-wp-class--is-active-tab="callbacks.isActiveTab"
        data-wp-bind--aria-selected="callbacks.isActiveTab"
        style="padding: 0.75rem 1.5rem; background: none; border: none; cursor: pointer; font-weight: 500; border-bottom: 2px solid transparent; margin-bottom: -2px;">
        <?php echo esc_html( $tab['label'] ); ?>
      </button>
    <?php endforeach; ?>
  </div>
  <?php foreach ( $a['tabs'] as $i => $tab ) : ?>
    <div
      role="tabpanel"
      data-index="<?php echo esc_attr( $i ); ?>"
      data-wp-bind--hidden="!callbacks.isActiveTab"
      style="padding: 1.5rem 0;">
      <p><?php echo esc_html( $tab['content'] ); ?></p>
    </div>
  <?php endforeach; ?>
</div>
JavaScript
import { store, getContext, getElement } from '@wordpress/interactivity';

store('myTheme/tabs', {
  actions: {
    selectTab: () => {
      const context = getContext();
      const { ref } = getElement();
      context.activeTab = parseInt(ref.dataset.index, 10);
    },
  },
  callbacks: {
    isActiveTab: () => {
      const context = getContext();
      const { ref } = getElement();
      return context.activeTab === parseInt(ref.dataset.index, 10);
    },
  },
});
CSS
.is-active-tab {
  border-bottom-color: currentColor !important;
  color: var(--wp--preset--color--primary, #111);
}

Novidades neste exemplo:

  • getElement() retorna { ref }, em que ref é o elemento DOM. Lemos data-index para saber em qual aba foi clicado. Assim, não é preciso criar uma ação separada para cada aba.
  • callbacks são valores derivados que são recalculados quando o contexto muda. Os botões das abas e os painéis usam callbacks.isActiveTab para verificar se o índice corresponde a context.activeTab.
  • data-wp-class--is-active-tab adiciona ou remove a classe is-active-tab com base no valor retornado pelo callback.

O modal apresenta o tratamento de eventos no nível do documento com data-wp-on-document--keydown para fechar ao pressionar Escape e ao clicar no fundo. Também demonstra os atributos de acessibilidade adequados para diálogos.

JSON
{
  "name": "my-theme/modal",
  "title": "Modal",
  "category": "text",
  "icon": "external",
  "description": "Button that opens a modal dialog.",
  "blockstudio": {
    "interactivity": true,
    "attributes": [
      { "id": "buttonText", "type": "text", "label": "Button Text", "default": "Open Modal" },
      { "id": "title", "type": "text", "label": "Modal Title", "default": "Modal Title" },
      { "id": "body", "type": "textarea", "label": "Modal Body", "default": "Modal content goes here." }
    ]
  }
}
PHP
<div useBlockProps
     data-wp-interactive="myTheme/modal"
     data-wp-context='{ "isOpen": false }'>
  <button
    data-wp-on--click="actions.open"
    style="padding: 0.75rem 1.5rem; background: #111; color: #fff; border: none; border-radius: 6px; cursor: pointer; font-size: 1rem;">
    <?php echo esc_html( $a['buttonText'] ); ?>
  </button>

  <div
    data-wp-bind--hidden="!context.isOpen"
    data-wp-on--click="actions.backdropClick"
    data-wp-on-document--keydown="actions.onKeydown"
    style="position: fixed; inset: 0; z-index: 9999; display: flex; align-items: center; justify-content: center; background: rgba(0,0,0,0.5);">
    <div
      role="dialog"
      aria-modal="true"
      data-wp-bind--aria-label="context.isOpen ? '<?php echo esc_attr( $a['title'] ); ?>' : false"
      data-wp-on--click="actions.stopPropagation"
      style="background: #fff; border-radius: 12px; padding: 2rem; max-width: 32rem; width: 100%; margin: 1rem; position: relative;">
      <h2 style="margin: 0 0 1rem; font-size: 1.25rem;"><?php echo esc_html( $a['title'] ); ?></h2>
      <p style="margin: 0 0 1.5rem; color: #555;"><?php echo esc_html( $a['body'] ); ?></p>
      <button
        data-wp-on--click="actions.close"
        style="padding: 0.5rem 1rem; background: #f3f4f6; border: none; border-radius: 6px; cursor: pointer;">
        Close
      </button>
    </div>
  </div>
</div>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myTheme/modal', {
  actions: {
    open: () => {
      const context = getContext();
      context.isOpen = true;
    },
    close: () => {
      const context = getContext();
      context.isOpen = false;
    },
    backdropClick: () => {
      const context = getContext();
      context.isOpen = false;
    },
    stopPropagation: (event) => {
      event.stopPropagation();
    },
    onKeydown: (event) => {
      if (event.key === 'Escape') {
        const context = getContext();
        context.isOpen = false;
      }
    },
  },
});

Novidades neste exemplo:

  • data-wp-on-document--keydown escuta no document em vez de no próprio elemento. O manipulador é acionado independentemente do elemento que estiver em foco, então Escape funciona em qualquer lugar.
  • Fechar ao clicar no fundo usa duas camadas: a div de sobreposição chama actions.backdropClick, enquanto o diálogo interno chama actions.stopPropagation para impedir que cliques dentro dele o fechem.
  • role="dialog" e aria-modal="true" informam aos leitores de tela que se trata de um diálogo modal. aria-label é vinculado para se aplicar apenas quando o modal estiver visível.
  • O atributo hidden na sobreposição oculta o modal e impede que o listener de keydown do documento seja acionado quando ele está fechado, pois as diretivas em elementos ocultos ficam pausadas.

Botão de curtida com estado do servidor

Este exemplo combina o estado do lado do servidor com ações do lado do cliente. A contagem de curtidas é inicializada a partir de PHP usando wp_interactivity_state(), e o botão a atualiza ao ser clicado.

JSON
{
  "name": "my-theme/like-button",
  "title": "Like Button",
  "category": "text",
  "icon": "heart",
  "description": "A like button with a count.",
  "blockstudio": {
    "interactivity": true,
    "attributes": [
      { "id": "itemId", "type": "text", "label": "Item ID", "default": "post-1" }
    ]
  }
}
PHP
<?php
$item_id = $a['itemId'];
$count   = (int) get_option( "likes_{$item_id}", 0 );

wp_interactivity_state( 'myTheme/likeButton', array(
	'count' => $count,
) );
?>
<div useBlockProps
     data-wp-interactive="myTheme/likeButton"
     data-wp-context='{ "liked": false }'>
  <button
    data-wp-on--click="actions.like"
    data-wp-class--is-liked="context.liked"
    style="display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.5rem 1rem; border: 2px solid #e5e7eb; border-radius: 999px; background: none; cursor: pointer; font-size: 1rem; transition: all 0.2s;">
    <span data-wp-text="context.liked ? '❤️' : '🤍'">🤍</span>
    <span data-wp-text="state.count"><?php echo esc_html( $count ); ?></span>
  </button>
</div>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

const { state } = store('myTheme/likeButton', {
  actions: {
    like: () => {
      const context = getContext();
      if (context.liked) {
        context.liked = false;
        state.count--;
      } else {
        context.liked = true;
        state.count++;
      }
    },
  },
});
CSS
.is-liked {
  border-color: #ef4444 !important;
  background: #fef2f2 !important;
}

Novidades neste exemplo:

  • wp_interactivity_state() inicializa a contagem a partir de PHP. O valor é serializado no HTML da página e fica disponível como state.count nas diretivas e em JavaScript.
  • state vs. context: a contagem fica em state (global, compartilhada), enquanto liked fica em context (por instância). Se houvesse vários botões de curtida para o mesmo item, eles compartilhariam a contagem, mas cada um poderia acompanhar o próprio status de curtida.
  • Desestruturação de store(): a chamada store() retorna um objeto reativo state que pode ser referenciado nas ações.

Ressalva importante: o estado do servidor funciona apenas no frontend. No editor, o bloco é renderizado pelo REST API, então wp_interactivity_state() não é incluído. O texto alternativo renderizado por PHP (<?php echo esc_html( $count ); ?>) aparece como valor inicial na prévia do editor. Para ter estado interativo no editor, use data-wp-context.

Dicas e padrões

Convenções de namespace. Use o nome do seu tema ou plugin como prefixo: myTheme/accordion, myPlugin/tabs. Isso evita conflitos quando vários blocos na mesma página usam a Interactivity API.

Não é necessária uma etapa de compilação. Blockstudio carrega script.js como módulo ES nativo e gera automaticamente o importmap para @wordpress/interactivity. Você escreve JavaScript padrão com instruções import e tudo funciona imediatamente.

Blocos que usam apenas diretivas. Se o seu bloco usa apenas data-wp-context com data-wp-bind--hidden ou data-wp-text, você não precisa de um script.js. A Interactivity API trata disso de forma declarativa. O exemplo do acordeão acima poderia funcionar sem JavaScript usando um truque com checkbox, mas a abordagem com script é mais simples.

Depuração com data-wp-watch. Adicione um callback de observação para registrar mudanças de contexto durante o desenvolvimento:

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<div data-wp-watch="callbacks.debug" ...>

Remova-o antes de publicar.

Mantenha o contexto mínimo. Coloque em data-wp-context apenas valores que realmente mudam. Dados estáticos, como rótulos e conteúdo, devem permanecer em PHP. O contexto JSON é serializado em cada instância do bloco, então objetos grandes aumentam o peso da página.

Próximas etapas