Skip to content
Office Oxide

Node.js-бібліотека для Office — швидкий старт

npm-пакет office-oxide — це нативна прив’язка до Node.js: через koffi динамічно завантажує liboffice_oxide і пропонує компактний, ідіоматичний JS API. Швидший і менший за WebAssembly-збірку, але постачається з prebuild-бінарниками для конкретних платформ, а не одним переносним файлом.

Якщо потрібен один артефакт, що працює в браузері, бандлерах чи Node без нативних бібліотек — беріть office-oxide-wasm.

Встановлення

npm install office-oxide

На postinstall пакет шукає сумісний prebuild у node_modules/office-oxide/prebuilds/<platform>-<arch>/. Якщо його нема, перед першим використанням налаштуйте одне з наступного:

  1. OFFICE_OXIDE_LIB — абсолютний шлях до бібліотеки (наприклад, /opt/office_oxide/liboffice_oxide.so).
  2. Каталог prebuild — покладіть бібліотеку в prebuilds/<platform>-<arch>/ (наприклад, linux-x64, darwin-arm64, win32-x64) у пакеті.
  3. Системний шлях бібліотек — встановіть так, щоб її знаходив LD_LIBRARY_PATH / DYLD_LIBRARY_PATH / PATH.

Працює на Node 18+.

Прочитати документ

import { Document } from 'office-oxide';

const doc = Document.open('report.docx');
try {
  console.log(doc.plainText());
} finally {
  doc.close();
}

Або з TC39 explicit resource management (Node 22+):

import { Document } from 'office-oxide';

using doc = Document.open('report.docx');
console.log(doc.plainText());
// doc.close() викликається автоматично на виході з області

Одноразовий помічник:

import { extractText } from 'office-oxide';
console.log(extractText('report.docx'));

Базовий API

import { Document } from 'office-oxide';

const doc = Document.open('file.xlsx');
try {
  console.log(doc.format);         // "xlsx"
  console.log(doc.plainText());
  console.log(doc.toMarkdown());
  console.log(doc.toHtml());
  const ir = doc.toIr();           // вже розпарсений об'єкт

  doc.saveAs('file.docx');         // цільовий формат — за розширенням
} finally {
  doc.close();
}

З сирих байтів (Uint8Array або Buffer):

import { readFileSync } from 'node:fs';
import { Document } from 'office-oxide';

const data = readFileSync('report.pptx');
using doc = Document.fromBytes(data, 'pptx');
console.log(doc.toMarkdown());

format повинен бути 'docx' | 'xlsx' | 'pptx' | 'doc' | 'xls' | 'ppt'.

Скорочення модульного рівня:

import { extractText, toMarkdown, toHtml, detectFormat, version } from 'office-oxide';

extractText('file.docx');      // string
toMarkdown('file.pptx');       // string
toHtml('file.xlsx');           // string
detectFormat('mystery.bin');   // "docx" | ... | null
version();                     // "0.1.0"

Редагування

Editable-handle зберігає всі незмінені OPC-частини при збереженні. Лише DOCX, XLSX, PPTX.

import { EditableDocument } from 'office-oxide';

using ed = EditableDocument.open('template.docx');
const n = ed.replaceText('{{name}}', 'Alice');
console.log(`${n} замін`);
ed.save('out.docx');

Запис клітинок XLSX

import { EditableDocument } from 'office-oxide';

using wb = EditableDocument.open('budget.xlsx');

wb.setCell(0, 'A1', 'Total');   // рядок
wb.setCell(0, 'B1', 42.5);      // число
wb.setCell(0, 'C1', true);      // булеве
wb.setCell(0, 'D1', null);      // порожнє

wb.save('budget.xlsx');

sheetIndex нумерується з нуля; cellRef — стандартна нотація.

Формат-незалежний IR

using doc = Document.open('report.docx');
const ir = doc.toIr();

for (const section of ir.sections) {
  console.log(section.title);
  for (const el of section.elements) {
    // el.kind: "Heading" | "Paragraph" | "Table" | "List" | ...
  }
}

Робота з байтами

import { Document } from 'office-oxide';

const res = await fetch('https://example.com/report.docx');
const data = new Uint8Array(await res.arrayBuffer());
using doc = Document.fromBytes(data, 'docx');
console.log(doc.toMarkdown());

Legacy-формати

using doc = Document.open('old.xls');
doc.saveAs('modern.xlsx');

CommonJS

const { Document } = require('office-oxide');
const doc = Document.open('file.docx');
try { console.log(doc.plainText()); } finally { doc.close(); }

Помилки

Збої кидають OfficeOxideError із числовим code та полем operation:

import { Document, OfficeOxideError } from 'office-oxide';

try {
  using doc = Document.open('missing.docx');
} catch (e) {
  if (e instanceof OfficeOxideError) {
    console.error(`code=${e.code} op=${e.operation}`);
  } else {
    throw e;
  }
}
Код Значення
0 OK
1 хибний аргумент
2 IO-помилка
3 помилка парсингу
4 збій видобування
5 внутрішня помилка
6 формат не підтримується

Діагностика

Симптом Що робити
office-oxide: failed to load native library Встановіть OFFICE_OXIDE_LIB як абсолютний шлях або покладіть відповідний prebuild у пакет.
koffi: ABI mismatch Prebuild не пасує платформі/архітектурі Node — перевстановіть або візьміть свіжий.
TypeError: data must be a Uint8Array or Buffer Document.fromBytes приймає лише бінарні типи. Використовуйте Buffer.from(base64, 'base64').
Document is closed Метод викликано після close() або після виходу з using. Відкрийте нову handle.
Legacy .doc відкривається, але показує кашу Зашифровані документи Word 97 не дешифруються — розшифруйте через LibreOffice.

Дивіться також