Office 浏览器编辑器接入

浏览器包提供五种惰性加载的编辑器。React、Vue 3、Web Components 和 Core API 使用相同的受控内容模型。

选择入口

浏览器包要求 Node.js 20 或更新版本。React 适配器支持 React 18.2 至 19.x，Vue 适配器支持 Vue 3.4 至 3.x。

bun add @aster-ai-lab/office react react-dom

挂载受控 React 编辑器

导入一次共享样式。为编辑器宿主设置明确高度，并保留 onChange 返回的完整内容。

import { useState } from 'react';
import type { DocumentContent } from '@aster-ai-lab/office/core';
import { DocumentEditor } from '@aster-ai-lab/office/react';
import '@aster-ai-lab/office/styles.css';

const initialContent: DocumentContent = {
  type: 'document',
  html: '<h1>Project brief</h1><p>Start editing here.</p>',
  pageSize: 'a4',
  pageColor: '#ffffff',
};

export function ProjectBrief() {
  const [content, setContent] = useState(initialContent);
  return (
    <main style={{ height: '100dvh', minHeight: 0 }}>
      <DocumentEditor content={content} onChange={setContent} theme="system" />
    </main>
  );
}

编辑器负责一次编辑事务。宿主决定内容的存储位置、保存时机和版本历史。

React 入口还导出 MarkdownEditor、SpreadsheetEditor、PresentationEditor 和 PdfViewer。preloadOfficeEditor 可以在用户意图出现时提前加载指定表面。

不挂载编辑器的文件流程

Core API 可以单独导入和导出文件：

import {
  createArtifact,
  createArtifactBlob,
  importOfficeFile,
} from '@aster-ai-lab/office/core';

const shell = createArtifact('blank-document');
const artifact = await importOfficeFile(file, {
  artifactId: shell.id,
  onProgress: ({ stage, progress }) => {
    console.info(stage, Math.round(progress * 100));
  },
});
const output = await createArtifactBlob(artifact);

导入的 DOCX artifact 保留源包引用。安全且未修改的包部件会按有界规则保留。不支持或不安全的结构会返回诊断或明确失败。

PDF 与运行时资产

PDF 使用显式 PDFium runtime。宿主必须把 pdfium.wasm 发布到 /vendor/embedpdf/pdfium.wasm，或通过 wasmUrl 提供绝对地址。

省略 PdfViewer 的 onSave 会保持只读模式。浏览器编辑器的 WASM、Worker 和字体资产也应由宿主明确发布，不能依赖隐式远程服务。

协作边界

Office 使用 Yjs/Yrs 内容、Awareness、远程位置和类型化修改。浏览器与原生副本可以交换标准 Yjs update 和 state vector。

宿主提供 Y.Doc、房间、认证、授权、传输、离线缓冲和持久化。Presence 只表示在线状态，不能作为授权依据。

协作修改使用稳定身份和预期状态。并发状态发生变化时，类型化修改会失败闭合，而不是覆盖整个文档。

验收清单

1. 核对编辑器宿主具有明确高度。
2. 导入目标文件并检查兼容诊断。
3. 修改内容并保留完整受控值。
4. 保存后重新读取导出文件。
5. 验证键盘、焦点和中文输入法。
6. 验证窄屏布局和运行时资产路径。
7. 使用协作副本时验证冲突与断线恢复。

实现依据

• 浏览器编辑器与 Core API
• React 公开入口
• Vue 公开入口
• Web Components 公开入口