Встроенный SVG-контент – изображения, SVG и HTML

Встроенный SVG-контент – это SVG-разметка, которая ссылается на содержимое не из базовых графических элементов или включает его внутрь документа: растровые изображения, другой SVG-файл или HTML-разметку. Эта тема важна, когда вы создаете диаграммы, отчеты, бейджи, инфографику, превью или экспортируемую графику, где векторные фигуры нужно объединить с логотипами, фотографиями, скриншотами или форматированными текстовыми блоками.

Краткий ответ: используйте SVG-элемент <image>, чтобы поместить PNG, JPG, GIF, WebP или другой SVG внутрь SVG-документа. Используйте <foreignObject>, когда нужно добавить HTML-разметку внутри SVG. Всегда задавайте x, y, width и height, управляйте масштабированием через preserveAspectRatio и убедитесь, что связанные ресурсы доступны при открытии, рендеринге или конвертации SVG.

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

Основы встроенного SVG-контента

SVG не ограничивается path-элементами, фигурами и текстом. Он также может включать содержимое из других форматов. Два наиболее распространенных элемента:

Элемент	Для чего использовать	Важные замечания
`<image>`	Растровые изображения PNG, JPG, GIF, WebP, а также другой SVG, используемый как графический ресурс	Требует `width` и `height`; внешние файлы должны быть доступны
`<foreignObject>`	HTML или другой XML-контент внутри SVG-области	Требует корректного пространства имен и может поддерживаться не во всех сценариях рендеринга

Используйте встроенный контент, когда исходный ресурс должен остаться изображением или HTML-фрагментом. Не путайте это с векторизацией. Если встроить PNG в SVG, PNG останется пиксельным изображением и не превратится в path-элементы. Если нужно трассировать растр в вектор, смотрите Конвертацию изображения в SVG на C# или Векторизацию изображений в Python.

Как встроить контент в SVG

Выберите <image> для растрового изображения или вложенного SVG-файла, а <foreignObject> – для HTML-разметки.
Задайте x и y, чтобы расположить встроенный контент в системе координат SVG.
Задайте width и height; без них многие рендереры не покажут содержимое.
Используйте href для пути к файлу, URL или data URI при работе с <image>.
Используйте preserveAspectRatio, если исходное изображение должно сохранить пропорции.
Проверяйте SVG в том же контексте, где он будет использоваться, особенно перед конвертацией в PDF, PNG или JPG.

Встраивание изображений в SVG

SVG-элемент <image> помещает графический ресурс в прямоугольную область внутри системы координат SVG. Ресурсом может быть растровое изображение, например PNG или JPG, либо другой SVG-файл, используемый как изображение.

Наиболее важные атрибуты:

Атрибут	Назначение
`x`, `y`	Положение области изображения
`width`, `height`	Размер области изображения; обычно требуется для рендеринга
`href`	Путь, URL или data URI графического ресурса
`preserveAspectRatio`	Управляет тем, как изображение вписывается, обрезается или растягивается

Следующий пример встраивает PNG-изображение и внешний SVG-файл в один родительский SVG. Оба изображения имеют явные координаты и размеры, поэтому макет остается предсказуемым.

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

В результате SVG показывает два встроенных ресурса: PNG-изображение слева и SVG-файл справа.

PNG и вложенный SVG, встроенные с помощью элементов image

Внешние изображения и изображения Data URI

Элемент <image> может ссылаться на внешний файл, удаленный URL или Base64 data URI. Внешние файлы делают SVG меньше и удобнее для редактирования, но эти файлы должны оставаться доступными. Data URI делает SVG более автономным, но может значительно увеличить размер файла и усложнить поддержку разметки.

Используйте внешние файлы для контролируемых сайтов, примеров документации и редактируемых проектов. Используйте data URI, когда SVG должен передаваться одним файлом, а встроенное растровое изображение достаточно маленькое, чтобы итоговый SVG оставался удобным.

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

Добавление HTML внутри SVG

Элемент <foreignObject> позволяет SVG содержать разметку из другого XML-пространства имен. В браузерном SVG самый частый сценарий – встраивание небольшого HTML-фрагмента. Это полезно для форматированных подписей, текстовых блоков с разметкой или UI-подобных аннотаций, которые проще выразить на HTML, чем через чистый SVG-текст.

Обязательные атрибуты:

Атрибут	Назначение
`x`, `y`	Положение области `<foreignObject>`
`width`, `height`	Размер области, в которой может отображаться HTML-контент

