Contents
Introducción: ¿qué son los InspectorControls y por qué usarlos?
En el editor de bloques de WordPress (Gutenberg), InspectorControls es el contenedor visual y lógico donde colocamos los controles que afectan a un bloque pero que no forman parte del contenido visible dentro del lienzo del editor. Es el panel de la barra lateral derecha (Sidebar) que aparece al seleccionar un bloque. Usar InspectorControls permite:
- Separar la configuración del contenido visual del bloque.
- Ofrecer controles intuitivos (toggles, selectores de color, rangos, etc.) para editar atributos.
- Persistir valores vía atributos del bloque y usarlos en save o en renderizado servidor.
Requisitos previos
Tener un bloque creado con la API moderna de bloques (ESNext/JSX) y estar cómodo editando el archivo de edición (edit) del bloque. Se dará por hecho que usas @wordpress/scripts o una configuración de build con Babel/webpack que soporte JSX.
Importaciones y estructura básica
Para usar InspectorControls en un bloque funcional típico necesitas importar componentes de los paquetes de WordPress:
import { __ } from @wordpress/i18n
import { useBlockProps, InspectorControls, RichText } from @wordpress/block-editor
import { PanelBody, ToggleControl, TextControl, RangeControl, SelectControl, ColorPalette, CheckboxControl } from @wordpress/components
La estructura mínima del edit será algo así: un fragmento principal para el lienzo y un bloque InspectorControls para la barra lateral.
export default function Edit( { attributes, setAttributes } ) {
const blockProps = useBlockProps()
return (
<>
{/ aquí van los controles /}
{/ UI del bloque en el lienzo: RichText, imágenes, etc. /}
)
}
Definir atributos
Siempre define los atributos del bloque en el registro (registerBlockType o block.json). Los valores que el usuario cambie en InspectorControls deben almacenarse en atributos. Ejemplo sencillo:
const attributes = {
title: { type: string, default: Título por defecto },
showSubtitle: { type: boolean, default: true },
fontSize: { type: number, default: 18 },
alignment: { type: string, default: left },
bgColor: { type: string, default: #ffffff }
}
Ejemplo completo: bloque con varios controles en InspectorControls
A continuación un ejemplo completo (simplificado) de archivo JS del bloque. Incluye PanelBody, ToggleControl, TextControl, RangeControl, SelectControl y un selector de color.
/
Ejemplo: my-plugin/inspector-controls-example
/
import { __ } from @wordpress/i18n
import { registerBlockType } from @wordpress/blocks
import { useBlockProps, InspectorControls, RichText } from @wordpress/block-editor
import { PanelBody, ToggleControl, TextControl, RangeControl, SelectControl, ColorPalette } from @wordpress/components
import { Fragment } from @wordpress/element
registerBlockType( my-plugin/inspector-controls-example, {
title: __( Inspector Controls Example, my-plugin ),
icon: admin-generic,
category: widgets,
attributes: {
title: { type: string, default: Hola Mundo },
showSubtitle: { type: boolean, default: true },
fontSize: { type: number, default: 20 },
alignment: { type: string, default: left },
bgColor: { type: string, default: #ffffff }
},
edit: ( { attributes, setAttributes } ) => {
const { title, showSubtitle, fontSize, alignment, bgColor } = attributes
const blockProps = useBlockProps()
return (
setAttributes( { title: value } ) }
/>
setAttributes( { showSubtitle: value } ) }
/>
setAttributes( { fontSize: value } ) }
min={ 12 }
max={ 48 }
/>
setAttributes( { alignment: value } ) }
/>
{ __( Color de fondo, my-plugin ) }
setAttributes( { bgColor: color } ) }
/>
setAttributes( { title: value } ) }
style={ { fontSize: fontSize px } }
/>
{ showSubtitle { Subtítulo de ejemplo }
}
)
},
save: ( { attributes } ) => {
const { title, showSubtitle, fontSize, alignment, bgColor } = attributes
return (
{ Subtítulo de ejemplo }
}
)
}
} )
Comentarios sobre el ejemplo
- useBlockProps aporta clases y atributos necesarios para la integración en el editor.
- Los controles actualizan atributos con setAttributes. Esos atributos se usan en save para renderizar el HTML que verá el front-end.
- ColorPalette es simple pero si necesitas un panel con accesos a temas, usa PanelColorSettings del paquete block-editor.
Buenas prácticas
- Evitar lógica compleja en InspectorControls. Mantén los controles como puros setters hacia atributos la lógica de renderizado puede estar en el componente edit o en el render PHP si es server-side.
- Validación y saneamiento. Valida los valores (por ejemplo, tamaño mínimo/máximo) antes de guardarlos o en el PHP si usas renderizado en servidor.
- Accesibilidad. Proporciona labels claros, placeholders descriptivos y usa help si el componente lo permite.
- Desempeño. Evita cálculos pesados en cada render memoriza o usa efectos si es necesario (useMemo/useEffect).
- Guardar estilos mínimos. Preferible almacenar valores semánticos (p. ej. tamaño: smallmediumlarge) y mapear a CSS en el front, para facilitar cambios de theme.
Mostrar controles condicionales
A veces quieres mostrar controles solo si se cumple cierta condición (por ejemplo, solo si el bloque tiene un tipo concreto). Esto se consigue con render condicional en JSX:
{ attributes.enableAdvanced ( setAttributes( { advancedValue: v } ) } /> ) }
Estilos del editor y del front-end
Si añades estilos que dependen de atributos (colores, tamaños), puedes:
- Inyectar estilos inline en la salida de save (como en el ejemplo) — simple pero puede ser menos limpio.
- Generar clases CSS dinámicas en save y tener las reglas en un archivo CSS del bloque (pref. con build) — más controlable.
Ejemplo de CSS sencillo para aplicar clases:
.my-plugin-block {
padding: 1rem
border-radius: 4px
}
.my-plugin-block.align-center { text-align: center }
.my-plugin-block.align-right { text-align: right }
Ejemplo de renderizado dinámico en PHP (opcional)
Si prefieres renderizado en servidor, registras un callback PHP en register_block_type. En ese caso InspectorControls sigue gestionando atributos en el editor, pero la salida se genera en PHP usando esos mismos atributos.
/
PHP: register render callback
/
function my_plugin_register_block() {
register_block_type( __DIR__ . /build/inspector-controls-example, array(
render_callback => my_plugin_render_block
) )
}
add_action( init, my_plugin_register_block )
function my_plugin_render_block( attributes ) {
title = isset( attributes[title] ) ? esc_html( attributes[title] ) :
bg = isset( attributes[bgColor] ) ? esc_attr( attributes[bgColor] ) : #fff
align = isset( attributes[alignment] ) ? esc_attr( attributes[alignment] ) : left
fontSize = isset( attributes[fontSize] ) ? intval( attributes[fontSize] ) : 20
ob_start()
?>
text-align:>
px>
Consejos avanzados
- Usa PanelColorSettings para integrar mejor con la paleta del tema.
- Si necesitas controles complejos (p. ej. galerías, listas reordenables), considera componentes de terceros o crear tu propio componente en la barra lateral.
- Para preservar compatibilidad futura, define atributos en block.json si usas el formato basado en JSON y enlaza los archivos JS/CSS con build system.
- Si tu bloque tiene muchas opciones, organiza controles en varios PanelBody con initialOpen adecuado para mejorar UX.
Resumen rápido
- InspectorControls es el lugar adecuado para la configuración de un bloque que no forma parte del DOM principal del contenido.
- Define atributos y actualízalos con setAttributes desde los controles.
- Mantén lógica ligera, valida valores y considera cómo se aplican las clases/estilos en el front-end.
- Para renderizado en servidor, registra un render_callback en PHP y usa los mismos atributos para producir HTML seguro.
Recursos útiles
- Block Edit Save — WordPress Developer
- InspectorControls — Component reference
- Componentes de @wordpress/components
|
|
Acepto donaciones de BAT's mediante el navegador Brave :) |