Saltar al contenido

Componentes

Composición

Los componentes UI incluidos están diseñados para combinarse, no para usarse de uno en uno. Un selector se abre dentro de un cuadro de diálogo, un formulario se valida dentro de un panel lateral y un menú aparece en una fila de tabla. Esta página explica cómo funcionan esas conexiones: cómo se estructuran las familias compuestas, cómo los disparadores transmiten las propiedades de los botones, qué hace por debajo el API de Interactivity y cómo el modelo de capas mantiene coherentes las superficies apiladas.

Familias compuestas

Un componente compuesto consta de un bloque raíz y bloques secundarios. La raíz controla el estado; cada elemento secundario declara su lugar en la familia mediante parent y usesContext en su block.json:

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

Las raíces exponen un área InnerBlocks con una lista de allowedBlocks y un template inicial, de modo que al insertar un cuadro de diálogo en el editor se generan su disparador, fondo y ventana emergente. Así, una familia se comporta igual si se compone en el editor, en una página basada en archivos o mediante etiquetas:

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>

Las ventanas emergentes y los paneles son áreas InnerBlocks reales, no espacios reservados con sintaxis especial. Un bsui/dialog-popup acepta bloques anidados igual que un bloque de grupo, lo que permite insertar un formulario, un selector u otro cuadro de diálogo como una composición normal.

Datos planos o elementos secundarios compuestos

Algunas familias aceptan el contenido como datos en vez de elementos secundarios. El selector genera su propio disparador y lista de opciones cuando se le proporciona una matriz options JSON, adecuada para opciones procedentes 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'],
    ]),
  ],
]);

Ambas formas producen el mismo contrato de marcado y el mismo comportamiento en tiempo de ejecución. Use elementos secundarios cuando se defina la estructura y options cuando se calcule.

Transmisión de propiedades del disparador

Los componentes superpuestos se abren desde un botón, que debe ser el botón del sistema. En vez de volver a implementar uno en cada disparador, los bloques de activación de bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible y bsui/tooltip incorporan bsui/button mediante un campo de bloque:

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

El idStructure añade los campos del botón al disparador con el prefijo trigger_. Están disponibles todas las propiedades del botón: 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" />

En la plantilla del disparador, $a['trigger'] es el botón completamente renderizado, de modo que su hoja de estilos y futuras mejoras lo acompañan. En tiempo de ejecución, una función auxiliar compartida transmite al botón interno las conexiones ARIA del contenedor (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) y las mantiene sincronizadas mediante un MutationObserver, para que las tecnologías de asistencia perciban un único control coherente.

El API de Interactivity subyacente

Cada familia interactiva es un WordPress Interactivity API almacén con el nombre de su bloque raíz: bsui/dialog, bsui/select, bsui/form, bsui/tabs, etc. De ello se derivan tres consecuencias.

El estado se inicializa en el servidor. La plantilla raíz imprime su estado inicial como data-wp-context, directamente a partir de los atributos del bloque:

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

La primera representación se muestra correctamente HTML, sin parpadeo durante la hidratación del cliente; las ventanas emergentes empiezan hidden, y el mismo marcado funciona en el lienzo del editor porque el contexto no depende de un paso de estado exclusivo del frontend.

El comportamiento se conecta mediante directivas, no con su JavaScript. Las plantillas conectan el marcado con los almacenes de forma declarativa. El disparador del selector, sin su PHP, solo contiene directivas:

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 dirige los eventos a acciones, data-wp-bind mantiene los atributos sincronizados con el estado derivado, data-wp-text muestra el estado como texto y data-wp-on-document--click permite que las raíces se cierren al hacer clic fuera. Componer componentes no requiere escribir manejadores de eventos; el almacén se incluye con el bloque como módulo integrado.

Sus almacenes pueden conectarse a estos componentes. Los controles de formulario aceptan expresiones de directiva como atributos, y la sintaxis con espacio de nombres del API de Interactivity los vincula a cualquier almacén. onChange dirige la gestión de cambios a una de sus acciones, checked vincula el estado del control con su estado y bindText muestra una etiqueta como un tramo data-wp-text vinculado a cualquier ruta 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á disponible en los elementos bsui/label, bsui/checkbox, bsui/switch, bsui/toggle y bsui/radio-group. En las casillas de verificación, interruptores y opciones de radio, se integra en la primitiva de etiqueta compartida, por lo que el texto controlado por el estado conserva exactamente la tipografía de las etiquetas del sistema. Los selectores y otros campos también generan un evento change con propagación desde su raíz, que incluye el nuevo valor en detail para integraciones más generales.

