Element Builders – Создание SVG-элементов в C# с Fluent Builder API

Aspose.SVG Builder API позволяет разработчикам создавать и редактировать SVG-элементы программно на C# с помощью fluent builder syntax. Вместо ручного создания SVG XML или прямого изменения DOM-атрибутов Element Builders предлагает более чистый и удобный для сопровождения подход к генерации SVG.

Builder API поддерживает распространенные SVG-элементы: прямоугольники, круги, пути, линии, полигоны, текст и группы. С помощью вложенных builders и цепочек методов разработчики могут создавать сложную SVG-графику с меньшим количеством шаблонного кода и лучшей читаемостью.

В этой статье объясняется, как создавать SVG-элементы в C#, программно строить SVG-графику и изменять существующие SVG-документы с помощью Aspose.SVG for .NET. Вы узнаете о базовом классе SVGElementBuilder, классе SVGSVGElementBuilder, специализированных конструкторах элементов и о том, как они упрощают программирование SVG.

Что такое SVG Element Builders?

Element Builders – это специализированные классы-конструкторы для программного создания SVG-элементов. Каждый builder соответствует определенному SVG-элементу и предоставляет строго типизированные методы для настройки SVG-атрибутов и стилей.

Builder API поддерживает:

SVG-фигуры;
текстовые элементы;
группы;
пути;
стилизацию;
трансформации;
переиспользуемые SVG-структуры.

Fluent-синтаксис упрощает генерацию SVG и улучшает сопровождаемость кода в .NET-приложениях.

Поддерживаемые SVG Element Builders

Builder	SVG-элемент
SVGSVGElementBuilder	`<svg>`
SVGRectElementBuilder	`<rect>`
SVGCircleElementBuilder	`<circle>`
SVGLineElementBuilder	`<line>`
SVGPathElementBuilder	`<path>`
SVGTextElementBuilder	`<text>`
SVGGElementBuilder	`<g>`
SVGPolygonElementBuilder	`<polygon>`
SVGPolylineElementBuilder	`<polyline>`

Полный список SVG element builders доступен на странице API Reference Aspose.Svg.Builder.

Создание новых элементов

Aspose.SVG SVG Builder API использует Fluent Builder Pattern – подход, который хорошо подходит для простого, понятного и гибкого управления SVG.

Fluent Builder Pattern

В SVG Builder API шаблон Fluent Builder используется для упрощения создания и обновления SVG-элементов, делая процесс более интуитивным и менее подверженным ошибкам. Суть шаблона – методы, которые настраивают SVG-элемент и возвращают экземпляр builder для цепочки вызовов.

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

1    using (SVGDocument document = new SVGDocument())
2    {
3        SVGSVGElement svgElement = new SVGSVGElementBuilder()
4            .AddCircle(circle => circle
5                .Cx(100).Cy(100).R(50)
6                .Fill(Color.Red).Stroke(Paint.None)
7                .StrokeWidth(2))
8            .Build(document);
9    }

Здесь circle => circle.Cx(100).Cy(100).R(50).Fill(Color.Red).Stroke(Paint.None).StrokeWidth(2) – краткий способ настроить центр, радиус, заливку и обводку круга. Такой подход упрощает конфигурацию элемента и повышает читаемость и сопровождаемость кода.

Создание SVG с нуля

Рассмотрим краткий подход к созданию SVG с нуля с помощью C#.

1using Aspose.Svg.Builder;
2using System.Drawing;
3using System.IO;

 1    // Create an SVG document from scratch using the SVG Builder API in C#
 2
 3    // Create an <svg> element with specified width, height and viewBox, and add into it other required elements
 4    SVGSVGElement svg = new SVGSVGElementBuilder()
 5        .Width(700).Height(300)
 6        .ViewBox(0, 0, 700, 300)
 7
 8        .AddG(g => g
 9        .AddCircle(circle => circle.Cx(130).Cy(130).R(60).Fill(Paint.None).Stroke(Color.FromArgb(200, 0, 0)).StrokeWidth(70).StrokeDashArray(2, 14))
10        .AddText("I can create SVG from scratch!", x: 270, y: 140, fontSize: 30, fill: Color.Teal)
11        )
12        .Build(document.FirstChild as SVGSVGElement);
13
14    // Save the document
15    document.Save(Path.Combine(OutputDir, "svg-from-scratch.svg"));
16}

Example-CreateSvgFromScratch.cs hosted with ❤ by GitHub

Визуализация файла svg-from-scratch.svg

В примере используется Fluent Builder Pattern внутри SVGSVGElementBuilder для построения SVG-элементов. Этот шаблон обеспечивает выразительный и удобный для сопровождения способ создания SVG-документов по сравнению с подходом из статьи Редактировать SVG-файл, который больше опирается на низкоуровневую работу с DOM и явную установку атрибутов. Этот подход:

предоставляет более fluent и читаемый способ создания сложных структур;
сокращает шаблонный код, поскольку атрибуты вроде cx, cy, r и fill задаются напрямую методами builder.

