@chao194/office

即插即用的 OnlyOffice 前端集成方案，支持 Vue 2/3、React 和原生 JavaScript。

特性

• 🚀 即插即用 - 简单的 API 设计，快速集成 OnlyOffice 文档编辑器
• 📦 多框架支持 - 支持 Vue 2、Vue 3、React 和原生 JavaScript
• 🔐 灵活的验签 - 支持自定义验签函数或内置验签接口
• 📝 TypeScript - 完整的 TypeScript 类型定义
• 🎯 Tree-shaking - 支持按需引入，优化打包体积
• 📚 完整文档 - 详细的 API 文档和使用示例

安装

# npm
npm install @chao194/office

# yarn
yarn add @chao194/office

# pnpm
pnpm add @chao194/office

快速开始

原生 JavaScript

import { createOfficeEditor } from '@chao194/office';

// 创建编辑器实例
const editor = createOfficeEditor();

// 配置文档参数
editor.configure({
  fileType: 'docx',
  key: 'your-document-key',
  url: 'https://example.com/document.docx',
  title: '示例文档',
  callbackUrl: 'https://your-server.com/callback',
  userId: 'user123',
  userName: '张三',
});

// 初始化编辑器（带验签）
const instance = await editor.initOffice({
  dom: document.getElementById('office-container'),
  officeApiUrl: 'https://your-onlyoffice-server/web-apps/apps/api/documents/api.js',
  auth: {
    appId: 'your-app-id',
    sign: 'your-sign',
    timestamp: Date.now(),
    verifyUrl: 'https://your-server.com',
  },
});

// 监听事件
instance.on('onDocumentReady', () => {
  console.log('文档已就绪');
});

// 组件销毁时清理
instance.destroy();

Vue 3 组件

<template>
  <OnlyOfficeEditor
    :office-api-url="officeApiUrl"
    :document="documentConfig"
    :auth="authConfig"
    @ready="onReady"
    @error="onError"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { OnlyOfficeEditor } from '@chao194/office/vue3';
import type { OfficeDocumentConfig, AuthConfig } from '@chao194/office';

const officeApiUrl = 'https://your-onlyoffice-server/web-apps/apps/api/documents/api.js';

const documentConfig: OfficeDocumentConfig = {
  fileType: 'docx',
  key: 'your-document-key',
  url: 'https://example.com/document.docx',
  title: '示例文档',
  callbackUrl: 'https://your-server.com/callback',
  userId: 'user123',
  userName: '张三',
};

const authConfig: AuthConfig = {
  appId: 'your-app-id',
  sign: 'your-sign',
  timestamp: Date.now(),
};

const onReady = (editor) => {
  console.log('编辑器已就绪', editor);
};

const onError = (error) => {
  console.error('编辑器错误', error);
};
</script>

Vue 3 组合式函数

<template>
  <div ref="containerRef" style="width: 100%; height: 600px;"></div>
</template>

<script setup lang="ts">
import { useOnlyOffice } from '@chao194/office/vue3';

const { containerRef, isReady, error } = useOnlyOffice({
  officeApiUrl: 'https://your-onlyoffice-server/web-apps/apps/api/documents/api.js',
  document: {
    fileType: 'docx',
    key: 'your-document-key',
    url: 'https://example.com/document.docx',
    title: '示例文档',
    callbackUrl: 'https://your-server.com/callback',
    userId: 'user123',
    userName: '张三',
  },
});
</script>

Vue 2 组件

<template>
  <OnlyOfficeEditor
    :office-api-url="officeApiUrl"
    :document="documentConfig"
    :auth="authConfig"
    @ready="onReady"
    @error="onError"
  />
</template>

<script>
import { OnlyOfficeEditor } from '@chao194/office/vue2';

export default {
  components: {
    OnlyOfficeEditor,
  },
  data() {
    return {
      officeApiUrl: 'https://your-onlyoffice-server/web-apps/apps/api/documents/api.js',
      documentConfig: {
        fileType: 'docx',
        key: 'your-document-key',
        url: 'https://example.com/document.docx',
        title: '示例文档',
        callbackUrl: 'https://your-server.com/callback',
        userId: 'user123',
        userName: '张三',
      },
      authConfig: {
        appId: 'your-app-id',
        sign: 'your-sign',
        timestamp: Date.now(),
      },
    };
  },
  methods: {
    onReady(editor) {
      console.log('编辑器已就绪', editor);
    },
    onError(error) {
      console.error('编辑器错误', error);
    },
  },
};
</script>

Vue 2 混入

<template>
  <div ref="officeContainer" style="width: 100%; height: 600px;"></div>
</template>

<script>
import { OnlyOfficeMixin } from '@chao194/office/vue2';

export default {
  mixins: [OnlyOfficeMixin],
  mounted() {
    this.$initOffice(
      this.$refs.officeContainer,
      'https://your-onlyoffice-server/web-apps/apps/api/documents/api.js',
      {
        fileType: 'docx',
        key: 'your-document-key',
        url: 'https://example.com/document.docx',
        title: '示例文档',
        callbackUrl: 'https://your-server.com/callback',
        userId: 'user123',
        userName: '张三',
      }
    );
  },
  beforeDestroy() {
    this.$destroyOffice();
  },
};
</script>

React 组件