Valores controlados

Deja value o checked sin definir si el control gestiona su propio valor. Usa defaultValue, defaultChecked o defaultPressed de Toggle para la selección inicial. Un Toggle independiente gestiona la entrada del puntero y del teclado sin un almacén consumidor.

Para controlar un campo desde tu propio almacén, proporciona tanto su enlace como una acción onChange que actualice el valor enlazado. value es una ruta de directiva, no un valor predeterminado literal. Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating y Time Picker admiten value. Checkbox, Switch y Toggle usan checked en su lugar.

Califica las rutas con el espacio de nombres propietario, por ejemplo my/settings::context.quantity o my/settings::state.quantity. Los controles compuestos tienen su propio espacio de nombres; una ruta sin calificar hace referencia a ese control, no automáticamente al almacén principal. Los enlaces de valores compuestos admiten rutas con puntos hacia el contexto o el estado, incluidas las claves numéricas de matrices, pero no expresiones JavaScript ni llamadas a funciones.

Aquí tienes un enlace completo de Number Field en un bloque personalizado con la compatibilidad con Interactivity API activada:

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

Establece el valor predeterminado correspondiente al valor inicial renderizado en el servidor. Una vez hidratado, los cambios del elemento principal actualizan todas las instancias enlazadas, incluidos los valores cero, falso y vacío. Los campos ocultos de formulario de Checkbox y Switch también siguen su enlace checked. Los valores de Time Picker usan HH:MM en formato de 24 horas o una cadena vacía. Para los controladores nativos de Input, Textarea y Password Input, lee event.target.value; los controles de valor compuestos publican event.detail.value. Los límites de Number Field son opcionales: si se omiten min y max, el campo no tiene límites, mientras que cero explícito sigue siendo un límite válido.

Select, Date Input, Phone Input y OTP Input publican los cambios mediante onChange, pero no exponen este enlace value controlado. Usa sus propiedades predeterminadas documentadas para los valores iniciales.

Componer desde sus propios bloques

La composición no se limita a las páginas. Las etiquetas de bloque se procesan automáticamente dentro de las plantillas de bloque, así que un bloque del proyecto puede generar componentes bsui directamente y envolverlos en su propia estructura:

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>

También funciona desde PHP con bs_block(), incluso con anidamiento mediante la clave content, como se describe en renderizado programático. En ambos casos, la hoja de estilos y el almacén del componente se cargan con él, y su bloque sigue siendo una capa ligera que organiza las piezas del sistema.

Para disponer los componentes en filas o columnas, bsui/stack es la fila o columna flex genérica: direction, gap en la escala de espaciado, align, justify y un conmutador wrap. De forma predeterminada, los elementos secundarios mantienen su tamaño natural; el conmutador grow los estira para que compartan por igual la longitud de la pila. Así, en un pie de página, dos botones se reparten el ancho en vez de amontonarse en un extremo.

Grupos de campos y tarjetas

bsui/field-group renderiza un conjunto de campos. La variante predeterminada agrupa campos relacionados sin añadir una superficie. Usa variant="card" para añadir un marco exterior atenuado y, después, coloca los campos dentro de bsui/field-group-content para obtener una superficie de contenido insertada. Mantén el título y la descripción fuera de ese bloque de contenido:

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" del grupo usa el comportamiento nativo de fieldset para desactivar sus controles de formulario. El estilo de tarjeta no cambia la variante predeterminada.

Separadores de la barra de herramientas

Coloque bsui/toolbar-separator entre los elementos de la barra de herramientas. Sigue la orientation del elemento principal: una barra horizontal obtiene un separador vertical de altura completa y una barra vertical obtiene un separador horizontal de ancho completo. Los separadores se extienden hasta los bordes interiores del contorno de la barra sin cambiar la altura de los controles. Una barra horizontal se desplaza cuando su contenido supera el ancho disponible.

El modelo de capas

Las superficies apiladas suelen ser el punto donde fallan las bibliotecas de componentes. Los componentes incluidos siguen un pequeño conjunto de reglas pensadas para quienes crean interfaces reales.

