Imágenes SVG en Flutter: incluye, dimensiona y comprueba recursos

Para mostrar un SVG en Flutter, añade flutter_svg, declara el archivo en pubspec.yaml y carga esa misma ruta con SvgPicture.asset. Dale dimensiones al widget o restricciones de disposición adecuadas e inspecciona la ilustración en la aplicación. El constructor de recursos del paquete documenta esta vía.

Separa dos preguntas: ¿cargó la aplicación el archivo previsto y reprodujo el renderizador la ilustración prevista? Exportar de nuevo un dibujo no repara una clave mal escrita. Corregir la clave no simplifica un efecto no compatible.

Este tutorial usa una ilustración original de colinas y sol para facilitar las comprobaciones. El código sigue la API documentada; no informa de una prueba de aplicación compilada.

Empieza con un original pequeño que puedas inspeccionar

Crea assets/illustrations/hills.svg en el proyecto Flutter:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 48">
  <circle cx="49" cy="11" r="6" fill="#e99b30"/>
  <path d="M4 42L24 14L44 42Z" fill="#167d8d"/>
  <path d="M28 42L43 23L60 42Z" fill="#233b63"/>
</svg>

Tiene dos colinas triangulares superpuestas y un sol ámbar separado. Usa rellenos explícitos, no tiene texto ni imágenes vinculadas y deja un hueco visible entre sol y colinas. Esos detalles dan una lista breve de aceptación al revisar la aplicación.

Conserva una copia de este archivo sencillo al introducir después tu ilustración. Si funciona el original pequeño y falla el sustituto, compara sus estructuras antes de cambiar toda la carga.

Un recurso SVG de Flutter también es distinto del XML VectorDrawable de Android. Si el destino es un drawable nativo Android, usa la guía de preparación de VectorDrawable en lugar de tratar ambos formatos como intercambiables.

Añade el paquete y declara el archivo exacto

Desde la raíz del proyecto, usa el comando oficial de instalación:

flutter pub add flutter_svg

Añade después esta entrada bajo la sección flutter: existente de pubspec.yaml:

flutter:
  assets:
    - assets/illustrations/hills.svg

Integra la entrada en la configuración actual en lugar de crear otra sección flutter:. Conserva la sangría. La documentación de recursos de Flutter define las rutas respecto a pubspec.yaml y explica cómo entran los archivos en el paquete de la aplicación.

Usa exactamente la misma escritura, mayúsculas y directorios en archivo, declaración y llamada Dart. Para la primera prueba, una entrada explícita es más fácil de comparar que una carpeta amplia. Si luego declaras directorios, Flutter documenta que cada entrada cubre los archivos directos; los directorios anidados necesitan sus propias entradas.

Después de cambiar la configuración, reconstruye y ejecuta con tu proceso normal. No asumas que un archivo visible en el editor ya está incluido en la aplicación que ves.

Carga la ilustración en una caja definida

Añade estas importaciones al archivo Dart del widget:

import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';

Coloca este widget en una parte adecuada de la pantalla:

SvgPicture.asset(
  'assets/illustrations/hills.svg',
  width: 128,
  height: 96,
  fit: BoxFit.contain,
  semanticsLabel: 'Sun above two hills',
  errorBuilder: (context, error, stackTrace) =>
      const Text('Illustration unavailable'),
)

La caja respeta las proporciones del original. Inspecciona el sol separado, ambos colores y márgenes exteriores antes de reducir el tamaño. Usa después las dimensiones de tu componente real; los números son un ejemplo, no un tamaño mínimo ni una recomendación de rendimiento.

La documentación del constructor recomienda dimensiones explícitas o restricciones ajustadas para que cargar no cambie inesperadamente la disposición. Si el dibujo parece pequeño dentro de la caja, inspecciona el espacio vacío de viewBox y las dimensiones del widget.

La etiqueta describe el propósito de esta imagen independiente. La API semanticsLabel la conecta con su etiqueta semántica. Para una imagen decorativa junto a texto que ya comunica el significado, considera excluirla de la semántica. excludeFromSemantics prevalece sobre la etiqueta. Revisa el significado hablado de todo el componente en lugar de etiquetar cada forma.

Distingue un marcador de carga de un error

Un indicador de carga no demuestra que se haya aceptado el SVG. El paquete ofrece placeholderBuilder para la adquisición o decodificación, mientras la API actual errorBuilder proporciona un widget cuando falla la carga.

El ejemplo usa un texto breve de reserva. Durante desarrollo, cambia deliberadamente la ruta Dart a un archivo inexistente y comprueba que puedas reconocer el fallo. Restaura la ruta correcta antes de continuar. Así pruebas la presentación del error sin cambiar el dibujo.

