# 文档编辑器 - API 接口文档

> **版本**: v1.1
> **创建日期**: 2026-01-05
> **最后更新**: 2026-01-15
> **负责人**: 前端团队
> **状态**: 已落地（前端组件 API）

---

## 📖 目录

- [1. API 概述](#1-api-概述)
- [2. 组件 Props API](#2-组件-props-api)
- [3. Ref API](#3-ref-api)
- [4. 事件回调](#4-事件回调)
- [5. 后端 API 状态](#5-后端-api-状态)

---

## 1. API 概述

本模块仅提供**前端组件 API**，不提供后端 HTTP/WebSocket 接口。

---

## 2. 组件 Props API

```typescript
interface DocumentEditorProps {
  value?: EditorContent;
  placeholder?: string;
  readOnly?: boolean;
  onChange?: (content: EditorContent) => void;
  onUploadImage?: (file: File) => Promise<string>;
  showToolbar?: boolean;
  showWordCount?: boolean;
  autoFocus?: boolean;
  className?: string;
  minHeight?: string;
  maxHeight?: string;
}
```

### 说明

- `value`：初始化内容（ProseMirror JSON）
- `onChange`：内容变更回调
- `onUploadImage`：图片上传回调，返回图片 URL
- `showToolbar`：是否展示顶部工具栏（目前为占位 UI）

---

## 3. Ref API

```typescript
interface DocumentEditorRef {
  getJSON(): EditorContent;
  getHTML(): string;
  getMarkdown(): string;
  setContent(content): void;
  isEmpty(): boolean;
  getHeadings(): HeadingItem[];
  getWordCount(): WordCount;
  focus(): void;
  blur(): void;
  getView(): EditorView | null;
  getState(): EditorState | null;
}
```

---

## 4. 事件回调

| 回调 | 触发时机 | 说明 |
|------|----------|------|
| `onChange` | 内容变化 | 返回 ProseMirror JSON |
| `onUploadImage` | 插入图片 | 返回可访问 URL |

---

## 5. 后端 API 状态

- 当前版本无后端服务与接口
- 如需存储/协同/版本管理，请由业务模块自行实现