Skip to content
Office Oxide

API-референс

Сводный референс поверхности Office Oxide, организованный по концептам, а не по привязкам. Каждая привязка повторяет одну и ту же форму — имена следуют конвенциям языка (snake_case в Rust/Python, camelCase в JS, PascalCase в C#/.NET, Pascal в Go).

Document — read-handle

Открыть из пути; формат определяется по расширению и magic-байтам.

Концепт 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() .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() (object) .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 и т. п.) — это lowercase-версии: "docx", "xlsx", "pptx", "doc", "xls", "ppt".

EditableDocument — read-modify-write

Та же открывающая 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

Editable-handle поддерживает только DOCX, XLSX, PPTX. Вызов replace_text на XLSX вернёт 0; используйте set_cell. Вызов set_cell на DOCX/PPTX вернёт ошибку.

Хелперы модульного уровня

Хелпер Возвращает Доступен в
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 — схема

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").

Ошибки

Ошибки выставляют типизированный код и имя сорвавшейся операции.

Код Значение
0 OK
1 Невалидный аргумент (nil-указатель, неизвестная строка формата)
2 I/O-ошибка
3 Ошибка парсинга (повреждённый документ)
4 Сбой извлечения (парсинг ОК, но рендер сорвался)
5 Внутренняя ошибка (баг — заведите 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 out-параметр

Feature-флаги (Rust-крейт)

[dependencies]
office_oxide = { version = "0.1.0", features = ["mmap", "parallel"] }
Feature Эффект
mmap Document::open_mmap для zero-copy открытия OOXML
parallel rayon-based хелперы параллельного парсинга
serde (по умолчанию) Serialize / Deserialize на типах IR
python PyO3-привязки (используются при сборке office-oxide-wheel для PyPI)

Подмодули по форматам (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

Используйте подмодули, когда нужен формат-специфичный доступ — итерация листов, манипуляции слайдами, custom XML — за пределами того, что выставляет унифицированный Document.

Смотрите также