Paint Builder – 在 C# 中配置 SVG Fill 和 Stroke

什么是 PaintBuilder?

Aspose.SVG Builder API 允许开发人员使用 fluent syntax 以编程方式配置 SVG 的 fill 和 stroke 属性。 PaintBuilder 类简化了 SVG paint values 的创建，包括纯色以及对 patterns 和 gradients 等 paint servers 的引用。

SVG paint configuration 常用于可复用背景、装饰纹理、图表样式、图标填充和矢量图形效果。通过嵌套 builders 和链式配置方法，SVG 生成更易读、更易维护。

本文介绍如何使用 PaintBuilder 为 SVG 元素创建 paint values。该类用于在应用颜色、patterns 或 gradients 时指定 SVG 形状和元素的 stroke 或 fill 属性值。

PaintBuilder 是 Aspose.SVG Builder API 的一部分，用于配置 SVG 的 fill 和 stroke 值。它支持多种 SVG paint values:

• 纯色
• SVG pattern 引用
• SVG gradient 引用
• 其他 paint server 引用

Builder API 使用一种 fluent configuration 模型，可简化 SVG 元素的创建和样式设置。

创建 SVG Pattern Fills

SVG patterns 允许使用重复的图形元素填充形状，而不是使用纯色。Pattern 只需定义一次，就可以在多个 SVG 元素中复用。在下面的示例中，PaintBuilder 类的 PaintServerId() 方法将 fill 值设置为按 Id 引用 paint server。

using Aspose.Svg.Builder;
using System.Drawing;
using System.IO;

// Create SVG pattern with polygons and apply as fill to rectangle using C# Builder API

using (SVGDocument document = new SVGDocument())
{
    SVGSVGElement svg = new SVGSVGElementBuilder()
        .Width(100, LengthType.Percentage).Height(100, LengthType.Percentage)
        .ViewBox(0, 0, 400, 400)
        .AddG(g => g
            .AddPattern(p => p.Id("stars")
                .ViewBox(0, 0, 20, 20)
                .Width(5, LengthType.Percentage)
                .Height(5, LengthType.Percentage)
                .PatternUnits(CoordinateUnits.UserSpaceOnUse)
                .AddPolygon(points: new double[] { 5, 0, 7, 3, 10, 5, 7, 7, 5, 10, 3, 7, 0, 5, 3, 3 }, fill: Color.Teal)
                .AddPolygon(points: new double[] { 15, 0, 17, 3, 20, 5, 17, 7, 15, 10, 13, 7, 10, 5, 13, 3 }, fill: Color.DarkRed)
                .AddPolygon(points: new double[] { 15, 10, 17, 13, 20, 15, 17, 17, 15, 20, 13, 17, 10, 15, 13, 13 }, fill: Color.DarkBlue)
            )
            .AddRect(r => r.Rect(20, 40, 440, 80).Fill(pt => pt.PaintServerId("stars")))
            )
        .Build(document.FirstChild as SVGSVGElement);
    document.Save(Path.Combine(OutputDir, "pattern-stars.svg"));
}

在此示例中，首先使用 AddPattern() 定义一个 pattern，将多个彩色多边形组合成复杂填充。该 pattern 的标识符为 stars，随后通过 Fill() 和 PaintServerId("stars") 应用于矩形。

将 Patterns 应用于 SVG 形状

Pattern fills 可应用于矩形、圆、路径、多边形和文本元素。任何支持 fill 的 SVG 元素都可以使用由 PaintBuilder 创建的 paint server 引用。

以下 C# 示例展示如何创建 SVG patterns 并将其应用到文档中的形状。该代码展示了“builder 中的 builder”方法，该方法使用多个 builder 类，其中一个 builder 嵌套在另一个 builder 中，以方便构建复杂的对象或结构，并为 SVG 文档的创建提供模块化和结构化的方法:

using Aspose.Svg.Builder;
using System.Drawing;
using System.IO;

// Create SVG patterns with reusable elements and apply them to circles using C# Builder API