Los modales se insertan en el cuerpo

Cuando se abre un cuadro de diálogo, un cuadro de diálogo de alerta o un panel lateral, su ventana emergente y su fondo se trasladan a document.body, y se deja un comentario como marcador de posición para indicar dónde deben volver al cerrarse. La inserción en el cuerpo libera el modal del overflow, las transformaciones y los contextos de apilamiento de sus ancestros. Al abrirlo también se bloquea el desplazamiento de la página: el bloqueo contabiliza las referencias de todos los componentes superpuestos y compensa el ancho de la barra de desplazamiento para que la página no se desplace. El fondo queda en z-index: 50 y la ventana emergente en 51; el foco pasa a la ventana emergente, queda atrapado en ella al pulsar Tab y vuelve al disparador al cerrarla.

Los modales se apilan. Abrir un diálogo desde otro diálogo lo añade a una pila compartida: solo el diálogo más externo muestra su fondo, y los diálogos que quedan detrás del superior se reducen y asoman por detrás. La pila controla una propiedad personalizada --bs-ui-nested-dialogs en cada ventana emergente de fondo, de modo que el desplazamiento y la escala del efecto aumentan con cada nivel, y el elemento principal ajusta su altura a la del secundario para que las capas asomen por igual. Al cerrar, todo se restaura en orden inverso, una capa cada vez.

Al cerrar un modal, el foco vuelve al elemento que lo abrió, y vuelve al elemento correcto. Un helper compartido getAnchor resuelve el contenedor del activador y localiza el botón del sistema que contiene, para que recupere el foco el control visible y no un contenedor invisible.

El modal superior nunca se transforma

El efecto de asomar transforma únicamente los diálogos de fondo. El modal superior permanece deliberadamente sin transformar, porque un elemento transformado se convierte en el bloque contenedor de sus descendientes position: fixed, lo que rompería todas las ventanas emergentes flotantes que se abrieran en su interior.

Esta es la regla que permite combinar todo el modelo de capas. Todas las capas flotantes se posicionan con coordenadas fijas, que solo se refieren a la ventana gráfica mientras no haya un antecesor transformado:

  • El menú y el cuadro combinado calculan su posición respecto al activador mediante la estrategia fixed de Floating UI: aparecen debajo y cambian de lado o se desplazan si la ventana gráfica no tiene espacio.
  • El selector hace lo mismo cuando no hay nada seleccionado. Si ya hay una selección, alinea su ventana emergente para que la opción seleccionada quede justo encima del activador, dentro de los límites de la ventana gráfica, como hacen los selectores nativos en macOS.
  • El menú contextual se abre en las coordenadas clientX/clientY del puntero.

Como el modal superior no está transformado, todos estos elementos se anclan correctamente a sus activadores dentro de un diálogo, un diálogo de alerta o un panel lateral, sin importar la profundidad del anidamiento. Ninguna ventana emergente sabe que está dentro de un modal, ni necesita saberlo.

Escape cierra primero la capa más interna

Cada pulsación de Escape cierra exactamente una capa, de dentro hacia fuera:

  1. Primero se cierra una capa flotante abierta (un cuadro de lista de un selector, un menú, un panel emergente o una ventana emergente de fecha o teléfono) y el foco vuelve a su activador. El selector detiene la propagación del evento, y los controladores del modal también dejan de actuar siempre que haya abierta alguna capa flotante, así que el diálogo subyacente nunca recibe esa pulsación.
  2. Después se cierra el modal superior.
  3. Si hay varios modales apilados, cada pulsación adicional de Escape quita uno más de la pila.

El cierre es una política, no un accidente. Un diálogo renderizado con dismissable="false" ignora tanto Escape como los clics en el fondo. Y bsui/alert-dialog responde a Escape como cualquier modal, pero ignora deliberadamente los clics en el fondo: el objetivo de este patrón es que haya que tomar esa decisión, en lugar de cerrar algo por accidente. Los clics en el fondo cierran un diálogo normal, ya que dismissable tiene el valor predeterminado true.

Un formulario en un diálogo

El patrón que pone en práctica todas las reglas anteriores a la vez: un activador abre un modal, el modal contiene un formulario con validación y el formulario incluye un selector flotante.

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>

