SVG en .NET MAUI: conserva el SVG y referencia el PNG

Para utilizar SVG en el proceso de imágenes incluidas de .NET MAUI, conserva el SVG en tu proyecto y referencia su nombre PNG generado desde XAML o C#. MAUI procesa el original vectorial durante la compilación. Por tanto, un Image que apunta a compass.png puede ser correcto aunque el archivo que añadiste sea compass.svg. La guía de imágenes de proyecto de Microsoft documenta esta conversión.

Eso explica el nombre, pero deja una pregunta de diseño: ¿qué tamaño debería generar MAUI y qué debes inspeccionar después? Sigue un pequeño emblema de brújula a través del original, los metadatos del proyecto y la declaración de visualización.

Sigue el original a través de la compilación

El SVG editable y la imagen empaquetada tienen trabajos diferentes. Conserva el original para poder ajustar después sus formas, espacio vacío o colores. Utiliza el nombre generado en la vista que lo muestra.

La documentación del control Image describe cómo entran en el paquete las imágenes para cada densidad de destino y cómo el sistema operativo selecciona la resolución adecuada. Conservar un original SVG no significa que este proceso concreto entregue un documento SVG activo a la vista.

Añade un SVG pequeño con límites claros

Guarda este ejemplo original como Resources/Images/compass.svg:

<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96">
  <circle cx="48" cy="48" r="34" fill="none" stroke="#173e52" stroke-width="8"/>
  <path d="M58 28L52 52L28 58Z" fill="#ed765e"/>
</svg>

El anillo deja un centro transparente y la aguja coral es una forma independiente. Esos detalles proporcionan algo concreto que comprobar después de importar. Las dimensiones declaradas y el viewBox cuadrado también dejan claro el encuadre previsto. Consulta la guía de archivos SVG para entender cómo difiere la geometría vectorial de un mapa de bits incrustado en un contenedor SVG.

En tu proyecto, confirma que el archivo tenga la acción de compilación MauiImage. Microsoft documenta la carpeta Resources/Images como ubicación normal. Antes de añadir XML, inspecciona los elementos existentes del proyecto: puede que ya incluya esa carpeta mediante un comodín. La configuración de imágenes de proyecto explica la ubicación y la acción de compilación.

Actualiza una vez un elemento existente

Si un comodín MauiImage existente ya incluye el archivo de brújula, coloca esta actualización de metadatos después de esa inclusión:

<ItemGroup>
  <MauiImage Update="Resources\Images\compass.svg" BaseSize="48,48" />
</ItemGroup>

Update cambia los metadatos de un elemento que ya existe. No añade un archivo ausente a la lista de elementos. Si tu proyecto no tiene una inclusión coincidente, añade el archivo una vez con la acción de compilación MauiImage o un Include explícito. La referencia de Item de MSBuild de Microsoft distingue esas operaciones.

Esto evita una reparación tentadora: añadir repetidamente entradas Include mientras depuras una imagen ausente. Establece primero si el archivo está incluido y después cambia sus metadatos.

Referencia el PNG y establece el área de visualización

Coloca esta declaración dentro de una página o composición existente de MAUI:

<Image Source="compass.png"
       WidthRequest="48"
       HeightRequest="48"
       Aspect="AspectFit"
       SemanticProperties.Description="Compass" />

La extensión .png es intencionada. El ancho y el alto solicitan un área de visualización cuadrada; AspectFit mantiene toda la imagen visible dentro de ella. Si tu ilustración es rectangular, utiliza un área de visualización adecuada en lugar de estirarla para llenar un cuadrado. La referencia de escalado de Image de Microsoft distingue ajuste, recorte y estiramiento.

El código de brújula es un ejemplo original de configuración, no una prueba registrada de renderizado en dispositivo. Compílalo en tu propio proyecto de destino e inspecciona la vista resultante. Un nombre de archivo correcto por sí solo no demuestra que tu diseño concreto se renderice como pretendes.

BaseSize y el tamaño de composición resuelven problemas diferentes

BaseSize="48,48" proporciona las dimensiones base desde las que MAUI deriva imágenes específicas de densidad. Sin un tamaño base explícito, MAUI utiliza las propias dimensiones del SVG. Microsoft documenta ambas reglas en Redimensionar una imagen.

En este ejemplo, el dibujo original utiliza un espacio de coordenadas de 96 por 96, mientras que la base solicitada y la vista son de 48 por 48. Esos números son decisiones deliberadas de creación, no dimensiones de salida medidas de una compilación. El anillo debería conservar sus proporciones al escalarse.

Si después utilizas el mismo emblema en una vista mucho mayor, revisa el tamaño de compilación e inspecciona también ese uso. Cambiar WidthRequest no edita el diseño original ni sus metadatos de compilación. A la inversa, cambiar BaseSize no elimina márgenes vacíos dentro del SVG. Ajusta los límites del dibujo en el original si el propio emblema parece demasiado pequeño dentro de una vista que, por lo demás, tiene el tamaño correcto.

