Guía práctica del soporte de SVG en React Native

Conclusiones clave

Empaqueta los iconos pequeños y confiables como componentes cuando importen el estilo y la disponibilidad sin conexión.
Trata el SVG remoto como entrada no confiable y define políticas explícitas de red y de saneamiento.
Usa el viewBox como contrato de escalado y prueba las relaciones de aspecto en ambas plataformas móviles.

React Native no renderiza SVG arbitrario a través del DOM web. Por lo general, los equipos usan una biblioteca nativa de SVG, transforman archivos de confianza en tiempo de compilación o solicitan recursos rasterizados ya preparados en tiempo de ejecución.

Usa el modelo de renderizado nativo

React Native no proporciona un DOM de navegador, por lo que las suposiciones de la web sobre <img>, el XML en línea, los selectores de CSS y los eventos de SVG no se trasladan directamente. Un paquete SVG nativo asigna los elementos y las propiedades de SVG compatibles a las API de dibujo en iOS y Android. Por lo tanto, el paquete, la plataforma y la configuración de compilación definen el conjunto real de funcionalidades.

Trata la compatibilidad con SVG como una dependencia de la aplicación y no como una capacidad de la extensión de archivo. Registra qué elementos, funcionalidades de pintado, filtros, comportamientos de texto, máscaras y referencias externas admite el renderizador seleccionado. Vuelve a revisar esa matriz cuando actualices React Native, el renderizador o cualquiera de las dos plataformas móviles.

Clasifica el material gráfico por confianza y ciclo de vida

Los iconos propios del producto se conocen en tiempo de compilación, se revisan junto con la aplicación y suelen ser pequeños. El material gráfico proporcionado por los clientes llega en tiempo de ejecución, puede cambiar de forma independiente de la versión publicada y debe tratarse como no confiable. Las ilustraciones de marketing pueden ser confiables, pero demasiado grandes o de uso demasiado poco frecuente como para justificar su empaquetado.

Esta clasificación debería guiar la carga y el renderizado. Empaqueta los símbolos de interfaz pequeños cuando importen el comportamiento sin conexión y el estilo del tema. Carga las ilustraciones remotas aprobadas solo cuando sea necesario. Sanea o rasteriza las subidas de los usuarios antes de mostrarlas, y ofrece un respaldo para el material gráfico que use funcionalidades de SVG no compatibles.

Componente empaquetado

Adecuado para iconos pequeños y confiables que deben funcionar sin conexión y responder a los colores o al estado de la aplicación.

Vector remoto

Adecuado para material gráfico controlado que cambia sin publicar una nueva versión de la aplicación y que se mantiene dentro de un perfil de funcionalidades probado.

Respaldo en ráster preparado

Adecuado para material gráfico no confiable o complejo, miniaturas predecibles y renderizadores que no pueden reproducir el archivo de origen de forma fiable.

Elige entre los flujos de trabajo de componentes y de archivos

Un icono basado en componentes usa primitivas SVG nativas directamente en JSX o se genera a partir de un archivo local confiable en tiempo de compilación. Esto hace cómodo el uso de props como el tamaño, el relleno, el trazo y la etiqueta de accesibilidad. También agrega los datos del trazado al paquete de la aplicación y puede producir código ruidoso si los archivos generados se editan de forma manual.

Un archivo remoto mantiene el material gráfico fuera del paquete, pero introduce red, almacenamiento en caché, análisis, estados de fallo y decisiones de confianza. Algunos renderizadores aceptan un URI, mientras que otros requieren que la aplicación obtenga primero el XML. Sigue la API compatible de la biblioteca en lugar de suponer que un componente de imagen web interpretará SVG arbitrario.

Configura las dependencias nativas de forma deliberada

La instalación varía entre los entornos de desarrollo gestionados y los proyectos nativos puros. Confirma si el paquete SVG y cualquier transformador de tiempo de compilación ya están incluidos, requieren enlazado nativo o requieren cambios en la configuración del empaquetador. Vuelve a compilar la aplicación nativa después de cambiar las dependencias, en lugar de depender de una recarga solo de JavaScript.

Un transformador que importa archivos .svg como componentes es una herramienta de compilación, no un saneador en tiempo de ejecución. Restríngelo a los recursos revisados del repositorio y mantén sus declaraciones de TypeScript alineadas con las props que realmente produce. Prueba las compilaciones de lanzamiento, porque los empaquetadores de desarrollo pueden ocultar reglas de recursos ausentes o configuración nativa.

Haz que el viewBox controle el escalado

Un viewBox válido establece el sistema de coordenadas del vector. El ancho y el alto del componente definen la caja de maquetación, mientras que el renderizador ajusta el viewBox dentro de esa caja. Si el archivo de origen solo tiene dimensiones fijas o un viewBox incorrecto, cambiar el tamaño puede recortar el contenido, agregar espacio inesperado o distorsionar el dibujo.

