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，支持 per-editor wildcard host，用于逐个文档销毁 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

生产构建默认使用精简 runtime profile：保留 Word、Spreadsheet、Presentation 三类编辑器、共享运行时、x2t、libs 和 en_US 字典；移除 PDF/Visio SDK、未选中字典、内置 help 大图和包内字体等低频资产。构建同时会在 .onlyoffice-runtime-asset-packs/{core,word,cell,slide} 生成 canonical 路径的拆分包。生产可部署 core 加实际支持的文档类型包；这些 pack 都可以直接拷贝到同一个 editor-host 根路径，不需要改写 OnlyOffice 内部路径。

使用

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

const editor = await createOfficeEditor(document.querySelector('#editor') as HTMLElement, {
  hostUrl: ({ sessionId }) => `https://${sessionId}.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；那是演示文稿文档主题资产，不是界面皮肤。

多文档同时打开时，宿主为每个文档创建一个容器和一个组件实例即可。推荐使用 wildcard DNS/TLS 给每个实例分配独立 host origin，例如 https://<session>.office-host.example.com/office-host.html；这样逐个关闭文档时，对应子框架任务可以独立退出。开发环境下，.localhost host 会自动派生为 host-<session>.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 启动。生成器默认使用精简的 zh-core 字体集，面向简体中文和经典英文 Office 文档；只有确实需要广泛语言覆盖时再传 --font-set full。详见 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