Después prueba tu original real. Si sigue fallando, inspecciona los diagnósticos y compara primero la ruta declarada. Que un ejemplo de red muestre otro SVG no demuestra que el archivo local esté incluido ni que sus funciones sean compatibles.

Decide si conservar la paleta o aplicar un tinte

Deja colorFilter sin asignar si las colinas deben seguir siendo de color verde azulado y azul marino, con un sol ámbar. Para un tratamiento deliberadamente de un color, añade un filtro como:

colorFilter: const ColorFilter.mode(
  Color(0xFF175CD3),
  BlendMode.srcIn,
),

El paquete documenta este patrón. La referencia de BlendMode de Flutter explica que srcIn usa la opacidad del destino e ignora sus canales de color. Un tinte uniforme elimina por tanto las diferencias de paleta; es una decisión de diseño, no una reparación para conservar color.

Comprueba si perder contraste entre los dos triángulos dificulta leer las colinas. Conserva la paleta si deben distinguirse esas zonas. El paquete también documenta ColorMapper para sustituciones selectivas, pero empieza sin filtro al diagnosticar una discrepancia.

Simplifica funciones solo después de cargar

La documentación de flutter_svg recomienda atributos de presentación al exportar desde Illustrator porque CSS tiene compatibilidad incompleta, e imágenes incrustadas en vez de vinculadas externamente. También ofrece una comprobación de compatibilidad basada en compilador. Síguela en tu entorno Flutter/Dart al investigar un recurso complejo.

La vista previa en navegador es una referencia útil de apariencia; no demuestra que cada función renderice idénticamente mediante el paquete. Conserva el original y simplifica una copia con un cambio cada vez.

Si hay letras, decide si deben ser texto de aplicación o ilustración fija. La guía de cambios de fuentes SVG explica la dependencia del manejo de texto y fuentes. No traces una etiqueta para resolver un problema de ruta.

Para una familia de recursos de interfaz, compara tamaños visuales y separación juntos. La guía de preparación de iconos para kits ayuda a comprobar coherencia.

Vectoriza cuando necesites recuperar el original

Conserva un SVG existente limpio. Una foto o fondo texturizado puede entregarse mejor rasterizado; cambiar la extensión no crea geometría vectorial útil.

Si una ilustración sencilla solo existe como PNG deficiente, el flujo PNG a SVG de PerfectVector puede ayudarte a preparar un candidato editable. Recorta al dibujo, revisa formas ausentes y fondos no deseados y descarga SVG. Añádelo al paquete y repite comprobaciones de carga, paleta, tamaño y semántica.

En las colinas, busca el sol separado y la separación entre laderas de distinto color. Confirma la estructura prevista; la guía de contenido rasterizado incrustado explica por qué un contenedor SVG puede conservar píxeles.

Juzga el recurso en la aplicación antes de optimizar. Este proceso no promete que SVG sea en general menor o más rápido que PNG.

Si reutilizas en .NET MAUI, sigue el flujo de original SVG a PNG de MAUI. El proyecto conserva el maestro SVG y la vista referencia un PNG preparado al compilar.

Preguntas frecuentes

¿Cómo añado una imagen SVG a Flutter? Añade flutter_svg, declara el recurso en pubspec.yaml y carga la ruta correspondiente con SvgPicture.asset. Establece dimensiones o restricciones adecuadas e inspecciona.

¿Por qué no aparece mi SVG local? Comprueba primero declaración, ruta exacta, error de carga y disposición. Si funciona un original sencillo, compara la estructura y funciones compatibles de la ilustración que falla.

¿Por qué todos los colores quedaron iguales? Un filtro uniforme srcIn sustituye la paleta visible por su tinte. Quítalo si deben distinguirse los colores originales.

¿Debo convertir PNG a SVG para Flutter? No. Usa una imagen rasterizada adecuada si encaja con la ilustración. Vectorizar es opcional para recuperar formas editables de un original sencillo.

Fuentes

1. flutter_svg — Instalación — Instalar el paquete e importar en Dart.
2. Flutter — Añadir recursos e imágenes — Declaraciones, rutas y empaquetado.
3. flutter_svg — SvgPicture.asset — Carga, dimensiones, ajuste y controles semánticos.
4. flutter_svg — errorBuilder — Presentación de fallos distinta de marcadores de carga.
5. flutter_svg — semanticsLabel — Propósito semántico de la imagen.
6. Flutter — BlendMode — Tratamiento srcIn basado en opacidad.
7. flutter_svg — Documentación del paquete — Tintes, sustitución selectiva de colores, exportación y comprobaciones de compatibilidad.

Empieza con un recurso declarado y comprueba ruta, paleta, tamaño y significado en la aplicación. Si necesitas recuperar una ilustración rasterizada, prepara un candidato SVG, inspecciona sus formas y repite las comprobaciones antes de añadirlo a la familia de recursos.