Document Editor

一个通用的文档编辑器组件库，支持 WPS 和 OnlyOffice 集成，提供 Vue 和 React 组件版本。

特性

• 🚀 支持 WPS Web Office 集成
• 📄 支持多种文档格式（.doc, .docx, .xls, .xlsx, .ppt, .pptx）
• 🎨 支持主题切换（明亮/暗黑）
• 🌍 支持国际化（中文/英文）
• 🔒 完善的权限控制系统
• 💾 自动保存功能
• ⚛️ React 和 Vue 组件支持
• 📱 响应式设计
• 🛠️ TypeScript 支持

安装

npm install @kdesigner/document-editor
# 或
yarn add @kdesigner/document-editor
# 或
pnpm add @kdesigner/document-editor

快速开始

基础使用

import { EditorManager } from '@kdesigner/document-editor'

// 配置编辑器
const config = {
  wps: {
    appId: 'your_app_id',
    appSecret: 'your_app_secret',
    serverUrl: 'https://your-wps-server.com'
  },
  locale: 'zh-CN',
  theme: 'light',
  permissions: {
    edit: true,
    download: true,
    print: true,
    comment: true
  }
}

// 创建编辑器实例
const container = document.getElementById('editor-container')
const editorManager = new EditorManager('wps', container)

// 初始化编辑器
await editorManager.initialize(config)

// 加载文档
await editorManager.loadDocument({
  id: 'doc_001',
  name: '测试文档.docx',
  url: 'https://example.com/document.docx',
  type: 'docx'
})

React 组件

import React, { useRef } from 'react'
import { DocumentEditor, DocumentEditorRef } from '@kdesigner/document-editor/react'

const MyApp = () => {
  const editorRef = useRef<DocumentEditorRef>(null)

  const handleSave = async () => {
    await editorRef.current?.save()
  }

  return (
    <div>
      <button onClick={handleSave}>保存</button>
      <DocumentEditor
        ref={editorRef}
        editor="wps"
        config={{
          wps: {
            appId: 'your_app_id',
            appSecret: 'your_app_secret',
            serverUrl: 'https://your-wps-server.com'
          }
        }}
        documentUrl="https://example.com/document.docx"
        width="100%"
        height="600px"
        onReady={() => console.log('编辑器就绪')}
        onSave={() => console.log('文档已保存')}
      />
    </div>
  )
}

Vue 组件

<template>
  <div>
    <button @click="handleSave">保存</button>
    <DocumentEditor
      ref="editorRef"
      editor="wps"
      :config="config"
      document-url="https://example.com/document.docx"
      width="100%"
      height="600px"
      @ready="onReady"
      @save="onSave"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { DocumentEditor } from '@kdesigner/document-editor/vue'

const editorRef = ref()
const config = {
  wps: {
    appId: 'your_app_id',
    appSecret: 'your_app_secret',
    serverUrl: 'https://your-wps-server.com'
  }
}

const handleSave = async () => {
  await editorRef.value?.save()
}

const onReady = () => console.log('编辑器就绪')
const onSave = () => console.log('文档已保存')
</script>

配置选项

EditorConfig

| 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | wps | WpsConfig | - | WPS 配置 | | onlyoffice | OnlyOfficeConfig | - | OnlyOffice 配置 | | locale | 'zh-CN' | 'en-US' | 'zh-CN' | 语言设置 | | theme | 'light' | 'dark' | 'light' | 主题设置 | | toolbar | ToolbarConfig | - | 工具栏配置 | | permissions | PermissionConfig | - | 权限配置 | | autoSave | boolean | true | 是否启用自动保存 | | autoSaveInterval | number | 30000 | 自动保存间隔（毫秒）|

WpsConfig

| 属性 | 类型 | 描述 | |------|------|------| | appId | string | WPS 应用 ID | | appSecret | string | WPS 应用密钥 | | serverUrl | string | WPS 服务器地址 | | version | string | API 版本（可选）|

PermissionConfig

| 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | edit | boolean | true | 是否可编辑 | | download | boolean | true | 是否可下载 | | print | boolean | true | 是否可打印 | | comment | boolean | true | 是否可评论 | | copy | boolean | true | 是否可复制 | | export | boolean | true | 是否可导出 |

API 参考

EditorManager

编辑器管理器是核心类，负责管理编辑器的生命周期。

方法

• initialize(config: EditorConfig): Promise<void> - 初始化编辑器
• destroy(): void - 销毁编辑器
• getContent(): Promise<string> - 获取文档内容
• setContent(content: string): Promise<void> - 设置文档内容
• save(): Promise<void> - 保存文档
• loadDocument(document: DocumentInfo): Promise<void> - 加载文档
• setPermissions(permissions: PermissionConfig): void - 设置权限
• on(event: EditorEvent, callback: EditorEventCallback): void - 添加事件监听器
• off(event: EditorEvent, callback: EditorEventCallback): void - 移除事件监听器

事件

• ready - 编辑器就绪
• load - 文档加载完成
• save - 文档保存完成
• change - 文档内容变化
• error - 错误事件
• destroy - 编辑器销毁

WpsAdapter

WPS 适配器提供了额外的 WPS 特定功能。

方法

• exportDocument(type: string): Promise<Blob> - 导出文档
• executeCommand(command: string, params?: any): Promise<any> - 执行 WPS 命令
• getSelection(): Promise<any> - 获取选中内容
• insertText(text: string): Promise<void> - 插入文本
• replaceText(searchText: string, replaceText: string): Promise<void> - 替换文本

使用场景

只读模式

const readOnlyConfig = {
  wps: { /* WPS 配置 */ },
  permissions: {
    edit: false,
    download: true,
    print: true,
    comment: false
  }
}

协同编辑

// 监听文档变化
editorManager.on('change', (data) => {
  // 发送变化到其他用户
  websocket.send(JSON.stringify({
    type: 'document_change',
    data
  }))
})

// 接收其他用户的变化
websocket.onmessage = (event) => {
  const message = JSON.parse(event.data)
  if (message.type === 'document_change') {
    // 应用变化到当前文档
    editorManager.setContent(message.data.content)
  }
}

自定义工具栏

const config = {
  toolbar: {
    visible: true,
    position: 'top',
    items: ['save', 'undo', 'redo', 'print']
  }
}

错误处理

editorManager.on('error', (error) => {
  console.error('编辑器错误:', {
    code: error.code,
    message: error.message,
    originalError: error.originalError
  })
  
  // 根据错误代码处理不同类型的错误
  switch (error.code) {
    case 'INIT_FAILED':
      showMessage('编辑器初始化失败，请刷新页面重试')
      break
    case 'LOAD_FAILED':
      showMessage('文档加载失败，请检查网络连接')
      break
    case 'SAVE_FAILED':
      showMessage('文档保存失败，请重试')
      break
    default:
      showMessage('未知错误，请联系技术支持')
  }
})

浏览器兼容性

| 浏览器 | 版本 | |--------|------| | Chrome | 70+ | | Firefox | 65+ | | Safari | 12+ | | Edge | 79+ |

开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 测试
pnpm test

# 类型检查
pnpm type-check

# 代码检查
pnpm lint

许可证

MIT