MarkdownEditor
所见即所得、源码与预览的 Markdown 编辑器
安装
pnpm add @talex-touch/tuffeximport { TxMarkdownEditor } from '@talex-touch/tuffex/markdown-editor'
import '@talex-touch/tuffex/markdown-editor/style.css'
// 编辑器内部渲染的组件,样式需单独引入
import '@talex-touch/tuffex/base-anchor/style.css'
import '@talex-touch/tuffex/base-surface/style.css'
import '@talex-touch/tuffex/card/style.css'
import '@talex-touch/tuffex/flow-light/style.css'
import '@talex-touch/tuffex/glass-surface/style.css'
import '@talex-touch/tuffex/icon/style.css'
import '@talex-touch/tuffex/spinner/style.css'
import '@talex-touch/tuffex/stream-text/style.css'
import 'katex/dist/katex.min.css' // 可选:公式按 KaTeX 排版,否则输出 MathML
import '@talex-touch/tuffex/base.css' // 设计令牌与重置样式,全应用引入一次
用法
基础
v-model 绑定 Markdown;传入 uploadImage、ai 与 v-model:comments 即开启图片上传、AI 改写和评论。
Loading demo...
自定义表情包
emojiPacks 把自己的表情图片加入选择器与 : 补全;文档里写的仍是 :name:,预览与所见即所得中显示为图片。
Loading demo...
多人协同
collaboration 接入实时协作:编辑器收发变更集与光标,并发编辑由适配器合并。
Loading demo...
最佳实践
- 用户或 provider 写的内容保持
sanitize=true;自定义表情的src用 https 或data:地址,sanitize开启时(默认如此)其他协议的地址会被消毒器去掉。 - 表情的
name(短代码)会写进文档,只增不改:改名后,旧文档里的:name:会变回文字;表情包的name只是标签页名字,可以随时改。emojiPacks要保持引用稳定,放进ref或const,不要在模板里写字面量数组。 - 模式或评论侧栏需要写入路由或 query 时,使用受控的
mode或v-model:comments-open;只想展开某个评论线程时调用openComments(id)。 uploadImage与ai响应signal:用户删除占位、停止或放弃时中止请求。- 宿主不扫描 tuffex 源码时,把
src/toolbar-icons.ts的MARKDOWN_EDITOR_ICON_CLASSES加入 UnoCSS safelist。
API 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | string | '' | Markdown 源文本,配合 v-model 使用。 |
placeholder | string | '' | 可编辑模式下的占位文本。 |
mode | 'wysiwyg' | 'source' | 'preview' | - | 受控模式。 |
defaultMode | 'wysiwyg' | 'source' | 'preview' | 'wysiwyg' | 非受控时的初始模式。 |
disabled | boolean | false | 禁用工具栏、模式切换与编辑区。 |
readonly | boolean | false | 禁止编辑,仍可阅读与切换模式。 |
sanitize | boolean | true | 用 DOMPurify 净化渲染的 HTML;只对可信内容关闭。 |
theme | 'auto' | 'light' | 'dark' | 'auto' | 主题;auto 跟随页面。 |
toolbar | boolean | true | 显示工具栏与模式切换。 |
toolbarActions | MarkdownEditorToolbarActionKey[] | 内置集合 | 工具栏按钮及顺序。 |
minHeight | string | number | 220 | 编辑区最小高度。 |
maxHeight | string | number | - | 编辑区最大高度。 |
ariaLabel | string | 'Markdown editor' | 两种编辑区共用的无障碍名称。 |
linkPrompt | (selectedText: string) => string | Promise<string> | - | 替换内置的链接输入框;返回 URL,返回 '' 取消。 |
math | boolean | true | 用 KaTeX 渲染 $…$ 与 $$…$$。 |
emoji | boolean | true | 渲染 :shortcode:,开启 : 补全与表情选择器。 |
emojiPacks | readonly TxEmojiPack[] | - | 自定义表情包:选择器里每个含合法表情的包一个标签页,:name: 渲染为图片。 |
highlight | boolean | true | ==文字== 高亮与高亮笔的颜色。 |
callouts | boolean | true | 首行为 [!NOTE]、[!TIP]、[!IMPORTANT]、[!WARNING]、[!CAUTION] 的引用显示为提示块。 |
codeTheme | MarkdownEditorCodeTheme | 'github' | 带语言的代码块的语法高亮预设;'none' 不着色。 |
slash | boolean | true | 所见即所得模式下,段首的 / 打开块菜单。 |
bubble | boolean | true | 所见即所得模式下,选中文字时浮出格式条。 |
ai | MarkdownEditorAi | - | 格式条上的 AI 改写;不传则不显示。 |
uploadImage | MarkdownEditorUploadImage | - | 上传粘贴、拖入或选择的图片,返回托管地址;不传时图片按钮改为填写地址。 |
comments | MarkdownEditorComment[] | - | 评论线程,配合 v-model:comments 使用;不传则隐藏评论。 |
commentsOpen | boolean | - | 评论侧栏是否打开,配合 v-model:comments-open 使用;不绑定时由编辑器自己维护。 |
user | MarkdownEditorUser | { id: 'local', name: labels.you } | 本地用户:评论作者,也是协作者看到的身份。 |
collaboration | MarkdownEditorCollaboration | - | 实时协作的传输。 |
statusBar | boolean | true | 底部的字数、字符数与协作者。 |
labels | Partial<MarkdownEditorLabels> | 英文文案 | 覆盖界面文案。 |
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
update:modelValue | (value: string) | 内容变化时触发。 |
change | (value: string) | 与 update:modelValue 同时触发。 |
update:mode | (mode: MarkdownEditorMode) | 切换模式时触发,配合 v-model:mode。 |
mode-change | (mode: MarkdownEditorMode) | 与 update:mode 同时触发。 |
focus | () | 编辑区获得焦点时触发。 |
blur | () | 编辑区失去焦点时触发。 |
update:comments | (comments: MarkdownEditorComment[]) | 线程变化或区间随编辑移动时触发,配合 v-model:comments。 |
update:commentsOpen | (open: boolean) | 评论侧栏打开或关闭时触发,配合 v-model:comments-open。 |
comment-create | (comment: MarkdownEditorComment) | 新建线程时触发。 |
comment-reply | (comment: MarkdownEditorComment, reply: MarkdownEditorCommentReply) | 回复线程时触发。 |
comment-resolve | (comment: MarkdownEditorComment) | 解决或重新打开线程时触发,以 resolved 区分。 |
comment-delete | (comment: MarkdownEditorComment) | 删除线程时触发。 |
upload-error | (error: unknown, file: File) | 图片上传失败时触发。 |
ai-error | (error: unknown) | AI 改写失败时触发。 |
暴露方法
| 方法 | 说明 |
|---|---|
focus() | 聚焦当前模式的编辑区。 |
blur() | 让当前编辑区失焦。 |
setMode(mode) | 切换模式。 |
getMode() | 返回当前模式。 |
openComments(id?) | 打开评论侧栏;传入线程 id 时选中该线程并滚动到它。 |
getValue() | 返回当前 Markdown。 |
setValue(value) | 以一次编辑替换全文:派发更新,并发送给协作者。 |
getSelection() | 返回选区,以 Markdown 源码偏移表示。 |
setSelection(selection) | 聚焦并设置选区。 |
insert(markdown) | 以用户编辑的方式把 Markdown 插入到选区。 |
类型
type MarkdownEditorMode = 'wysiwyg' | 'source' | 'preview'
type MarkdownEditorToolbarActionKey =
| 'heading' | 'bold' | 'italic' | 'strike' | 'code' | 'highlight' | 'quote'
| 'bulletList' | 'orderedList' | 'taskList' | 'link' | 'image' | 'table'
| 'codeBlock' | 'math' | 'divider' | 'emoji' | 'undo' | 'redo'
type MarkdownEditorCodeTheme = 'github' | 'one' | 'vitesse' | 'catppuccin' | 'solarized' | 'none'
// 自定义表情:name 只含小写字母、数字、_、+、-,2 到 40 个字符
interface TxCustomEmoji { name: string, src: string, keywords?: string }
interface TxEmojiPack { id: string, name: string, emoji: TxCustomEmoji[] }
interface MarkdownEditorAiRequest {
action: 'improve' | 'shorten' | 'expand' | 'fix' | 'translate' | 'custom'
instruction: string // custom 时为用户输入的要求
text: string // 选中的 Markdown,答案将替换它
before: string // 前后各至多 2,000 字符的上下文
after: string
signal: AbortSignal // 停止、重试或放弃时中止
}
type MarkdownEditorAi = (request: MarkdownEditorAiRequest) => string | Promise<string> | AsyncIterable<string>
type MarkdownEditorUploadImage = (
file: File,
context: { onProgress: (percent: number) => void, signal: AbortSignal },
) => Promise<string | { url: string, alt?: string, title?: string }>
interface MarkdownEditorUser { id: string, name: string, color?: string, avatar?: string }
interface MarkdownEditorComment {
id: string
from: number // 源码区间,随编辑移动
to: number
quote: string // 区间失配时按它重新定位
author: MarkdownEditorUser
body: string
createdAt: number
resolved?: boolean
replies?: MarkdownEditorCommentReply[]
}
// 一次替换;变更集中的偏移都相对变更前的文档
interface MarkdownTextChange { from: number, to: number, insert: string }
interface MarkdownEditorCollaboration {
send: (changes: MarkdownTextChange[]) => void
sendPresence?: (presence: { selection: MarkdownEditorSelection | null, mode: MarkdownEditorMode }) => void
subscribe: (handlers: {
onChanges: (changes: MarkdownTextChange[]) => void // 相对编辑器当前的文档
onPeers?: (peers: MarkdownEditorPeer[]) => void
}) => () => void
}
变更集
协作适配器用这些函数合并并发编辑,均从 @talex-touch/tuffex/markdown-editor 导出。
| 函数 | 说明 |
|---|---|
applyMarkdownChanges(doc, changes) | 把变更集应用到文本。 |
composeMarkdownChanges(a, b, docLength) | 把先后两个变更集合成一个。 |
mapMarkdownPosition(pos, changes, assoc?) | 位置经过变更集后的落点;assoc 决定插入点上的位置落在插入内容之前(-1)还是之后(1)。 |
transformMarkdownChanges(a, b, docLength) | 重排两个并发变更集,返回 [a', b'];同一处插入时 a 在前。 |
字数统计
状态栏用 @talex-touch/tuffex/markdown-editor 导出的 markdownStats 计数;在编辑器之外显示同样的数字时调用它。
| 函数 | 说明 |
|---|---|
markdownStats(markdown) | 返回 { words, characters }。Markdown 标记与链接地址不计入;汉字、假名与谚文每个字计一词;characters 不含空白。 |
概述
- 传入
mode为受控模式,否则由defaultMode初始化;三种模式共用同一份 Markdown。预览不能输入,格式按钮停用,任务列表的勾选框仍可点击切换。 - 所见即所得按块渲染;光标进入加粗、链接、行内公式等格式时露出 Markdown 标记,可直接编辑。段首输入
/(中文输入法下为、)打开块菜单。 - 输入
:打开补全,或点工具栏的表情按钮打开选择器;选择器的标签页依次为「最近」、各个含合法表情的表情包、内置分类。自定义表情的name只能是小写字母、数字、_、+、-,2 到 40 个字符,不合法的条目被忽略;与内置短代码同名时自定义表情生效。:name:在预览与所见即所得中显示为图片,源码模式显示文字。 - 选中文字浮出格式条:格式、高亮颜色、链接、评论与 AI。AI 的答案流式显示,可逐词查看改动,再替换、插入到下方、重试或放弃;
Esc放弃并恢复选区。 - 图片先以带进度的占位插入,上传完成后换成
uploadImage返回的地址,删除占位即中止上传。每次编辑都以变更集提交,撤销历史、评论区间与协作者的光标随之移动。 - 两种编辑模式共用快捷键:
Mod+B加粗、Mod+I斜体、Mod+E行内代码、Mod+Shift+X删除线、Mod+Shift+H高亮、Mod+K链接、Mod+Alt+1–6标题、Mod+Alt+M评论。模式切换是role="group"的切换按钮组;Esc关闭打开着的表情或高亮颜色菜单并认领这个按键,外层浮层因此保持打开。
技术实现
- 源码模式基于 CodeMirror 6;所见即所得是 contenteditable 的块视图,按 marked 的词法结果渲染,与源码逐字符映射。代码块用 CSS Custom Highlight API 着色,shiki、KaTeX 与 AI 面板都在首次用到时加载。
- 内置表情数据源自 emojilib 2.4.0(MIT)。
- 自定义表情包的类型
TxEmojiPack与图标选择器共用,定义在icon/src/emoji-pack.ts。 - 源码:
packages/tuffex/packages/components/src/markdown-editor/。
查看源码
packages/tuffex/packages/components/src/markdown-editor/index.ts