简介
Word 文档将图像、文本框和其他自由漂浮的对象放置在一个绘图层中，该层独立于段落和表格的常规流。Aspose.Words FOSS for .NET 通过 Shape 和 ShapeBase 类公开此绘图层，提供对 Word 本身内部使用的相同 AutoShape、图片、文本框和 OLE 对象模型的编程访问。本指南展示了库如何在 DOCX、DOCM、DOTX 和 DOTM 文档中表示和操作这些绘图对象——定位、填充和轮廓格式、嵌入图片以及形状内部的文本布局。
这对于编写代码生成带有定位徽标或图形的报告或信头模板、生成包含浮动文本框和标注的文档，或检查已上传文档中已有的形状非常有用——例如提取嵌入图片的字节、读取签名行的签署人姓名，或重新定位已有的图像。
Aspose.Words FOSS for .NET 在 MIT 许可证下发布，并面向 .NET Standard 2.0，因此它可在 .NET Framework 4.6.2+ 和 .NET 6、8、10 上运行，无需本地依赖。通过 NuGet 安装，或从源码构建（见下文快速入门）。它是商业使用的同一 Aspose.Words 文档引擎，而非重写或包装，因此此处描述的 Shape 和绘图层类是生产环境的 API。
关键特性
Shape 和 ShapeBase 对象模型
Word 文档中锚定的每个 AutoShape、文本框、嵌入图片、OLE 对象或 ActiveX 控件，都由 Shape 类表示——该类为 sealed，并基于抽象的 ShapeBase 基类构建。两者共享相同的定位和格式化界面：用于几何的 Shape.Left、Shape.Top、Shape.Width、Shape.Height、Shape.Rotation 和 Shape.ZOrder，以及描述实例所持对象类型的标志 Shape.IsGroup、Shape.IsImage、Shape.IsWordArt、Shape.IsInline。ShapeType 枚举列举了 Word 识别的具体形状类型——矩形、椭圆、线条、箭头、一系列标注和连接器类型、TextBox、图片以及 OleObject，共超过八十种值——因此遍历文档形状的代码可以基于 Shape.ShapeType 分支，以决定如何处理每一种。多个形状可以合并为单个 GroupShape，它本身是 ShapeBase 的子类，能够将一组形状一起定位和重新大小；DocumentBuilder.InsertGroupShape(shapes) 则可以从现有形状数组构建此对象。
文本框和 WordArt
任何 Shape 都可以通过 TextBox 类携带自己的文本，公开为 Shape.TextBox。TextBox 属性控制文本在形状内部的布局：用于内边距的 TextBox.InternalMarginLeft、TextBox.InternalMarginRight、TextBox.InternalMarginTop 和 TextBox.InternalMarginBottom，TextBox.FitShapeToText 用于让形状随内容增长，LayoutFlow 用于文本方向，TextBoxWrapMode 用于文本在框内的换行方式，TextBox.VerticalAnchor —— 一个 TextBoxAnchor 值，例如 Top、Middle、BottomCentered 或 TopBaseline —— 用于垂直对齐。链接的文本框（当溢出文本继续到第二个框时）使用 TextBox.Next 和 TextBox.Previous 建模。另一个相关但不同的类 TextPath 定义了沿形状轮廓而非内部的 WordArt 样式文本，具有如 TextPath.Text、TextPath.FontFamily、TextPath.Bold、TextPath.RotateLetters 等属性，以及一个包含 Stretch、Center 和 LetterJustify 等值的 TextPathAlignment 枚举。
图片和嵌入式图像
当形状包含图片时，Shape.HasImage 为 true，Shape.ImageData 返回一个 ImageData 对象。ImageData 通过 ImageData.ImageBytes 暴露原始字节，通过 ImageType 暴露检测到的格式（值包括 Jpeg、Png、Bmp、Gif、Emf、Wmf、Pict、Eps 和 WebP），通过 ImageSize 提供像素尺寸和分辨率，并通过 ImageData.CropTop、ImageData.CropBottom、ImageData.CropLeft、ImageData.CropRight 实现裁剪。颜色调整——ImageData.Brightness、ImageData.Contrast、ImageData.GrayScale、ImageData.BiLevel、ImageData.ChromaKey——是同一对象上的属性，ImageData.IsLink/ImageData.IsLinkOnly 用于区分嵌入式图片与仅引用外部文件路径的图片。DocumentBuilder.InsertImage() 提供接受图像、文件路径、字节数组或流的重载版本，包括在插入时还设置显式宽度、高度、水平和垂直位置以及 WrapType 的变体。
填充、描边和形状效果
每个 Shape 和 GroupShape 都包含一个用于内部的 Fill 对象和一个用于轮廓的 Stroke 对象。Fill 通过 FillType 支持六种填充类型，值包括 Solid、Patterned、Gradient、Textured、Background 和 Picture，可使用 Fill.Solid(color)、Fill.OneColorGradient(style, variant, degree)、Fill.TwoColorGradient(color1, color2, style, variant)、Fill.Patterned(patternType) 或 Fill.SetImage(fileName) 等方法设置。Stroke 控制轮廓：Stroke.Weight、DashStyle、JoinStyle、EndCap 和 Stroke.LineStyle（一个 ShapeLineStyle 值）覆盖线本身，而 Stroke.StartArrowType 和 Stroke.EndArrowType 与 ArrowWidth、ArrowLength 枚举配合，配置连接器和线形状的箭头。除填充和描边外，Shape 公开四个进一步的效果对象——ShadowFormat、ReflectionFormat、GlowFormat、SoftEdgeFormat——每个对象都有其对应视觉效果的颜色和透明度属性。
定位和文本环绕
相对于页面或段落浮动的形状使用 RelativeHorizontalPosition 和 RelativeVerticalPosition 进行锚定——例如锚定到页边距、页面或栏——并配合 RelativeHorizontalSize 和 RelativeVerticalSize 进行尺寸锚定，再加上 HorizontalAlignment 和 VerticalAlignment 实现左/居中/右或上/中/下的简单定位。周围文本对形状的响应由 WrapType 控制，取值包括 Inline、Square、Tight、TopBottom 和 None；对于 Square 和 Tight 环绕，WrapSide 进一步细分为 Left、Right、Both 或 Largest。FlipOrientation 在不改变坐标的情况下水平或垂直镜像形状，Shape.AllowOverlap/Shape.BehindText 标志则控制形状与其他浮动内容以及其下方文本层的交互方式。
签名线和水平分隔线
同一绘图模型中还有另外两种专用形状类型。SignatureLine 在插入时通过 SignatureLineOptions 配置（属性包括 SignatureLineOptions.Signer、SignatureLineOptions.SignerTitle、SignatureLineOptions.Email、SignatureLineOptions.Instructions、SignatureLineOptions.ShowDate 和 SignatureLineOptions.AllowComments），渲染可打印文档中可见的可视签名块，并在签名应用后公开 SignatureLine.IsSigned 和 SignatureLine.IsValid——这与其他地方讨论的加密数字签名验证不同，后者针对已签名的文档部分而不是形状本身。HorizontalRuleFormat 处理通过 DocumentBuilder.InsertHorizontalRule() 插入的普通分隔线，具有 HorizontalRuleFormat.WidthPercent、HorizontalRuleFormat.Height、HorizontalRuleFormat.NoShade、HorizontalRuleFormat.Color 和 HorizontalRuleFormat.Alignment 属性（最后一个是 HorizontalRuleAlignment 值）。
快速入门
Aspose.Words FOSS 用于 .NET 可通过 NuGet 获得：
dotnet add package Aspose.Words.FOSS改为从源码构建：
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
在你的应用程序中添加对 Aspose.Words.csproj 的项目引用。此后，使用绘图层遵循本文中贯穿的模式：加载或创建一个 Document，使用 Document.GetChildNodes(NodeType.Shape, true) 遍历其形状，或使用 DocumentBuilder 方法（如 DocumentBuilder.InsertImage()、DocumentBuilder.InsertGroupShape() 或 DocumentBuilder.InsertHorizontalRule()）插入新的形状，然后在返回的 Shape 上读取或设置属性——包括 Shape.ImageData、Shape.TextBox、Shape.Fill、Shape.Stroke、Shape.WrapType 等——最后调用 Document.Save()。
支持的格式
| 格式 | 扩展名 | 读取 | 写入 |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| 平面 OPC (所有变体) | (各种) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
此版本特意排除页面布局和渲染——不支持 PDF、XPS 或图像导出，也不支持打印——因此形状的 Shape.Bounds 和依赖布局的几何形状反映文档中存储的值，而不是计算后的页面布局。额外的格式转换器（DOC、RTF、ODT、HTML、EPUB、MHTML、MOBI、AZW3，以及 WordML）不进行读取或写入；这些正是为保持此版本免费而从商业代码库中移除的子系统。
开源与许可
Aspose.Words FOSS for .NET 在 MIT 许可证下发布，可免费用于商业和个人用途，无版税或再分发限制。完整源代码可在 GitHub 的 Aspose.Words FOSS for .NET 仓库 中获取。
