Crear componentes interactivos
Por defecto, los bloques WordPress son estáticos. El editor guarda HTML en la base de datos, el frontend lo muestra y ahí termina todo. Para muchos bloques, esto es exactamente lo adecuado. Pero algunos componentes deben responder a la interacción del usuario: mostrar u ocultar contenido, cambiar de pestaña, abrir cuadros de diálogo y actualizar contadores.
La WordPress Interactivity API añade comportamiento reactivo del lado del cliente a los bloques mediante atributos HTML llamados directivas. Escriba data-wp-on--click en lugar de addEventListener, y data-wp-bind--hidden en lugar de element.hidden = true. API gestiona automáticamente la reactividad, el aislamiento del contexto y la hidratación.
Blockstudio se encarga de la conexión. Configure "interactivity": true en su block.json y Blockstudio generará el mapa de importación, cargará API tanto en el editor como en el frontend y resolverá las importaciones de sus módulos ES. Sin compilación, sin empaquetador y sin configuración de webpack. Consulte la referencia de Interactivity para ver los detalles de configuración.
Esta guía explica cuatro componentes completos, cada uno de los cuales introduce conceptos nuevos. Al terminar, tendrá patrones funcionales para los elementos interactivos UI más comunes.
Cómo funciona
Directivas
Las directivas son atributos data-wp-* que declaran comportamiento reactivo directamente en su HTML. Estas son las más utilizadas:
| Directiva | Propósito | Ejemplo |
|---|---|---|
data-wp-interactive |
Define el espacio de nombres de la tienda | data-wp-interactive="myBlock" |
data-wp-context |
Estado reactivo local por instancia | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Controlador de eventos | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Vincula un atributo HTML | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Alterna una clase CSS | data-wp-class--is-active="context.isActive" |
data-wp-text |
Establece el contenido de texto | data-wp-text="state.count" |
data-wp-style--[prop] |
Establece un estilo en línea | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Evento global del documento | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Ejecuta una función de retorno cuando cambia el estado | data-wp-watch="callbacks.log" |
data-wp-each |
Recorre una matriz | data-wp-each="state.items" |
La tienda
Cada bloque interactivo tiene una tienda, que se crea llamando a store() con un espacio de nombres y un objeto que contiene actions, callbacks y, opcionalmente, state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Dentro de las acciones, getContext() devuelve el objeto data-wp-context más cercano en el árbol DOM. getElement() devuelve una referencia al elemento DOM que activó la acción, útil para leer atributos data-*.
Contexto frente a estado
El contexto (data-wp-context) es local a cada instancia del bloque. Si coloca tres acordeones en una página, cada uno tiene su propio valor isOpen. Alternar uno no afecta a los demás.
El estado (wp_interactivity_state()) es global y se comparte entre todas las instancias de un bloque. Úselo para datos que provienen del servidor (como el recuento de comentarios) o para valores que deben ser iguales en todas partes.
El contexto funciona tanto en el editor como en el frontend. El estado solo funciona en el frontend porque WordPress lo serializa en una etiqueta de script que no se incluye en las respuestas REST API del editor.
Acordeón
El patrón interactivo más sencillo: haga clic en un botón para mostrar u ocultar contenido. Este ejemplo solo necesita tres directivas y unas pocas líneas 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;
},
},
});
Cómo funciona:
data-wp-context='{ "isOpen": false }'crea un valor booleano local para esta instancia.- Al hacer clic en el botón se llama a
actions.toggle, que inviertecontext.isOpen. data-wp-bind--hidden="!context.isOpen"oculta o muestra el panel.data-wp-bind--aria-expandedydata-wp-textactualizan el estado del botón para la accesibilidad y el indicador visual.
Como cada instancia del bloque obtiene su propio contexto, puede colocar varios acordeones en una página sin configuración adicional. Se alternan de forma independiente.
Pestañas
Las pestañas introducen dos conceptos nuevos: data-wp-class--*, para alternar clases CSS, y getElement(), para leer atributos de datos del elemento que activó una acción.
Este ejemplo utiliza un campo repetidor para que los editores puedan añadir tantas pestañas como necesiten.
{
"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);
}
Novedades:
getElement()devuelve{ ref }, donderefes el elemento DOM. Leemosdata-indexpara saber en qué pestaña se hizo clic. Así no hace falta crear una acción distinta para cada pestaña.callbacksson valores derivados que se vuelven a evaluar cuando cambia el contexto. Los botones de pestaña y los paneles utilizancallbacks.isActiveTabpara comprobar si su índice coincide concontext.activeTab.data-wp-class--is-active-tabañade o elimina la claseis-active-tabsegún el valor que devuelve la función de retorno.
Ventana modal
La ventana modal introduce la gestión de eventos a nivel de documento mediante data-wp-on-document--keydown para cerrarla al pulsar Escape, además de cerrarse al hacer clic en el fondo. También muestra los atributos adecuados para garantizar la accesibilidad del cuadro de diálogo.
{
"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;
}
},
},
});
Novedades:
data-wp-on-document--keydownescucha endocumenten lugar de hacerlo en el propio elemento. El controlador se activa independientemente del elemento que tenga el foco, así que Escape funciona desde cualquier parte.- El cierre al hacer clic en el fondo utiliza dos capas: el div superpuesto llama a
actions.backdropClick, mientras que el cuadro de diálogo interior llama aactions.stopPropagationpara impedir que los clics dentro del cuadro lo cierren. role="dialog"yaria-modal="true"indican a los lectores de pantalla que se trata de un cuadro de diálogo modal.aria-labelestá vinculado para que solo se aplique cuando la ventana modal esté visible.- El atributo
hiddendel elemento superpuesto oculta la ventana modal e impide que el controlador de pulsación de teclas del documento se active cuando está cerrada, ya que las directivas de los elementos ocultos quedan en pausa.
Botón «Me gusta» con estado del servidor
Este ejemplo combina el estado del servidor con acciones del cliente. El recuento de «Me gusta» se inicializa desde PHP mediante wp_interactivity_state(), y el botón lo actualiza al hacer clic.
{
"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;
}
Novedades:
wp_interactivity_state()inicializa el recuento a partir de PHP. El valor se serializa en HTML de la página y está disponible comostate.counten las directivas y JavaScript.statefrente acontext: el recuento está enstate(global y compartido), mientras quelikedestá encontext(por instancia). Si tuviera varios botones de «Me gusta» para el mismo elemento, compartirían el recuento, pero cada uno podría llevar su propio estado de «Me gusta».- Desestructurar desde
store(): la llamada astore()devuelve un objeto reactivostateal que puede hacer referencia en sus acciones.
Advertencia importante: El estado del servidor solo funciona en el frontend. En el editor, el bloque se renderiza mediante REST API, por lo que no se incluye wp_interactivity_state(). El texto alternativo renderizado por PHP (<?php echo esc_html( $count ); ?>) se muestra como valor inicial en la vista previa del editor. Para que el estado sea interactivo en el editor, use data-wp-context.
Consejos y patrones
Convenciones de espacios de nombres. Use el nombre de su tema o complemento como prefijo: myTheme/accordion, myPlugin/tabs. Así se evitan conflictos cuando varios bloques de una misma página utilizan Interactivity API.
No hace falta compilar. Blockstudio carga script.js como módulo ES nativo y genera automáticamente el mapa de importación para @wordpress/interactivity. Escriba JavaScript estándar con instrucciones import y funcionará de inmediato.
Bloques que solo usan directivas. Si su bloque solo utiliza data-wp-context con data-wp-bind--hidden o data-wp-text, no necesita ningún script.js. Interactivity API se encarga de todo de forma declarativa. El ejemplo del acordeón podría funcionar sin JavaScript mediante un truco con casillas de verificación, pero el enfoque con un script es más limpio.
Depuración con data-wp-watch. Añada una función de retorno de observación para registrar los cambios de contexto durante el desarrollo:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Elimínela antes de publicar.
Mantenga el contexto al mínimo. Incluya en data-wp-context solo los valores que realmente cambien. Los datos estáticos, como las etiquetas y el contenido, deben permanecer en PHP. El contexto JSON se serializa en cada instancia del bloque, por lo que los objetos grandes aumentan el peso de la página.
Próximos pasos
- Referencia de Interactivity: opciones de configuración, detalles sobre la compatibilidad con el editor y formato de objeto del ajuste
interactivity. - Recursos: cómo Blockstudio carga
script.js,style.cssy otros recursos de bloques. - Documentación de Interactivity de WordPressAPI: referencia completa de API, incluidos
data-wp-each,data-wp-init,data-wp-runy otras directivas que no se tratan en esta guía.