# 文档编辑器模块

> 基于 ProseMirror 的企业级富文本编辑器

> **模块位置**: `frontend/src/features/document-editor/`
> **技术栈**: ProseMirror + React + Zustand + TypeScript
> **形态**: 前端组件模块（无后端服务）

## 模块概述

文档编辑器是一个通用的富文本编辑组件，为系统中所有需要文档编辑功能的业务模块提供统一的编辑器服务。基于 ProseMirror 构建，支持 Markdown 语法、斜杠命令、实时协作等现代编辑体验。

## 实现状态

| 功能 | 状态 | 说明 |
|------|------|------|
| **核心架构** | ✅ 完成 | Extension 系统、Store 管理 |
| **节点扩展** | ✅ 完成 | 15 个节点类型 |
| **标记扩展** | ✅ 完成 | 7 个格式标记 |
| **插件扩展** | ✅ 完成 | 6 个功能插件 |
| **UI 组件** | ✅ 完成 | 斜杠菜单、工具栏、链接编辑器等 |
| **Markdown 导出** | ✅ 完成 | 完整序列化支持 |
| **协同编辑** | 🔜 待实现 | Yjs 集成 |

**总体进度**: 95%（除协同编辑与后端能力外全部完成）

## 核心功能

### 文本格式化

| 功能 | Markdown 语法 | 快捷键 |
|------|---------------|--------|
| **粗体** | `**text**` | ⌘B |
| *斜体* | `*text*` | ⌘I |
| <u>下划线</u> | - | ⌘U |
| ~~删除线~~ | `~~text~~` | ⌘⇧S |
| `代码` | `` `code` `` | ⌘E |
| ==高亮== | `==text==` | ⌘⇧H |
| [链接](url) | `[text](url)` | ⌘K |

### 块级元素

| 元素 | Markdown 语法 | 斜杠命令 |
|------|---------------|----------|
| 标题 H1-H6 | `# ~ ######` | `/heading1~3` |
| 无序列表 | `- ` / `* ` | `/bullet` |
| 有序列表 | `1. ` | `/numbered` |
| 引用块 | `> ` | `/quote` |
| 代码块 | ` ``` ` | `/code` |
| 分割线 | `---` | `/divider` |
| 表格 | - | `/table` |
| 图片 | - | `/image` |
| 提示框 | `:::info` | `/callout-*` |

### 斜杠命令菜单

输入 `/` 触发命令菜单，支持：
- 关键词搜索过滤
- 键盘导航 (↑↓ Enter Esc)
- 15+ 内置命令

### 浮动工具栏

选中文本时自动显示格式化工具栏

### 代码高亮

支持 17+ 编程语言语法高亮：JavaScript、TypeScript、Python、Go、Rust、Java、SQL 等

## 文档导航

| 文档 | 说明 | 状态 |
|------|------|------|
| [01-prd.md](./01-prd.md) | 产品需求文档 | ✅ |
| [02-user-journey.md](./02-user-journey.md) | 用户旅程 | 🚧 Draft |
| [03-architecture.md](./03-architecture.md) | 架构设计文档 | ✅ |
| [04-state-machine.md](./04-state-machine.md) | 状态机 | 🚧 Draft |
| [05-ui-interaction-spec.md](./05-ui-interaction-spec.md) | UI 交互规范 | 🚧 Draft |
| [06-data-model.md](./06-data-model.md) | 数据模型 | 🚧 Draft |
| [07-api.md](./07-api.md) | 组件 API 文档 | ✅ |
| [08-error-codes.md](./08-error-codes.md) | 错误码 | 🚧 Draft |
| [09-test-scenarios.md](./09-test-scenarios.md) | 测试场景 | 🚧 Draft |
| [10-e2e-test-spec.md](./10-e2e-test-spec.md) | E2E 规范 | 🚧 Draft |

## 快速开始

### 基础用法

```tsx
import { DocumentEditor, type DocumentEditorRef } from '@/features/document-editor';
import { useRef } from 'react';

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

  const handleSave = () => {
    const json = editorRef.current?.getJSON();
    const markdown = editorRef.current?.getMarkdown();
    console.log({ json, markdown });
  };

  return (
    <DocumentEditor
      ref={editorRef}
      placeholder="开始编写..."
      showWordCount
      onChange={(json) => console.log('内容变更:', json)}
    />
  );
}
```

### 只读模式

```tsx
<DocumentEditor value={content} readOnly />
```

### 带图片上传

```tsx
<DocumentEditor
  value={content}
  onUploadImage={async (file) => {
    const url = await uploadToServer(file);
    return url;
  }}
