Skip to content
Office Oxide

API 参考

按概念而非按绑定整理的 Office Oxide 接口参考。每种绑定都镜像同样的形态 — 名字遵循各语言惯例（Rust/Python 用 snake_case，JS 用 camelCase，C#/.NET 用 PascalCase，Go 用 Pascal）。

Document — 只读句柄

按路径打开；格式由扩展名和魔术字节检测。

概念 Rust Python JavaScript Go C# C
打开文件 Document::open(path) Document.open(path) Document.open(path) officeoxide.Open(path) Document.Open(path) office_document_open
从字节打开 Document::from_reader(r, fmt) Document.from_bytes(b, fmt) Document.fromBytes(b, fmt) OpenFromBytes(b, fmt) Document.FromBytes(b, fmt) office_document_open_from_bytes
格式 .format() .format .format .Format() .Format office_document_format
纯文本 .plain_text() .plain_text() .plainText() .PlainText() .PlainText() office_document_plain_text
Markdown .to_markdown() .to_markdown() .toMarkdown() .ToMarkdown() .ToMarkdown() office_document_to_markdown
HTML .to_html() .to_html() .toHtml() .ToHTML() .ToHtml() office_document_to_html
IR .to_ir()（带类型） .to_ir()（dict） .toIr()（对象） .ToIRJSON() .ToIrJson() office_document_to_ir_json
保存/转换 .save_as(path) .save_as(path) .saveAs(path) .SaveAs(path) .SaveAs(path) office_document_save_as
关闭 drop 退出 with 块 close() / using .Close() Dispose / using office_document_free

DocumentFormat

Docx | Xlsx | Pptx | Doc | Xls | Ppt

FFI 边界（from_bytes 等）使用的是上述名称的 小写 形式: "docx"、"xlsx"、"pptx"、"doc"、"xls"、"ppt"。

EditableDocument — 读—改—写

打开 API 与 Document 相同。保存时保留所有未修改的 OPC 部件。

概念 Rust Python JavaScript Go C# C
打开 EditableDocument::open EditableDocument.open EditableDocument.open OpenEditable EditableDocument.Open office_editable_open
替换文本 .replace_text(n, r) .replace_text(n, r) .replaceText(n, r) .ReplaceText(n, r) .ReplaceText(n, r) office_editable_replace_text
设置 XLSX 单元格 .set_cell(idx, ref, v) .set_cell(idx, ref, v) .setCell(idx, ref, v) .SetCell(idx, ref, v) .SetCell(idx, ref, v) office_editable_set_cell
保存 .save(path) .save(path) .save(path) .Save(path) .Save(path) office_editable_save
保存为字节 .write_to(w) .save_to_bytes() .saveToBytes() .SaveToBytes() .SaveToBytes() office_editable_save_to_bytes

可编辑句柄 仅支持 DOCX、XLSX、PPTX。在 XLSX 上调用 replace_text 返回 0；改用 set_cell。在 DOCX/PPTX 上调用 set_cell 会出错。

模块级辅助

辅助 返回 可用于
extract_text(path) UTF-8 字符串 所有绑定
to_markdown(path) GFM Markdown 字符串 所有绑定
to_html(path) HTML 片段字符串 所有绑定
detect_format(path) 格式名或 null 所有绑定
version() "0.1.0" 所有绑定
create_from_ir(ir, fmt, path) unit / void Rust、Python

DocumentIR — Schema

DocumentIR {
    sections: [Section]
}

Section {
    title:    Option<string>
    elements: [Element]
}

Element = Heading   { level, text }
        | Paragraph { runs: [Run] }
        | List      { ordered, items: [string] }
        | Table     { rows: [[string]] }
        | Image     { filename, data: bytes }

Run {
    text, bold, italic, underline, hyperlink: Option<string>
}

在 Python 中，Element 通过 kind 字段（"Heading"、"Paragraph"、"List"、"Table"、"Image"）分派。

错误

错误暴露带类型的 code 与失败操作名。

Code 含义
0 OK
1 参数无效（nil 指针、未知 format 字符串）
2 I/O 错误
3 解析错误（文档损坏）
4 提取失败（解析成功但渲染失败）
5 内部错误（bug — 请提 issue）
6 不支持（扩展名或特性）
绑定 类型
Rust office_oxide::OfficeError（enum）
Python OfficeOxideError（异常，.code、.operation）
JavaScript OfficeOxideError（Error 子类，.code、.operation）
Go *officeoxide.Error（.Code、.Op）
C# OfficeOxideException（.Code、.Operation）
C int *error_code 出参

Feature 标志（Rust crate）

[dependencies]
office_oxide = { version = "0.1.0", features = ["mmap", "parallel"] }
Feature 作用
mmap Document::open_mmap 实现零拷贝 OOXML 打开
parallel 基于 rayon 的并行解析辅助
serde （默认）IR 类型上的 Serialize / Deserialize
python PyO3 绑定（用于 office-oxide PyPI wheel 构建）

按格式子模块（Rust）

office_oxide::docx   — DocxDocument、DocxBuilder、edit::DocxEditor
office_oxide::xlsx   — XlsxDocument、XlsxBuilder、edit::{XlsxEditor, CellValue}
office_oxide::pptx   — PptxDocument、PptxBuilder、edit::PptxEditor
office_oxide::doc    — DocDocument
office_oxide::xls    — XlsDocument
office_oxide::ppt    — PptDocument
office_oxide::ir     — DocumentIR、Section、Element、Run
office_oxide::edit   — EditableDocument
office_oxide::create — create_from_ir

需要超出统一 Document 暴露范围的格式特性时使用 — 工作表迭代、幻灯片操作、自定义 XML。

相关链接