快速开始

Tiptap Vue Pro 是基于 Tiptap v3 + Vue 3 的富文本编辑器组件。日常业务项目建议直接安装与你的 UI 库匹配的 Adapter;需要自绘 UI 时再使用 Core。

3 分钟跑起来

如果你的项目使用 Element Plus,先安装 adapter、Element Plus 和 Tiptap v3 运行时依赖:

pnpm add tiptap-vue-pro-element-plus element-plus
pnpm add @tiptap/core @tiptap/pm @tiptap/vue-3

然后在页面里导入组件和样式:

<script setup lang="ts">
import { ref } from 'vue'
import { ProEditorElementPlus } from 'tiptap-vue-pro-element-plus'
import 'tiptap-vue-pro-element-plus/style.css'
// 数学公式渲染样式(含 KaTeX 字体,按需加载;不需要公式可省略)
import 'tiptap-vue-pro-element-plus/katex.css'
import 'element-plus/dist/index.css'

const content = ref('<p>hello world</p>')
</script>

<template>
  <ProEditorElementPlus v-model="content" />
</template>

Naive UI 和 Ant Design Vue 的 API 保持对等,只需要换成对应 adapter、组件名和样式入口。

安装

Element Plus

pnpm add tiptap-vue-pro-element-plus element-plus
pnpm add @tiptap/core @tiptap/pm @tiptap/vue-3

Naive UI

pnpm add tiptap-vue-pro-naive naive-ui
pnpm add @tiptap/core @tiptap/pm @tiptap/vue-3

Ant Design Vue

pnpm add tiptap-vue-pro-ant-design-vue ant-design-vue
pnpm add @tiptap/core @tiptap/pm @tiptap/vue-3

关于 Tiptap 版本

Tiptap v3 官方包之间互相精确锁定版本(@tiptap/vue-3 要求 @tiptap/core 必须完全同版本)。推荐不要手动锁定 @tiptap/* 版本,按上面默认安装最新的全家桶即可,所有包会自动保持一致。

如果你的项目必须锁定旧版本(例如 3.27.1),请确保所有 @tiptap/* 包都锁同一版本,并在 package.json 中配合 overrides(npm)固定全家桶,否则 npm 解析时会出现 ERESOLVE 冲突或多副本运行时错误:

{
  "overrides": {
    "@tiptap/core": "3.27.1",
    "@tiptap/pm": "3.27.1",
    "@tiptap/vue-3": "3.27.1"
  }
}

最小示例

<script setup lang="ts">
import { ref } from 'vue'
import { ProEditorElementPlus } from 'tiptap-vue-pro-element-plus'
import 'tiptap-vue-pro-element-plus/style.css'
// 数学公式渲染样式(含 KaTeX 字体,按需加载;不需要公式可省略)
import 'tiptap-vue-pro-element-plus/katex.css'
import 'element-plus/dist/index.css'

const content = ref('<p>hello world</p>')
</script>

<template>
  <ProEditorElementPlus v-model="content" />
</template>

Naive UI 和 Ant Design Vue 的写法只需要替换组件名、样式文件和包名。完整示例见 完整示例。

样式入口

不同 adapter 的组件样式需要显式导入:

import 'tiptap-vue-pro-element-plus/style.css'
// 数学公式渲染样式(含 KaTeX 字体,按需加载;不需要公式可省略)
import 'tiptap-vue-pro-element-plus/katex.css'
import 'element-plus/dist/index.css'

import 'tiptap-vue-pro-naive/style.css'

import 'tiptap-vue-pro-ant-design-vue/style.css'
import 'ant-design-vue/dist/reset.css'

如果项目已经在全局导入了对应 UI 库样式,页面里只需要保留 Tiptap Vue Pro adapter 的 style.css。

Slash Command

开箱组件默认启用 Slash Command。把光标放在可编辑段落中,输入 / 会打开快捷插入菜单;可以继续输入中文、英文或拼音别名筛选命令,例如 /表、/table、/todo、/img、/code。

默认菜单包含标题、待办、无序列表、有序列表、表格、图片、分割线、代码块和 Mermaid 图表。Enter 执行当前项,Esc 关闭菜单并保留已经输入的 /query 文本。Slash Command 是编辑器交互能力,不会改变 Markdown 导入/导出的语义。

查找替换

开箱组件默认支持编辑器内查找替换。点击工具栏里的查找图标,或在光标位于编辑器内时按 Ctrl/⌘ + F,都可以打开面板;输入关键字后会高亮全部匹配,并显示当前命中序号和总数。面板支持上/下一个、大小写敏感、替换当前和替换全部。

只读或预览状态下仍可查找和跳转,但替换入口会隐藏。查找替换只作用于 ProseMirror 文档文本,不会搜索工具栏、弹窗等 UI 文案,也不会改变 Markdown 导入/导出的语义。

图片上传

传入 uploadImage 后,工具栏上传、粘贴图片和拖拽图片都会走同一个上传函数。函数返回图片 URL 后会自动插入编辑器。

<script setup lang="ts">
async function uploadImage(file: File): Promise<string | null> {
  const formData = new FormData()
  formData.append('file', file)
  const res = await fetch('/api/upload', { method: 'POST', body: formData })
  const { url } = await res.json()
  return url
}
</script>

<template>
  <ProEditorElementPlus v-model="content" :upload-image="uploadImage" />
</template>

跑不起来先看这里

• 样式没生效:确认已经导入 adapter 的 style.css 和对应 UI 库样式。
• 依赖冲突:确认 @tiptap/* 版本保持一致,不要只单独锁其中一个包。
• Nuxt / SSR:用 <ClientOnly> 包裹编辑器组件,详见 Nuxt / SSR。
• 上传没反应:确认传入了 uploadImage 或 uploadAsset,并且上传函数返回可访问 URL。
• 工具栏按钮缺失:检查是否传入了自定义 toolbar,自定义配置会决定实际显示哪些按钮。

本地开发

pnpm install
pnpm dev
pnpm docs:dev
pnpm test
pnpm typecheck
pnpm build
pnpm test:slash:e2e
pnpm test:find-replace:e2e