UI Icons
Un gestor de iconos genérico para Drupal que integra perfectamente paquetes de iconos de terceros utilizando la API de iconos del núcleo de Drupal.
ui_icons
Overview
UI Icons es un sistema completo de gestión de iconos para Drupal que proporciona una forma unificada de integrar, gestionar y mostrar iconos de varios paquetes de iconos de terceros. Construido sobre la API de iconos del núcleo de Drupal (introducida en Drupal 11.1), ofrece una integración perfecta en todo el ecosistema de Drupal, incluyendo campos, menús, editores de texto, entidades de medios y UI Patterns.
El módulo proporciona una arquitectura extensible con múltiples submódulos para integraciones específicas. Los iconos pueden descubrirse desde varias fuentes, incluyendo archivos SVG, fuentes web (TTF/WOFF), archivos de codepoint, JSON y configuraciones YAML. El sistema de búsqueda inteligente utiliza coincidencia difusa con resultados basados en prioridad y caché para un rendimiento óptimo.
Las capacidades principales incluyen un elemento de formulario con autocompletado para la selección de iconos, un selector visual modal, filtros de texto para incrustar iconos en el contenido, integración con CKEditor 5, tipos de campo y widgets para campos de iconos y enlaces, y soporte de iconos en enlaces de menú con posiciones de visualización personalizables.
Features
- Descubrimiento de paquetes de iconos: Descubre y carga automáticamente paquetes de iconos definidos en archivos *.icons.yml desde módulos y temas, soportando múltiples extractores (path, SVG, font, sprite)
- Elemento de formulario con autocompletado: Proporciona un elemento de formulario icon_autocomplete con búsqueda difusa inteligente que prioriza coincidencias exactas, coincidencias de orden de palabras y coincidencias parciales con límites de resultados configurables (predeterminado 24, máximo 132)
- Selector visual de iconos: Selector de iconos basado en modal (icon_picker) para una selección intuitiva de iconos con visualización en cuadrícula y paginación AJAX
- Navegador de biblioteca de iconos: Interfaz de administración en /admin/appearance/ui/icons para explorar todos los paquetes de iconos disponibles con búsqueda, filtrado por grupo y visualización paginada (100 iconos por página)
- Integración de tipo de campo: Tipo de campo Icon (ui_icon) para campos de entidad con restricciones configurables de paquetes de iconos permitidos
- Widget de campo de enlace: Widgets de campo de enlace extendidos (icon_link_widget) para agregar iconos a campos de enlace con opciones de posición (antes, después, solo icono)
- Filtro de texto: Incrustar iconos en el contenido usando etiquetas <drupal-icon> con el filtro icon_embed, soportando configuraciones personalizadas y atributos de accesibilidad
- Integración con CKEditor 5: Inserción visual de iconos en el editor de texto enriquecido con un diálogo dedicado para la selección y configuración de iconos
- Soporte de iconos en menús: Agrega automáticamente la selección de iconos a las entidades de contenido de enlaces de menú con posiciones de visualización configurables e integración con la barra de herramientas del módulo Navigation
- Fuente de medios: Plugin de fuente de medios de iconos para crear entidades de medios de iconos reutilizables con soporte completo de metadatos incluyendo ID del paquete, etiqueta, licencia e información de origen
- Integración con UI Patterns: Plugin de fuente de iconos para UI Patterns 1.x y 2.x con soporte de tipo de prop de icono
- Extractor de fuentes web: Extrae iconos de fuentes web (.ttf, .woff), archivos codepoint, JSON y definiciones YAML usando la biblioteca dompdf/php-font-lib
- Extensión Twig: Función Twig icon_preview(pack_id, icon_id, settings) para renderizar vistas previas de iconos en plantillas
- Compatibilidad con temas: Adaptación automática de CSS para los temas de administración Gin, DaisyUI y DSFR
- Sistema de caché: Caché de búsqueda basado en hash XXH3 con etiquetas de caché de paquetes de iconos y colectores para un rendimiento óptimo
- Gestión de configuración: Soporte de configuración por extractor de icono con generación dinámica de formularios basada en la configuración del paquete de iconos
Use Cases
Agregar iconos de redes sociales al contenido
Habilita UI Icons Fields y agrega un campo Icon a tu tipo de contenido. Configura los paquetes de iconos permitidos para limitar la selección a tu paquete de iconos de redes sociales. Usa el widget de autocompletado o selector para que los editores de contenido seleccionen iconos. Muestra usando el formateador de iconos con configuración de tamaño personalizada.
Crear menús de navegación mejorados con iconos
Habilita UI Icons for Menu para agregar automáticamente selección de iconos a la edición de enlaces de menú. Los editores pueden seleccionar iconos para cada elemento del menú y elegir la posición de visualización (antes del texto, después del texto o solo icono). Los iconos se renderizan automáticamente en la salida del menú con el marcado apropiado.
Incrustar iconos en contenido de texto enriquecido
Habilita UI Icons Text y UI Icons for CKEditor 5. Configura tu formato de texto para habilitar el filtro Embed icon con los paquetes de iconos permitidos. Los usuarios pueden insertar iconos usando el botón de la barra de herramientas de CKEditor. Los iconos se renderizan como etiquetas <drupal-icon> en el contenido y se procesan al mostrar.
Construir una biblioteca de medios de iconos reutilizable
Habilita UI Icons Media y crea un tipo de medio Icon. Los editores de contenido pueden agregar iconos a la biblioteca de medios para reutilizarlos en todo el contenido. Los iconos de medios incluyen metadatos completos (paquete, licencia, fuente) y miniaturas automáticas para navegación visual.
Tematización con integración de iconos
Usa la función Twig icon_preview en las plantillas de tu tema: {{ icon_preview('mi_paquete', 'id_icono', {size: 24}) }}. Los iconos se renderizan usando la plantilla definida por el paquete o la plantilla de respaldo icon-preview.html.twig.
Crear paquetes de iconos personalizados
Define paquetes de iconos en tu módulo o tema usando archivos *.icons.yml. Especifica el tipo de extractor (path, svg, font, sprite), archivos fuente y formularios de configuración opcionales. La API de iconos descubre y registra automáticamente tus iconos para su uso en todo el sitio.
Tips
- Usa el formato de resultados en cuadrícula para el autocompletado de iconos cuando trabajes con paquetes de iconos que tienen muchos iconos similares - la cuadrícula visual ayuda a distinguir entre ellos
- Habilita el submódulo UI Icons Library durante el desarrollo para explorar y probar tus paquetes de iconos antes de integrarlos en el contenido
- Para el rendimiento, limita los paquetes de iconos permitidos en los campos solo a aquellos paquetes realmente necesarios - esto reduce el alcance de búsqueda y mejora la velocidad del autocompletado
- Al usar el filtro icon_embed, siempre incluye atributos ARIA apropiados (aria-label o aria-hidden) para el cumplimiento de accesibilidad
- La búsqueda usa coincidencia difusa con prioridades - las coincidencias exactas de palabras aparecen primero, haciendo que las convenciones de nomenclatura comunes (action-arrow-right) sean altamente buscables
- La configuración de iconos se almacena por paquete, permitiendo diferentes configuraciones visuales para el mismo icono en diferentes contextos
Technical Details
Admin Pages 2
/admin/appearance/ui/icons
Explora todos los paquetes de iconos disponibles en tu sitio. Muestra una cuadrícula de tarjetas de paquetes de iconos con vistas previas (hasta 32 iconos aleatorios por paquete), nombre del paquete, descripción, versión, información de licencia y conteo total de iconos. Incluye un interruptor para mostrar/ocultar paquetes deshabilitados.
/admin/appearance/ui/icons/{pack_id}
Busca y explora iconos dentro de un paquete de iconos específico. Proporciona búsqueda por palabras clave, filtrado por grupo, configuración de ajustes de iconos y visualización paginada de 100 iconos por página a 64px de tamaño.
Permisos 1
Hooks 4
hook_preprocess_menu
Preprocesa elementos de menú para agregar marcado de iconos basado en las opciones de iconos almacenadas en las URLs de enlaces de menú. Maneja los modos de visualización antes, después y solo icono.
hook_link_alter
Altera enlaces para mostrar iconos en el contexto de gestión del menú de administración (/admin/structure/menu/manage) para enlaces con opciones de iconos.
hook_navigation_menu_link_tree_alter
Altera el árbol de enlaces de menú del módulo Navigation para soportar la visualización de iconos con configuración de clases apropiada para la integración de la barra de herramientas.
hook_entity_base_field_info_alter
Altera el campo link en las entidades menu_link_content para usar el widget icon_link_widget, habilitando la selección de iconos en enlaces de menú.
Troubleshooting 5
Asegúrate de que los paquetes de iconos estén correctamente definidos en archivos *.icons.yml con la configuración correcta de extractor y fuente. Limpia las cachés después de agregar o modificar definiciones de paquetes de iconos. Verifica que el paquete de iconos no esté marcado como deshabilitado.
Verifica que el formato de texto tenga el filtro icon_embed habilitado y posicionado después de los filtros filter_html y filter_autop. Asegúrate de que la etiqueta <drupal-icon> esté permitida en las restricciones HTML con los atributos requeridos: data-icon-id, data-icon-settings, class, aria-label, aria-hidden, role.
Instala la biblioteca dompdf/php-font-lib usando Composer. Verifica que los archivos fuente estén correctamente especificados en la definición de tu paquete de iconos con las extensiones de archivo apropiadas (.ttf, .woff, .codepoints, .json, .yml).
Verifica la configuración de 'Paquetes de iconos permitidos' del campo. Si se seleccionan paquetes específicos, solo esos iconos estarán disponibles. Déjalo vacío para permitir todos los paquetes.
Verifica que la plantilla de menú de tu tema renderice correctamente $item['title'] que incluye el marcado del icono. El icono se renderiza en línea con el texto del enlace usando FormattableMarkup.
Security Notes 3
- El filtro icon_embed sanitiza correctamente los atributos HTML para prevenir XSS al renderizar configuraciones de iconos proporcionadas por el usuario
- Los endpoints de autocompletado de iconos requieren el permiso 'access content' para prevenir la enumeración no autorizada de iconos
- La biblioteca UI Icons requiere el permiso 'access ui icons library', manteniendo la exploración de iconos restringida a usuarios autorizados