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:
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.
{
"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." }
]
}
}
<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>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/accordion', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Como funciona:
data-wp-context='{ "isOpen": false }'cria um booleano local para esta instância.- Clicar no botão chama
actions.toggle, que invertecontext.isOpen. data-wp-bind--hidden="!context.isOpen"oculta ou mostra o painel.data-wp-bind--aria-expandededata-wp-textatualizam 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.
{
"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." }
]
}
]
}
}
<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>
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);
},
},
});
.is-active-tab {
border-bottom-color: currentColor !important;
color: var(--wp--preset--color--primary, #111);
}
Novidades neste exemplo:
getElement()retorna{ ref }, em querefé o elemento DOM. Lemosdata-indexpara saber em qual aba foi clicado. Assim, não é preciso criar uma ação separada para cada aba.callbackssão valores derivados que são recalculados quando o contexto muda. Os botões das abas e os painéis usamcallbacks.isActiveTabpara verificar se o índice corresponde acontext.activeTab.data-wp-class--is-active-tabadiciona ou remove a classeis-active-tabcom base no valor retornado pelo callback.
Modal
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.
{
"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." }
]
}
}
<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>
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--keydownescuta nodocumentem 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 chamaactions.stopPropagationpara impedir que cliques dentro dele o fechem. role="dialog"earia-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
hiddenna 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.
{
"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
$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>
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++;
}
},
},
});
.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 comostate.countnas diretivas e em JavaScript.statevs.context: a contagem fica emstate(global, compartilhada), enquantolikedfica emcontext(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 chamadastore()retorna um objeto reativostateque 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:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<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
- Referência de Interactivity: opções de configuração, detalhes sobre o suporte no editor e a forma de objeto da configuração
interactivity. - Recursos: como Blockstudio carrega
script.js,style.csse outros recursos de bloco. - WordPress Documentação de Interactivity API: a referência completa de API, incluindo
data-wp-each,data-wp-init,data-wp-rune outras diretivas não abordadas neste guia.