using (SVGDocument document = new SVGDocument())
{
    SVGSVGElement svg = new SVGSVGElementBuilder()
        .Width(100, LengthType.Percentage).Height(100, LengthType.Percentage)
        .ViewBox(0, 0, 600, 600)
        .AddG(g => g
            .FontFamily("Arial")
            .FontSize(10)
            .AddPattern(p => p.Id("Pat3a")
                .Rect(0, 0, 20, 20)
                .PatternUnits(CoordinateUnits.UserSpaceOnUse)
                .AddRect(r => r.Rect(0, 0, 10, 10).Fill(Color.LightSlateGray))
                .AddRect(r => r.Rect(10, 0, 10, 10).Fill(Color.Teal))
                .AddRect(r => r.Rect(0, 10, 10, 10).Fill(Color.DarkRed))
                .AddRect(r => r.Rect(10, 10, 10, 10).Fill(Color.Gold))
            )
            .AddPattern(p => p.Id("Pat3b")
                .Href("#Pat3a")
                .Width(23).Height(23)
            )
            .AddPattern(p => p.Id("Pat3c")
                .Href("#Pat3a")
                .Width(15).Height(15)
            )
            .AddCircle(circle => circle.Cx(90).Cy(130).R(70).Fill(pt => pt.PaintServerId("Pat3a")))
            .AddText(t => t.X(55).Y(50)
                .AddContent("Pattern #Pat3a")
            )
            .AddCircle(circle => circle.Cx(240).Cy(130).R(70).Fill(pt => pt.PaintServerId("Pat3b")))
            .AddText(t => t.X(205).Y(50)
                .AddContent("Pattern #Pat3b")
            )
            .AddCircle(circle => circle.Cx(390).Cy(130).R(70).Fill(pt => pt.PaintServerId("Pat3c")))
            .AddText(t => t.X(355).Y(50)
                .AddContent("Pattern #Pat3c")
            )
        )
        .Build(document.FirstChild as SVGSVGElement);
    document.Save(Path.Combine(OutputDir, "patterns.svg"));
}

Pattern 如何工作

<pattern> 元素定义一个可复用的图块，该图块会在填充的形状中重复。在此示例中:

• Width() 和 Height() 定义重复图块的大小;
• PatternUnits(UserSpaceOnUse) 使用固定坐标进行 pattern 重复;
• circle 元素定义 pattern 内部重复的图形内容。

Pattern 可以通过引用同一个 pattern ID 在多个 SVG 元素中复用。较小的 pattern 尺寸会产生更密集的重复，较大的值会增加重复元素之间的间距。

在此示例中，向 SVG 文档添加了三个不同的 pattern，分别命名为 Pat3a、Pat3b 和 Pat3c。

• 对于 Pat3a，在 AddG() 方法中使用 AddPattern() 方法定义了一个 pattern。在该 pattern 中，添加了四个矩形以在 20x20 单位的空间（即图块）内定义不同颜色的不同区域。
• Pat3b 和 Pat3c 被定义为对 Pat3a 的引用，并使用 Width() 和 Height() 方法指定了不同的图块大小。

pattern 元素中图块的高度和宽度定义了 SVG 文档中重复 pattern 单元的大小。该大小决定了 pattern 在应用于形状或元素时的外观。在 pattern Pat3b 中，增加图块的高度和宽度会放大 pattern 单元，从而导致出现未填充（透明）的区域。在 pattern Pat3c 中，减小图块的高度和宽度会使 pattern 看起来更密集，从而产生不同的视觉效果。

因此，调整 SVG <pattern> 元素中图块的高度和宽度可让您控制 SVG 文档中 pattern 的密度和重复，并能够创建多样化的视觉效果。

创建 Linear Gradient Fills

Aspose.SVG Builder API 允许创建可复用的 SVG linear gradients，并以编程方式将其应用到 SVG 形状。Gradients 常用于背景、图表、按钮和装饰图形。

using Aspose.Svg.Builder;
using System.Drawing;
using System.IO;