Корневой HTML-элемент внутри <foreignObject> должен объявлять пространство имен XHTML http://www.w3.org/1999/xhtml. Без корректного пространства имен содержимое может не отобразиться. Для надежного рендеринга задавайте критически важные стили текста, такие как font-size, font-family, line-height и color, прямо на XHTML-элементе или используйте CSS-правило, проверенное в целевом рендерере.

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

На рисунке показан HTML-текстовый блок, отображенный внутри SVG-области с помощью <foreignObject>.

HTML-текстовый блок, встроенный в SVG через foreignObject

<foreignObject> дает гибкость, но он менее переносим, чем базовые SVG-фигуры и текст. Некоторые экспортные, серверные или защищенные сценарии рендеринга могут ограничивать HTML, CSS, скрипты или внешние ресурсы внутри встроенного контента. Если SVG должен одинаково отображаться везде, предпочтительнее использовать чистый SVG-текст и фигуры.

Типичные ошибки и исправления

Проблема	Причина	Исправление
Встроенное изображение не отображается	У `<image>` отсутствует `width` или `height`	Задайте явные размеры, чтобы определить область изображения
Изображение исчезает после конвертации	Связанный файл или удаленный URL недоступен рендереру	Используйте доступный путь, настройте доступ к ресурсам или встроите небольшое изображение как data URI
Изображение растянуто	`preserveAspectRatio` отсутствует или задан как `none`	Используйте `preserveAspectRatio="xMidYMid meet"`, чтобы сохранить пропорции
HTML внутри `<foreignObject>` невидим	Пространство имен XHTML указано неверно или отсутствует	Используйте `xmlns="http://www.w3.org/1999/xhtml"` на корневом HTML-элементе
Результат отличается в разных инструментах	Поддержка `<foreignObject>` зависит от рендерера, CSS-поддержки или контекста безопасности	Используйте чистую SVG-разметку, если нужен стабильный результат конвертации, или задавайте критичные HTML-стили непосредственно в атрибуте `style`
SVG-файл становится слишком большим	Большое растровое изображение встроено как Base64	Оставляйте крупные изображения внешними или оптимизируйте их перед встраиванием

Быстрые рецепты

Встроить PNG-изображение

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

Встроить внешний SVG-файл

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

Сохранить пропорции изображения

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

Добавить небольшую HTML-подпись

1<foreignObject x="20" y="20" width="160" height="80">
2  <div xmlns="http://www.w3.org/1999/xhtml">HTML-подпись</div>
3</foreignObject>

FAQ – встроенный SVG-контент

Можно ли встроить PNG или JPG внутрь SVG?

Да. Используйте элемент <image> с атрибутами href, x, y, width и height. Растровое изображение остается растровым содержимым внутри SVG и не преобразуется в векторные path-элементы.

Можно ли встроить один SVG внутрь другого SVG?

Да. Можно сослаться на другой SVG-файл через <image href="file.svg">, если нужно отобразить его как графический ресурс. Если нужно редактировать структуру вложенного SVG как часть родительского документа, встроите SVG-разметку непосредственно в родительский документ.

Может ли SVG содержать HTML?

Да, через <foreignObject>. Встроенный HTML должен использовать пространство имен XHTML, и его нужно проверять в целевом браузере или рендерере, потому что поддержка может отличаться.

Почему встроенное изображение пропадает при выводе в PDF или PNG?

Рендерер может не иметь доступа к связанному файлу, URL, шрифту, CSS или HTML-контенту. Используйте стабильные пути к ресурсам, встраивайте небольшие файлы как data URI или настройте доступ к ресурсам перед конвертацией.

Встроить изображение – это то же самое, что конвертировать изображение в SVG?

Нет. Встраивание помещает исходное растровое изображение внутрь SVG. Конвертация или векторизация изображения трассирует пиксели в SVG path-элементы и фигуры.

Связанные ресурсы

Спецификация SVG 2 Embedded Content определяет, как SVG работает со встроенными ресурсами, включая элементы <image> и <foreignObject>.
SVG-фигуры объясняет базовую SVG-геометрию перед объединением фигур со встроенными изображениями.
SVG-текст рассматривает нативный SVG-текст, который переносимее, чем HTML внутри <foreignObject>.
Цвет SVG объясняет fill, stroke, прозрачность и значения цвета, используемые в окружающей SVG-графике.
Конвертация изображения в SVG на C# объясняет векторизацию растровых изображений, которая отличается от встраивания изображения через <image>.
Конвертация SVG в изображение на C# рассматривает рендеринг SVG-документов, которые могут содержать связанные изображения, шрифты, CSS или другие ресурсы.

Цвет фона SVG SVG-фильтры