【office2pdf】office2pdf - 产品需求文档 (PRD.md)

1. 概述

office2pdf是一个库和命令行工具，使用纯 Rust 将 DOCX、XLSX 和 PPTX 文件转换为 PDF。
它无需外部运行时（LibreOffice、Chromium、Docker）即可独立运行，使用 Typst 引擎作为布局/PDF 后端。

核心价值

• 零依赖：无需外部二进制文件/服务，作为单个可执行文件运行
• 高质量输出：以 95% 的保真度再现原始文档的布局/样式
• 库优先：可嵌入到其他 Rust 项目中，CLI 只是一个轻量封装

2. 目标用户

3. 功能需求

3.1 输入格式

DOCX (Word)

PPTX (PowerPoint)

XLSX (Excel)

3.2 输出

4. 非功能需求

5. 架构

5.1 转换流水线

输入文件 (.docx/.pptx/.xlsx) │ ▼ [1. 解析器] ─── docx-rs / ppt-rs / umya-spreadsheet │ ▼ [2. IR (中间表示)] ← 格式无关的文档模型 │ ▼ [3. Typst 代码生成] ─── IR → Typst 标记生成 │ ▼ [4. Typst 编译] ─── typst-as-lib / typst crate │ ▼ [5. PDF 导出] ─── typst-pdf │ ▼ output.pdf

5.2 IR (中间表示) 设计

所有输入格式在输出到 Typst 之前都转换为统一的 IR：

pubstructDocument{pubmetadata:Metadata,pubpages:Vec<Page>,pubstyles:StyleSheet,}pubenumPage{Flow(FlowPage),// DOCX：流式文本页面Fixed(FixedPage),// PPTX：固定坐标页面Table(TablePage),// XLSX：基于表格的页面}pubstructFlowPage{pubsize:PageSize,pubmargins:Margins,pubheader:Option<HeaderFooter>,pubfooter:Option<HeaderFooter>,pubcontent:Vec<Block>,}pubenumBlock{Paragraph(Paragraph),Table(Table),Image(Image),PageBreak,List(List),}

5.3 项目结构

office2pdf/ ├── Cargo.toml # 工作区根目录 ├── crates/ │ ├── office2pdf/ # 库 crate │ │ ├── Cargo.toml │ │ └── src/ │ │ ├── lib.rs # 公共 API │ │ ├── error.rs # thiserror 错误类型 │ │ ├── ir/ # 中间表示 │ │ │ ├── mod.rs │ │ │ ├── document.rs # Document, Page, Block 等 │ │ │ ├── style.rs # 样式/格式模型 │ │ │ └── elements.rs # Paragraph, Table, Image 等 │ │ ├── parser/ # 输入格式解析器 │ │ │ ├── mod.rs # Parser trait │ │ │ ├── docx.rs # DOCX → IR │ │ │ ├── pptx.rs # PPTX → IR │ │ │ └── xlsx.rs # XLSX → IR │ │ ├── render/ # IR → PDF 渲染 │ │ │ ├── mod.rs │ │ │ ├── typst_gen.rs # IR → Typst 标记生成 │ │ │ └── pdf.rs # Typst 编译 + PDF 输出 │ │ └── config.rs # 转换选项 │ └── office2pdf-cli/ # CLI crate │ ├── Cargo.toml │ └── src/ │ └── main.rs # 基于 clap 的 CLI ├── tests/ # 集成测试 │ ├── fixtures/ # 测试文档文件 │ └── integration_tests.rs └── fonts/ # 内置默认字体

5.4 关键依赖

6. 公共 API（库）

useoffice2pdf::{Document,ConvertOptions,Format};// 简单用法letpdf_bytes=office2pdf::convert("input.docx")?;std::fs::write("output.pdf",pdf_bytes)?;// 带选项letoptions=ConvertOptions::builder().paper_size(PaperSize::A4).font_paths(vec!["./fonts"]).pdf_standard(PdfStandard::PdfA2b).build();letpdf_bytes=office2pdf::convert_with_options("input.xlsx",&options)?;// 从字节转换letdocx_bytes=std::fs::read("input.docx")?;letpdf_bytes=office2pdf::convert_bytes(&docx_bytes,Format::Docx,&options)?;// 仅转换特定工作表/幻灯片letoptions=ConvertOptions::builder().sheet_names(vec!["Sheet1"])// XLSX：仅特定工作表.slide_range(1..=5)// PPTX：仅幻灯片 1-5.build();

7. CLI 接口

# 基本转换office2pdf input.docx# → input.pdfoffice2pdf input.pptx-ooutput.pdf# 指定输出路径# 选项office2pdf input.xlsx--sheets"Sheet1,Sheet2"# 仅特定工作表office2pdf input.pptx--slides1-5# 仅特定幻灯片office2pdf input.docx--papera4--landscape# 纸张设置office2pdf input.docx --font-path ./fonts# 字体路径# 批量转换office2pdf *.docx--outdir./pdfs/# 批量转换多个文件# 信息office2pdf--versionoffice2pdf--help

8. 实施阶段

阶段 1：MVP（基础文本 + 图片）

• 项目结构搭建（工作区、CI）
• IR 定义
• DOCX P0 功能 → IR → Typst → PDF
• PPTX P0 功能 → IR → Typst → PDF
• XLSX P0 功能 → IR → Typst → PDF
• 基础 CLI 功能

阶段 2：格式 + 样式

• 所有 P1 功能实现
• 字体嵌入/回退
• 增强错误处理

阶段 3：高级功能

• P2 功能实现
• PDF/A 支持
• 性能优化
• 批量转换

阶段 4：完善

• P3 功能（在可行范围内）
• 边缘情况处理
• 文档、示例、crates.io 发布

9. 验证方法

10. 风险