C# 使用 Spire.PDF 创建标签 PDF (Tagged PDF) 的完整指南

什么是标签 PDF 及其核心作用

标签 PDF 不仅仅是视觉上的页面呈现，它在底层包含了一套描述文档逻辑结构的元数据。这些数据形成了一个层次化的“标记树”（Tag Tree），将文档内容排列成有序的结构[1]。这种不可见的标记层具有以下重要意义：

• 增强可访问性：屏幕阅读器依赖这些标签来理解内容含义并按正确顺序朗读。没有标签，软件可能只是机械地提取字符，导致阅读顺序混乱。
• 优化排版适应：标签有助于将内容流式传输到智能手机或平板电脑等小屏幕设备，使其能够根据视口大小重新组合内容块。
• 结构化元素：最常见的标签包括正文、标题、链接、列表以及图像的替代文本（Alt Text）。

C# 环境准备

为了在 .NET 环境中创建标签 PDF，我们需要引入专业的 PDF API。本文以 Spire.PDF for .NET 为例进行操作。

1. 安装 NuGet 包：在项目中引用 Spire.PDF 命名空间下的相关类。
2. 关键命名空间：主要涉及 Spire.Pdf（文档基础操作）、Spire.Pdf.Graphics（绘图元素）以及 Spire.Pdf.Interchange.TaggedPdf（标签与交互互操作）。

第 1 步：初始化文档并启用标签功能

首先创建文档对象，指定页面尺寸，并开启结构顺序模式。这一步是生成标准标签 PDF 的前提。

using Spire.Pdf;
using Spire.Pdf.Graphics;
using Spire.Pdf.Interchange.TaggedPdf;
using System.Drawing;

namespace CreateTaggedPDF
{
    class Program
    {
        static void Main(string[] args)
        {
            // 1. 创建 PdfDocument 对象
            PdfDocument pdf = new PdfDocument();
            
            // 2. 添加 A4 空白页
            pdf.Pages.Add(PdfPageSize.A4);
            
            // 3. 设置 Tab Order 为 Structure，这是创建标签 PDF 的关键步骤
            pdf.Pages[0].SetTabOrder(TabOrder.Structure);
            
            // 4. 创建 PdfTaggedContent 对象用于管理标签结构
            PdfTaggedContent taggedContent = new PdfTaggedContent(pdf);
            taggedContent.SetLanguage("en-US"); // 设置文档语言
            taggedContent.SetTitle("test");     // 设置文档标题（元数据）

第 2 步：构建标记树并写入文本

文本内容是 PDF 的核心。我们需要创建结构元素（如 Document、Paragraph、Span），并将绘制操作包裹在标记内容（Marked Content）中。这样可以确保屏幕阅读器知道这段文字属于哪个段落。

            // 5. 创建字体、画刷和字符串格式
            PdfTrueTypeFont font = new PdfTrueTypeFont(new Font("Times New Roman", 10), true);
            PdfSolidBrush brush = new PdfSolidBrush(Color.Black);
            PdfStringFormat format = new PdfStringFormat(PdfTextAlignment.Left);

            // 6. 建立层级结构：Root -> Document -> Paragraph -> Span
            PdfStructureElement article = taggedContent.StructureTreeRoot.AppendChildElement(PdfStandardStructTypes.Document);
            PdfStructureElement paragraph1 = article.AppendChildElement(PdfStandardStructTypes.Paragraph);
            PdfStructureElement span1 = paragraph1.AppendChildElement(PdfStandardStructTypes.Span);
            
            // 开始标记内容
            span1.BeginMarkedContent(pdf.Pages[0]);
            
            // 7. 在指定坐标绘制文本
            pdf.Pages[0].Canvas.DrawString(
                "A PDF tag is the key to accessing the contents of PDF documents with supporting technologies such as screen readers. ", 
                font, brush, new Rectangle(40, 0, 480, 80), format);
            
            // 结束标记内容
            span1.EndMarkedContent(pdf.Pages[0]);

同理，可以重复上述步骤添加第二个段落。

            PdfStructureElement paragraph2 = article.AppendChildElement(PdfStandardStructTypes.Paragraph);
            paragraph2.BeginMarkedContent(pdf.Pages[0]);
            pdf.Pages[0].Canvas.DrawString(
                "A PDF tag arranges the PDF content in a hierarchical architecture or tag tree.", 
                font, brush, new Rectangle(40, 80, 480, 80), format);
            paragraph2.EndMarkedContent(pdf.Pages[0]);

第 3 步：为图像添加替代文本与结构标记

图像本身对屏幕阅读器而言是不可读的，必须为其提供“替代文本”（Alternate Text/Alt Text）作为描述。我们将图像对象包装在 `Figure` 类型的结构元素中，并设置其 `Alt` 属性。

            // 8. 处理图片：创建 Figure 类型结构元素
            PdfStructureElement figure1 = article.AppendChildElement(PdfStandardStructTypes.Figure);
            
            // 9. 设置替代文本，这对无障碍至关重要
            figure1.Alt = "replacement text1";
            
            figure1.BeginMarkedContent(pdf.Pages[0], null);
            
            // 加载并绘制图片
            PdfImage image = PdfImage.FromFile(@"logo.png");
            pdf.Pages[0].Canvas.DrawImage(image, new PointF(40, 200), new SizeF(100, 100));
            
            figure1.EndMarkedContent(pdf.Pages[0]);

对于图形形状或其他非自然图像，也可以采用相同的方式，为其赋予语义描述。

第 4 步：保存文档与验证

完成所有元素的标记后，保存文件即可生成标准的标签 PDF。建议使用 Adobe Acrobat Pro 等专业工具打开生成的 PDF，检查“结构”窗格是否正确显示了标记树。

            // 10. 保存生成的带标签 PDF 文件
            pdf.SaveToFile("CreateTaggedFile_result.pdf");
            
            // 可选：在调试环境下直接打开查看
            // System.Diagnostics.Process.Start("CreateTaggedFile_result.pdf");
        }
    }
}

运行结果示意

成功执行上述代码后，您将得到一个包含层级结构（Document → Paragraph → Figure）且带有语言属性和替代文本的 PDF 文件。以下是生成的文档结构示意图：

总结与注意事项

创建标签 PDF 的核心在于 PdfTaggedContent 的使用。通过在绘制任何可见内容之前调用 BeginMarkedContent，并在之后调用 EndMarkedContent，我们可以将视觉呈现与逻辑语义关联起来。这对于开发企业级文档系统或面向残障人士的应用程序尤为重要。

关键点回顾：

• 必须调用 SetTabOrder(TabOrder.Structure)。
• 每个需要被识别的内容块都必须包裹在相应的结构元素中。
• 图像务必设置 Alt 属性，否则可能被读作“图形”或忽略。

以上就是 C# 利用 Spire.PDF 创建标签 PDF 文件的详细内容，更多关于 C# 编程技巧与 PDF 自动化处理资料请关注本站其它相关文章！