npm package: @kdesigner/document-editor
Description: 通用文档编辑器组件库，支持WPS和OnlyOffice集成
Author: KDesigner Team
Latest version: 0.0.3

# Document Editor

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

## 特性

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

## 安装

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

## 快速开始

### 基础使用

```typescript
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 组件

```tsx
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 组件

```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>` - 替换文本

## 使用场景

### 只读模式

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

### 协同编辑

```typescript
// 监听文档变化
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)
  }
}
```

### 自定义工具栏

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

## 错误处理

```typescript
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+ |

## 开发

```bash
# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 测试
pnpm test

# 类型检查
pnpm type-check

# 代码检查
pnpm lint
```

## 许可证

MIT