@zhiyu/editor

v0.6.2

Published

a month ago

The non-official starter kit of the Tiptap editor contains common extensions.

0High
0Medium
0Low

zhiyu

tiptap tiptap-extension

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

依赖架构

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

🎨 交互式菜单

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

📁 文件处理

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

🎭 丰富内容块

媒体内容: 图片、音频、视频播放器
图表支持: 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.

Marks

Nodes

Extensions

🚀 快速开始

安装

# 使用 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 组件 (推荐)

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 扩展

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 属性发生变化时，只更新发生变化的部分，而不是替换整个文档内容。这在协作编辑、自动保存等场景中特别有用。

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

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

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

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

AI 功能配置

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

文件上传配置

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}
  // 其他配置...
/>;

🛠️ 开发指南

本地开发

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

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

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

构建项目

# 构建样式文件
pnpm style

# 构建库文件
pnpm build

# 监听模式构建
pnpm watch

项目脚本

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

🔧 技术实现

核心架构设计

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

组件层 (src/components/)
- TipTapEditor.tsx - 主编辑器 React 组件
- 提供统一的编辑器接口和配置选项
- 支持 TypeScript 类型定义
扩展层 (src/extensions/)
- starter-kit/ - 扩展集合和配置管理
- ai/ - AI 助手功能实现
- markdown/ - Markdown 解析和渲染
- *-menu/ - 各种交互菜单实现
- uploader/ - 文件上传处理
节点层 (src/nodes/)
- 各种内容节点的实现
- 支持媒体、图表、数学公式等复杂内容
标记层 (src/marks/)
- 文本格式化标记的实现
- 支持粗体、斜体、高亮等格式

关键技术特性

1. 模块化扩展系统

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

2. 类型安全的 API

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 预处理器，支持主题定制

发布流程

# 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 变量进行主题定制：

: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;
}

自定义样式

.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+

贡献流程

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

代码规范

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

# 代码检查
pnpm lint

# 类型检查
pnpm type-check

📄 许可证

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

🙏 致谢

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

👥 维护者

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