Skip to content
Office Oxide

Node.js Office ライブラリ — クイックスタート

office-oxide npm パッケージは ネイティブ な Node.js バインディングです — koffi 経由で liboffice_oxide を動的にロードし、シンプルで idiomatic な JavaScript API を提供します。WebAssembly ビルドより高速・小サイズですが、単一バイナリではなくプラットフォーム別の prebuild を出荷します。

ブラウザ・バンドラー・ネイティブライブラリ不要の Node 環境を 1 つの成果物でカバーしたい場合は、office-oxide-wasm を使ってください。

インストール

npm install office-oxide

postinstall で node_modules/office-oxide/prebuilds/<platform>-<arch>/ の prebuild を確認します。見つからない場合は、初回利用前に次のいずれかを設定してください。

  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"

編集

編集可能ハンドルは保存時に変更されていない 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 は 0 始まり、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());

レガシーフォーマット

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;
  }
}
Code 意味
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 プロセスと不一致。再インストールするか新しい prebuild を取得。
TypeError: data must be a Uint8Array or Buffer Document.fromBytes はバイナリ型のみ。Buffer.from(base64, 'base64') を使用。
Document is closed close() 後または using スコープ脱出後にメソッドが呼ばれた。新しいハンドルを開く。
レガシー .doc を開けるが文字化け 暗号化された Word 97 ドキュメントは復号されません — LibreOffice で先に復号してください。

関連項目