npm package: @mozhou-tech/editor
Description: The non-official starter kit of the Tiptap editor contains common extensions.
Author: zhengzhiyu@yeah.net
Latest version: 0.5.7

# TipTap 编辑器扩展包，基于 `@syfxlin/tiptap-starter-kit` 的本地化版本，提供了功能完整的富文本编辑器解决方案。

原项目：@syfxlin/tiptap-starter-kit

## 🚀 项目概述

本项目是一个基于 TipTap 的现代化富文本编辑器扩展包，提供了开箱即用的编辑器组件和丰富的扩展功能。项目采用 TypeScript 开发，支持 React 18+，具有完整的类型定义和现代化的开发体验。

### 核心特性

- 🎯 **开箱即用**：提供完整的 TipTapEditor React 组件
- 🤖 **AI 集成**：内置 AI 助手功能，支持文本润色、扩写、翻译等
- 📝 **Markdown 支持**：基于 remark 的完整 Markdown 支持
- 🎨 **丰富的 UI**：浮动菜单、斜杠菜单、拖拽按钮等交互组件
- 📁 **文件处理**：支持拖拽上传、粘贴上传等文件操作
- 🎭 **多媒体内容**：支持图片、音频、视频、图表、数学公式等
- 🌙 **主题支持**：内置亮色/暗色主题切换
- 🔧 **高度可配置**：所有功能都可以独立配置和定制

## 📋 项目结构

```
tiptap-starter-kit/
├── src/                          # 源代码目录
│   ├── components/               # React 组件
│   │   └── editor/              # TipTapEditor 组件
│   │       ├── TipTapEditor.tsx # 主编辑器组件
│   │       └── styles.css       # 编辑器样式
│   ├── extensions/              # TipTap 扩展
│   │   ├── ai/                  # AI 助手扩展
│   │   ├── block-menu/          # 块级菜单扩展
│   │   ├── float-menu/          # 浮动菜单扩展
│   │   ├── click-menu/          # 点击菜单扩展
│   │   ├── markdown/            # Markdown 支持扩展
│   │   ├── uploader/            # 文件上传扩展
│   │   └── starter-kit/         # 扩展集合
│   ├── marks/                   # 文本标记扩展
│   ├── nodes/                   # 节点扩展
│   └── utils/                   # 工具函数
├── demo/                        # 演示示例
├── api/                         # API 模拟服务
├── server/                      # 开发服务器
└── dist/                        # 构建输出
```

## 🏗️ 技术架构

### 核心技术栈