using (SVGDocument document = new SVGDocument())
{
    SVGSVGElement svg = new SVGSVGElementBuilder()
        .Width(400).Height(200)
        .ViewBox(0, 0, 400, 200)
        .AddDefs(defs => defs
            .AddLinearGradient(gradient => gradient
                .Id("gradientFill")
                .X1(0, LengthType.Percentage).Y1(0, LengthType.Percentage)
                .X2(100, LengthType.Percentage).Y2(0, LengthType.Percentage)
                .AddStop(stop => stop
                    .Offset(0, StopUnitType.Percentage)
                    .Attribute("stop-color", "gold"))
                .AddStop(stop => stop
                    .Offset(100, StopUnitType.Percentage)
                    .Attribute("stop-color", "teal"))))
        .AddRect(rect => rect
            .Rect(20, 20, 360, 160)
            .Fill(paint => paint.PaintServerId("gradientFill")))
        .Build(document.FirstChild as SVGSVGElement);

    document.Save(Path.Combine(OutputDir, "linear-gradient-fill.svg"));
}

Gradient 如何工作

示例在 <defs> 中创建可复用的 SVG <linearGradient> 定义，并将其应用于矩形填充。

• AddLinearGradient() 定义 gradient 的方向和标识符;
• AddStop() 定义颜色过渡点;
• PaintServerId("gradientFill") 将 gradient paint server 应用于矩形填充，并在 SVG 输出中生成 url(#gradientFill) 引用;
• gradient 可在多个 SVG 元素中复用。

常见错误和修复

问题	原因	修复方法
Pattern 不可见	Pattern ID 不正确	确保 PaintServerId() 与 Id() 匹配
Pattern 看起来被拉伸	图块大小过大	调整 pattern 的 Width() 和 Height()
Pattern 无法正确重复	PatternUnits 值不正确	需要固定图块时使用 UserSpaceOnUse
Fill 未应用	Pattern 定义在不可访问范围之外	在应用之前定义 patterns

FAQ

1. SVG 中的 paint server 是什么?
Paint server 是提供 fill 或 stroke 值的 SVG 资源。常见 paint servers 包括通过 url(#id) 引用的 patterns 和 gradients。

2. 可以将同一个 SVG pattern 用于多个形状吗?
可以。通过 PaintServerId() 引用同一个 ID，一个 SVG pattern 可用于多个元素。

3. UserSpaceOnUse 和 ObjectBoundingBox 有什么区别?
UserSpaceOnUse 使用固定坐标，而 ObjectBoundingBox 会根据目标元素大小缩放 pattern。

4. 为什么 SVG pattern 看起来被拉伸?
通常是因为 pattern 图块过大，或坐标系统与目标 SVG 元素尺寸不匹配。

5. 可以将 SVG patterns 应用于文本元素吗?
可以。SVG 文本元素支持 fill，可以像形状一样使用 pattern fills。

6. PaintBuilder 支持 SVG gradients 吗?
支持。PaintBuilder 支持 paint server 引用，用于以编程方式配置 SVG gradient fills。

Related Resources

• SVG Builder API 文章介绍了如何使用 Aspose.SVG Builder API 在 C# 中以编程方式创建和操作 SVG 元素。了解 fluent builders 如何简化 SVG 生成并提高 .NET 应用程序中的代码可读性。
• Element Builders 文章探讨了 Aspose.SVG for .NET 中的 SVG 元素 builders。了解专门的 builder 类如何简化在 C# 中创建 SVG 形状、图形和文档结构。
• Path Builder 文章介绍了如何使用 C# 以编程方式创建 SVG 路径。了解 PathBuilder 类如何使用 fluent 语法简化复杂 SVG 形状、曲线和矢量图形的生成。
• Rule Builder 文章介绍了如何使用 RuleBuilder 类在 C# 中为 SVG 文档创建 CSS 样式规则。了解如何在 .NET 应用程序中以编程方式配置 SVG 样式。
• SVG Filters 文章介绍了如何在 C# 中创建高斯模糊、投影、光照和饱和度等 SVG 滤镜效果。了解如何使用 Aspose.SVG for .NET 以编程方式应用 SVG 滤镜。
• SVG Gradients 文章介绍了如何在 C# 中创建线性和径向 SVG 渐变。了解如何在 XML 中定义可复用的 SVG 渐变填充并以编程方式生成它们。
• SVG 绘图基础 部分介绍了 SVG 图形创建的基础知识，包括使用 C# 和 Aspose.SVG for .NET 进行形状、路径、填充、渐变、滤镜和变换。