Browser Office Editor

基于 OnlyOffice 9.3 和 onlyoffice-x2t-wasm 的纯浏览器端 Office 预览/编辑组件。

组件在宿主传入的 DOM 容器内打开 DOCX、XLSX、PPTX、CSV。转换、编辑、保存、导出都在独立 origin 的 sandbox editor host iframe 中完成，不需要 OnlyOffice DocumentServer、不需要后端会话、不上传文档、不需要用户账号。

仓库提供什么

• JS/TS API：createOfficeEditor(container, options)。
• 一页多文档：宿主为每个文档创建一个容器和一个组件实例。
• 独立 origin 的 office-host.html，使用可复用的 12 个 origin 池，兼顾逐文档 iframe 销毁、内存隔离和缓存复用。
• public/wasm/x2t 本地转换链路。
• public/web-apps、public/sdkjs OnlyOffice 浏览器运行时。
• / 极简 demo/test 宿主页面。
• 集成文档：docs/integration.zh.md 和 docs/integration.md。

安装

npm install @agentbridges-ai/onlyoffice-browser

import { createOfficeEditor } from '@agentbridges-ai/onlyoffice-browser';

npm 主包只包含 JS/TS 组件 API。office-host.html 和 OnlyOffice runtime 资产需要从本仓库 public/、Release 附件或你自己的 CDN 单独部署到独立 origin。

运行时资源需要能从 editor host origin 访问：

• /web-apps/ 和 /sdkjs/
• /wasm/x2t/
• /dictionaries/、/libs/
• 生成后的字体资产：/onlyoffice-browser-font-assets.json、/sdkjs/common/AllFonts.js、/sdkjs/common/Images/fonts_thumbnail*.png、/fonts/、/server/FileConverter/bin/font_selection.bin
• /document_editor_service_worker.js、/plugins.json、/themes.json、/reset.html

生产构建会选择 Word、Spreadsheet、Presentation 三类编辑器、共享运行时、x2t、libs 和支持的字典，并排除未使用的 SDK、帮助图片和重复压缩资源。release:build 会把这些运行时与生成后的完整字体集封装为一个不可变的 office-resources.oobpack；安装器以经过校验的 24 MiB 分段传输，但始终向用户呈现一个资源包和一条进度流程。.onlyoffice-runtime-asset-packs/{core,word,cell,slide} 中的 canonical 路径包仅保留为构建期兼容产物，不再作为独立的用户下载项。

使用

import { createOfficeEditor } from '@agentbridges-ai/onlyoffice-browser';

const editor = await createOfficeEditor(document.querySelector('#editor') as HTMLElement, {
  hostUrl: ({ hostSlot }) => `https://${hostSlot}.office-host.example.com/office-host.html`,
  file,
  fileName: file.name,
  mode: 'edit',
  lang: 'zh',
  saveBehavior: 'callback',
  onSave(savedFile) {
    console.log('把这个文件写入你的最终存储', savedFile.name, savedFile.size);
  },
  onDirtyChange(dirty) {
    console.log('dirty', dirty);
  },
});

// 程序化保存仍可用于自动化。面向用户的 UI 应使用编辑器工具栏里的
// OnlyOffice 原生保存按钮。
const saved = await editor.save('DOCX');
editor.setReadonly(true);
editor.setReadonly(false);
editor.destroy();

mode 可选值：

• edit：完整编辑器。
• readonly：编辑运行时，但禁用编辑权；可通过 setReadonly(false) 恢复编辑。
• preview：OnlyOffice 上游 embedded viewer，不显示编辑 ribbon；需要销毁并重建实例才能切回编辑。

拼写检查默认关闭。只有宿主应用确实需要默认打开拼写检查时，才传入 spellcheck: true。 Word 和演示文稿在编辑器运行态中默认使用适合宽度缩放，让页面/幻灯片优先占满可用预览区域。 autosave 和 forcesave 默认关闭；面向用户的保存应走编辑器工具栏里的 OnlyOffice 原生保存按钮，editor.save() 仅作为程序化集成和测试 API 保留。 OnlyOffice 界面主题只支持现代三项：interfaceTheme: 'system' | 'light' | 'dark'。组件会映射到 theme-system、theme-white、theme-night，并把历史 OnlyOffice 主题值（如 theme-classic-light、theme-light、theme-gray、theme-dark、theme-contrast-dark）迁移到最接近的现代主题。不要删除 sdkjs/slide/themes；那是演示文稿文档主题资产，不是界面皮肤。

