syncfusion-dotnet-word

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Word (DOCX) Document Processing

Word（DOCX）文档处理

Overview

概述

Create, edit, and convert Word (.docx, .doc) files using the Syncfusion Word Library. This skill supports two operational modes — generating C# code for the user's project or executing tasks directly through a CSX script.

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

Key Capabilities

核心功能

Create & Edit: Documents (.docx, .doc, .rtf, .txt, .xml), paragraphs, headings, styles, lists, tables, charts, shapes, images, hyperlinks, bookmarks, watermarks, headers/footers, form fields, content controls, SmartArt, OLE objects
Advanced Features: Mail merge (DataTable, JSON, XML, custom objects), track changes, comments, mathematical equations (LaTeX), compare/split/merge documents, table of contents
Conversion: Word to PDF (font embedding, PDF/A, accessibility), Word to Image (PNG, JPEG, BMP, TIFF), HTML ↔ DOCX, RTF ↔ DOCX, Text ↔ DOCX, XML ↔ DOCX
Security: Password encryption/decryption, document protection with editable ranges, macro management

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

Prerequisites

前置条件

.NET SDK 8+ and

dotnet-script

dotnet tool install -g dotnet-script

Syncfusion License: https://www.syncfusion.com/products/communitylicense

.NET SDK 8+ 和

dotnet-script

：

dotnet tool install -g dotnet-script

Syncfusion许可证：https://www.syncfusion.com/products/communitylicense

Quick Start Examples

快速入门示例

Example 1: Generate Code (Mode 1)

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

User: "Show me how to create a Word document with a table"

Result: C# code snippet displayed (no files created)

用户： "展示如何创建带表格的Word文档"

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

Example 2: Execute Task (Mode 2)

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

User: "Create a Word document with a table at output/report.docx"

Result: Physical file created at specified path

用户： "在output/report.docx路径创建带表格的Word文档"

结果： 在指定路径生成实体文件

Two Modes — Choose Based on User Intent

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

Before choosing a mode, infer what the user wants to accomplish:

选择模式前，请推断用户的目标：

Mode 1: Generate C# Code for the User's Project (default)

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

Use this mode when the user wants to view, write, review, refactor, or modify C# code related to Word processing.

Trigger keywords: "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"

Workflow:

当用户需要查看、编写、审阅、重构或修改与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"

工作流：

Step 1 — Detect the Application Type and Suggest the Correct NuGet Package(s)

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

Inspect the workspace project files (
```
.csproj
```
,
```
web.config
```
,
```
App.config
```
,
```
Startup.cs
```
,
```
Program.cs
```
, etc.) and use the detection signals table in
```
references/nuget-packages.md
```
to identify the application type.
Look up the correct package(s) from
```
references/nuget-packages.md
```
based on the detected app type and tell the user to install them before generating any code.

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

Step 2 — Generate Code from Reference Files Only

步骤2——仅从参考文件生成代码

Do NOT invent, guess, or suggest any API, method, property, class, or namespace not explicitly present in the reference files.

Read the relevant
```
references/*.md
```
file(s) for the requested feature
Build C# code strictly from the APIs and snippets found in those files
Select the correct snippet variant based on the app type detected in Step 1:
- Windows-specific apps (WinForms, WPF, .NET Framework Console, ASP.NET MVC4/5, UWP) → use Windows-specific snippets
- Cross-platform apps (ASP.NET Core, .NET Core/.NET 5+ Console, Blazor, MAUI, Xamarin) → use cross-platform /
```
.Net.Core
```
  snippets
Do not create or run any
```
.csx
```
script

不得发明、猜测或建议任何未在参考文件中明确提及的API、方法、属性、类或命名空间。

读取与请求功能相关的
```
references/*.md
```
文件
严格基于这些文件中的API和代码片段构建C#代码
根据步骤1中检测到的应用类型选择正确的代码片段变体：
- Windows专属应用（WinForms、WPF、.NET Framework控制台、ASP.NET MVC4/5、UWP）→ 使用Windows专属代码片段
- 跨平台应用（ASP.NET Core、.NET Core/.NET 5+控制台、Blazor、MAUI、Xamarin）→ 使用跨平台/
```
.Net.Core
```
  代码片段
