syncfusion-dotnet-word

Word（DOCX）文档处理

概述

使用 Syncfusion Word Library 创建、编辑和转换 Word（.docx、.doc）文件。 此技能支持两种操作模式——为用户的项目生成 C# 代码，或直接通过 CSX 脚本执行任务。

主要功能

• 创建与编辑： 文档（.docx、.doc、.rtf、.txt、.xml）、段落、标题、样式、列表、表格、图表、形状、图像、超链接、书签、水印、页眉/页脚、表单字段、内容控件、SmartArt、OLE 对象，以及在保存 Word 文档时嵌入字体
• 高级功能： 邮件合并（DataTable、JSON、XML、自定义对象）、修订跟踪、批注、数学公式（LaTeX）、比较/拆分/合并文档、目录
• 转换： Word 转 PDF（嵌入字体、注册自定义字体、PDF/A、无障碍支持）、Word 转图像（PNG、JPEG、BMP、TIFF、注册自定义字体）、HTML ↔ DOCX、RTF ↔ DOCX、文本 ↔ DOCX、XML ↔ DOCX
• 安全： 密码加密/解密、带可编辑区域的文档保护、宏管理和数字签名

先决条件

• .NET SDK 8+ 和 dotnet-script：dotnet tool install -g dotnet-script
• Syncfusion 许可证：https://www.syncfusion.com/products/communitylicense

快速入门示例

示例 1：生成代码（模式 1）

用户：“告诉我如何创建带表格的 Word 文档”

结果： 显示 C# 代码片段（不创建文件）

示例 2：执行任务（模式 2）

用户：“在 output/report.docx 创建带表格的 Word 文档”

结果： 在指定路径创建实际文件

两种模式——根据用户意图选择

选择模式前，先推断用户想要完成什么：

模式 1：为用户的项目生成 C# 代码（默认）

当用户想要查看、编写、审查、重构或修改与 Word 处理相关的 C# 代码时，使用此模式。

触发关键词：“show me how”、“how to”、“how can I”、“how do I”、“provide code”、“provide an example”、“give an example”、“demonstrate”、“code snippet”、“sample code”、“example”、“sample”、“give me”、“show me”、“Program.cs”、“example code”、“generate code for”、“codesnippet”

工作流：

第 1 步——检测应用类型并推荐正确的 NuGet 包

• 检查工作区项目文件（.csproj、web.config、App.config、Startup.cs、Program.cs 等），并使用 references/nuget-packages.md 中的检测信号表识别应用类型。
• 根据检测到的应用类型，从 references/nuget-packages.md 中查找正确的包，并告知用户在生成任何代码之前安装这些包。

第 2 步——仅根据参考文件生成代码

不得臆造、猜测或建议参考文件中未明确列出的任何 API、方法、属性、类或命名空间。

