Skip to content
Office Oxide

编辑 Office 文档

EditableDocument 是 Document 的读—改—写版本。它会完整保留所有未修改的 OPC 部件——图片、图表、样式、主题、关系——所以你的修改不会让周围内容重新排版，也不会让下游消费者失效。

编辑支持 DOCX、XLSX 和 PPTX。旧版 DOC、XLS、PPT 是只读的——需要编辑请先用 save_as 转换。

你能做什么

操作 DOCX XLSX PPTX 方法
在正文/占位符中替换文本 ✓ — ✓ replace_text
设置单元格值（字符串/数字/布尔/空） — ✓ — set_cell
保存到磁盘 ✓ ✓ ✓ save
保存为字节 ✓ ✓ ✓ save_to_bytes

在 XLSX 上调用 replace_text 会返回 0（XLSX 里没有 <w:t> 或 <a:t> 元素）；电子表格请改用 set_cell。

打开、编辑、保存

Rust

use office_oxide::edit::EditableDocument;

let mut ed = EditableDocument::open("template.docx")?;
ed.replace_text("{{name}}", "Alice");
ed.replace_text("{{date}}", "2026-04-19");
ed.save("filled.docx")?;

Python

from office_oxide import EditableDocument

with EditableDocument.open("template.docx") as ed:
    ed.replace_text("{{name}}", "Alice")
    ed.replace_text("{{date}}", "2026-04-19")
    ed.save("filled.docx")

JavaScript

import { EditableDocument } from 'office-oxide';

using ed = EditableDocument.open('template.docx');
ed.replaceText('{{name}}', 'Alice');
ed.replaceText('{{date}}', '2026-04-19');
ed.save('filled.docx');

Go

ed, err := officeoxide.OpenEditable("template.docx")
defer ed.Close()
ed.ReplaceText("{{name}}", "Alice")
ed.ReplaceText("{{date}}", "2026-04-19")
ed.Save("filled.docx")

C#

using var ed = EditableDocument.Open("template.docx");
ed.ReplaceText("{{name}}", "Alice");
ed.ReplaceText("{{date}}", "2026-04-19");
ed.Save("filled.docx");

C

int err = 0;
OfficeEditableHandle *ed = office_editable_open("template.docx", &err);
office_editable_replace_text(ed, "{{name}}", "Alice", &err);
office_editable_replace_text(ed, "{{date}}", "2026-04-19", &err);
office_editable_save(ed, "filled.docx", &err);
office_editable_free(ed);

保存为字节（用于上传/流式传输）

Rust

let mut ed = EditableDocument::open("template.docx")?;
ed.replace_text("{{name}}", "Alice");

let mut buf = std::io::Cursor::new(Vec::new());
ed.write_to(&mut buf)?;
let bytes: Vec<u8> = buf.into_inner();

Python

with EditableDocument.open("template.docx") as ed:
    ed.replace_text("{{name}}", "Alice")
    bytes_out = ed.save_to_bytes()
    # upload bytes_out to S3 / send over HTTP / etc.

JavaScript

using ed = EditableDocument.open('template.docx');
ed.replaceText('{{name}}', 'Alice');
const bytes = ed.saveToBytes();   // Uint8Array

C

int err = 0;
OfficeEditableHandle *ed = office_editable_open("template.docx", &err);
office_editable_replace_text(ed, "{{name}}", "Alice", &err);

size_t out_len = 0;
uint8_t *buf = office_editable_save_to_bytes(ed, &out_len, &err);
/* stream buf[0..out_len], then: */
office_oxide_free_bytes(buf, out_len);
office_editable_free(ed);

"保留 OPC 部件"到底意味着什么

OOXML 文件是 ZIP 包，里面包含几十个 XML 部件以及二进制部件（图片、字体、嵌入对象）。粗糙的编辑器在保存时会重新序列化所有部件，这可能导致：

  • 关系被重新排序，链接失效
  • 编辑器无法识别的扩展部件丢失（自定义 XML、AlternateContent 回退）
  • XML 被重新格式化，破坏下游差异比对和数字签名

EditableDocument 只重写你修改过的部件，其余部件逐字节复制。最终结果是输入与输出之间尽可能小的差异——对版本控制、签名校验和在其他工具间往返都更友好。

何时改用格式专用 API

EditableDocument 覆盖了 80% 的场景（模板填充、批量写入、单元格更新）。如果需要更复杂的编辑——添加段落、插入表格、调整样式、从零构建幻灯片——请使用格式专用 API：

use office_oxide::docx::edit::DocxEditor;

let mut docx = DocxEditor::open("report.docx")?;
docx.append_paragraph("New section", Some("Heading2"));
docx.save("report.docx")?;

格式专用编辑器在每个绑定的参考文档中均有说明（Rust: docx::edit、xlsx::edit、pptx::edit）。

相关链接