@kdesigner/document-editor

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