SVG-текст – элементы text, tspan и textPath

SVG может отображать три основных типа графического содержимого: векторные фигуры, изображения и текст. SVG-текст – это не просто надпись на холсте. Его можно позиционировать координатами, стилизовать через CSS или presentation attributes, трансформировать, обрезать и размещать вдоль path. Эта статья объясняет, как текст записывается и располагается в SVG-разметке.

В этой статье вы узнаете, как:

использовать <text>, чтобы разместить SVG-текст в конкретной позиции базовой линии;
использовать <tspan> для многострочного SVG-текста и inline-стилизации;
использовать <textPath>, чтобы текст следовал кривой path;
управлять выравниванием, направлением, writing mode, textLength и расстоянием между глифами;
понимать разницу между символами, глифами и шрифтами.

Что такое глифы, шрифты и символы?

Глиф – визуальное представление символа внутри шрифта. Глиф задается одной или несколькими фигурами, часто path-элементами, а иногда и дополнительными подсказками для рендеринга.
Шрифт – набор глифов с общим дизайном. Векторные шрифты хранят контуры глифов как масштабируемую геометрию, поэтому текст можно увеличивать без потери четкости.
Символ – абстрактная кодовая точка, например Unicode, которую программа сопоставляет с глифом в шрифте. Символы располагаются вдоль воображаемой базовой линии, которая может быть горизонтальной или вертикальной в зависимости от письменности.

Понимание связи между символами, глифами и шрифтами важно, когда нужен точный контроль над рендерингом SVG-текста.

Элементы текстового содержимого SVG

SVG определяет три элемента содержимого, которые создают видимый текст:

Элемент	Назначение
`<text>`	Задает блок текста.
`<tspan>`	Позволяет точно позиционировать и стилизовать части текста внутри `<text>`.
`<textPath>`	Выравнивает текст вдоль кривой `<path>`.

Как добавить текст в SVG

Создайте элемент <text> внутри SVG-документа.
Задайте атрибуты x и y, чтобы расположить базовую линию текста.
Добавьте атрибуты шрифта и painting, например font-family, font-size, fill или stroke.
Используйте элементы <tspan>, если одному текстовому блоку нужны несколько строк или смешанная стилизация.
Используйте <textPath>, если текст должен идти по path, а не по прямой базовой линии.
Проверьте viewport, базовую линию и размер шрифта, если текст обрезается.

SVG-элемент `<text>`

Элемент <text> создает текстовый фрагмент. Атрибуты x и y задают начало базовой линии текста, а не левый верхний угол текстового блока. Поскольку базовая линия проходит ближе к нижней части букв, слишком маленькое значение y может поместить часть текста выше viewport. На практике задавайте y достаточно большим для выбранного font-size.

Следующий пример показывает, почему положение базовой линии важно. Первый текст использует очень маленькое значение y, поэтому буквы обрезаются. Второй текст смещает базовую линию вниз и становится полностью видимым ( svg-text-position.svg).

1<svg height="100" width="200" xmlns="http://www.w3.org/2000/svg">
2    <text x="10" y="6" fill="red">The text is not fully visible </text>
3    <text x="10" y="30" fill="green">The text is fully visible </text>
4</svg>

Пример позиционирования базовой линии SVG-текста с обрезанным и полностью видимым текстом

Атрибуты <text> и <tspan> управляют направлением письма, выравниванием, шрифтом, интервалами и позиционированием символов. Самые распространенные атрибуты:

x, y – абсолютные координаты начала базовой линии.
dx, dy – относительные смещения для отдельных символов.
rotate – угол поворота, применяемый к каждому символу.
textLength – заставляет отрисованный текст занимать заданную длину.
lengthAdjust – управляет тем, как интервалы и масштаб глифов адаптируются к textLength (spacing, spacingAndGlyphs).
text-anchor – выравнивание текста относительно координаты x (start, middle, end).
writing-mode – задает направление потока текста (lr, rl, tb, bt).

Эти атрибуты можно комбинировать, чтобы создавать сложные макеты: растянутый текст, письменность справа налево или вертикальную запись.

1<svg height="300" width="400" xmlns="http://www.w3.org/2000/svg">
2    <text x="180" y="30" fill="red">Aspose.SVG</text>
3    <text x="180" y="60" fill="blue" textLength="140">Aspose.SVG</text>
4    <text x="180" y="90" fill="grey" textLength="160" lengthAdjust="spacingAndGlyphs"
5          style="direction: rtl; unicode-bidi: bidi-override">Aspose.SVG</text>
6    <text x="180" y="120" fill="green" style="text-anchor: middle">Aspose.SVG</text>
7    <text x="260" y="90" style="writing-mode: tb">Aspose.SVG</text>
8</svg>

Пример расположения SVG-текста с textLength, text-anchor, направлением справа налево и вертикальной записью

Красный текст использует значение по умолчанию text-anchor:start.
Зеленый текст центрируется с помощью text-anchor:middle.
Серый текст показывает направление справа налево через direction:rtl.
Синий и серый тексты показывают, как textLength и lengthAdjust растягивают глифы.
Вертикальный текст использует writing-mode:tb, то есть направление сверху вниз.

`<tspan>` – inline-стилизация и переносы строк

<tspan> может находиться внутри <text> или другого <tspan>. Как дочерний элемент, <tspan> выполняет две важные функции при отображении и форматировании текста:

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