- **框架**: [TipTap](https://tiptap.dev) - 基于 ProseMirror 的富文本编辑器框架
- **UI 框架**: [React](https://react.dev) 18+ - 现代化的用户界面库
- **语言**: [TypeScript](https://www.typescriptlang.org) - 类型安全的 JavaScript 超集
- **构建工具**: [Bunchee](https://github.com/huozhi/bunchee) - 现代化的库构建工具
- **开发工具**: [Vite](https://vitejs.dev) - 快速的开发服务器

### 依赖架构

```mermaid
graph TD
    A[TipTapEditor Component] --> B[StarterKit Extension]
    B --> C[Core Extensions]
    B --> D[Custom Extensions]

    C --> E[TipTap Official Extensions]
    D --> F[AI Extension]
    D --> G[Markdown Extension]
    D --> H[Menu Extensions]
    D --> I[Upload Extension]

    F --> J[AI API Service]
    G --> K[Remark Ecosystem]
    H --> L[Tippy.js]
    I --> M[File Processing]
```

## ✨ 主要功能

### 🤖 AI 助手功能

- **文本优化**: 润色、扩写、简化文本内容
- **语气调整**: 专业、随意、自信、友好等语气转换
- **多语言翻译**: 支持中英日韩法德西等多种语言
- **智能续写**: 基于上下文的内容续写
- **内容总结**: 自动提取文本要点和摘要
- **自定义端点**: 支持配置不同的 AI 服务提供商

### 📝 Markdown 增强

- **完整语法支持**: 基于 [remark](https://github.com/remarkjs/remark) 生态系统
- **实时预览**: 所见即所得的 Markdown 编辑体验
- **GFM 扩展**: 支持 GitHub Flavored Markdown
- **数学公式**: 支持 KaTeX 数学公式渲染
- **代码高亮**: 基于 Lowlight 的语法高亮
- **双向转换**: Markdown ↔ HTML ↔ JSON 格式互转

### 🎨 交互式菜单

- **浮动菜单**: 选中文本时显示的格式化工具栏
- **斜杠菜单**: 输入 `/` 触发的块级内容插入菜单
- **拖拽菜单**: 支持拖拽重排的内容块操作按钮
- **智能搜索**: 菜单项支持模糊搜索和快速过滤

### 📁 文件处理

- **多种上传方式**: 拖拽、粘贴、点击上传
- **文件类型支持**: 图片、音频、视频、文档等
- **自定义处理**: 支持自定义文件上传和处理逻辑
- **进度反馈**: 上传进度显示和错误处理

### 🎭 丰富内容块

- **媒体内容**: 图片、音频、视频播放器
- **图表支持**: Mermaid 流程图、PlantUML 图表
- **数学公式**: 行内和块级 LaTeX 数学公式
- **代码块**: 支持语法高亮的代码块
- **表格**: 可编辑的表格支持
- **任务列表**: 可交互的待办事项列表
- **折叠内容**: Details/Summary 折叠块
- **表情符号**: Emoji 表情支持

## Theme

[Theme configuration](./docs/styles/theme.md)

## Included extensions

> Some of the extensions are inherited from the official Tiptap extensions, and the changes are minor,
> so the documentation is not provided for the time being, will be added later.

### Marks

- [Subscript](https://tiptap.dev/docs/editor/extensions/marks/subscript)
- [Superscript](https://tiptap.dev/docs/editor/extensions/marks/superscript)
- [Bold](https://tiptap.dev/docs/editor/extensions/marks/bold)
- [Code](https://tiptap.dev/docs/editor/extensions/marks/code)
- [Link](https://tiptap.dev/docs/editor/extensions/marks/link)
- [Italic](https://tiptap.dev/docs/editor/extensions/marks/italic)
- [Strike](https://tiptap.dev/docs/editor/extensions/marks/strike)
- [Highlight](https://tiptap.dev/docs/editor/extensions/marks/highlight)
- [Underline](https://tiptap.dev/docs/editor/extensions/marks/underline)

### Nodes

- [Text](https://tiptap.dev/docs/editor/extensions/nodes/text)
- [Document](https://tiptap.dev/docs/editor/extensions/nodes/document)
- [Heading](https://tiptap.dev/docs/editor/extensions/nodes/heading)
- [Paragraph](https://tiptap.dev/docs/editor/extensions/nodes/paragraph)
- [Blockquote](https://tiptap.dev/docs/editor/extensions/nodes/blockquote)
- [HardBreak](https://tiptap.dev/docs/editor/extensions/nodes/hard-break)
- [CodeBlock](https://tiptap.dev/docs/editor/extensions/nodes/code-block-lowlight)
- [HorizontalRule](https://tiptap.dev/docs/editor/extensions/nodes/horizontal-rule)
- [BulletList](https://tiptap.dev/docs/editor/extensions/nodes/bullet-list)
- [OrderedList](https://tiptap.dev/docs/editor/extensions/nodes/ordered-list)
- [ListItem](https://tiptap.dev/docs/editor/extensions/nodes/list-item)
- [TaskList](https://tiptap.dev/docs/editor/extensions/nodes/task-list)
- [TaskItem](https://tiptap.dev/docs/editor/extensions/nodes/task-item)
- [Details](./docs/nodes/details.md)
- [DetailsContent](./docs/nodes/details.md)
- [DetailsSummary](./docs/nodes/details.md)
- [Table](https://tiptap.dev/docs/editor/extensions/nodes/table)
- [TableRow](https://tiptap.dev/docs/editor/extensions/nodes/table-row)
- [TableCell](https://tiptap.dev/docs/editor/extensions/nodes/table-cell)
- [TableHeader](https://tiptap.dev/docs/editor/extensions/nodes/table-header)
- [Emoji](./docs/nodes/emoji.md)
- [Embed](./docs/nodes/embed.md)
- [Image](./docs/nodes/image.md)
- [Audio](./docs/nodes/audio.md)
- [Video](./docs/nodes/video.md)
- [Mermaid](./docs/nodes/mermaid.md)
- [Plantuml](./docs/nodes/plantuml.md)
- [MathBlock](./docs/nodes/math-block.md)
- [MathInline](./docs/nodes/math-inline.md)

### Extensions

- [Uploader](./docs/extensions/uploader.md)
- [Markdown](./docs/extensions/markdown.md)
- [Clipboard](./docs/extensions/clipboard.md)
- [BlockMenu](./docs/extensions/block-menu.md)
- [FloatMenu](./docs/extensions/float-menu.md)
- [ClickMenu](./docs/extensions/click-menu.md)
- [History](https://tiptap.dev/docs/editor/extensions/functionality/undo-redo)
- [Gapcursor](https://tiptap.dev/docs/editor/extensions/functionality/gapcursor)
- [Dropcursor](https://tiptap.dev/docs/editor/extensions/functionality/dropcursor)

## 🚀 快速开始

### 安装

```bash
# 使用 pnpm (推荐)
pnpm add @wanyan/editor @tiptap/core @tiptap/pm react react-dom

# 使用 npm
npm install @wanyan/editor @tiptap/core @tiptap/pm react react-dom

# 使用 yarn
yarn add @wanyan/editor @tiptap/core @tiptap/pm react react-dom
```

### 基本使用

#### 1. 使用 TipTapEditor 组件 (推荐)

```tsx
import React, { useState } from "react";
import TipTapEditor from "@wanyan/editor";

function MyEditor() {
  const [content, setContent] = useState("# Hello World\n\n开始编辑...");

  return (
    <TipTapEditor
      value={content}
      onChange={setContent}
      enableAI={true}
      aiEndpoint="/api/ai/improve-text"
      enableUploader={true}
      incrementalUpdate={true} // 启用增量更新模式
      placeholder="开始输入内容..."
    />
  );
}
```

#### 2. 使用 StarterKit 扩展

```typescript
import { useEditor } from "@tiptap/react";
import { StarterKit } from "@wanyan/editor";

const editor = useEditor({
  extensions: [
    StarterKit.configure({
      // 禁用某些功能
      emoji: false,
      // 配置功能选项
      heading: {
        levels: [1, 2, 3],
      },
      // 启用 AI 功能
      ai: {
        enabled: true,
        apiEndpoint: "/api/ai/improve-text",
      },
    }),
  ],
  content: "# Hello World",
});
```

### 高级配置

#### 增量更新模式

TipTap 编辑器支持增量更新模式，当外部 `value` 属性发生变化时，只更新发生变化的部分，而不是替换整个文档内容。这在协作编辑、自动保存等场景中特别有用。

```tsx
<TipTapEditor
  value={content}
  onChange={setContent}
  incrementalUpdate={true} // 启用增量更新模式
  placeholder="开始输入内容..."
/>
```

**增量更新 vs 完全替换对比：**

| 模式     | 优势                                   | 适用场景                     |
| -------- | -------------------------------------- | ---------------------------- |
| 增量更新 | 保持光标位置和选择状态，更好的用户体验 | 协作编辑、自动保存、实时同步 |
| 完全替换 | 简单可靠，确保内容完全一致             | 切换文档、应用模板、重置操作 |

详细说明请参考：[增量更新文档](docs/incremental-update.md)

#### AI 功能配置

```tsx
<TipTapEditor
  value={content}
  onChange={setContent}
  enableAI={true}
  aiEndpoint="https://api.openai.com/v1/chat/completions"
  // 其他配置...
/>
```

#### 文件上传配置

```tsx
const handleUpload = async (files: FileList) => {
  // 自定义文件上传逻辑
  const uploadedFiles = [];
  for (const file of files) {
    const formData = new FormData();
    formData.append("file", file);

    const response = await fetch("/api/upload", {
      method: "POST",
      body: formData,
    });

    const result = await response.json();
    uploadedFiles.push({
      name: file.name,
      type: file.type,
      size: file.size,
      url: result.url,
    });
  }
  return uploadedFiles;
};

<TipTapEditor
  value={content}
  onChange={setContent}
  enableUploader={true}
  onUpload={handleUpload}
  // 其他配置...
/>;
```

## 🛠️ 开发指南

### 本地开发

```bash
# 克隆项目
git clone https://github.com/auleti/tiptap-starter-kit.git
cd tiptap-starter-kit

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 启动完整开发环境 (包含 API 服务)
pnpm dev:full
```

### 构建项目

```bash
# 构建样式文件
pnpm style

# 构建库文件
pnpm build

# 监听模式构建
pnpm watch
```

### 项目脚本

- `pnpm dev` - 启动 Vite 开发服务器
- `pnpm api` - 启动模拟 API 服务器
- `pnpm dev:full` - 同时启动开发服务器和 API 服务器
- `pnpm build` - 构建生产版本
- `pnpm style` - 编译 Less 样式文件

## 🔧 技术实现

### 核心架构设计

项目采用模块化架构，主要分为以下几个层次：

1. **组件层** (`src/components/`)
   - `TipTapEditor.tsx` - 主编辑器 React 组件
   - 提供统一的编辑器接口和配置选项
   - 支持 TypeScript 类型定义

2. **扩展层** (`src/extensions/`)
   - `starter-kit/` - 扩展集合和配置管理
   - `ai/` - AI 助手功能实现
   - `markdown/` - Markdown 解析和渲染
   - `*-menu/` - 各种交互菜单实现
   - `uploader/` - 文件上传处理

3. **节点层** (`src/nodes/`)
   - 各种内容节点的实现
   - 支持媒体、图表、数学公式等复杂内容

4. **标记层** (`src/marks/`)
   - 文本格式化标记的实现
   - 支持粗体、斜体、高亮等格式

### 关键技术特性

#### 1. 模块化扩展系统

```typescript
// 扩展可以独立配置和禁用
StarterKit.configure({
  ai: { enabled: true, apiEndpoint: "/api/ai" },
  markdown: { html: false },
  uploader: { maxFileSize: 10 * 1024 * 1024 },
});
```

#### 2. 类型安全的 API

```typescript
interface TipTapEditorProps {
  value: string;
  onChange: (value: string) => void;
  enableAI?: boolean;
  aiEndpoint?: string;
  enableUploader?: boolean;
  onUpload?: (files: FileList) => Promise<UploadResult[]>;
}
```

#### 3. 插件化菜单系统

- 基于 Tippy.js 的浮动菜单
- 支持搜索和过滤的命令面板
- 可拖拽的内容块操作

#### 4. 智能内容处理

- Markdown 双向转换
- 文件类型自动识别
- 内容格式自动优化

### 构建和发布

#### 构建配置

- **Bunchee**: 现代化的库构建工具，支持 ESM/CJS 双格式输出
- **TypeScript**: 完整的类型定义和检查
- **Less**: CSS 预处理器，支持主题定制

#### 发布流程

```bash
# 1. 构建样式文件
pnpm style

# 2. 构建库文件
pnpm build

# 3. 发布到私有 npm 仓库
npm publish --registry https://wanyan.co/npm
```

## 📚 API 文档

### TipTapEditor 组件 Props

| 属性             | 类型                                                    | 默认值              | 描述                       |
| ---------------- | ------------------------------------------------------- | ------------------- | -------------------------- |
| `value`          | `string`                                                | -                   | 编辑器内容 (Markdown 格式) |
| `onChange`       | `(value: string) => void`                               | -                   | 内容变化回调               |
| `placeholder`    | `string`                                                | `"开始输入内容..."` | 占位符文本                 |
| `className`      | `string`                                                | `""`                | 自定义 CSS 类名            |
| `readOnly`       | `boolean`                                               | `false`             | 是否只读模式               |
| `enableAI`       | `boolean`                                               | `false`             | 是否启用 AI 功能           |
| `aiEndpoint`     | `string`                                                | -                   | AI API 端点地址            |
| `enableUploader` | `boolean`                                               | `false`             | 是否启用文件上传           |
| `onUpload`       | `(files: FileList) => Promise<UploadResult[]>`          | -                   | 文件上传处理函数           |
| `onToast`        | `(message: string, type: "success" \| "error") => void` | -                   | 消息提示回调               |

### TipTapEditor Ref 方法

| 方法            | 返回类型         | 描述                     |
| --------------- | ---------------- | ------------------------ |
| `getJSON()`     | `any`            | 获取编辑器 JSON 格式内容 |
| `getMarkdown()` | `string`         | 获取 Markdown 格式内容   |
| `getHTML()`     | `string`         | 获取 HTML 格式内容       |
| `editor`        | `Editor \| null` | 获取 TipTap 编辑器实例   |

## 🎨 主题定制

### CSS 变量

项目支持通过 CSS 变量进行主题定制：

```css
:root {
  --tiptap-primary-color: #3b82f6;
  --tiptap-background-color: #ffffff;
  --tiptap-text-color: #1f2937;
  --tiptap-border-color: #e5e7eb;
  --tiptap-hover-color: #f3f4f6;
}

.dark {
  --tiptap-background-color: #1f2937;
  --tiptap-text-color: #f9fafb;
  --tiptap-border-color: #374151;
  --tiptap-hover-color: #374151;
}
```

### 自定义样式

```css
.my-editor {
  --tiptap-primary-color: #10b981;
}

.my-editor .rich-text-editor {
  border-radius: 12px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}
```

## 🤝 贡献指南

### 开发环境要求

- Node.js 18+
- pnpm 8+
- TypeScript 5+

### 贡献流程

1. Fork 项目仓库
2. 创建功能分支: `git checkout -b feature/amazing-feature`
3. 提交更改: `git commit -m 'Add amazing feature'`
4. 推送分支: `git push origin feature/amazing-feature`
5. 创建 Pull Request

### 代码规范

项目使用 ESLint 和 TypeScript 进行代码质量控制：

```bash
# 代码检查
pnpm lint

# 类型检查
pnpm type-check
```

## 📄 许可证

本项目基于 [MIT](https://opensource.org/licenses/MIT) 许可证开源。

## 🙏 致谢

- [TipTap](https://tiptap.dev) - 优秀的富文本编辑器框架
- [Milkdown](https://github.com/Milkdown/milkdown) - 设计灵感来源
- [Outline](https://github.com/outline/outline) - 功能参考
- [Notion](https://www.notion.so) - 交互体验参考
- [@syfxlin/tiptap-starter-kit](https://github.com/syfxlin/tiptap-starter-kit) - 原始项目

## 👥 维护者

- **zhengzhiyu** - 项目维护者
- 基于 **@syfxlin/tiptap-starter-kit** 项目，感谢 [Otstar Lin](https://github.com/syfxlin) 的原始工作

---

<div align="center">
  <p>如果这个项目对你有帮助，请给它一个 ⭐️</p>
  <p>Made with ❤️ by Wanyan Team</p>
</div>