/>
```

## 公共 API

### 组件

| 导出 | 说明 |
|------|------|
| `DocumentEditor` | 主编辑器组件 |
| `SlashMenu` | 斜杠命令菜单 |
| `FloatingToolbar` | 浮动格式工具栏 |
| `Toolbar` | 顶部工具栏 |
| `LinkEditor` | 链接编辑弹窗 |
| `ImageUploader` | 图片上传组件 |

### Hooks & Store

| 导出 | 说明 |
|------|------|
| `useEditor` | 编辑器初始化 Hook |
| `useEditorStore` | Zustand 状态 Store |

### 扩展系统

| 导出 | 说明 |
|------|------|
| `Extension` | 扩展基类 |
| `NodeExtension` | 节点扩展基类 |
| `MarkExtension` | 标记扩展基类 |
| `PluginExtension` | 插件扩展基类 |
| `ExtensionManager` | 扩展管理器 |

### 工具函数

| 导出 | 说明 |
|------|------|
| `serializeToMarkdown` | 导出为 Markdown |

## Ref 方法

```typescript
interface DocumentEditorRef {
  getJSON(): EditorContent;      // 获取 JSON 内容
  getHTML(): string;             // 获取 HTML 内容
  getMarkdown(): string;         // 获取 Markdown 内容
  setContent(content): void;     // 设置内容
  isEmpty(): boolean;            // 检查是否为空
  getHeadings(): HeadingItem[];  // 获取标题列表 (TOC)
  getWordCount(): WordCount;     // 获取字数统计
  focus(): void;                 // 聚焦编辑器
  blur(): void;                  // 失焦编辑器
  getView(): EditorView | null;  // 获取 ProseMirror View
  getState(): EditorState | null; // 获取 ProseMirror State
}
```

## 技术栈

| 层次 | 技术 | 说明 |
|------|------|------|
| **编辑器核心** | ProseMirror | 底层编辑引擎 |
| **UI 框架** | React 19 | 组件开发 |
| **状态管理** | Zustand | 轻量级 Store |
| **代码高亮** | highlight.js | 语法高亮 |
| **图标** | Lucide React | 图标库 |
| **样式** | Tailwind CSS | 样式框架 |

## 目录结构

```
frontend/src/features/document-editor/
├── index.ts                 # 公共 API 导出
├── core/                    # 核心层
│   ├── types.ts             # 类型定义
│   ├── Extension.ts         # Extension 基类
│   └── ExtensionManager.ts  # 扩展管理器
├── extensions/              # 扩展层
│   ├── nodes/               # 节点扩展 (15个)
│   ├── marks/               # 标记扩展 (7个)
│   └── plugins/             # 插件扩展 (6个)
├── components/              # UI 组件
├── hooks/                   # React Hooks
├── stores/                  # Zustand Store
├── utils/                   # 工具函数
└── styles/                  # 样式文件
```

## 依赖本模块的业务

| 模块 | 使用场景 |
|------|----------|
| [知识库](../knowledge-base/) | 文章编辑 |
| [表单引擎](../form-engine/) | 富文本字段 |

## 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.1.0 | 2026-01-14 | 功能完善：SlashMenu 扩展集成、Markdown 导出、表格支持 |
| v1.0.0 | 2026-01-05 | 初始版本，从知识库模块中剥离编辑器功能 |

---

**状态**: ✅ 已实现 | **优先级**: P1 | **负责人**: 前端团队