Редактирование SVG

Один из мощных способов программного редактирования SVG – использование Element Builders.

Добавление новых элементов

Редактирование SVG с помощью Element Builders предоставляет гибкий подход к программному управлению векторной графикой. В следующем примере существующий SVG-файл открывается, дополняется новыми элементами и сохраняется:

1using Aspose.Svg.Builder;
2using System.Drawing;
3using System.IO;

 1// Add circle and polyline elements to an existing SVG using SVG Builder in C#
 2
 3string documentPath = Path.Combine(DataDir, "circles.svg");
 4
 5// Initialize an SVG document
 6using (SVGDocument document = new SVGDocument(documentPath))
 7{
 8    // Create a <circle> element with attributes
 9    SVGCircleElement circle = new SVGCircleElementBuilder()
10     .Cx(350).Cy(70).R(50).Fill(Paint.None).Stroke(Color.FromArgb(80, 132, 132)).StrokeWidth(10)
11     .Build(document);
12
13    // Append the newly created <circle> element to the root <svg> element
14    document.RootElement.AppendChild(circle);
15
16    // Create a <polyline> element with attributes
17    SVGPolylineElement polyline = new SVGPolylineElementBuilder()
18    .Points(new double[] { 125, 130, 275, 180, 425, 130 }).Stroke(Color.FromArgb(80, 132, 132)).Fill(Paint.None).StrokeWidth(10)
19    .Build(document);
20
21    // Append the newly created <polyline> element to the root <svg> element
22    document.RootElement.AppendChild(polyline);
23
24    // Save the document
25    document.Save(Path.Combine(OutputDir, "circles-edited.svg"));
26}

Example-AddShapesToSvg.cs hosted with ❤ by GitHub

В этом примере:

Новый элемент <circle> создается с помощью SVGCircleElementBuilder. Его атрибуты cx, cy, r, fill, stroke и stroke-width настраиваются через fluent-вызовы методов.
Новый элемент <polyline> создается с помощью SVGPolylineElementBuilder, а точки и параметры обводки задаются программно.
После настройки каждого элемента метод Build(Document document) создает элемент и возвращает его для добавления в документ.
Новые элементы <circle> и <polyline> добавляются как дочерние элементы к корневому элементу <svg> SVG-документа.

На рисунке (a) показан исходный файл circles.svg, а на рисунке (b) – отредактированный файл circles-edited.svg с добавленными кругом и полилинией.

Визуализация исходного файла circles.svg и отредактированного файла circles-edited.svg с добавленными элементами circle и polyline.

Изменение существующих элементов

В следующем C# примере мы обновляем существующий SVG-документ, изменяя цвет заливки и обводки первого SVG-элемента <circle> в документе:

1using Aspose.Svg;
2using Aspose.Svg.Builder;
3using System.Drawing;
4using Aspose.Svg.Dom.Svg;
5using System.Linq;
6using System.IO;

 1// Modify an existing SVG circle element using SVG Builder in C#
 2
 3string documentPath = Path.Combine(DataDir, "circles.svg");
 4
 5// Initialize an SVG document
 6using (SVGDocument document = new SVGDocument(documentPath))
 7{
 8    // Assume an existing SVG element is part of the document
 9    SVGCircleElement circle = document.GetElementsByTagName("circle").First() as SVGCircleElement;
10
11    // Modify the first <circle> element using SVGCircleElementBuilder
12    new SVGCircleElementBuilder()
13        .Stroke(Color.DarkRed).Fill(Color.LightGray)
14
15        // The first <circle> element is now updated with new configurations
16        .Build(circle);
17
18    // Save the document
19    document.Save(Path.Combine(OutputDir, "circles-modified.svg"));
20}

Example-ModifyingExistingElements.cs hosted with ❤ by GitHub

Element Builders предоставляет метод Build(T element) для обновления существующих SVG-элементов и изменения их атрибутов или стилей. На рисунке (a) показан исходный файл circles.svg, а на рисунке (b) – circles-modified.svg с перекрашенным первым кругом.

Визуализация исходного файла circles.svg и измененного файла circles-modified.svg с перекрашенным первым элементом circle.

Пример использования Element Builders

Следующий фрагмент кода показывает, как использовать Element Builders для создания SVG-документа с различными SVG-фигурами.

