Skip to content
Office Oxide

WASM-Office-Bibliothek — Schnellstart

Das Paket office-oxide-wasm ist office_oxide nach WebAssembly kompiliert. Keine nativen Abhängigkeiten, eine einzige Binärdatei mit dem Rust-Kern und drei Subpath-Entrypoints — damit läuft es überall, wo JavaScript läuft: Browser, Node.js und Bundler wie Vite, Webpack und Rollup.

Für Node.js ohne den WASM-Overhead lieber das native office-oxide.

Installation

npm install office-oxide-wasm

Kein Postinstall-Schritt. Läuft auf Node 18+, modernen Browsern mit WebAssembly-Support und allem mit ES-Module-/CommonJS-Loader.

Subpath-Exports

Importpfad Ziel Format
office-oxide-wasm (Standard) Bundler-freundliches ESM (Vite, Webpack, Rollup) ESM
office-oxide-wasm/node Node.js CommonJS
office-oxide-wasm/web Browser via <script type="module"> oder import ESM, braucht init()

Wähl die Variante, die zu deiner Laufzeit passt.

Ein Dokument lesen

Bundler (ESM)

import { WasmDocument } from 'office-oxide-wasm';

const res = await fetch('/report.docx');
const data = new Uint8Array(await res.arrayBuffer());
const doc = new WasmDocument(data, 'docx');
try {
  console.log(doc.plainText());
} finally {
  doc.free();
}

Node.js (CJS)

const { readFileSync } = require('node:fs');
const { WasmDocument } = require('office-oxide-wasm/node');

const data = readFileSync('report.docx');
const doc = new WasmDocument(data, 'docx');
try {
  console.log(doc.plainText());
} finally {
  doc.free();
}

Browser (ohne Bundler)

<script type="module">
  import init, { WasmDocument } from 'https://cdn.jsdelivr.net/npm/office-oxide-wasm/web/office_oxide.js';
  await init();

  const res = await fetch('/report.docx');
  const data = new Uint8Array(await res.arrayBuffer());
  const doc = new WasmDocument(data, 'docx');
  try {
    document.body.textContent = doc.plainText();
  } finally {
    doc.free();
  }
</script>

Nur im Browser: vor dem Anlegen eines WasmDocument musst du await init() aufrufen. Die Node- und Bundler-Entrypoints kümmern sich intern um die Initialisierung.

Kern-API

WasmDocument ist das einzige Handle — der WASM-Build hat keine Trennung in Document / EditableDocument (Editing-Funktionen leben in den nativen Bindings).

import { WasmDocument } from 'office-oxide-wasm';

const doc = new WasmDocument(bytes, 'xlsx');
try {
  console.log(doc.formatName());   // "xlsx"
  console.log(doc.plainText());
  console.log(doc.toMarkdown());
  console.log(doc.toHtml());
  const ir = doc.toIr();           // bereits geparstes Objekt
} finally {
  doc.free();   // Pflicht — WASM-Speicher wird nicht vom GC verwaltet
}

Alle Methoden sind in camelCase: plainText, toMarkdown, toHtml, toIr, formatName. bytes muss ein Uint8Array sein. format muss eines aus 'docx' | 'xlsx' | 'pptx' | 'doc' | 'xls' | 'ppt' sein.

Die Legacy-Binärformate (doc, xls, ppt) werden auch in WASM geparst.

Bearbeiten (nicht in WASM)

EditableDocument — Textersetzung und Zellenschreibzugriff — wird im WASM-Build nicht bereitgestellt. Für Editing nimm:

Für Read-only-Workflows — Text / Markdown / HTML / IR — ist WASM voll funktionsfähig.

Formatunabhängige IR

const doc = new WasmDocument(bytes, 'docx');
const ir = doc.toIr();
doc.free();

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

Das IR-Schema entspricht eins-zu-eins der DocumentIR aus Rust, sodass Server- und Client-Pipelines denselben Processor teilen können.

Bytes rein, Bytes raus

Der WASM-Build akzeptiert ausschließlich Bytes — kein File-I/O.

// Aus einem <input type="file">
const file = inputEl.files[0];
const data = new Uint8Array(await file.arrayBuffer());
const doc = new WasmDocument(data, file.name.split('.').pop().toLowerCase());

// Aus fetch
const res = await fetch(url);
const data = new Uint8Array(await res.arrayBuffer());

// In Node
const data = new Uint8Array(require('node:fs').readFileSync('file.docx'));

Bundler

// Vite — meist Zero-Config
import { WasmDocument } from 'office-oxide-wasm';

// Webpack 5 — in module.rules ergänzen:
//   { test: /\.wasm$/, type: 'asset/resource' }

TypeScript

Typdefinitionen (office_oxide.d.ts) liegen neben dem JS-Glue jedes Subpath-Exports. Beim Import aus der Wurzel werden automatisch die Bundler-Typen gezogen; import type { WasmDocument } from 'office-oxide-wasm/node' funktioniert ebenfalls.

Speicherverwaltung

const doc = new WasmDocument(bytes, 'docx');
try {
  // ... Arbeit
} finally {
  doc.free();
}

Wer free() vergisst, lässt den WASM-Speicher leaken, bis die Instanz weggeht.

Fehler

Fehler tauchen als gewöhnliche Error-Instanzen mit aussagekräftiger Nachricht auf. Da der WASM-Build JsValue::from_str benutzt, gibt’s keine numerischen Fehlercodes — schau in den Message-String.

Fehlersuche

Symptom Lösung
ReferenceError: WebAssembly is not defined Ziel unterstützt kein WASM. Stattdessen das native office-oxide nehmen.
Browser: TypeError: ... before init() await init() bei office-oxide-wasm/web vergessen.
Bundler beschwert sich über .wasm WASM-Asset-Regel ergänzen oder Bundler-Target auf esnext stellen.
unsupported format: pdf Nur sechs Formate werden akzeptiert: docx, xlsx, pptx, doc, xls, ppt.
Speicher wächst in heißer Schleife unbegrenzt Du rufst zwischen den Iterationen nicht doc.free() auf.

Siehe auch