Conserva la relación de aspecto en logotipos e ilustraciones, salvo que la distorsión sea intencional. Coloca el SVG en un contenedor padre con restricciones de maquetación explícitas y luego prueba dispositivos estrechos y anchos, configuraciones de texto grande y ambas orientaciones. Evita derivar la maquetación de un tamaño intrínseco supuesto cuando el recurso remoto puede cambiar.

Renderizar un icono escalable con react-native-svg

import type { ReactNode } from 'react'

import Svg, { Circle, Path } from 'react-native-svg'

export function StatusIcon(): ReactNode {
  return (
    <Svg
      accessible
      accessibilityLabel="Upload complete"
      accessibilityRole="image"
      width={24}
      height={24}
      viewBox="0 0 24 24"
    >
      <Circle cx={12} cy={12} r={10} fill="#13795b" />
      <Path d="m7 12 3 3 7-7" fill="none" stroke="#fff" strokeWidth={2} />
    </Svg>
  )
}

Gestiona el color y la tipografía en todas las plataformas

Usa props de componente o una asignación documentada de tokens para los iconos propios del producto. currentColor, el CSS basado en clases y las propiedades personalizadas de la web pueden no comportarse como lo hacen en un navegador, así que prueba el renderizador exacto. No reescribas las ilustraciones multicolor como iconos de un solo color solo para adaptarlas a una API cómoda.

Los elementos de texto son especialmente sensibles a la disponibilidad de fuentes de la plataforma, a la asignación de grosores, a la conformación del texto y al respaldo. Convertir las letras en trazados conserva la apariencia, pero aumenta la geometría y elimina la semántica de texto seleccionable. Para el texto significativo dirigido al usuario, prefiere un componente de texto nativo junto al gráfico y deja que el SVG siga siendo ilustrativo.

Añade la interacción en la capa de React Native

Envuelve un gráfico interactivo en el control pulsable habitual de la aplicación y proporciona un área táctil adecuada, comportamiento deshabilitado, comportamiento de foco y estado visible. No dependas de un trazado diminuto como único objetivo táctil. La interacción compleja forma por forma es posible en algunos renderizadores, pero debería verificarse en ambas plataformas.

Mantén la lógica de negocio fuera de los componentes SVG generados. Pasa los callbacks y el estado visual a través de un pequeño envoltorio revisado, y evita que los elementos hijos decorativos se conviertan en objetivos de accesibilidad confusos. Si un gráfico o un mapa necesita varias regiones interactivas, define una alternativa predecible de teclado o de lector de pantalla en lugar de exponer un conjunto de trazados sin estructura.

Ofrece accesibilidad fuera de los elementos internos del SVG

Un renderizador nativo puede ignorar <title> y <desc> aunque los navegadores sí los usen. Coloca la etiqueta accesible, el rol, la pista y el estado en el control de React Native o en el contenedor semántico con el que interactúan las personas usuarias. Las imágenes decorativas deberían excluirse para que un lector de pantalla no anuncie nombres de archivo ni etiquetas redundantes.

No codifiques información esencial únicamente mediante el color o la forma. Un icono de estado necesita texto adyacente o una etiqueta accesible clara. Las visualizaciones de datos necesitan un resumen textual y, cuando las personas usuarias deben inspeccionar valores, una lista o tabla accesible. Prueba con VoiceOver y TalkBack en lugar de inferir el comportamiento a partir del árbol de componentes.

Limita el contenido remoto y los estados de fallo

Para SVG remoto, permite solo esquemas de URL y orígenes aprobados, establece límites de tamaño de respuesta y de tiempo, verifica el contenido detectado y sanea antes de renderizar. No confíes únicamente en un sufijo .svg ni en una cabecera de respuesta. Bloquea los recursos externos inesperados y evita insertar XML sin sanear en cualquier respaldo basado en WebView.

Diseña estados explícitos de carga, sin conexión, tiempo de espera agotado, error de análisis y función no compatible. Almacena en caché según una identidad de recurso versionada, no de forma indefinida según una URL mutable. Una ilustración rota no debería colapsar la maquetación circundante ni impedir el uso de un control, y los reintentos deberían tener límites.

Política de red

Permite orígenes aprobados, exige transporte seguro, limita las redirecciones y aplica límites de tamaño de respuesta y de tiempo de espera.

Política de contenido

Valida y sanea el XML frente al subconjunto que se espera que admita el renderizador nativo.

Política de respaldo

Reserva espacio de maquetación y muestra un marcador de posición determinista o una alternativa rasterizada cuando falle el renderizado vectorial.

Controla el costo del renderizado y genera respaldos

Los vectores no son automáticamente más económicos que los rásteres. Miles de segmentos de trazado, máscaras, degradados, filtros y elementos de texto pueden resultar costosos de analizar y dibujar, sobre todo en una lista con desplazamiento. Analiza el rendimiento en dispositivos representativos de menor potencia y evita analizar repetidamente XML sin cambios durante los rerenderizados.