• 读取与所请求功能相关的 references/*.md 文件
• 严格依据这些文件中的 API 和代码片段编写 C# 代码
• 根据第 1 步检测到的应用类型选择正确的代码片段变体：
  • 特定于 Windows 的应用（WinForms、WPF、.NET Framework Console、ASP.NET MVC5）→ 使用特定于 Windows 的代码片段
  • 跨平台应用（ASP.NET Core、.NET Core/.NET 5+ Console、Blazor、MAUI）→ 使用跨平台 / .Net.Core 代码片段
• 不要创建或运行任何 .csx 脚本

---

模式 2：通过 CSX 脚本执行（不会触及项目文件）

仅当用户明确要求执行、生成文件或生成完整的输出（例如已完成的 Docx 文件）时，使用此模式。

触发关键词：“create a word document”、“make a document”、“generate a document”、“open”、“edit”、“modify”、“change”某个 .docx 文件、“without modifying my project”、“run a csx script”，或用户提供文件路径时（例如 output/report.docx）。

工作流：

步骤 1 — 创建临时 CSX 脚本

• 以 references/template.csx 为基础
• 创建于：{skill-root}/syncfusion-dotnet-word/scripts/temp-{uniqueId}.csx（例如，skill-root = .codestudio/skills）
• 使用随机 GUID 作为唯一文件名（例如，temp-a3f7b2c1.csx）；切勿在工作区根目录中创建

步骤 2 — 根据参考文件构建脚本

• 不要编造参考文件中没有的 API/方法
• 阅读相关的 references/*.md 文件并提取代码片段
• 替换所有占位符：文件路径、文档属性、数据值、字段名称等

步骤 3 — 执行脚本

• 运行：dotnet script {skill-root}/syncfusion-dotnet-word/scripts/temp-{uniqueId}.csx
• 验证是否成功执行并捕获任何错误

步骤 4 — 清理并报告

• 执行后删除临时 .csx 文件
• 报告 SUCCESS/ERROR，以及输出文件路径和任何错误消息及其修复方法

---

代码参考

所有模板和代码片段均位于 references/ 文件夹中：

文件	内容
template.csx	CSX 脚本基本结构（仅限模式 2）
document-structure.md	创建/加载文档、添加章节、页面设置、保存到文件或流、保存 DOCX 时嵌入字体、支持的格式
styles-and-formats.md	段落、标题、项目符号列表和编号列表
paragraph-and-styles.md	添加段落、段落格式、样式（内置/自定义）、文本格式、制表位、分隔符、符号、文本框
tables.md	创建表格、设置单元格格式、合并单元格
bookmarks.md	创建书签、导航、检索、插入、替换、删除内容、书签结束位置选项
charts.md	从零开始创建图表/从 Excel 创建图表、修改数据、刷新、自定义元素、设置 3D 格式、转换为图像
shapes.md	添加形状、设置格式、旋转、组合和取消组合形状
mail-merge.md	简单字段合并、使用区域（组）合并、嵌套合并、DataTable、动态对象、业务对象、DataView、XML、JSON、图像合并字段、合并事件（MergeField、MergeImageField、BeforeClearField、BeforeClearGroupField）、字段映射、检索合并字段名称、删除空段落、清除字段选项
form-fields.md	添加复选框、下拉列表、文本输入字段、修改属性
macros.md	加载/保存启用宏的文档（DOTM、DOCM）、检查是否含有宏、删除宏、转换时保留宏
mathematical-equation.md	创建公式（分数、根式、矩阵、N 元组等）、修改现有公式、支持 LaTeX、公式格式
split-word-documents.md	按章节、标题、书签、占位文本拆分文档
merge-word-documents.md	在新页面或同一页面合并文档、保留导入的列表样式
table-of-contents.md	添加目录、更新目录、应用开关、自定义样式、图表目录、删除目录
compare-word-documents.md	比较两个 Word 文档、设置作者和日期、比较选项、忽略格式更改
html-conversions.md	将 HTML 转换为 DOCX、将 DOCX 转换为 HTML、XHTML 验证、自定义图像（导入/导出）、CSS 选择器、导出选项、导出页眉/页脚
rtf-conversions.md	将 RTF 转换为 DOCX、将 DOCX 转换为 RTF、保留格式和内容
markdown-conversion.md	将 Markdown 转换为 DOCX、将 DOCX 转换为 Markdown、自定义图像、支持 CommonMark 和 GitHub 风格语法
text-conversions.md	将文本转换为 DOCX、将 DOCX 转换为文本、提取纯文本、保留文本内容
xml-conversions.md	将 Word 转换为 XML（WordML）、将 XML 转换为 Word、Word Processing XML 格式（2007+）
word-to-pdf.md	将 DOCX 转换为 PDF、嵌入字体、自定义字体注册、符合 PDF/A 标准、无障碍 PDF、保留表单字段、字体替换、按脚本类型和 Unicode 范围使用回退字体
word-to-image.md	将 DOCX 转换为图像、自定义字体注册、将指定页面或页面范围转换为图像
word-to-odt.md	将 Word 转换为 ODT、保留格式和内容、支持的文档元素、文本格式
encryption.md	使用密码加密、打开加密文档、移除加密、保护文档免于编辑、可编辑区域
digital-signature.md	添加不可见数字签名、插入并签署一条或多条可见签名行、指定签名标准、验证、检查和移除签名；代码片段适用于跨平台和 Windows 专用应用
watermark.md	文本和图片水印、水印布局、缩放、淡化效果、移除水印
find-and-replace.md	Find/FindAll/FindNext、Replace（字符串/正则表达式）、ReplaceSingleLine 和 FindItem* API
footnotes-and-endnotes.md	添加脚注和尾注、设置位置（页面底部/章节末尾）、编号格式、分隔符、修改内容、移除注释
track-changes.md	启用/禁用修订、接受/拒绝更改、按审阅者筛选、修订信息
comments.md	添加/修改/移除批注、在指定文本上插入批注、访问父批注、检索带批注的项目
content-controls.md	块级和行内内容控件、类型（富文本、纯文本、复选框、日期、下拉列表、图片）、属性、保护、填写表单、XML 映射
header-footer.md	添加/移除页眉和页脚、使用字段（日期、时间）插入页码、奇偶页、首页不同、边框、图像、链接到前一节
hyperlinks.md	网页超链接、电子邮件超链接、文件超链接、书签超链接、图像超链接、修改超链接
ole-object.md	添加嵌入式 OLE 对象、将 OLE 对象提取到文件、移除 OLE 对象、对象类型
smartarts.md	创建 SmartArt 布局、添加/修改节点、更改外观、助理节点、移除 SmartArt

---

规则

• 输出文件放在 ./output/ 目录中
• 临时 .csx 脚本必须创建在 {skill-root}/syncfusion-dotnet-word/scripts/ 中，切勿放在工作区根目录或客户的 scripts/ 文件夹中
• 切勿使用 Python 库（例如 python-docx）
• 执行后切勿留下临时 .csx 文件