Saltar al contenido

Componentes

Blockstudio incluye 59 UI componentes en cada compilación. Se registran automáticamente, se diseñan con tokens de diseño y se crean con la misma sintaxis de etiquetas que cualquier otro bloque.

Blockstudio 7.3 incluye un conjunto integrado de bloques UI sin interfaz propia, impulsados por WordPress Interactivity API. Están registrados en el espacio de nombres bsui/* y se pueden combinar en plantillas, páginas basadas en archivos, patrones y contenido de entradas.

Nota

Los componentes UI están en fase beta mientras recopilamos comentarios sobre el conjunto de componentes, su nomenclatura, comportamiento y patrones de uso en proyectos. Ya se pueden probar en 7.3, pero es posible que la interfaz de API se ajuste antes de declararse estable.

Activar los componentes UI

Los componentes UI incluidos están desactivados de forma predeterminada. Actívalos en el blockstudio.json de tu tema:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

O actívalos con un filtro:

PHP
add_filter('blockstudio/settings/ui/enabled', '__return_true');

Al activarlo, Blockstudio registra la biblioteca de componentes incluida desde includes/ui/blocks.

Inventario público y ejemplos

Los bloques de implementación incluidos siguen siendo registros normales de bsui/*, pero quienes los usan deben consultar el inventario público de familias al crear una galería de componentes:

PHP
use Blockstudio\Ui;

$families = Ui::inventory();
$examples = Ui::examples();

Ui::inventory() agrupa cada componente compuesto bajo su raíz pública y enumera los registros de implementación que requiere esa familia. Ui::examples() añade una declaración normalizada determinista con datos predeterminados e ilustrativos. Conserva las relaciones necesarias entre la raíz y sus elementos secundarios, por lo que el resultado se puede pasar directamente a Blockstudio\Render::document().

El inventario público de Canvas expone estos ejemplos con el tipo ui y omite los registros de implementación incluidos del tipo normal blocks. Así se obtiene un ejemplo completo por cada familia de componentes pública, en lugar de una galería de fragmentos internos de raíz, activador, ventana emergente y capa.

Al ensamblar un documento ya renderizado, Ui::global_assets($block_names, $html) devuelve el estilo y el script globales incluidos exactos solo cuando la salida seleccionada utiliza realmente un componente UI.

Renderizado

Usa la sintaxis normal de etiquetas de bloque:

HTML
<block name="bsui/button" label="Save" variant="default"></block>

También funciona la sintaxis abreviada <bs:>:

HTML
<bs:bsui-button label="Save" variant="default" />

En las plantillas Blockstudio, las etiquetas de bloque se renderizan automáticamente. En las páginas basadas en archivos y los patrones, se sincronizan como bloques nativos de WordPress. Si quieres renderizar componentes UI directamente desde el contenido de las entradas o las áreas de widgets, activa las etiquetas de bloque a nivel de página:

JSON
{
  "ui": {
    "enabled": true
  },
  "blockTags": {
    "enabled": true,
    "allow": ["bsui/*", "app/*"]
  }
}

Componentes básicos

Los componentes simples se renderizan como un único bloque:

HTML
<block name="bsui/button" label="Continue" variant="default"></block>
<block name="bsui/badge" label="Beta"></block>
<block
  name="bsui/input"
  nameAlt="email"
  type="email"
  placeholder="Email"
></block>
<block name="bsui/textarea" name="message" placeholder="Message"></block>
<block name="bsui/spinner"></block>

Los atributos se asignan directamente a los atributos block.json de cada componente. Por ejemplo, bsui/button admite label, icon, iconPosition, href, variant, size y disabled.

PHP
bs_render_block([
  'name' => 'bsui/button',
  'data' => [
    'label' => 'Continue',
    'icon' => [
      'set' => 'heroicons',
      'subSet' => 'outline',
      'icon' => 'arrow-right',
    ],
    'iconPosition' => 'right',
  ],
]);

Componentes compuestos

Muchos componentes UI son bloques compuestos. El bloque raíz administra el estado y los bloques secundarios declaran cuál es su elemento principal.

Pestañas

HTML
<block name="bsui/tabs" defaultValue="tab1">
  <block name="bsui/tabs-list">
    <block name="bsui/tabs-trigger" value="tab1" title="Features"></block>
    <block name="bsui/tabs-trigger" value="tab2" title="Pricing"></block>
    <block name="bsui/tabs-trigger" value="tab3" title="FAQ"></block>
  </block>
  <block name="bsui/tabs-panel" value="tab1">
    <p>Features content.</p>
  </block>
  <block name="bsui/tabs-panel" value="tab2">
    <p>Pricing content.</p>
  </block>
  <block name="bsui/tabs-panel" value="tab3">
    <p>FAQ content.</p>
  </block>
</block>

Diálogo

HTML
<block name="bsui/dialog">
  <block name="bsui/dialog-trigger" label="Open Dialog"></block>
  <block name="bsui/dialog-backdrop"></block>
  <block name="bsui/dialog-popup">
    <p>Dialog content.</p>
    <block name="bsui/dialog-close" label="Close"></block>
  </block>
</block>

Selector

HTML
<block name="bsui/select" placeholder="Choose a fruit" nameAlt="fruit">
  <block name="bsui/select-trigger"></block>
  <block name="bsui/select-popup">
    <block name="bsui/select-option" value="apple" label="Apple"></block>
    <block name="bsui/select-option" value="banana" label="Banana"></block>
    <block name="bsui/select-option" value="cherry" label="Cherry"></block>
  </block>
</block>

Campos de formulario

HTML
<block name="bsui/form" block="contact/form" successMessage="Thank you!">
  <block name="bsui/field">
    <block name="bsui/field-label" text="Email"></block>
    <block name="bsui/input" nameAlt="email" type="email"></block>
    <block name="bsui/field-error"></block>
  </block>
</block>

Bloques disponibles

La biblioteca UI incluida contiene:

Área Bloques
Diseño bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
Acciones bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
Entradas bsui/checkbox, bsui/color-picker, bsui/date-input, bsui/file-upload, bsui/input, bsui/number-field, bsui/otp-input, bsui/password-input, bsui/phone-input, bsui/radio-group, bsui/rating, bsui/select, bsui/slider, bsui/switch, bsui/textarea, bsui/time-picker
Superposiciones bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
Navegación bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs
Comentarios bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast
Formularios bsui/field, bsui/field-group, bsui/form

Los componentes compuestos también exponen bloques secundarios como bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup y bsui/select-option.

Estilos

Los componentes UI incluyen sus propias propiedades personalizadas de CSS con el prefijo --bs-ui-*. Puedes sobrescribirlas desde el CSS de tu tema:

CSS
:root {
  --bs-ui-radius: 0.5rem;
  --bs-ui-primary: oklch(0.45 0.18 260);
  --bs-ui-primary-foreground: white;
}

Los componentes no incluyen una interfaz predeterminada, pero tienen opiniones suficientes para poder usarse desde el primer momento. Sobrescribe primero los tokens y luego añade CSS específicos de cada componente cuando sea necesario.

El CSS de los componentes incluidos se emite en la capa de cascada bsui indicada. El CSS del tema que no esté en una capa puede sobrescribir las reglas de los componentes sin !important:

CSS
.button-brand {
  background: var(--brand-primary);
}

Para añadir una variante personalizada de bsui/button, agrega la opción del selector con el filtro de atributos existente y proporciona el CSS de la variante con blockstudio/ui/button/variants-style:

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (($block['name'] ?? '') === 'bsui/button' && ($attribute['id'] ?? '') === 'variant') {
    $attribute['options'][] = [
      'label' => 'Brand',
      'value' => 'brand',
    ];
  }

  return $attribute;
}, 10, 2);

add_filter('blockstudio/ui/button/variants-style', function($css) {
  return $css . '
[data-bsui-button][data-variant="brand"] {
  background: var(--brand-primary);
  color: white;
}';
});

Todos los componentes

Acordeón Secciones apiladas que despliegan un panel a la vez. Cuadro de diálogo de alerta Un modal que interrumpe el flujo y requiere una respuesta antes de cerrarse. Relación de aspecto Mantiene el contenido en una proporción fija entre ancho y alto. Avatar Una imagen de usuario que muestra sus iniciales si no se puede cargar. Insignia Una etiqueta pequeña para estados, recuentos y categorías. Ruta de navegación Muestra la posición de la página actual dentro de la jerarquía. Botón Activa una acción con variantes para cada nivel de énfasis. Grupo de botones Agrupa botones relacionados en un único control segmentado. Calendario Una cuadrícula de fechas para seleccionar un solo día. Tarjeta Un contenedor que agrupa un encabezado, un cuerpo y un pie. Carrusel Una secuencia de diapositivas que permite deslizarse y ofrece compatibilidad con el teclado. Casilla de verificación Una opción binaria que también admite un estado indeterminado. Plegable Oculta y muestra una única región de contenido. Selector de color Permite elegir un color y enviarlo con el formulario correspondiente. Cuadro combinado Un campo de texto que filtra una lista de opciones mientras escribes. Menú contextual Acciones que aparecen al hacer clic con el botón derecho y se anclan al puntero. Campo de entrada de fecha Un campo enmascarado para escribir fechas sin un selector. Cuadro de diálogo Una capa modal para tareas que requieren atención y confirmaciones. Panel deslizante Un panel que se desliza desde cualquier borde de la pantalla. Campo Agrupa un control con su etiqueta, descripción y error. Grupo de campos Agrupa campos relacionados bajo un título común. Carga de archivos Una zona para soltar archivos y un selector compatible con varios archivos. Formulario Envía sus campos e informa del éxito sin recargar la página. Entrada Un campo de texto de una sola línea para los tipos de entrada habituales. Atajo de teclado Muestra un atajo de teclado en una tecla propia. Etiqueta Un texto para un control que comparten todos los componentes etiquetados. Menú Una lista desplegable de acciones anclada a un activador. Barra de menús Una barra horizontal de menús, como en una aplicación de escritorio. Medidor Muestra una medida dentro de un intervalo conocido. Menú de navegación Navegación del sitio con enlaces anidados y paneles al pasar el cursor. Campo numérico Una entrada numérica con controles de incremento y un intervalo limitado. Entrada de código OTP Casillas separadas para introducir un código de acceso de un solo uso. Paginación Enlaces de página con opciones anterior, siguiente y truncamiento. Campo de contraseña Un campo de contraseña con un interruptor para mostrarla. Campo de teléfono Un campo de teléfono con selección de país y formato. Menú emergente Contenido enriquecido anclado a un activador que se cierra al hacer clic fuera. Tarjeta de vista previa Una tarjeta al pasar el cursor que muestra una vista previa del destino de un enlace. Progreso Muestra el progreso de una tarea. Grupo de opciones de radio Un conjunto de opciones en el que se puede seleccionar exactamente una. Valoración Un control de estrellas para asignar una puntuación. Área de desplazamiento Un contenedor desplazable con barras de desplazamiento superpuestas y con estilo. Seleccione Una lista desplegable para elegir entre varias opciones. Separador Una línea que separa contenido o grupos de controles. Esqueleto Una forma de marcador de posición que se muestra mientras se carga el contenido. Deslizador Permite elegir un valor o intervalo arrastrando a lo largo de una pista. Espacio Un paso vertical fijo de la escala de espaciado. Indicador giratorio Indica que hay trabajo en curso cuya duración se desconoce. Pila Organiza los elementos secundarios en una fila o columna con un espaciado uniforme. Interruptor Activa o desactiva un ajuste que se aplica de inmediato. Tabla Datos tabulares con ordenación opcional y filas alternas. Pestañas Alterna entre paneles que ocupan el mismo espacio. Text Muestra texto con el tamaño y la etiqueta semántica elegidos. Área de texto Un campo de texto de varias líneas que crece según el número de filas. Selector de hora Permite elegir una hora del día con el intervalo seleccionado. Proveedor de notificaciones emergentes Aloja notificaciones temporales en una esquina de la pantalla. Alternancia Un botón que permanece presionado para representar el estado activado. Grupo de alternancia Un conjunto de interruptores que permite elegir una o varias opciones. Barra de herramientas Una fila de controles entre los que se desplaza el foco. Información sobre herramientas Una breve indicación que aparece al pasar el cursor o al enfocar.