PdfTocExtractor 2.0.0

PdfTocExtractor

PdfTocExtractor 是一个纯 C# 实现的轻量级PDF目录提取库，用于从PDF文件中提取目录（TOC）并导出为多种格式。支持Markdown、JSON、XML、纯文本等格式，完全摆脱命令行依赖，无需额外的PDF处理工具，适合在 .NET 项目中内嵌、分发或集成自动化流程中使用。

通过PdfTocExtractor，您可以轻松从PDF文档中提取书签和目录结构，生成清晰的导航文档，完美适用于文档处理、内容分析和自动化工作流。

🚀 跨平台、零依赖、极速提取，一切尽在 PdfTocExtractor！

✨ 功能特点

• 📖 从PDF文件提取书签/目录信息
• 📄 支持多种输出格式：Markdown、JSON、XML、纯文本
• 🎯 可配置的导出选项（层级深度、页码格式等）
• 🔧 可扩展的导出器架构，支持自定义格式
• ⚡ 异步操作支持，高性能处理
• 🌐 跨平台支持：Windows、Linux、macOS

📦 安装

通过 NuGet 安装

dotnet add package PdfTocExtractor

或在 Package Manager Console 中：

Install-Package PdfTocExtractor

🚀 快速开始

基本用法

using PdfTocExtractor;
using PdfTocExtractor.Exporters;

// 创建提取器实例
var extractor = new PdfTocExtractor();

// 提取目录
var tocItems = await extractor.ExtractTocAsync("document.pdf");

// 导出为Markdown
await extractor.ExportToFileAsync(tocItems, "output.md", "markdown");

// 导出为JSON
await extractor.ExportToFileAsync(tocItems, "output.json", "json");

高级用法

// 使用自定义导出选项
var exportOptions = new ExportOptions
{
    MaxDepth = 3,
    IncludePageNumbers = true,
    CustomTitle = "文档目录",
    IndentString = "  ",
    PageNumberFormat = "第 {0} 页"
};

await extractor.ExportToFileAsync(tocItems, "output.md", "markdown", exportOptions);

// 直接从PDF提取并导出
await extractor.ExtractAndExportAsync("document.pdf", "output.xml");

📄 支持的输出格式

• Markdown (md, markdown) - 适合文档和网页显示，支持层级结构
• JSON (json) - 适合程序处理和API集成，包含完整元数据
• XML (xml) - 结构化数据交换，标准化格式
• Text (txt, text) - 纯文本格式，简洁易读

⚙️ 导出选项

• MaxDepth - 最大层级深度（0表示无限制）
• IncludePageNumbers - 是否包含页码信息
• IncludeLinks - 是否包含链接（如果格式支持）
• CustomTitle - 自定义文档标题
• IndentString - 缩进字符串
• PageNumberFormat - 页码格式化字符串
• Encoding - 文件编码格式

🔧 扩展性

您可以通过实现 IExporter 接口来创建自定义导出器：

public class CustomExporter : IExporter
{
    public string FormatName => "Custom";
    public string FileExtension => "custom";

    public string Export(IEnumerable<TocItem> tocItems, ExportOptions? options = null)
    {
        // 实现自定义导出逻辑
        return "custom format content";
    }

    public async Task ExportToFileAsync(IEnumerable<TocItem> tocItems, string filePath, ExportOptions? options = null)
    {
        var content = Export(tocItems, options);
        await File.WriteAllTextAsync(filePath, content);
    }
}

// 注册自定义导出器
extractor.RegisterExporter("custom", new CustomExporter());

📝 示例输出

Markdown 输出示例

# 文档目录

- [第1章 概述](#第1章-概述) (第 1 页)
  - [1.1 背景](#11-背景) (第 2 页)
  - [1.2 目标](#12-目标) (第 3 页)
- [第2章 技术架构](#第2章-技术架构) (第 5 页)
  - [2.1 系统设计](#21-系统设计) (第 6 页)
    - [2.1.1 核心组件](#211-核心组件) (第 7 页)
    - [2.1.2 数据流](#212-数据流) (第 8 页)

JSON 输出示例

{
  "title": "文档目录",
  "generatedAt": "2024-01-15T10:30:00",
  "items": [
    {
      "title": "第1章 概述",
      "level": 1,
      "page": "第 1 页",
      "pageNumber": 1,
      "children": [
        {
          "title": "1.1 背景",
          "level": 2,
          "page": "第 2 页",
          "pageNumber": 2
        }
      ]
    }
  ]
}

🛠️ 技术实现

PdfTocExtractor 使用以下技术：

• .NET 8.0 - 现代化的.NET平台
• iText 9.2.0 - 强大的PDF处理库
• iText7.bouncy-castle-adapter 9.2.0 - 加密PDF支持（必需）
• Newtonsoft.Json 13.0.3 - JSON序列化

🔧 故障排除

常见问题

"PdfEncryption exception" 错误

如果遇到此错误，通常是因为PDF文件使用了加密或权限保护。请确保已安装 itext7.bouncy-castle-adapter 包：

dotnet add package itext7.bouncy-castle-adapter

"此PDF文件没有目录（书签）信息" 错误

这表示PDF文件确实没有嵌入的书签/目录信息。可以：

• 检查PDF是否在其他阅读器中显示目录面板
• 考虑使用其他工具为PDF添加书签

📄 许可证

MIT License

🤝 相关项目

• PdfTocExtractor.Cli - 命令行工具版本
• 项目主页 - 完整的项目文档和示例

📞 支持

如果您遇到问题或有建议，请：

• 📋 提交Issue
• 💬 参与讨论
• ⭐ 如果这个项目对您有帮助，请给个Star！