import React from 'react';
import { OnlyOfficeEditor } from '@chao194/office/react';
import type { OfficeDocumentConfig, AuthConfig } from '@chao194/office';

const officeApiUrl = 'https://your-onlyoffice-server/web-apps/apps/api/documents/api.js';

const documentConfig: OfficeDocumentConfig = {
  fileType: 'docx',
  key: 'your-document-key',
  url: 'https://example.com/document.docx',
  title: '示例文档',
  callbackUrl: 'https://your-server.com/callback',
  userId: 'user123',
  userName: '张三',
};

const authConfig: AuthConfig = {
  appId: 'your-app-id',
  sign: 'your-sign',
  timestamp: Date.now(),
};

function App() {
  return (
    <div style={{ width: '100%', height: '600px' }}>
      <OnlyOfficeEditor
        officeApiUrl={officeApiUrl}
        document={documentConfig}
        auth={authConfig}
        onReady={(editor) => console.log('编辑器已就绪', editor)}
        onError={(error) => console.error('编辑器错误', error)}
      />
    </div>
  );
}

export default App;

React Hook

import React from 'react';
import { useOnlyOffice } from '@chao194/office/react';

function App() {
  const { containerRef, isReady, error } = useOnlyOffice({
    officeApiUrl: 'https://your-onlyoffice-server/web-apps/apps/api/documents/api.js',
    document: {
      fileType: 'docx',
      key: 'your-document-key',
      url: 'https://example.com/document.docx',
      title: '示例文档',
      callbackUrl: 'https://your-server.com/callback',
      userId: 'user123',
      userName: '张三',
    },
  });

  return (
    <div>
      <div ref={containerRef} style={{ width: '100%', height: '600px' }} />
      {error && <div style={{ color: 'red' }}>{error}</div>}
    </div>
  );
}

export default App;

API 文档

核心 API

createOfficeEditor()

创建一个新的 Office 编辑器实例。

返回值: OfficeEditor

initOffice(config)

快速初始化 Office 编辑器（带验签）。

参数:

• config: OfficeInitConfig - 初始化配置

返回值: Promise<OfficeEditorInstance>

init(dom, officeApiUrl, callback?)

简化初始化（无验签）。

参数:

• dom: HTMLElement - 挂载的 DOM 元素
• officeApiUrl: string - OnlyOffice API 地址
• callback?: OfficeCallback - 事件回调函数

返回值: OfficeEditorInstance

OfficeEditor 实例方法

configure(config)

配置文档参数。

参数:

• config: OfficeDocumentConfig - 文档配置

initOffice(config)

初始化编辑器（带验签）。

参数:

• config: OfficeInitConfig - 初始化配置

返回值: Promise<OfficeEditorInstance>

init(dom, officeApiUrl, callback?)

简化初始化（无验签）。

参数:

• dom: HTMLElement - 挂载的 DOM 元素
• officeApiUrl: string - OnlyOffice API 地址
• callback?: OfficeCallback - 事件回调函数

返回值: OfficeEditorInstance

on(event, callback)

监听事件。

参数:

• event: OfficeEventType - 事件类型
• callback: (...args: any[]) => void - 回调函数

off(event, callback)

移除事件监听。

参数:

• event: OfficeEventType - 事件类型
• callback: (...args: any[]) => void - 回调函数

destroy()

销毁编辑器实例。

getConfig()

获取当前配置。

返回值: DocumentConfig & EditorConfig

getEditor()

获取内部 OnlyOffice 编辑器实例。

返回值: any

类型定义

OfficeDocumentConfig

interface OfficeDocumentConfig {
  height?: string;
  width?: string;
  fileType?: FileType;
  key?: string;
  url?: string;
  title?: string;
  permissions?: DocumentPermissions;
  callbackUrl?: string;
  userId?: string;
  userName?: string;
  userGroup?: string;
}

OfficeInitConfig

interface OfficeInitConfig {
  dom: HTMLElement;
  officeApiUrl: string;
  callback?: OfficeCallback;
  auth?: AuthConfig;
  verifyFunction?: VerifyTokenSignFunction;
}

AuthConfig

interface AuthConfig {
  appId: string;
  sign: string;
  timestamp: number;
  verifyUrl?: string;
}

OfficeEventType

type OfficeEventType =
  | 'documentStateChange'
  | 'onDocumentReady'
  | 'onInfo'
  | 'onError'
  | 'onRequestHistory'
  | 'onRequestHistoryData'
  | 'onRequestHistoryClose'
  | 'onRequestRestore'
  | 'onRequestSendNotify'
  | 'onRequestUsers';

从旧版本迁移

从 script 标签方式迁移

旧版本使用 <script> 标签加载全局变量 officeSdk：

<script src="https://your-dev-server.example.com/sdk/office-sdk-dev.js"></script>
<script>
  officeSdk.sdk.config({...});
  officeSdk.sdk.initOffice({...});
</script>

新版本使用 npm 包导入：

import { createOfficeEditor } from '@chao194/office';

const editor = createOfficeEditor();
editor.configure({...});
await editor.initOffice({...});

主要变化

1. 导入方式: 从全局变量改为 ES Module 导入
2. 验签配置: 验签配置从 signData 改为 auth，支持自定义验签函数
3. 实例管理: 从全局单例改为可创建多个独立实例
4. 类型支持: 完整的 TypeScript 类型定义

许可证

MIT