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

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

🚀 项目概述

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

$3

- 🎯 开箱即用：提供完整的 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/ # 构建输出
`

🏗️ 技术架构

$3

- 框架: TipTap - 基于 ProseMirror 的富文本编辑器框架
- UI 框架: React 18+ - 现代化的用户界面库
- 语言: TypeScript - 类型安全的 JavaScript 超集
- 构建工具: Bunchee - 现代化的库构建工具
- 开发工具: Vite - 快速的开发服务器

$3

`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]
`

✨ 主要功能

$3

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

$3

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

$3

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

$3

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

$3

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

Theme

Theme configuration

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.

$3

- Subscript
- Superscript
- Bold
- Code
- Link
- Italic
- Strike
- Highlight
- Underline

$3

- Text
- Document
- Heading
- Paragraph
- Blockquote
- HardBreak
- CodeBlock
- HorizontalRule
- BulletList
- OrderedList
- ListItem
- TaskList
- TaskItem
- Details
- DetailsContent
- DetailsSummary
- Table
- TableRow
- TableCell
- TableHeader
- Emoji
- Embed
- Image
- Audio
- Video
- Mermaid
- Plantuml
- MathBlock
- MathInline

$3

- Uploader
- Markdown
- Clipboard
- BlockMenu
- FloatMenu
- ClickMenu
- History
- Gapcursor
- Dropcursor

🚀 快速开始

$3

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

$3

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

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

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

return (
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",
});
`

$3

#### 增量更新模式

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

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

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

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

详细说明请参考：增量更新文档

#### AI 功能配置

`tsx
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;
};

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

🛠️ 开发指南

$3

`bash


克隆项目

git clone https://github.com/auleti/tiptap-starter-kit.git
cd tiptap-starter-kit

安装依赖

pnpm install

启动开发服务器

pnpm dev

启动完整开发环境 (包含 API 服务)

pnpm dev:full
`

$3

`bash


构建样式文件

pnpm style

构建库文件

pnpm build

监听模式构建

pnpm watch
`

$3

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

🔧 技术实现

$3

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

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

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

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

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

$3

#### 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;
}
`

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

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

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

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

$3

#### 构建配置

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

#### 发布流程

`bash


1. 构建样式文件

pnpm style

2. 构建库文件

pnpm build

3. 发布到私有 npm 仓库

npm publish --registry https://wanyan.co/npm
`

📚 API 文档

$3

| 属性 | 类型 | 默认值 | 描述 |
| ---------------- | ------------------------------------------------------- | ------------------- | -------------------------- |
| 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 | - | 文件上传处理函数 |
| onToast | (message: string, type: "success" \| "error") => void | - | 消息提示回调 |

$3

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

🎨 主题定制

$3

项目支持通过 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;
}
`

$3

`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);
}
`

🤝 贡献指南

$3

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

$3

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

$3

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

`bash


代码检查

pnpm lint

类型检查

pnpm type-check
``

📄 许可证

本项目基于 MIT 许可证开源。

🙏 致谢

- TipTap - 优秀的富文本编辑器框架
- Milkdown - 设计灵感来源
- Outline - 功能参考
- Notion - 交互体验参考
- @syfxlin/tiptap-starter-kit - 原始项目

👥 维护者

- zhengzhiyu - 项目维护者
- 基于 @syfxlin/tiptap-starter-kit 项目，感谢 Otstar Lin 的原始工作

---