Saltar al contenido

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:

JavaScript
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.

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

Cómo funciona:

  1. data-wp-context='{ "isOpen": false }' crea un valor booleano local para esta instancia.
  2. Al hacer clic en el botón se llama a actions.toggle, que invierte context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" oculta o muestra el panel.
  4. data-wp-bind--aria-expanded y data-wp-text actualizan 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.

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

Novedades:

  • getElement() devuelve { ref }, donde ref es el elemento DOM. Leemos data-index para saber en qué pestaña se hizo clic. Así no hace falta crear una acción distinta para cada pestaña.
  • callbacks son valores derivados que se vuelven a evaluar cuando cambia el contexto. Los botones de pestaña y los paneles utilizan callbacks.isActiveTab para comprobar si su índice coincide con context.activeTab.
  • data-wp-class--is-active-tab añade o elimina la clase is-active-tab según el valor que devuelve la función de retorno.

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.

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

Novedades:

  • data-wp-on-document--keydown escucha en document en 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 a actions.stopPropagation para impedir que los clics dentro del cuadro lo cierren.
  • role="dialog" y aria-modal="true" indican a los lectores de pantalla que se trata de un cuadro de diálogo modal. aria-label está vinculado para que solo se aplique cuando la ventana modal esté visible.
  • El atributo hidden del 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.

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

Novedades:

  • wp_interactivity_state() inicializa el recuento a partir de PHP. El valor se serializa en HTML de la página y está disponible como state.count en las directivas y JavaScript.
  • state frente a context: el recuento está en state (global y compartido), mientras que liked está en context (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 a store() devuelve un objeto reactivo state al 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:

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<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