Rust PDF处理库pdf_derive的使用指南

概述

pdf_derive是一个Rust库，通过派生宏(derive macro)简化PDF文件的生成和解析过程。它允许开发者使用Rust结构体来定义PDF文档结构，然后自动生成序列化和反序列化的代码。

主要特性

• 通过派生宏自动实现PDF对象的序列化/反序列化
• 简化PDF文档结构的定义
• 类型安全的PDF操作
• 减少手动编写PDF格式代码的工作量

安装

在Cargo.toml中添加依赖：

[dependencies]
pdf_derive = "0.1"  # 请检查最新版本
pdf = "0.8"  # 基础pdf库

基本使用方法

1. 定义PDF对象结构体

use pdf_derive::{PdfWrite, PdfObj};

#[derive(PdfObj, PdfWrite)]
struct MyPdfObject {
    title: String,
    author: String,
    page_count: u32,
    is_encrypted: bool,
}

2. 生成PDF文档

use pdf::file::File;
use pdf::object::*;
use pdf::build::*;

fn create_pdf() -> Result<(), pdf::error::PdfError> {
    let mut builder = Builder::new();
    
    let my_obj = MyPdfObject {
        title: "My Document".to_string(),
        author: "John Doe".to_string(),
        page_count: 10,
        is_encrypted: false,
    };
    
    let obj_ref = builder.add(my_obj)?;
    
    // 创建文档结构
    let mut catalog = CatalogBuilder::new();
    let mut pages = PagesBuilder::new();
    
    // 添加页面等操作...
    
    builder.build("output.pdf")?;
    Ok(())
}

3. 解析PDF文档

fn read_pdf(path: &str) -> Result<(), pdf::error::PdfError> {
    let file = File::open(path)?;
    
    // 假设我们知道对象在索引1的位置
    if let Some(my_obj) = file.get(1)?.as_dict() {
        let parsed: MyPdfObject = my_obj.try_into()?;
        println!("Title: {}", parsed.title);
        println!("Author: {}", parsed.author);
    }
    
    Ok(())
}

高级用法

自定义字段映射

#[derive(PdfObj, PdfWrite)]
struct CustomObject {
    #[pdf(key = "/CustomName")]
    normal_name: String,
    
    #[pdf(skip)]  // 跳过序列化
    internal_data: Vec<u8>,
}

嵌套对象

#[derive(PdfObj, PdfWrite)]
struct PageInfo {
    width: f32,
    height: f32,
}

#[derive(PdfObj, PdfWrite)]
struct Document {
    info: PageInfo,
    pages: Vec<String>,  // 页面内容
}

完整示例代码

// src/pdf_models.rs
use pdf_derive::{PdfObj, PdfWrite};

// 定义PDF文档信息结构体
#[derive(PdfObj, PdfWrite, Debug)]
pub struct DocumentInfo {
    #[pdf(key = "/Title")]
    pub title: String,
    
    #[pdf(key = "/Author")]
    pub author: String,
    
    #[pdf(key = "/CreationDate")]
    pub creation_date: String,
    
    #[pdf(skip)]
    pub internal_id: u32,  // 不序列化到PDF中
}

// 定义页面结构体
#[derive(PdfObj, PdfWrite)]
pub struct PdfPage {
    pub width: f32,
    pub height: f32,
    pub contents: String,
}

// src/main.rs
use pdf::{
    build::*,
    error::PdfError,
    file::File,
    object::*,
};
use pdf_derive::{PdfObj, PdfWrite};
use crate::pdf_models::{DocumentInfo, PdfPage};

fn main() -> Result<(), PdfError> {
    // 创建PDF文档
    create_sample_pdf()?;
    
    // 读取PDF文档
    read_sample_pdf("sample.pdf")?;
    
    Ok(())
}

fn create_sample_pdf() -> Result<(), PdfError> {
    let mut builder = Builder::new();
    
    // 创建文档信息
    let info = DocumentInfo {
        title: "示例文档".to_string(),
        author: "Rust开发者".to_string(),
        creation_date: "D:20230101000000".to_string(),
        internal_id: 12345,
    };
    
    // 创建页面内容
    let page1 = PdfPage {
        width: 595.0,  // A4宽度
        height: 842.0, // A4高度
        contents: "BT /F1 24 Tf 100 700 Td (Hello, PDF世界!) Tj ET".to_string(),
    };
    
    // 添加到PDF构建器
    let _info_ref = builder.add(info)?;
    let _page_ref = builder.add(page1)?;
    
    // 构建并保存PDF
    builder.build("sample.pdf")?;
    
    println!("PDF创建成功!");
    Ok(())
}

fn read_sample_pdf(path: &str) -> Result<(), PdfError> {
    let file = File::open(path)?;
    
    // 遍历所有对象
    for i in 1..file.len() {
        if let Ok(obj) = file.get(i) {
            if let Some(dict) = obj.as_dict() {
                // 尝试解析为DocumentInfo
                if let Ok(info) = dict.try_into::<DocumentInfo>() {
                    println!("找到文档信息:");
                    println!("标题: {}", info.title);
                    println!("作者: {}", info.author);
                    println!("创建日期: {}", info.creation_date);
                }
                
                // 尝试解析为PdfPage
                if let Ok(page) = dict.try_into::<PdfPage>() {
                    println!("\n找到页面:");
                    println!("尺寸: {}x{}", page.width, page.height);
                    println!("内容: {}", page.contents);
                }
            }
        }
    }
    
    Ok(())
}

注意事项

1. 确保结构体字段类型实现了必要的trait（如PdfWrite）
2. 复杂PDF操作可能需要直接使用底层的pdf库
3. 派生宏目前可能不支持所有PDF特性，检查文档了解限制

示例项目结构

my_pdf_project/
├── Cargo.toml
└── src/
    ├── main.rs
    └── pdf_models.rs  # 放置PDF结构体定义

pdf_derive通过简化PDF处理代码，让开发者能更专注于业务逻辑而不是PDF格式细节。对于更复杂的需求，可以结合使用底层的pdf库功能。