1<svg height="300" width="600" xmlns="http://www.w3.org/2000/svg">
2    <text x="20" y="60" style="font-family:arial">
3        <tspan style="font-weight:bold; font-size:55px">ASPOSE</tspan>
4        <tspan x="50" y="90" style="font-size:20px; fill:grey">Your File Format APIs </tspan>
5    </text>
6</svg>

Пример SVG tspan с многострочным текстом, разными размерами шрифта и цветом fill

x и y на <tspan> начинают новую строку в указанных координатах.
Inline-свойства style, например font-weight, font-size и fill, влияют только на этот <tspan>.

SVG `<textPath>` – текст вдоль кривой

<textPath> прикрепляет текст к элементу <path>, позволяя символам следовать любой векторной кривой. Path можно указать двумя способами:

href или xlink:href – ссылка на <path> по его id.
path – SVG path data прямо внутри атрибута.

 1<svg height="300" width="800" xmlns="http://www.w3.org/2000/svg">
 2    <path id="my_path1" d="M 50 100 Q 25 10 180 100 T 350 100 T 520 100 T 690 100"
 3          fill="transparent" />
 4    <path id="my_path2" d="M 50 100 Q 25 10 180 100 T 350 100"
 5          transform="translate(0,75)" fill="transparent" />
 6    <text>
 7        <textPath href="#my_path1">
 8            Aspose.SVG for .NET is a flexible library for SVG file processing and is fully compatible with its specifications.
 9        </textPath>
10        <textPath href="#my_path2">
11            Aspose.SVG for .NET is a flexible library for SVG file processing and is fully compatible with its specifications.
12        </textPath>
13    </text>
14</svg>

Пример SVG textPath, где текст следует двум изогнутым path

Если path короче текста, лишняя часть обрезается в конце path. Стилизация работает так же, как с обычным текстом: можно применять CSS-свойства font-weight, font-style, text-decoration и text-transform.

Иллюстрация показывает две текстовые строки, прикрепленные к двум разным path. Первая строка следует длинной волнообразной кривой, а вторая заканчивается раньше, потому что связанный с ней path короче.

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

Проблема	Причина	Решение
Текст обрезается в верхней части viewport	Значение `y` меньше размера шрифта	Задайте `y` больше размера шрифта, например `y="30"` для текста 24 px
Текст не следует кривой как ожидалось	`href` указывает на несуществующий `id` элемента `<path>`	Проверьте `id` элемента `<path>` и убедитесь, что значение `href` совпадает точно
Глифы выглядят искаженными	`lengthAdjust` задан как `spacing` при использовании `textLength`	Используйте `lengthAdjust="spacingAndGlyphs"`, чтобы масштабировать и интервалы, и глифы
Текст справа налево все еще отображается слева направо	Отсутствует `unicode-bidi:bidi-override`	Добавьте `style="direction: rtl; unicode-bidi: bidi-override"` к `<text>` или `<tspan>`
Текст не переносится на новую строку	Ожидается автоматический перенос	Вставьте новый `<tspan>` с собственными координатами `x`/`y` для каждой строки

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

Цель	SVG-фрагмент для копирования
Центрировать текст по горизонтали	`<text x="50%" y="50%" text-anchor="middle" dominant-baseline="middle">Centered</text>`
Вертикальный текст сверху вниз	`<text x="20" y="20" writing-mode="tb">Vertical</text>`
Растянуть текст до точной ширины	`<text x="10" y="40" textLength="200" lengthAdjust="spacingAndGlyphs">Stretch me</text>`
Разместить текст на кривой	`<path id="curve" d="M10,80 C40,10 65,10 95,80" fill="none"/> <text><textPath href="#curve">On a curve</textPath></text>`
Добавить подчеркивание и надчеркивание	`<text x="10" y="40" style="text-decoration: underline overline;">Styled</text>`

FAQ – SVG Text

Как позиционировать SVG-текст?

Задайте атрибуты x и y на элементе <text>. Значение y позиционирует базовую линию, поэтому оно обычно должно быть больше размера шрифта, чтобы текст не обрезался сверху viewport.

Как создать многострочный SVG-текст?

Используйте несколько элементов <tspan> внутри одного элемента <text>. Задайте каждой строке собственные значения x и y или используйте dy, чтобы смещать каждую строку относительно предыдущей.

Может ли SVG-текст идти по кривой?

Да. Определите <path> с id, затем сошлитесь на него из <textPath href="#path-id">. Текст будет следовать геометрии path и при этом может стилизоваться текстовыми CSS-свойствами.

Можно ли преобразовать SVG-текст в векторные контуры?

Да. Текст можно преобразовать в векторные paths, когда нужен результат, не зависящий от установленного шрифта. Смотрите Text Vectorization & Text Security – .NET и Преобразование SVG-текста в вектор в Python.

Спецификация и связанные ресурсы

Раздел спецификации SVG о text elements определяет поведение <text>, <tspan> и <textPath>.
Используйте Заливка и обводка в SVG, чтобы стилизовать SVG-текст через fill, stroke, opacity и paint-свойства.
Откройте SVG Path Data, если нужно понять path, используемый элементом <textPath>.
Смотрите Работа со шрифтами и текстом для .NET API-примеров, которые проверяют шрифты, глифы и поведение рендеринга текста.
Смотрите Рисование SVG-текста в Python для Python via .NET-примеров, которые создают элементы <text> и программно стилизуют SVG-текст.
Используйте Преобразование текста в вектор, когда SVG-текст нужно преобразовать в векторные контуры.
Используйте Редактирование SVG-файла для .NET API-примеров, которые программно создают и редактируют SVG-элементы.

SVG Path Data Базовые SVG-трансформации