不得创建或运行任何
```
.csx
```
脚本

Mode 2: Execute via CSX Script (does not touch project files)

模式2：通过CSX脚本执行（不修改项目文件）

Use this mode only when the user explicitly requests execution, file generation, or a fully produced output (such as a completed Docx file).

Trigger keywords: "create a word document", "make a document", "generate a document", "open", "edit", "modify", "change" a

.docx

file, "without modifying my project", "run a csx script", or when the user provides a file path (e.g.,

output/report.docx

Workflow:

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

触发关键词： "create a word document"、"make a document"、"generate a document"、"open"、"edit"、"modify"、"change" a

.docx

file、"without modifying my project"、"run a csx script"，或当用户提供文件路径时（如

output/report.docx

）。

工作流：

Step 1 — Create Temp CSX Script

步骤1——创建临时CSX脚本

Start with
```
references/template.csx
```
as the base

Create at:

{skill-root}/syncfusion-dotnet-word/scripts/temp-{uniqueId}.csx

(e.g.,

skill-root

.codestudio/skills

)

Use random GUID for unique filename (e.g.,
```
temp-a3f7b2c1.csx
```
); never create in workspace root

以
```
references/template.csx
```
为基础

创建路径：

{skill-root}/syncfusion-dotnet-word/scripts/temp-{uniqueId}.csx

（例如

skill-root

.codestudio/skills

）

使用随机GUID作为唯一文件名（如
```
temp-a3f7b2c1.csx
```
）；绝对不能在工作区根目录创建

Step 2 — Build Script from Reference Files

步骤2——基于参考文件构建脚本

Do NOT invent APIs/methods not in reference files
Read relevant
```
references/*.md
```
file(s) and extract code snippets
Replace all placeholders: file paths, document properties, data values, field names, etc.

不得发明参考文件中未包含的API/方法
读取相关的
```
references/*.md
```
文件并提取代码片段
替换所有占位符：文件路径、文档属性、数据值、字段名等

Step 3 — Execute Script

步骤3——执行脚本

Run:

dotnet script {skill-root}/syncfusion-dotnet-word/scripts/temp-{uniqueId}.csx

Verify successful execution and capture any errors

运行命令：

dotnet script {skill-root}/syncfusion-dotnet-word/scripts/temp-{uniqueId}.csx

验证执行是否成功并捕获所有错误

Step 4 — Clean Up and Report

步骤4——清理并报告

Delete the temp
```
.csx
```
file after execution
Report SUCCESS/ERROR with output file path(s) and any error messages with fixes

执行完成后删除临时
```
.csx
```
文件
报告成功/错误状态，包含输出文件路径及任何错误信息和修复方案

Code References

代码参考

All templates and snippets are in the

references/

folder:

File	Contents
template.csx	Base CSX script structure (Mode 2 only)
document-structure.md	Create/load document, add sections, page setup, save to file or stream, supported formats
styles-and-formats.md	Paragraphs, headings, bullet & numbered lists
paragraph-and-styles.md	Add paragraphs, paragraph formatting, styles (built-in/custom), text formatting, tab stops, breaks, symbols, text boxes
tables.md	Create tables, cell formatting, merge cells
bookmarks.md	Create bookmarks, navigate, retrieve, insert, replace, delete content
charts.md	Create charts from scratch/Excel, modify data, refresh, customize elements, 3D formatting, convert to image
shapes.md	Add shapes, format, rotate, group, ungroup shapes
mail-merge.md	Simple field merge, merge with regions (groups), nested merge, DataTable, dynamic objects, business objects, DataView, XML, JSON, image merge fields, merge events (MergeField, MergeImageField, BeforeClearField, BeforeClearGroupField), field mapping, retrieve merge field names, remove empty paragraphs, clear fields option
form-fields.md	Add checkboxes, dropdowns, text input fields, modify properties
macros.md	Load/save macro-enabled documents (DOTM, DOCM), check for macros, remove macros, preserve macros through conversion
mathematical-equation.md	Create equations (fraction, radical, matrix, N-array, etc.), modify existing equations, LaTeX support, equation formatting
split-word-documents.md	Split documents by sections, headings, bookmarks, placeholder text
merge-word-documents.md	Merge documents in new page, same page, maintain imported list styles
table-of-contents.md	Add TOC, update, apply switches, custom styles, table of figures, remove TOC
compare-word-documents.md	Compare two Word documents, set author and date, comparison options, ignore format changes
html-conversions.md	Convert HTML to DOCX, convert DOCX to HTML, XHTML validation, customize images (import/export), CSS selectors, export options, headers/footers export
rtf-conversions.md	Convert RTF to DOCX, convert DOCX to RTF, preserve formatting and content
markdown-conversion.md	Convert Markdown to DOCX, convert DOCX to Markdown, customize images, CommonMark and GitHub-flavored syntax support
text-conversions.md	Convert Text to DOCX, convert DOCX to Text, extract plain text, preserve text content
xml-conversions.md	Convert Word to XML (WordML), convert XML to Word, Word Processing XML format (2007+)
word-to-pdf.md	Convert DOCX to PDF, embed fonts, PDF/A conformance, accessible PDF, preserve form fields, font substitution, fallback fonts by script type and Unicode ranges
word-to-image.md	Convert DOCX to Image
word-to-odt.md	Convert Word to ODT, preserve formatting and content, supported document elements, text formatting
encryption.md	Encrypt with password, open encrypted doc, remove encryption, protect from editing, editable ranges
watermark.md	Text and picture watermarks, watermark layout, scaling, washout effect, remove watermark
find-and-replace.md	Find/FindAll/FindNext, Replace (string/regex), ReplaceSingleLine, and FindItem* APIs
footnotes-and-endnotes.md	Add footnotes and endnotes, set positions (bottom of page/end of section), numbering formats, separators, modify content, remove notes
track-changes.md	Enable/disable track changes, accept/reject changes, filter by reviewer, revision information
comments.md	Add/modify/remove comments, insert on specific text, access parent comments, retrieve commented items
content-controls.md	Block and inline content controls, types (rich text, plain text, checkbox, date, dropdown, picture), properties, protection, form filling, XML mapping
header-footer.md	Add/remove headers and footers, page numbers with fields (date, time), odd/even pages, first page different, borders, images, link to previous
hyperlinks.md	Web hyperlink, email hyperlink, file hyperlink, bookmark hyperlink, image hyperlink, modify hyperlink
ole-object.md	Add embedded OLE objects, extract OLE objects to file, remove OLE objects, object types
smartarts.md	Create SmartArt layouts, add/modify nodes, change appearance, assistant nodes, remove SmartArt

所有模板和代码片段均位于

references/

文件夹中：

文件	内容
template.csx	基础CSX脚本结构（仅适用于模式2）
document-structure.md	创建/加载文档、添加节、页面设置、保存到文件或流、支持的格式
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	密码加密、打开加密文档、移除加密、编辑保护、可编辑区域
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

Rules

规则

Output files go in
```
./output/
```
directory
Temp
```
.csx
```
scripts must be created inside
```
{skill-root}/syncfusion-dotnet-word/scripts/
```
— never in the workspace root or customer
```
scripts/
```
folder
Use license key from
```
SyncfusionLicense.txt
```
at workspace root or env var
```
SYNCFUSION_LICENSE_KEY
```
Never use Python libraries (e.g., python-docx)
Never leave temp
```
.csx
```
files after execution

输出文件保存到
```
./output/
```
目录
临时
```
.csx
```
脚本必须在
```
{skill-root}/syncfusion-dotnet-word/scripts/
```
目录下创建——绝对不能在工作区根目录或客户的
```
scripts/
```
文件夹中创建
使用工作区根目录
```
SyncfusionLicense.txt
```
中的许可证密钥，或环境变量
```
SYNCFUSION_LICENSE_KEY
```
禁止使用Python库（如python-docx）
执行完成后必须删除临时
```
.csx
```
文件