Evita utilizar Resize="false" como solución general de nitidez. Desactiva el redimensionado de imágenes vectoriales en este proceso. Elígelo solo cuando ese sea el comportamiento previsto, siguiendo la opción de redimensionado documentada.

Comprueba en orden una imagen ausente o inesperada

1. Confirma el nombre de archivo y el elemento del proyecto. Utiliza un nombre en minúsculas como compass.svg y comprueba si hay otra imagen con el mismo nombre. Las reglas de nombres de Microsoft requieren nombres únicos de imagen y caracteres compatibles con Android.
2. Comprueba el origen de la vista. Para el proceso de SVG incluidos, utiliza compass.png en XAML o C#.
3. Compara el área de visualización prevista con el tamaño base. Un cambio de tamaño de vista y uno de compilación corresponden a lugares diferentes.
4. Inspecciona el propio diseño. ¿Sigue abierto el centro del anillo? ¿Se distingue la aguja coral? ¿Está centrado el emblema o lo desplaza un espacio vacío invisible del original?

Inspecciona también cualquier metadato de imagen que cambie la pintura. La guía de imágenes de proyecto documenta TintColor y Color para tinte y color de fondo. Déjalos sin establecer en este ejemplo de dos colores salvo que quieras modificar su apariencia. Comprueba la imagen sobre el fondo real de la página, donde es más fácil detectar la pérdida de una abertura transparente.

Cuando necesitas comportamiento SVG en tiempo de ejecución

El contenido SVG descargado, los trazados interactivos o las ediciones en tiempo de ejecución requieren una decisión de implementación independiente. Las instrucciones de imágenes incluidas anteriores no establecen compatibilidad con esos trabajos.

Por ejemplo, el proyecto de ejemplos SVG de Vapolia documenta sus propios controles SvgImage y SvgImageSource y la configuración de recursos incrustados. Es un contrato de carga diferente. Evalúa las funciones y plataformas de destino compatibles con el renderizador utilizando tu archivo real antes de incorporarlo; cambiar la extensión del nombre de archivo en una declaración normal de Image no instala un renderizador.

El mismo diseño también necesita configuraciones distintas en el proceso de imágenes SVG de Flutter, el catálogo de recursos de SwiftUI y una importación de VectorDrawable de Android. Reutiliza el original y después sigue las reglas de cada destino.

Prepara un original vectorial cuando solo queda un PNG

Si la brújula o el logotipo solo existen como PNG, PerfectVector puede ayudar a crear un diseño SVG editable antes de añadirlo al proyecto MAUI. Convierte el PNG en SVG y después inspecciona la abertura del anillo, las pequeñas piezas separadas y el espaciado en un editor. Conserva un original limpio para posteriores cambios de tamaño o color.

La vectorización no repara una declaración MauiImage ni convierte el proceso de imágenes incluidas en un analizador SVG en tiempo de ejecución. Si el original ya es un SVG editable, trabaja directamente en la configuración del proyecto o en el dibujo. Las fotos y las ilustraciones con textura pueden resultar más útiles como imágenes rasterizadas; trazarlas solo porque la aplicación acepta originales SVG añade una decisión gráfica independiente.

Preguntas frecuentes

¿Por qué referencio un PNG si añadí un SVG? .NET MAUI convierte los originales SVG incluidos en PNG durante la compilación. Conserva el SVG en el proyecto y referencia el nombre PNG desde XAML o C#.

¿Establece BaseSize el tamaño del control Image? BaseSize establece las dimensiones base utilizadas para derivar las imágenes de compilación específicas de densidad. La composición y las solicitudes de tamaño de la vista controlan su área de visualización.

¿Debo añadir otro MauiImage Include para cambiar BaseSize? Comprueba si el archivo ya está incluido, también mediante un comodín. Utiliza Update para cambiar metadatos de un elemento existente; usa Include solo cuando deba añadirse el elemento.

¿Cargará esto un SVG descargado después de compilar la aplicación? El proceso de imágenes incluidas no cubre descargar e interpretar SVG en tiempo de ejecución. Elige y prueba un método de renderizado en tiempo de ejecución para ese requisito.

Fuentes

1. Microsoft — Añadir imágenes a un proyecto de aplicación .NET MAUI — procesamiento SVG a PNG, elementos de imagen, nombres, tamaño base y metadatos de compilación.
2. Microsoft — Image — referencias de imágenes locales, selección según densidad de destino, tamaño de vista y comportamiento de escalado.
3. Microsoft — Elemento Item de MSBuild — diferencia entre añadir un elemento con Include y cambiar metadatos existentes con Update.
4. Vapolia — Ejemplos SVG — un control SVG en tiempo de ejecución y un proceso de carga de recursos independientes.

¿Trabajas con un emblema de aplicación que solo existe rasterizado? Convierte tu PNG en un SVG editable, comprueba sus aberturas y espaciado y después añade ese original a MAUI e inspecciona la imagen generada en tu aplicación de destino.