多文档同时打开时，宿主为每个文档创建一个容器和一个组件实例即可。组件会为每个活动编辑器租用 12 个稳定星座槽位（aries 到 pisces）之一，并在 destroy() 时释放。部署时配置这 12 个 DNS/TLS 名称（或匹配的 wildcard），再根据 hostSlot 解析 hostUrl。稳定 origin 既保留逐文档 renderer 隔离，也让 editor Service Worker 复用已校验的 Office Pack 分段；同时打开第 13 个编辑器会抛出 OfficeHostPoolExhaustedError。开发环境下，.localhost URL 会自动派生为 host-<hostSlot>.office.localhost。

开发

pnpm install
pnpm run dev
pnpm run lint
pnpm run test
pnpm run build:lib
pnpm run pack:dry
pnpm run build

pnpm run test:real-load 用于真实文件同页压力测试。Chrome CDP 参数和文件参数见集成文档。

构建

pnpm run build

将生成的 dist/ 和运行时资源部署到 editor host origin。父应用创建实例时必须通过 hostUrl 传入这个 host 的 office-host.html 地址。

如果需要在 demo 构建之外单独生成优化后的 runtime 资产：

npm run assets:build

生成的 .onlyoffice-runtime-assets 可直接部署；.onlyoffice-runtime-asset-packs 中包含拆分后的 core、word、cell、slide 包，适合 CDN 或 Release artifact 工作流。需要更窄或更宽的资产范围时，可直接调用 scripts/build-onlyoffice-runtime-assets.mjs 并传入 --types word,slide 或 --dictionaries en_US,en_GB。本轮暂不拆 preview/edit 模式；每个文档类型 pack 内仍同时保留 embed 和 main 外壳。

GitHub Actions

• CI：lint、TypeScript、单元测试、npm package build/dry-pack、demo 生产构建、Playwright E2E。
• Deploy demo：手动部署 GitHub Pages demo。OnlyOffice runtime 资产较大，所以不在每次 main push 自动上传。
• Publish npm：基于 tag 或手动触发的 npm 发布 workflow，已按 npm Trusted Publishing 准备。

启用 Publish npm 时，在 npm package 设置里配置 Trusted Publisher：

• Package：@agentbridges-ai/onlyoffice-browser
• Repository：agentbridges-ai/onlyoffice-browser
• Workflow：publish.yml
• Environment：留空，除非之后 workflow 显式增加 environment

配置完成后 workflow 会通过 GitHub OIDC 发布，不再需要长期 npm token。

浏览器内边界

• 不使用 OnlyOffice DocumentServer。
• 正常打开、编辑、保存不会上传用户文档。
• 不依赖 /doc/.../c、websocket、long-poll、CommandService、ConvertService。
• Blob URL 只在当前标签页生命周期内有效。
• 协同编辑、服务端历史、包内部直接写文件不在本轮范围内；宿主应用通过 onSave 负责最终持久化。

字体

本项目不内置 runtime 字体文件。打开文档前必须先生成并挂载字体资产：npm run fonts:generate -- --input /path/to/fonts --output .onlyoffice-font-assets 或 npx onlyoffice-browser-generate-font-assets --input /path/to/fonts --output .onlyoffice-font-assets，再用 npm run fonts:verify -- --input .onlyoffice-font-assets 或 npx onlyoffice-browser-verify-font-assets --input .onlyoffice-font-assets 验证，本地开发用 npm run dev:fonts 启动。生成器默认导出 All-in-One Office 包使用的完整 full 字体集；只有明确需要精简部署时才传入 --font-set zh-core。详见 docs/fonts.zh.md。

参考

• cryptpad/onlyoffice-editor
• agentbridges-ai/onlyoffice-x2t-wasm
• cryptpad/onlyoffice-x2t-wasm（仅作源码分析参考，不向该上游提交本包变更）
• ONLYOFFICE/Docker-DocumentServer
• ONLYOFFICE web-apps
• ONLYOFFICE sdkjs
• npm Trusted Publishing

许可证

AGPL-3.0