vue-vben-admin 富文本编辑器组件 VbenTiptap 完整指南API、图片上传与自定义扩展【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin导读VbenTiptap是 vue-vben-admin 中基于 Tiptap 封装的富文本编辑器组件位于packages/effects/plugins/src/tiptap/提供开箱即用的文本格式化、标题/列表/引用等结构功能、链接与图片插入、文字颜色与背景高亮、对齐调整以及弹窗预览能力并内置了完整的图片上传选择、拖拽、粘贴三通道与进度反馈机制。阅读本文后你将掌握该组件的全部 Props/Events API、工具栏各功能对应的 Tiptap 命令链、图片上传的底层实现原理blob URL 占位与进度更新以及如何通过extensions属性接入自定义 Tiptap 扩展。框架提供的组件并非束缚。如果你觉得现有封装不够理想或不符合需求可以直接使用原生 Tiptap或亲手封装一个适合的组件使用与否完全取决于你的需求与自由。组件列表与快速上手VbenTiptap 由两个组件构成均可从vben/plugins/tiptap导入见 index.ts组件说明VbenTiptap富文本编辑器主组件含工具栏与编辑区VbenTiptapPreview富文本内容预览组件用于只读展示编辑器内容基于v-html渲染见 preview.vue基础用法只需通过v-model双向绑定一段 HTML 字符串script setup langts import { ref } from vue; import { VbenTiptap } from vben/plugins/tiptap; const content ref(pHello, VbenTiptap!/p); /script template VbenTiptap v-modelcontent / /template完整可运行的示例见文档 Demobasic 基础用法。主组件在内部通过defineModelstring接收modelValue编辑内容变化时以editor.getHTML()回写并同时派发包含 HTML / JSON / 纯文本三种形态的change事件见 tiptap.vue。API 详解VbenTiptap Props属性名说明类型默认值modelValue(v-model)编辑器内容HTML 字符串stringeditable是否可编辑booleantruetoolbar是否显示工具栏booleantruepreviewable是否显示预览按钮booleantrueplaceholder占位提示文本string$t(ui.tiptap.placeholder)多语言minHeight最小高度number \| string240maxHeight最大高度number \| string400extensions自定义 Tiptap 扩展配置Extensions-imageUpload图片上传配置ImageUploadOptions-参数类型定义与默认值均可在 types.ts 与 tiptap.vue 中找到对应实现。其中minHeight/maxHeight同时接受数字内部自动追加px或 CSS 字符串通过 CSS 变量--vben-tiptap-min-height、--vben-tiptap-max-height作用于编辑区tiptap.vue。editable变化时组件会调用editor.setEditable(editable)实时同步tiptap.vue因此工具栏按钮的禁用状态也会随editable联动见useTiptapToolbar中的canRunAction判断use-tiptap-toolbar.ts。Events事件名说明参数类型change内容变化时触发VbenTiptapChangeEventVbenTiptapChangeEvent在一次编辑操作中同时给出三种内容形态便于按需存储或导出interface VbenTiptapChangeEvent { html: string; // HTML 内容 json: JSONContent; // JSON 结构内容 text: string; // 纯文本内容 }源码中该事件在useEditor的onUpdate回调里派发html来自editor.getHTML()json来自editor.getJSON()text来自editor.getText()tiptap.vue。ImageUploadOptions图片上传配置项定义于 types.tsinterface ImageUploadOptions { /** 允许的文件类型默认 image/* */ accept?: string; /** 最大文件大小(字节)默认 5MB */ maxSize?: number; /** 上传失败回调未提供时使用 alert 弹窗提示 */ onUploadError?: (error: unknown) void; /** 上传函数返回图片 URL可选 onProgress 回调报告上传进度 */ upload: ( file: File, onProgress?: (percent: number) void, ) Promisestring; }VbenTiptapPreview Props属性名说明类型默认值content要预览的 HTML 内容stringminHeight最小高度number \| string160class自定义类名any-预览组件将内容通过v-html输出并复用.vben-tiptap-content样式类保证与编辑器内渲染效果一致preview.vue。工具栏功能全景工具栏由 toolbar.ts 中的createToolbarGroups()按功能分组声明组与组之间以分隔线区分。每个按钮对应一条 Tiptap 命令链并对可用性can与激活态active/isActive做了封装实际执行与样式切换逻辑统一由useTiptapToolbar提供use-tiptap-toolbar.ts。格式化撤销/重做-undo()/redo()仅在可执行时启用清除格式-clearNodes().unsetAllMarks()一键还原为纯段落粗体-toggleBold()斜体-toggleItalic()下划线-toggleUnderline()删除线-toggleStrike()行内代码-toggleCode()结构标题- 下拉菜单可切换「段落、H1-H4」按钮文本实时显示当前块级状态P/H1-H4见getHeadingTriggerText有序列表-toggleOrderedList()无序列表-toggleBulletList()引用块-toggleBlockquote()代码块-toggleCodeBlock()链接与图片插入链接- 弹出输入框填写 URL空值则移除链接URL 无协议前缀时自动补全为https://normalizeLinkUrltoolbar.ts移除链接-unsetLink()插入图片- 弹出输入框通过 URL 调用setImage()插入图片样式文字颜色- 预设色板editorColorPresets含前景色、warning/success/destructive 语义色及COLOR_PRESETS主题色支持一键清除颜色色板按钮下会显示当前文字颜色的指示条背景颜色- 高亮色板editorHighlightPresets基于语义色与主题色的半透明变体同样支持清除色板交互由VbenPopover弹出选中当前色时色块以对勾标记相关判断逻辑见getPaletteCurrentColoruse-tiptap-toolbar.ts。对齐左对齐-setTextAlign(left)居中对齐-setTextAlign(center)右对齐-setTextAlign(right)其他预览- 在弹窗中通过VbenTiptapPreview只读预览当前编辑内容tiptap.vue工具栏所有文案按钮 label、提示、弹窗内容均通过$t走多语言翻译键位于 packages/locales/src/langs/zh-CN/ui.json 的ui.tiptap下。图片上传三通道与进度反馈Demo 示例见 image-upload。当配置了imageUpload时工具栏的图片按钮会变为下拉菜单包含「本地上传」和「URL 插入」两个选项toolbar.ts。三种上传方式文件选择- 点击工具栏「本地上传」触发uploadImage命令内部动态创建input typefile并模拟点击拖拽上传- 直接拖拽图片到编辑器区域由imageUploadDropProseMirror 插件拦截并按鼠标落点计算插入位置粘贴上传- 粘贴图片到编辑器由imageUploadPaste插件拦截剪贴板中的图片文件拖拽与粘贴的拦截逻辑均以Plugin形式注入编辑器见 extensions.ts。上传进度显示上传过程中组件会先在光标处插入一个以 blob URL 为src的占位图片节点data-uploadingtrue并通过自定义 NodeView 渲染加载指示器- 旋转动画指示上传进行中.vben-tiptap-upload-spinner进度条- 当上传函数调用onProgress(percent)时占位节点属性data-upload-progress被实时更新进度条宽度随之变化.vben-tiptap-upload-progress-fill进度与状态样式见 style.css。上传成功后占位节点的src会被替换为上传函数返回的真实 URL并清除上传标记上传失败则会自动删除占位节点并触发错误处理。blob URL 会被blobUrlTracker追踪在组件卸载时统一URL.revokeObjectURL释放避免内存泄漏extensions.ts、tiptap.vue。文件校验accept- 指定允许的文件类型MIME 类型默认image/*支持*/*通配与image/*这类类型前缀匹配也支持逗号分隔的精确 MIME 列表maxSize- 最大文件大小限制字节默认 5MB常量DEFAULT_ACCEPT与validateFile见 extensions.ts校验失败会触发onUploadError回调未提供时内部使用alert(message, ...)弹窗提示错误信息支持多语言fileTooLarge、fileTypeNotAllowed等注意事项仅支持单张图片上传多图拖拽/粘贴时会提示并仅处理第一张上传中不要保存编辑器内容getHTML()因为此时图片 URL 为临时 blob URL尚未替换为真实地址自定义extensions时图片上传功能将不显示因为可能缺少uploadImage命令自定义扩展通过extensions属性可以传入自定义的 Tiptap 扩展配置script setup langts import { VbenTiptap } from vben/plugins/tiptap; import StarterKit from tiptap/starter-kit; import Underline from tiptap/extension-underline; const extensions [ StarterKit, Underline, // 其他扩展... ]; /script template VbenTiptap v-modelcontent :extensionsextensions / /template从源码看组件对extensions的处理非常明确useEditor中优先使用传入的extensions仅在未传入时才调用createDefaultTiptapExtensions组装默认扩展tiptap.vue同时只要传入了自定义extensions工具栏的图片上传选项也会被强制隐藏tiptap.vue。自定义扩展注意事项默认扩展配置将不会生效需自行配置所需的编辑器功能图片上传功能不可用工具栏不显示上传选项组件内置的类型声明已为tiptap/core注册uploadImage命令types.ts若你的自定义扩展未包含该命令直接调用会失败默认扩展配置参考若想了解组件开箱即用的能力边界可参考 extensions.ts 中的createDefaultTiptapExtensions它按以下策略组装扩展StarterKit- 标题仅启用 H1-H4并关闭内置link由下方独立Link扩展接管TextAlign- 对齐作用于标题与段落TextStyle Color- 文字颜色Highlight- 背景高亮multicolor: true支持任意颜色Link- 开启autolink默认协议https支持mailto:、tel:协议Image- 允许 base64图片类名为vben-tiptap__image配置imageUpload时替换为带上传能力的自定义 Image 扩展Placeholder- 空内容占位提示支持多语言默认扩展中 Image 相关样式最大宽度 640px、圆角、悬停效果等定义在 style.css 中预览组件共用同一套样式体系保证了「编辑所见」与「预览所得」的一致。【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考