1using Aspose.Svg;
2using Aspose.Svg.Builder;
3using System.Drawing;
4using Aspose.Svg.Dom.Svg;
5using System.IO;

 1// Create basic SVG shapes programmatically using SVG Builder in C#
 2
 3string svgContent = "<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>";
 4using (SVGDocument document = new SVGDocument(svgContent, "."))
 5{
 6    SVGSVGElement svg = new SVGSVGElementBuilder()
 7        .Width(100, LengthType.Percentage).Height(100, LengthType.Percentage)
 8        .ViewBox(0, 0, 800, 800)
 9
10            .AddG(g => g.FontSize(20).TextAnchor(TextAnchor.End)
11                .AddText("<rect>", y: 30)
12                .AddText("<circle>", y: 70)
13                .AddText("<ellipse>", y: 110)
14                .AddText("<line>", y: 150)
15                .AddText("<polyline>", x: 300, y: 30)
16                .AddText("<polygon>", x: 300, y: 70)
17                .AddText("<path>", x: 300, y: 110)
18                )
19
20            .AddG(gg => gg.Fill(Color.Teal).StrokeWidth(3)
21                .AddRect(r => r.X(35).Y(5).Width(30).Height(30))
22                .AddCircle(c => c.Cx(50).Cy(60).R(17))
23                .AddEllipse(e => e.Cx(50).Cy(100).Rx(25).Ry(12))
24                .AddLine(l => l.X1(30).X2(70).Y1(140).Y2(140).Stroke(Color.Teal))
25                )
26            .AddG(ggg => ggg.Fill(Paint.None).StrokeWidth(3).Stroke(Color.Teal).Transform(t => t.Translate(300, -160))
27                .AddPolygon(points: new double[] { 30, 215, 90, 215, 120, 230, 70, 240, 30, 215 }, fill: Color.Teal)
28                .AddPolyline(points: new double[] { 30, 200, 65, 170, 90, 190, 120, 180 })
29                .AddPath(d: path => path.M(30, 275).Q(55, 250, 70, 250).T(80, 275).T(120, 260))
30                )
31
32        .Build(document.FirstChild as SVGSVGElement);
33    document.Save(Path.Combine(OutputDir, "svg-elements.svg"));
34}

Example-CreateBasicSvgShapes.cs hosted with ❤ by GitHub

Визуализация файла svg-elements.svg с названиями и изображениями семи SVG-фигур.

Element Builders предоставляет fluent и выразительный синтаксис для построения SVG-элементов, улучшая читаемость и сопровождаемость кода. В этом примере SVGSVGElementBuilder создает SVG-элемент с атрибутами width, height и viewBox. Затем Fluent Builder Pattern используется для создания прямоугольников, кругов, эллипсов, линий, полилиний, полигонов и путей, размещенных и стилизованных внутри элементов <g>.

Зачем использовать Fluent SVG Builders?

DOM-манипуляции	Builder API
Ручная работа с атрибутами	Строго типизированные методы
Более многословный код	Fluent-цепочки вызовов
Сложнее сопровождать	Легче читать
Повторяющиеся XML-операции	Переиспользуемая builder-логика

FAQ

1. Почему разработчики используют Builder APIs вместо прямой генерации XML?
Builder APIs заменяет ручное создание XML типизированными fluent-методами, делая SVG-код более читаемым, сопровождаемым и расширяемым.

2. Соответствует ли сгенерированный SVG стандартам?
Да. Aspose.SVG генерирует SVG-разметку на основе стандартов, совместимую с современными SVG-рендерерами.

3. Можно ли создавать интерактивную SVG-графику с Element Builders?
Да. Сгенерированные SVG-элементы можно позже стилизовать, анимировать или изменять с помощью CSS и JavaScript в веб-приложениях.

4. Можно ли встроить сгенерированную SVG-графику прямо в HTML-страницы?
Да. SVG-документы, созданные с Aspose.SVG, можно встраивать inline в HTML или использовать как самостоятельные SVG-файлы.

Частые ошибки и исправления

Проблема	Возможная причина	Рекомендуемое исправление
SVG-элемент не виден	Отсутствует заливка или обводка	Примените `Fill()` или `Stroke()`
Изменения SVG не сохраняются	Документ не сохранен после изменения	Вызовите `document.Save()` после обновлений
Элементы находятся за пределами холста	Неверные координаты или viewBox	Проверьте размеры и позиции SVG
Существующий элемент не обновляется	Неверная ссылка на элемент	Убедитесь, что целевой элемент получен правильно
Фигуры выглядят искаженными	Неверные пропорции viewBox	Используйте согласованные SVG-системы координат

Смотрите также

Статья SVG Builder API объясняет, как программно создавать и изменять SVG-элементы в C# с помощью Aspose.SVG Builder API. Узнайте, как fluent builders упрощают генерацию SVG и улучшают читаемость кода в .NET-приложениях.
В статье Редактировать SVG-файл вы узнаете, как редактировать SVG с помощью библиотеки Aspose.SVG for .NET и рассмотрите подробные примеры C# того, как добавлять элементы в SVG-документ и редактировать их.
Посетите статью Path Builder, чтобы узнать, как использовать Path Builder для программного создания SVG-путей – набора команд для рисования различных контуров или фигур путем комбинирования SVG-линий, дуг и кривых Безье.
Статья Rule Builder посвящена классу RuleBuilder, который является классом-конструктором для создания правил стилей CSS в документе SVG.
Статья Paint Builder посвящена PaintBuilder, классу-конструктору для создания значений paint для элементов SVG. Этот класс используется для указания значения атрибутов stroke или fill для различных фигур и элементов SVG при их заполнении краской, узором или градиентом.

SVG Builder API Path Builder