Contenido SVG incrustado – imágenes, SVG anidado y HTML

El contenido incrustado en SVG es marcado SVG que referencia o contiene contenido que no pertenece al dibujo básico, como imágenes raster, otro archivo SVG o marcado HTML. Este tema importa cuando creas diagramas, informes, insignias, infografías, vistas previas o gráficos exportados que combinan formas vectoriales con logotipos, fotos, capturas de pantalla o bloques de texto con formato.

Respuesta rápida: Usa el elemento SVG <image> para colocar PNG, JPG, GIF, WebP u otro SVG dentro de un documento SVG. Usa <foreignObject> cuando necesites marcado HTML dentro de SVG. Define siempre x, y, width y height, controla el escalado con preserveAspectRatio y asegúrate de que los recursos vinculados estén disponibles cuando el SVG se abra, renderice o convierta.

<svg width="300" height="180" xmlns="http://www.w3.org/2000/svg">
  <image href="logo.png" x="20" y="20" width="120" height="120" />
</svg>

Conceptos básicos del contenido incrustado SVG

SVG no se limita a paths, formas y texto. También puede incluir contenido de otros formatos. Los dos elementos más comunes son:

Elemento	Úsalo para	Notas importantes
<image>	Imágenes raster como PNG, JPG, GIF, WebP y otro SVG usado como recurso de imagen	Requiere width y height; los archivos externos deben ser accesibles
<foreignObject>	HTML u otro contenido XML dentro de una región SVG	Requiere el namespace correcto y puede tener soporte limitado en algunos flujos de renderizado

Usa contenido incrustado cuando la fuente deba seguir siendo una imagen o un fragmento HTML. No lo confundas con la vectorización. Incrustar un PNG dentro de SVG mantiene el PNG como píxeles; no convierte el PNG en paths. Si necesitas trazado raster a vector, consulta Convertir imagen a SVG en C# o Vectorizar imágenes en Python.

Cómo incrustar contenido en SVG

1. Elige <image> para una imagen raster o un archivo SVG anidado, y <foreignObject> para marcado HTML.
2. Define x e y para posicionar el contenido incrustado dentro del sistema de coordenadas SVG.
3. Define width y height; sin ellos, muchos renderizadores no mostrarán el contenido.
4. Usa href para el archivo fuente, URL o data URI cuando trabajes con <image>.
5. Usa preserveAspectRatio cuando la imagen fuente deba conservar sus proporciones.
6. Prueba el SVG en el mismo contexto donde se usará, especialmente antes de convertirlo a PDF, PNG o JPG.

Incrustar imágenes en SVG

El elemento SVG <image> coloca un recurso de imagen en un viewport rectangular dentro del sistema de coordenadas SVG. El recurso puede ser una imagen raster, como PNG o JPG, u otro archivo SVG usado como imagen.

Los atributos más importantes son:

Atributo	Propósito
x, y	Posición del viewport de la imagen
width, height	Tamaño del viewport de la imagen; normalmente requerido para renderizar
href	Ruta, URL o data URI del recurso de imagen
preserveAspectRatio	Controla si la imagen se ajusta, se recorta o se estira

El siguiente ejemplo incrusta una imagen PNG y un archivo SVG externo en un SVG padre. Ambas imágenes se posicionan y dimensionan con atributos explícitos para que el diseño sea predecible.

<svg width="500" height="400" xmlns="http://www.w3.org/2000/svg">
  <image href="https://docs.aspose.com/svg/images/svg.png" x="20" y="20" width="180" height="180" />
  <image href="https://docs.aspose.com/svg/files/shapes.svg"
         x="250" y="10" width="220" height="220"
         preserveAspectRatio="xMidYMid meet" />
  <text x="40" y="250">Embedded PNG image</text>
  <text x="300" y="250">Embedded SVG image</text>
</svg>

El SVG renderizado muestra dos recursos incrustados: una imagen PNG a la izquierda y un archivo SVG a la derecha.

Archivos de imagen externos frente a imágenes data URI

Un elemento <image> puede referenciar un archivo externo, una URL remota o un data URI en Base64. Los archivos externos mantienen el SVG más pequeño y fácil de editar, pero deben seguir disponibles. Los data URI hacen que el SVG sea más autocontenido, aunque pueden aumentar mucho el tamaño del archivo y dificultar el mantenimiento del marcado.

Usa archivos externos para sitios controlados, muestras de documentación y proyectos editables. Usa data URI cuando el SVG deba viajar como un único archivo y la imagen raster incrustada sea lo bastante pequeña para mantener manejable el SVG final.

<image href="data:image/png;base64,..." x="0" y="0" width="200" height="120" />

Añadir HTML dentro de SVG

El elemento <foreignObject> permite que SVG contenga marcado de otro namespace XML. En SVG basado en navegador, el caso común es incrustar un pequeño fragmento HTML. Esto resulta útil para etiquetas con formato, bloques de texto enriquecido o anotaciones similares a UI que son más fáciles de expresar en HTML que con texto SVG puro.

Los atributos requeridos son:

Atributo	Propósito
x, y	Posición de la región del objeto externo
width, height	Tamaño de la región donde puede renderizarse el contenido HTML

