SVG Formatter
Proporciona un formateador de campo que permite mostrar imágenes SVG en sitios web Drupal a través de campos de archivo e imagen.
svg_formatter
Instalar
composer require 'drupal/svg_formatter:^2.0'
composer require 'drupal/svg_formatter:8.x-1.18'
Overview
El módulo SVG Formatter aborda una limitación fundamental en el campo de imagen estándar de Drupal, que no soporta de forma nativa imágenes SVG (Scalable Vector Graphics). Este módulo proporciona un formateador de campo especializado que puede aplicarse a campos de archivo o campos de imagen (cuando se usa con el módulo SVG Image), permitiendo que los archivos SVG se muestren en su sitio web.
El módulo ofrece dos modos de salida: salida estándar con etiqueta de imagen usando el elemento <img>, o salida SVG en línea donde el marcado SVG se incrusta directamente en el HTML. El modo en línea es particularmente útil cuando necesita manipular el SVG con CSS o JavaScript, como para animaciones, gráficos interactivos o cambios dinámicos de color.
Una característica de seguridad clave es la integración con la biblioteca enshrined/svg-sanitize, que sanea el contenido SVG en línea para prevenir ataques XSS (Cross-Site Scripting). Esto es crítico cuando se permite a los usuarios subir archivos SVG, ya que los SVG maliciosos pueden contener código JavaScript incrustado. El módulo también soporta dimensiones configurables, texto alternativo y atributos de título con integración de Token para valores dinámicos.
Features
- Proporciona el formateador de campo SVG Formatter para tipos de campo de archivo e imagen
- Modo de salida SVG en línea para manipulación CSS y JavaScript de gráficos SVG
- Saneamiento de SVG usando la biblioteca enshrined/svg-sanitize para prevenir ataques XSS de cargas de SVG maliciosos
- Dimensiones de imagen configurables (ancho y alto) que pueden aplicarse tanto a elementos SVG en línea como a etiquetas img
- Soporte de atributo alt con generación automática desde el nombre de archivo o valores personalizados basados en Token
- Soporte de atributo title para accesibilidad, añade automáticamente aria-labelledby para SVGs en línea
- Integración con Token para valores dinámicos de alt y title basados en campos de entidad (requiere el módulo Token)
- Filtrado automático para procesar solo archivos con tipo MIME image/svg+xml
- Compatible tanto con campos de archivo como de imagen (los campos de imagen requieren el módulo SVG Image)
Use Cases
Mostrar logos e iconos con personalización CSS
Use el modo SVG en línea para mostrar logos de marca o iconos que necesiten cambiar de color según el tema o la interacción del usuario. Con SVG en línea, puede apuntar a elementos SVG con selectores CSS para cambiar colores de relleno, anchos de trazo o aplicar efectos hover.
Gráficos vectoriales responsivos
Muestre ilustraciones, diagramas o infografías como imágenes SVG que escalan perfectamente a cualquier resolución. Configure las dimensiones en el formateador o déjelas para ser controladas por CSS para un comportamiento completamente responsivo.
Iconografía accesible
Cree conjuntos de iconos accesibles habilitando los atributos alt y title. Use tokens para generar dinámicamente texto descriptivo basado en el contenido, asegurando que los lectores de pantalla puedan describir adecuadamente las imágenes.
Contenido SVG subido por usuarios con seguridad
Permita que editores de contenido o usuarios del sitio suban imágenes SVG mientras protege contra ataques XSS. Habilite la opción de saneamiento para eliminar automáticamente scripts potencialmente maliciosos y manejadores de eventos de SVGs subidos.
Visualizaciones de datos interactivas
Use el modo SVG en línea para mostrar gráficos, diagramas o mapas interactivos que puedan ser manipulados con JavaScript. El modo en línea expone los elementos DOM del SVG, permitiendo que bibliotecas como D3.js interactúen con los gráficos.
Tips
- Para mejor manipulación CSS, use el modo SVG en línea y asegúrese de que sus archivos SVG usen clases o IDs en los elementos que quiere estilizar.
- La integración con el módulo Token permite usar tokens como [node:title] o [file:name] para texto dinámico de alt y title basado en la entidad padre.
- El texto alt se genera automáticamente desde el nombre del archivo si no se especifica un token personalizado - 'my-icon.svg' se convierte en 'My icon'.
- Para accesibilidad, los SVGs en línea con title habilitado incluyen automáticamente atributos aria-labelledby enlazando al elemento title.
- El formateador omite automáticamente archivos no SVG en campos de múltiples valores, así que puede mezclar SVG y otros tipos de archivo en el mismo campo.
Technical Details
Hooks 2
hook_help
Implementa hook_help para proporcionar documentación del módulo en la página de ayuda.
hook_theme
Implementa hook_theme para registrar el hook de tema svg_formatter con sus variables.
Troubleshooting 5
Instale el módulo SVG Image (drupal/svg_image). El formateador solo aparece para campos de imagen cuando el módulo SVG Image está instalado, ya que el campo de imagen del core de Drupal no soporta cargas de SVG por defecto.
Verifique que la biblioteca enshrined/svg-sanitize esté instalada. Ejecute 'composer require enshrined/svg-sanitize' si falta. La casilla de saneamiento estará deshabilitada si la biblioteca no se encuentra.
Instale y habilite el módulo Token para soporte de tokens. El módulo proporciona un navegador de tokens en la configuración del formateador para ayudar a seleccionar tokens válidos para su tipo de entidad.
Asegúrese de que 'Establecer dimensiones de imagen' esté habilitado en la configuración del formateador. Para SVGs en línea, las dimensiones se establecen como atributos en el elemento raíz del SVG. Algunos SVGs pueden anular esto con CSS interno - revise el código fuente del SVG.
El archivo SVG puede tener XML inválido o problemas de codificación. Asegúrese de que el SVG sea XML válido y use codificación UTF-8. El módulo usa DOMDocument para analizar SVGs, lo cual requiere XML bien formado.
Security Notes 4
- Siempre instale el módulo vía Composer para asegurar que la biblioteca enshrined/svg-sanitize esté incluida. Sin esta biblioteca, los SVGs en línea no serán saneados y pueden exponer su sitio a vulnerabilidades XSS.
- Cuando permita a usuarios no confiables subir archivos SVG, siempre habilite la opción 'Sanear SVG en línea' para eliminar código JavaScript potencialmente malicioso incrustado en archivos SVG.
- La biblioteca de saneamiento elimina etiquetas script, manejadores de eventos y otros elementos potencialmente peligrosos de archivos SVG cuando se usa el modo en línea.
- Cuando se usa el modo no en línea (etiqueta img), los SVGs se tratan como recursos externos y la seguridad del navegador previene la ejecución de scripts, haciendo el saneamiento menos crítico pero aún recomendado para defensa en profundidad.