syncfusion-dotnet-pdf

PDF 文档处理

概述

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

主要功能

• 创建和编辑： 从头创建 PDF 文件；添加文本、图像（各种格式）、表格、形状、段落、标题、样式、列表、超链接、书签、页眉/页脚和水印；管理模板；编辑元数据
• 表单和交互元素： 创建、填写和扁平化表单（AcroForms 和 XFA）、书签、批注、附件、按钮和内容控件
• 高级功能： 批注、图层（添加、移除、扁平化）、PDF 作品集、JavaScript 执行、3D 模型嵌入和交互、富媒体内容（音频/视频）、光学字符识别（Tesseract 引擎）、文本涂黑、图像涂黑、数字签名和验证
• 转换： SVG 转 PDF、XPS 转 PDF、PDF 转符合 PDF/A 标准的文件
• 提取： 从 PDF 文档中提取文本和图像
• 安全： 密码加密/解密、高级加密标准、带可编辑范围的文档保护、宏管理、数字签名功能
• 条形码和标准： 一维条形码、二维条形码、ZUGFeRD 发票支持、PDF/A-1B、PDF/A-1A、PDF/A-2B、PDF/A-2A、PDF/A-2U、PDF/A-3B、PDF/A-3A、PDF/A-3U、PDF/A-4、PDF/A-4E、PDF/A-4F、PDF/X1-A 符合性、符合 Section 508 标准的无障碍 PDF/标记 PDF（PDF/UA）
• 其他操作： 合并和拆分 PDF 文件，打开并修改现有 PDF 文件，压缩 PDF 文件，检测损坏的 PDF 文件。

快速入门示例

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

用户：“给我展示创建包含标题、章节标题和段落的 PDF 的 C# 代码。” **结果：**显示 C# 代码片段（不创建文件）

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

用户：“生成一份会议议程文档，并保存到 output/agenda.pdf。” **结果：**在指定路径创建实际文件

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

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

触发关键词：“code”、“snippet”、“how to write”、“Program.cs”、“show me”、“sample”、“example code”、“generate code for”。

工作流：