El elemento raíz HTML dentro de <foreignObject> debe declarar el namespace XHTML http://www.w3.org/1999/xhtml. Sin el namespace correcto, el contenido puede no renderizarse. Para un renderizado fiable, coloca estilos críticos de texto como font-size, font-family, line-height y color directamente en el elemento XHTML, o usa una regla CSS que hayas probado en el renderizador de destino.

<svg width="500" height="400" viewBox="0 0 250 200" xmlns="http://www.w3.org/2000/svg">
  <circle cx="70" cy="70" r="60" fill="red" fill-opacity="0.1" />
  <foreignObject x="20" y="40" width="210" height="180">
    <div xmlns="http://www.w3.org/1999/xhtml"
         style="color:#555; font-family:Arial, sans-serif; font-size:12px; line-height:1.4;">
      Convert SVG to PNG, PDF, XPS, and major image formats with Aspose.SVG.
    </div>
  </foreignObject>
</svg>

La figura muestra un bloque de texto HTML renderizado dentro de una región SVG con <foreignObject>.

<foreignObject> es potente, pero menos portable que las formas y el texto SVG básicos. Algunos flujos de exportación, seguridad o renderizado del lado servidor pueden restringir HTML, CSS, scripts o recursos externos dentro del contenido incrustado. Si el SVG debe renderizarse de forma consistente en todas partes, prefiere texto y formas SVG puros.

Errores comunes y soluciones

Problema	Causa	Solución
La imagen incrustada no aparece	Falta width o height en <image>	Añade dimensiones explícitas para definir el viewport de la imagen
La imagen desaparece después de la conversión	El archivo vinculado o la URL remota no están disponibles para el renderizador	Usa una ruta accesible, configura el acceso a recursos o incrusta una imagen pequeña como data URI
La imagen se estira	Falta preserveAspectRatio o está en none	Usa preserveAspectRatio="xMidYMid meet" para conservar proporciones
El HTML dentro de <foreignObject> es invisible	Namespace XHTML incorrecto o ausente	Usa xmlns="http://www.w3.org/1999/xhtml" en el elemento HTML raíz
La salida difiere entre herramientas	El soporte de <foreignObject> varía según renderizador, CSS o contexto de seguridad	Usa marcado SVG puro cuando se requiera una salida de conversión consistente, o mantén los estilos HTML críticos en línea
El archivo SVG se vuelve demasiado grande	Una imagen raster grande se incrusta como Base64	Mantén las imágenes grandes externas u optimízalas antes de incrustarlas

Recetas rápidas

Incrustar una imagen PNG

<svg width="200" height="200" xmlns="http://www.w3.org/2000/svg">
  <image href="image.png" x="0" y="0" width="200" height="200" />
</svg>

Incrustar un archivo SVG externo

<svg width="300" height="300" xmlns="http://www.w3.org/2000/svg">
  <image href="icon.svg" x="10" y="10" width="280" height="280" />
</svg>

Conservar la proporción de la imagen

<svg width="250" height="250" xmlns="http://www.w3.org/2000/svg">
  <image href="photo.jpg"
         x="0" y="0"
         width="250" height="250"
         preserveAspectRatio="xMidYMid meet" />
</svg>

Añadir una etiqueta HTML pequeña

<foreignObject x="20" y="20" width="160" height="80">
  <div xmlns="http://www.w3.org/1999/xhtml">HTML label</div>
</foreignObject>

FAQ – Contenido SVG incrustado

¿Puedo incrustar PNG o JPG dentro de SVG?

Sí. Usa el elemento <image> con href, x, y, width y height. La imagen raster sigue siendo contenido raster dentro del SVG; no se convierte en paths vectoriales.

¿Puedo incrustar otro SVG dentro de un SVG?

Sí. Puedes referenciar otro archivo SVG con <image href="file.svg"> cuando quieras mostrarlo como recurso de imagen. Si necesitas editar la estructura del SVG anidado como parte del documento padre, inserta el marcado SVG en línea.

¿Puede SVG contener HTML?

Sí, mediante <foreignObject>. El HTML incrustado debe usar el namespace XHTML y probarse en el navegador o renderizador de destino porque el soporte puede variar.

¿Por qué falta mi imagen incrustada en la salida PDF o PNG?

Es posible que el renderizador no pueda acceder al archivo, URL, fuente, CSS o contenido HTML referenciado. Usa rutas estables, incrusta recursos pequeños como data URI o configura el acceso a recursos antes de la conversión.

¿Incrustar una imagen es lo mismo que convertir una imagen a SVG?

No. Incrustar coloca la imagen raster original dentro de SVG. Convertir o vectorizar una imagen traza píxeles y los convierte en paths y formas SVG.

Recursos relacionados

• La especificación SVG 2 sobre contenido incrustado define cómo SVG maneja recursos incrustados, incluidos los elementos <image> y <foreignObject>.
• Formas SVG explica la geometría SVG básica antes de combinar formas con recursos de imagen incrustados.
• Texto SVG cubre el texto SVG nativo, que es más portable que HTML dentro de <foreignObject>.
• Color SVG explica fill, stroke, opacidad y valores de color usados por el arte SVG circundante.
• Convertir imagen a SVG en C# explica la vectorización de imágenes raster, que es diferente de incrustar una imagen con <image>.
• Convertir SVG a imagen en C# cubre la renderización de documentos SVG que pueden contener imágenes vinculadas, fuentes, CSS u otros recursos.