Conserva el material gráfico maestro en un almacenamiento que controles y genera respaldos acotados en PNG o WebP para las ubicaciones que no puedan renderizar de forma fiable las funciones de SVG necesarias. Produce dimensiones adecuadas para cada superficie móvil y su política de densidad. La preparación de archivos no instala el paquete nativo de SVG, ni configura la compilación, ni sustituye la entrega de recursos de la aplicación.

Prueba ambas plataformas y la ruta completa del recurso

Crea archivos de prueba para un icono simple, degradados, recortes, máscaras, texto, relaciones de aspecto inusuales, XML mal formado, un documento de tamaño excesivo y un recurso remoto ausente. Prueba las compilaciones de lanzamiento de iOS y Android con temas claro y oscuro, modo sin conexión, redes lentas, lectores de pantalla y densidades de píxeles altas.

Supervisa los fallos de obtención, los rechazos del saneamiento, los errores de análisis y el uso de respaldos, sin registrar el contenido SVG proporcionado por los usuarios. Versiona el renderizador y la política de procesamiento de recursos para poder rastrear las regresiones. Cuando una actualización de la biblioteca cambie el renderizado, compara las capturas de pantalla aprobadas y las pruebas de interacción antes de publicarla de forma amplia.

Detalles técnicos que conviene conocer

React Native no tiene el DOM SVG del navegador. Las bibliotecas asignan los elementos SVG admitidos a las API nativas de dibujo, y el soporte para filtros, HTML incrustado, fuentes o referencias externas puede variar.
Los transformadores de SVG en tiempo de compilación hacen que sea cómodo aplicar estilos a gráficos de confianza como si fueran componentes, pero también colocan cada trazado empaquetado en el paquete de la aplicación en lugar de cargarlo bajo demanda.
El SVG remoto puede contener referencias y contenido complejo que un renderizador no previó. Los límites de descarga, el saneamiento, el almacenamiento en caché y un respaldo rasterizado son aspectos distintos de seguridad y fiabilidad.
El texto de un SVG puede renderizarse de forma distinta cuando la fuente esperada no está disponible en un dispositivo; convertir el texto en contornos mejora la consistencia, pero sacrifica la selección y la accesibilidad.
Los vectores complejos pueden resultar más costosos de analizar y dibujar que un respaldo rasterizado acotado, sobre todo cuando aparecen muchas ilustraciones en una lista con desplazamiento.
Las etiquetas de accesibilidad corresponden al componente de React Native y a la interacción que lo rodea, no únicamente a los elementos de título del SVG que un renderizador nativo puede ignorar.

Un enfoque práctico

1
Separa los iconos propios del producto del material gráfico proporcionado por los clientes.
2
Selecciona una vía de renderizado y registra qué funcionalidades de SVG admite.
3
Genera imágenes de respaldo con límites definidos para cada densidad y ubicación necesarias.
4
Prueba la carga sin conexión, las etiquetas para lectores de pantalla, los temas de color y los archivos de origen con formato incorrecto.

Un flujo de trabajo multimedia de cuatro etapas

Límite de la arquitectura

El renderizado de SVG en React Native depende de la biblioteca nativa elegida y de la compilación de la plataforma. La preparación de recursos no puede instalar dependencias nativas ni garantizar que todas las funciones de SVG orientadas al navegador se correspondan con iOS y Android.

Preguntas frecuentes

¿Para qué se usa habitualmente SVG en React Native?

Se usa habitualmente para iconos escalables, logotipos, diagramas, gráficos e ilustraciones. Una biblioteca SVG nativa interpreta los elementos compatibles y los dibuja mediante las API de la plataforma, porque React Native no tiene el DOM SVG del navegador.

¿Deberían importarse los archivos SVG locales como componentes?

Ese enfoque funciona bien con recursos pequeños, de confianza y de uso frecuente que necesitan colores o tamaños definidos por props. Resulta menos adecuado para ilustraciones grandes, contenido remoto que cambia con frecuencia o subidas no confiables, porque añade geometría al paquete y ocurre antes de la validación en tiempo de ejecución.

¿Por qué un SVG puede renderizarse de forma distinta en iOS y en Android?

Los stacks de dibujo nativos, las fuentes instaladas, la conformación del texto, la compatibilidad con filtros y las implementaciones del renderizador pueden variar. Además, los elementos no compatibles pueden ignorarse. Mantén un perfil de funcionalidades probado e inspecciona las compilaciones de lanzamiento de ambas plataformas.

¿SVG siempre es más rápido que PNG en una aplicación móvil?

No. Un icono simple puede ser compacto y económico de dibujar, mientras que una ilustración compleja puede requerir un trabajo considerable de análisis y renderizado. Un ráster preparado suele ser más predecible para material gráfico detallado que se muestra en un tamaño fijo o se repite en una lista larga.

¿Dónde debería definirse la etiqueta de accesibilidad de un SVG?

Defínela en el componente de React Native o en el contenedor interactivo que participa en el árbol de accesibilidad nativo. No dependas únicamente de los elementos title internos del SVG, porque los renderizadores nativos podrían no exponerlos de forma coherente.