Skip to content
Office Oxide

Biblioteca Office WASM — Início Rápido

O pacote office-oxide-wasm é o office_oxide compilado para WebAssembly. Zero dependências nativas, um único binário do core em Rust e três entradas via subpath para que rode em qualquer lugar onde JavaScript rode — navegadores, Node.js e bundlers como Vite, Webpack e Rollup.

Para Node.js sem o overhead de WASM, use o pacote nativo office-oxide.

Instalação

npm install office-oxide-wasm

Sem passo de postinstall. Funciona em Node 18+, navegadores modernos com suporte a WebAssembly e qualquer ambiente com loader ES module / CommonJS.

Exports por subpath

Caminho de import Alvo Formato
office-oxide-wasm (padrão) ESM amigável a bundlers (Vite, Webpack, Rollup) ESM
office-oxide-wasm/node Node.js CommonJS
office-oxide-wasm/web Navegadores via <script type="module"> ou import ESM, requer init()

Escolha a variante que combina com seu runtime.

Ler um documento

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();
}

<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>

Apenas no navegador: é obrigatório await init() antes de construir um WasmDocument. As entradas para Node e bundlers cuidam da inicialização internamente.

API principal

WasmDocument é o único handle — o build WASM não tem a divisão Document / EditableDocument (a edição vive nos bindings nativos).

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();           // objeto já parseado
} finally {
  doc.free();   // obrigatório — memória WASM não é gerida por GC
}

Todos os métodos são em camelCase: plainText, toMarkdown, toHtml, toIr, formatName. bytes precisa ser Uint8Array. format precisa ser um de 'docx' | 'xlsx' | 'pptx' | 'doc' | 'xls' | 'ppt'.

Os formatos binários legados (doc, xls, ppt) também são parseados em WASM.

Edição (não está no WASM)

EditableDocument — substituição de texto e escrita de células — não é exposto pelo build WASM. Para editar, use:

Para fluxos somente leitura — texto / Markdown / HTML / IR — o WASM tem todos os recursos.

IR independente de formato

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

O esquema IR bate exatamente com a DocumentIR em Rust, então pipelines do lado do servidor e do cliente podem compartilhar o mesmo processador.

Bytes entram, bytes saem

O build WASM aceita só bytes — não há superfície de I/O de arquivo.

// De um <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());

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

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

Bundlers

// Vite — geralmente sem configuração
import { WasmDocument } from 'office-oxide-wasm';

// Webpack 5 — adicione em module.rules:
//   { test: /\.wasm$/, type: 'asset/resource' }

TypeScript

Definições de tipo (office_oxide.d.ts) acompanham o glue JS para cada subpath. Importar pela raiz pega automaticamente os tipos para bundler; import type { WasmDocument } from 'office-oxide-wasm/node' também funciona.

Gerenciamento de memória

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

Esquecer o free() faz a memória WASM vazar até a instância ser destruída.

Erros

As falhas surgem como instâncias normais de Error, com mensagem descritiva. Como o build WASM usa JsValue::from_str, os códigos de erro não são expostos numericamente — verifique o texto da mensagem.

Solução de problemas

Sintoma O que fazer
ReferenceError: WebAssembly is not defined O ambiente alvo não suporta WASM. Use o pacote nativo office-oxide.
Navegador: TypeError: ... before init() Esqueceu o await init() ao usar office-oxide-wasm/web.
Bundler reclama de .wasm Adicione uma regra de asset para WASM ou troque o target para esnext.
unsupported format: pdf Apenas seis formatos são aceitos: docx, xlsx, pptx, doc, xls, ppt.
Memória cresce sem parar em loop quente Não está chamando doc.free() entre as iterações.

Veja também