1. 使用 references/*.md 文件中的代码片段编写 C# 代码，并将占位符替换为实际内容
2. 将代码直接添加到用户的项目文件中（例如 Program.cs）
3. 不要创建或运行任何 .csx 脚本

注意：对于跨平台项目，此代码应使用 Syncfusion.Drawing 命名空间，而不是 System.Drawing。这样可确保与 Windows、macOS 和 Linux 兼容。

注意：如果建议使用 Syncfusion.Pdf.Net.Core 包，则必须使用 Syncfusion.Drawing 命名空间执行图形操作，而不是 System.Drawing，以确保跨平台兼容性。Syncfusion.Pdf.Net.Core 包专为与 Syncfusion.Drawing 命名空间配合使用而设计，该命名空间为不同平台上的绘图操作提供一致的 API。使用 System.Drawing 可能导致兼容性问题，尤其是在非 Windows 平台上，因为它依赖于 GDI+，而 GDI+ 在 Windows 以外的平台上并未得到完全支持。因此，在跨平台环境中处理 PDF 图形时，务必使用 Syncfusion.Drawing。

注意：如果需要使用 RectangleF、PointF、SizeF 或 Color 类型，为确保跨平台兼容性，请使用 Syncfusion.Drawing 命名空间中的类型，而不是 System.Drawing 中的类型。这样可确保代码无需依赖 GDI+，即可在 Windows、macOS 和 Linux 上正常运行。

---

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

触发关键词：“创建 PDF 文档”、“制作文档”、“生成文档”、“打开”、“编辑”、“修改”、“更改” .pdf 文件、“不修改我的项目”、“运行 csx 脚本”，或用户提供文件路径时（例如 output/report.pdf）。

工作流：

1. 使用 references/template.csx 作为基础模板；对于 OCR 专用操作，则使用 references/template-ocr.csx，创建 {skill-root}/syncfusion-dotnet-pdf/scripts/temp-{timestamp}.csx。例如，skill-root = .github/skills。
2. 从 references/*.md 代码片段中添加所需操作，并将占位符替换为实际内容
3. 运行：dotnet script {skill-root}/syncfusion-dotnet-pdf/scripts/temp-{timestamp}.csx
4. 执行后删除临时脚本
5. 报告 SUCCESS/ERROR，并显示输出文件路径

注意：此 csx 脚本中请使用 Syncfusion.Drawing 命名空间，而不是 System.Drawing。

---

代码参考

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

文件	内容
template.csx	核心 CSX 脚本模板（用于 Mode 2）
document-structure.md	文档生命周期：创建、保存、关闭；章节和页面设置
open-pdf.md	从文件流、字节数组、加密文件、损坏的文档和云存储（Azure Blob、AWS S3、Google Drive、Google Cloud Storage、Dropbox）打开现有 PDF
save-pdf.md	将新建和已加载的 PDF 保存到文件路径、MemoryStream、字节数组和云存储（Azure Blob、AWS S3、Google Drive、Google Cloud Storage、Dropbox）
pages.md	添加、插入、移除、旋转、重新排列、导入和配置页面；页数、空白页检测、页面标签、章节编号、PageAdded 事件和页面级操作
pdf-graphics.md	使用 PdfGraphics：文本、图像和形状
shapes.md	绘制形状：线条、矩形、椭圆、多边形、弧线、贝塞尔曲线、路径
brushes.md	使用纯色、线性渐变、径向渐变、平铺和阴影线画刷填充形状；PdfBrushes 静态颜色；组合画笔和画刷
images.md	插入、绘制、替换、移除、裁剪、变换和分页栅格图像（JPEG、PNG、BMP、GIF、TIFF、ICO）；图像蒙版；多页 TIFF 转 PDF；图像放置的单位转换
text.md	使用标准、TrueType、OpenType 和 CJK 字体绘制文本；对齐、RTL、复杂脚本、HTML 样式文本、多列、分页文本流、有序／无序列表、字符串测量、文本裁剪检测和单位转换
conversions.md	转换指南，适用于复杂 HTML 转 PDF 等需要使用转换器 API 而非直接绘图 API 的场景
merge-pdf.md	将多个 PDF 合并为一个文件
split-pdf.md	将单个 PDF 拆分为多个文件
compress-pdf.md	减小并优化 PDF 文件大小
extract-text.md	获取 PDF 文本内容并在其中查找文本
extract-image.md	使用 PdfPageBase 和 PdfDocumentExtractor 从 PDF 页面和整个文档中提取图像及图像元数据（边界、索引）
ocr.md	使用 Tesseract 对扫描版 PDF 和图像执行 OCR；支持区域 OCR、旋转页面、布局结果、页面分割模式、引擎模式、图像增强、白名单／黑名单、Unicode 和图像转 PDF
tables.md	使用 PdfGrid 在 PDF 中构建表格
headers-and-footers.md	添加带自动字段和动态内容的页眉和页脚
bookmarks.md	创建和管理 PDF 书签（大纲导航）
attachments.md	在 PDF 中添加、管理和提取文件附件
security.md	使用密码和权限加密并保护 PDF
actions.md	在 PDF 中添加交互操作、触发器和 JavaScript
hyperlinks.md	使用 PdfTextWebLink、PdfDocumentLinkAnnotation 和 PdfFileLinkAnnotation 添加网页 URL 链接、文档内部导航和外部文件链接
watermarks.md	添加透明且可旋转的文本和图像水印
portfolio.md	创建嵌入多个文件的 PDF 作品集
layers.md	在 PDF 中创建和管理图层（可选内容）
metadata.md	使用文档和图像 XMP 元数据；属性架构和自定义字段
redact.md	涂黑示例和用法（基于文本／图像／模式／正则表达式的涂黑）
digital-sign.md	数字签名示例：基本签名 → 高级签名（TSA、LTV、外部签名）
import-export-annotation.md	导入和导出批注（FDF、XFDF、JSON）——文件、流和往返工作流
pdf-forms.md	创建、填写、修改、扁平化和管理 AcroForm 字段（文本框、组合框、单选按钮、列表框、复选框、签名、按钮）；涵盖字段属性、可见性、只读、自动命名、复杂脚本和外观
import-export-form.md	导入和导出 AcroForm 字段数据（FDF、XFDF、JSON）——填写、导出、往返和扁平化
annotations.md	添加、修改、移除和扁平化 PDF 批注（弹出式、自由文本、线条、图章、墨迹、标记、URI、涂黑、云状边框等）
barcode.md	添加一维（Code 39、EAN-13、EAN-8、Codabar、Code 93、Code 128、PDF417）和二维（QR、DataMatrix）条码；将条码导出为图像
colorspace.md	使用 DeviceGray、DeviceRGB、DeviceCMYK 和基于 ICC 的颜色空间绘图和处理图像
conformance.md	生成符合 PDF/A（1B、2B、3B）和 PDF/X 标准的文件；将现有 PDF 转换为符合性标准
named-destinations.md	添加、修改、移除和链接命名目标，用于文档内导航和基于 URL 的导航
pdf-templates.md	创建和使用 PdfTemplate、PdfPageTemplateElement（页眉／页脚）和 PdfPageTemplate；创建叠加层并将页面捕获为模板
accessible-pdf.md	创建带标签的 PDF、PDF/UA-2、Well-Tagged PDF，并提取无障碍标签元素
tagged-pdf.md	创建带标签（无障碍／结构化）的 PDF，并使用逻辑结构树支持屏幕阅读器和重排
zugferd-invoice.md	创建嵌入 XML 的 ZUGFeRD 电子发票 PDF（PDF/A-3b）；支持 ZUGFeRD 1.0、2.0、Factur-X 和 XRechnung 符合性级别；从现有 ZUGFeRD PDF 中提取 XML
xps-to-pdf.md	使用 XPSToPdfConverter 将 XPS（XML Paper Specification）文档转换为 PDF
svg-to-pdf.md	使用 SvgConverter 和 PdfGraphics.DrawPdfTemplate 将 SVG 文件转换为 PDF 文档

---

规则

• 输出文件放入 ./output/ 目录
• 临时 .csx 脚本必须在 {skill-root}/syncfusion-dotnet-pdf/scripts/ 中创建，绝不能放在工作区根目录或客户的 scripts/ 文件夹中
• 使用工作区根目录下 SyncfusionLicense.txt 中的许可证密钥
• 绝不使用 Python 库（例如 python-pdf）
• 执行后绝不保留临时 .csx 文件
• 始终使用最新版本的 NuGet 包

前置条件

• .NET SDK 8+ 和 dotnet-script：dotnet tool install -g dotnet-script
• Syncfusion 许可证：SyncfusionLicense.txt 或环境变量 SYNCFUSION_LICENSE_KEY
• 免费许可证：https://www.syncfusion.com/products/communitylicense

文档

• Syncfusion PDF 文档
• API 参考