acc-document-editing

基于 React 的文档编辑组件。组件本身不再携带 OnlyOffice 与 X2T 静态资源，运行时只通过 assetBaseUrl 读取外部静态资源。

特性

• 支持作为 npm 包发布与安装
• 运行时只依赖外部传入的 assetBaseUrl
• 不再把 OnlyOffice 与 wasm 资源打进 npm 包
• 支持通过 ref 调用保存能力

安装

npm install acc-document-editing react

当前包将 react 作为 peerDependencies，请确保宿主项目已安装 React 18 或更高版本。

资源要求

组件依赖 OnlyOffice 和 wasm 静态资源，但这些资源不再随 npm 包一起发布。接入方需要自己准备可访问的静态资源目录，并通过 assetBaseUrl 显式传入。

例如你的静态资源根目录为：

https://app.example.com/document-editing

对应的关键资源路径例如：

https://app.example.com/document-editing/web-apps/apps/api/documents/api.js
https://app.example.com/document-editing/wasm/x2t/x2t.js

请确保该地址与宿主页面同源，避免 OnlyOffice iframe 跨域。

基础用法

import React, { useRef } from "react";
import DocumentEditor, { DocumentEditorRef } from "acc-document-editing";

export default function App() {
  const editorRef = useRef<DocumentEditorRef>(null);

  return (
    <div style={{ width: "100%", height: "100vh" }}>
      <DocumentEditor
        ref={editorRef}
        file={{
          fileName: "example.docx",
          file: null,
        }}
        assetBaseUrl="/document-editing"
        onSave={(data) => {
          console.log("保存结果", data.fileName, data.bin);
        }}
        onContentChange={() => {
          console.log("文档内容发生变化");
        }}
      />
    </div>
  );
}

Props

file

当前文档信息。

{
  fileName: string;
  file: File | null;
}

• fileName: 文档名称，决定打开或新建的文件类型
• file: 传入 File 表示打开已有文件，传入 null 表示按扩展名创建空白文档

onSave

保存回调：

(data: { bin: Uint8Array; fileName: string }) => void

onContentChange

文档内容变化时触发。

assetBaseUrl

静态资源基础路径，必传。

string

例如：

<DocumentEditor
  file={{ fileName: "example.docx", file: null }}
  assetBaseUrl="https://app.example.com/document-editing"
/>

Ref 方法

组件通过 forwardRef 暴露以下方法：

interface DocumentEditorRef {
  save: () => Promise<{ bin: Uint8Array; fileName: string } | null>;
  isDirty: () => boolean;
}

示例：

const result = await editorRef.current?.save();
const changed = editorRef.current?.isDirty();

构建

npm run build

构建内容包括：

• dist/index.js
• dist/index.d.ts

发布

发布前建议执行：

npm run build
npm pack --dry-run

正式发布：

npm publish

注意事项

• 组件运行时必须传入 assetBaseUrl
• assetBaseUrl 指向的目录需要包含完整的 web-apps 与 wasm/x2t 资源
• 推荐使用同源地址，避免 OnlyOffice iframe 跨域
• 默认更适合浏览器端 React 项目使用