rdocx使用

`rdocx` 的定位比较特殊：它不只是一个简单的 DOCX 读写库，而是一个**完全用 Rust 编写的、集成了文档模型与布局引擎的原生文档栈**。核心优势在于不依赖外部 Office 套件或转换服务，就能完成从编辑到 PDF 渲染的完整流程。

### 🚀 快速上手

**1. 添加依赖**
在 `Cargo.toml` 中引入 `rdocx`。如果需要确定性的字体渲染（不依赖系统字体），可以关闭默认特性：
```toml
[dependencies]
rdocx = "0.14.0"
# 或者，仅使用内置字体：
# rdocx = { version = "0.14.0", default-features = false }
```
它要求 Rust 1.93 或更高版本。

**2. 核心 API 速览**

它的 API 设计受到了 `python-docx` 的启发，上手比较直观。

* **创建与保存**：
```rust
use rdocx::Document;

let mut doc = Document::new();
doc.add_paragraph("Hello, World!");
doc.save("output.docx").unwrap();
```

* **编辑现有文档**：
```rust
let mut doc = Document::open("template.docx").unwrap();
doc.add_paragraph("Approved");
doc.save("approved.docx").unwrap();
```

* **格式化文本（Run 级别）**：
你可以对段落内的“Run”进行精细化控制：
```rust
let mut para = doc.add_paragraph("");
para.add_run("Bold text").bold(true);
para.add_run(" | ");
para.add_run("Red text").color("FF0000");
para.add_run(" | ");
para.add_run("Italic").italic(true);
```

* **表格与列表**：
`rdocx` 支持创建表格、设置列宽以及自定义列表编号。

* **模板替换**：
内置了基于占位符的替换功能，适合批量生成合同、报告等：
```rust
use std::collections::HashMap;
let mut replacements = HashMap::new();
replacements.insert("{{name}}", "Jane Doe");
doc.replace_all(&replacements);
```

### 📄 多格式输出

这是 `rdocx` 区别于许多同类库的地方。它自带布局引擎，可以直接从文档对象导出其他格式，无需安装 Microsoft Word 或 LibreOffice。

* **PDF**：`doc.save_pdf("report.pdf")`。支持字体子集化和书签。
* **HTML / Markdown**：`let html = doc.to_html();` 或 `let md = doc.to_markdown();`。
* **图片**：可以将页面渲染为 PNG 图像。

### 🛠️ 命令行工具 (CLI)

如果你不想写代码，可以直接使用 `rdocx-cli` 完成常见任务：
```bash
# 安装
cargo install rdocx-cli

# 查看文档信息
rdocx inspect report.docx

# 转换为 PDF
rdocx convert report.docx --to pdf -o report.pdf

# 替换模板中的占位符
rdocx replace report.docx --placeholder "Draft" --value "Final" -o final.docx
```

### 💡 使用建议与注意点

1. **关于 Python 绑定的“歧义”**：搜索时你会看到 PyPI 上也有一个 `rdocx-py` 包。需要注意的是，这个 Python 包底层调用的正是这个 Rust 引擎，但它的 Python API 并不承诺与 `python-docx` 完全兼容，属于独立的封装。
2. **并非“克隆版 Word”**：`rdocx` 的渲染目标是**商业文档**（如合同、报告）。对于包含 3D 效果、复杂 WordArt 或专有艺术字渲染的文档，它可能不会做到像素级复刻，而是会给出诊断信息或保留原始 XML。
3. **版本迭代较快**：从搜索结果看，它的版本号在较短时间内有更新（如 0.14.0），API 可能还在演进中，建议以最新的官方文档（docs.rs 或 GitHub）为准。