Todas las etiquetas y atributos anteriores son esenciales: el activador reenvía al botón del sistema, el título y la descripción reciben content, los campos incluyen los nombres que serializa el formulario, y required="true" se convierte en un booleano real en el analizador de etiquetas.

Qué hace cada almacén en tiempo de ejecución

bsui/dialog inicializa {"open":false,"dismissable":true} en el contexto del servidor. Al hacer clic en el activador, se ejecuta actions.open: la ventana emergente y el fondo se trasladan al body, el desplazamiento se bloquea con compensación para la barra de desplazamiento, la ventana emergente aparece con una animación de 150ms, el foco pasa a su primer elemento enfocable y Tab recorre los elementos dentro de ella. Las regiones del encabezado, el contenido y el pie distribuyen el espacio según los tokens de separación del modal.

bsui/select espera dentro del formulario con el cuadro de lista hidden. Al hacer clic en el activador, se alterna context.open, el cuadro de lista se posiciona con coordenadas fijas de la ventana gráfica y, como defaultValue="editor" ya está seleccionado, la ventana emergente se alinea para que Editor quede justo encima del activador. Las teclas de flecha, Inicio, Fin y la búsqueda por caracteres cambian la opción activa; Enter o un clic la seleccionan; Tab y los clics fuera cierran la ventana sin seleccionar. El texto visible del activador se actualiza mediante data-wp-text="state.displayValue", y el campo oculto <input name="role"> mantiene el valor mediante data-wp-bind--value="state.selectedValue", que es lo que luego serializa el formulario. Todo se ancla correctamente dentro del diálogo porque el modal superior no está transformado.

bsui/form intercepta el envío. El bsui/button al final del formulario muestra un elemento button simple sin atributo type, por lo que es el control de envío del formulario por defecto de HTML; el botón Cancelar está en el pie, fuera del elemento form, y no puede enviar nada. Al enviar, el almacén serializa el FormData del formulario y lo envía a través del API de datos del bloque indicado en block, creando aquí una fila en el esquema de base de datos de team/invite esquema de base de datos. Los errores de validación se devuelven por campo: cada bsui/field recibe su name, se marca como no válido, redirige el anillo de enfoque al color destructivo y muestra el mensaje en su alerta bsui/field-error. Si todo sale bien, el cuerpo del formulario se oculta y aparece successMessage, ambos mediante data-wp-bind--hidden.

Las capas se cierran en orden. Con el cuadro de lista abierto, Escape lo cierra y devuelve el foco al activador del selector; la siguiente pulsación de Escape cierra el diálogo y devuelve el foco a Invitar a un compañero de equipo. Un clic en el fondo cierra el diálogo porque dismissable conservó su valor predeterminado. Al cerrarlo, se desbloquea el desplazamiento y la ventana emergente vuelve a su lugar en el documento.

El mismo marcado pegado en una página basada en archivos se sincroniza como bloques nativos, y la misma composición creada en el editor se previsualiza de forma interactiva en el lienzo, porque todos los comportamientos anteriores dependen de directivas y almacenes que se cargan en ambos contextos.

Qué mantiene estas conexiones en funcionamiento

Las conexiones anteriores no son convenciones, sino invariantes que la biblioteca mantiene dondequiera que renderice: todas las etiquetas se resuelven con una tipografía idéntica, todas las ventanas emergentes modales comparten la misma superficie y atenúan la página detrás de ellas, las ventanas emergentes flotantes permanecen ancladas al activador mientras se desplaza la página, y Escape cierra exactamente una capa cada vez, de dentro hacia fuera. Estas garantías se mantienen tanto en el frontend como en el lienzo del editor, con los tokens predeterminados o los de tu tema, así que una composición que funciona en un contexto se comporta igual en los demás.

Ejemplos interactivos

Las composiciones de esta página son la gramática; /ui/examples es el libro de frases. Reúne composiciones renderizadas e interactivas en tres niveles: pares que demuestran una conexión entre dos o tres componentes, patrones de producto reconocibles creados con unos cuantos de ellos y miniaplicaciones completas ensambladas como los componentes que se incluyen en productos reales. Cada página de componente en /ui añade sus propios ejemplos prácticos, desde un campo con etiqueta hasta un calendario detrás de un panel emergente.

Interactividad

El modelo de directivas y almacenes en el que se basan los componentes UI y cómo utilizarlo en tus propios bloques.