核心是利用 tiptap 的 mention 插件实现。@人名 显示蓝色，普通文字显示黑色。
这个组件导出的是 HTML 格式的富文本，而不是纯文本。
<script lang="ts" setup>
import { autoPlacement, autoUpdate, offset, useFloating } from "@floating-ui/vue";
import Document from "@tiptap/extension-document";
import Mention from "@tiptap/extension-mention";
import Paragraph from "@tiptap/extension-paragraph";
import Text from "@tiptap/extension-text";
import type { SuggestionProps } from "@tiptap/suggestion";
import { EditorContent, useEditor, type JSONContent } from "@tiptap/vue-3";
import { useElementVisibility } from "@vueuse/core";
import { useDebounceFn } from "@vueuse/core";
import type { ScrollbarDirection } from "element-plus";
import { omit } from "es-toolkit/object";
import type { MaybePromise, Suggestion } from "./suggestion";
const props = defineProps<{
/** 获取建议列表的函数 */
fetchSuggestions: (query: string) => MaybePromise<Suggestion[]>;
}>();
/** 编辑器 HTML 内容的双向绑定 */
const modelValue = defineModel<string>();
const emit = defineEmits<{
infiniteScroll: [query: string | undefined, items: Suggestion[] | undefined];
updateMentions: [list: Suggestion[]];
}>();
/** 监听外部内容变化，同步到编辑器 */
watch(modelValue, (value) => {
if (value === editor.value?.getHTML()) return;
editor.value?.commands.setContent(value || "", { emitUpdate: false });
});
/** 当前 TipTap 建议对象，包含触发提及的位置等信息 */
const suggestion = reactive<Partial<SuggestionProps<Suggestion>>>({});
/**
* 计算提及触发的参考元素
* 用于定位建议弹窗
*/
const reference = computed(() => {
const { decorationNode } = suggestion;
if (!(decorationNode instanceof HTMLElement)) return;
return decorationNode;
});
/** 检测参考元素是否在视口中可见 */
const isMentionVisible = useElementVisibility(reference);
const floating = useTemplateRef("floating-element");
/**
* 计算是否应该显示建议弹窗
*/
const isShowPopper = computed(() => {
const { items } = suggestion;
return items?.length && reference.value && isMentionVisible.value;
});
/** 当前选中的建议索引 */
const selectedIndex = ref(0);
/**
* 更新选中的建议索引并滚动到对应元素
*
* @param index - 新的选中索引
*/
const changeSelectedIndex = (index: number) => {
selectedIndex.value = index;
const list = floating.value?.querySelectorAll(`[type="button"]`);
if (!list) return;
list[index]?.scrollIntoView({
block: "nearest",
behavior: "smooth",
});
};
const { floatingStyles } = useFloating(reference, floating, {
whileElementsMounted: autoUpdate,
middleware: [
offset(4),
autoPlacement({
allowedPlacements: ["bottom-start", "top-start", "bottom-end", "top-end"],
padding: 4,
}),
],
});
/**
* 设置自动更新并重置选中索引
*/
const startUpdatePosition = (value: SuggestionProps) => {
Object.assign(suggestion, omit(value, ["editor"]));
changeSelectedIndex(0);
};
const mentionExtension = Mention.configure({
deleteTriggerWithBackspace: true,
suggestion: {
allowedPrefixes: null,
/**
* 获取建议项列表
* @returns 建议项列表
*/
items: ({ query }) => {
return props.fetchSuggestions(query);
},
/**
* 自定义建议列表渲染器
* 处理建议列表的显示、隐藏和键盘导航
*/
render: () => {
return {
/** 开始显示建议时触发 */
onStart(props) {
startUpdatePosition(props);
},
/** 建议更新时触发 */
onUpdate(props) {
startUpdatePosition(props);
},
/** 键盘事件处理 */
onKeyDown({ event }) {
// ESC 键：关闭建议
if (event.key === "Escape") {
suggestion.items = undefined;
return true;
}
const items = suggestion.items || [];
const length = items.length;
const current = selectedIndex.value;
// 上箭头：选择上一项
if (event.key === "ArrowUp") {
changeSelectedIndex((current + length - 1) % length);
return true;
}
// 下箭头：选择下一项
if (event.key === "ArrowDown") {
changeSelectedIndex((current + 1) % length);
return true;
}
// 回车：选择当前项
if (event.key === "Enter") {
const item = items[current];
if (item) handleClickItem(item);
return true;
}
return false;
},
/** 退出建议状态时触发 */
onExit() {
suggestion.items = undefined;
},
};
},
},
});
/**
* 递归查找文档中的所有提及节点
*
* 该函数遍历 TipTap JSON 文档树，提取所有类型为 "mention" 的节点，
* 并将其 id 和 label 属性收集到结果数组中。支持单个节点或节点数组作为输入。
*
* @param doc - TipTap JSON 文档对象或节点数组，undefined 时函数直接返回
* @param result - 用于收集提及数据的结果数组，函数会将找到的提及节点追加到此数组
*
* @example
* ```typescript
* const mentions: Suggestion[] = [];
* const json = editor.getJSON();
* findMention(json, mentions);
* console.log(`找到 ${mentions.length} 个提及`);
* ```
*/
const findMention = (doc: JSONContent | JSONContent[] | undefined, result: Suggestion[]): void => {
if (!doc) return;
if (Array.isArray(doc)) {
doc.forEach((node) => findMention(node, result));
return;
}
const { type, content, attrs } = doc;
if (type === "mention") {
if (!attrs) return;
const { id, label } = attrs;
result.push({ id, label });
return;
}
if (content) {
content.forEach((node) => findMention(node, result));
return;
}
};
/**
* 创建 TipTap 编辑器实例
* 配置基础的文档结构、段落、文本和提及功能
*/
const editor = useEditor({
extensions: [Document, Paragraph, Text, mentionExtension],
content: modelValue.value || "",
onUpdate: useDebounceFn(() => {
if (!editor.value) return;
modelValue.value = editor.value.getHTML() || "";
// 提取所有提及节点并更新提及列表
const list: Suggestion[] = [];
findMention(editor.value.getJSON(), list);
emit("updateMentions", list);
}, 200),
});
/**
* 处理编辑器容器的点击事件
* 在编辑器未聚焦时点击容器将聚焦到编辑器末尾
*
* @param event - 鼠标点击事件
*/
const handleClickContainer = (event: MouseEvent) => {
if (editor.value?.isFocused) return;
const { target } = event;
if (!(target instanceof Element)) return;
if (target.closest(".tiptap")) return;
event.preventDefault();
editor.value?.commands.focus("end");
};
/**
* 处理建议项的点击事件
* 执行 TipTap 的提及命令来插入选中的建议项
*
* @param item - 被选中的建议项
*/
const handleClickItem = (item: Suggestion) => {
const { command } = suggestion;
if (command) command(item);
};
/**
* 处理无限滚动事件
* 当用户滚动到建议列表底部时加载更多建议
*/
const handleInfiniteScroll = (direction: ScrollbarDirection) => {
if (direction !== "bottom") return;
const { query, items } = suggestion;
emit("infiniteScroll", query, items);
};
</script>
<template>
<article :class="$style.mentionEditor" @click="handleClickContainer">
<EditorContent :editor="editor" />
<div
v-if="isShowPopper"
ref="floating-element"
:class="$style.mentionPopper"
:style="floatingStyles"
>
<ElScrollbar max-height="30vh" :distance="10" @end-reached="handleInfiniteScroll">
<div :class="$style.mentionList">
<button
v-for="(item, index) in suggestion?.items"
:key="index"
type="button"
:class="[$style.mentionItem, { [$style.isActive]: index === selectedIndex }]"
@click="handleClickItem(item)"
>
{{ item.label }}
</button>
</div>
</ElScrollbar>
</div>
</article>
</template>
<style module>
.mentionEditor {
border: 1px solid var(--el-border-color);
border-radius: 0.375rem;
padding: 0.5rem 0.75rem;
}
.mentionEditor :global(.tiptap:focus) {
outline: none;
}
.mentionEditor:focus-within {
border-color: var(--el-color-primary);
outline: none;
}
.mentionEditor :global(.tiptap) {
[data-type="mention"] {
color: var(--el-color-primary);
}
p {
margin: 0;
line-height: 1.5;
}
}
.mentionPopper {
position: fixed;
border-radius: 0.25rem;
background-color: white;
box-shadow: 0 0 0.5rem rgba(0, 0, 0, 0.1);
}
.mentionList {
display: flex;
flex-direction: column;
gap: 2px;
padding: 4px;
}
/* 建议项样式 */
.mentionItem {
border-radius: 0.25rem;
padding: 0.25rem 0.35rem;
transition: background-color 100ms;
border: none;
outline: none;
display: flex;
align-items: center;
min-width: 5rem;
cursor: pointer;
font-size: 0.85rem;
}
/* 建议项悬停状态 */
.mentionItem:hover {
background-color: rgb(243 244 246);
}
/* 建议项激活状态（键盘选中） */
.mentionItem.isActive {
background-color: rgb(55 65 81);
color: white;
}
</style>
一些工具类型。
/** 可能是 Promise 的类型 */
export type MaybePromise<T> = T | Promise<T>;
/**
* 提及选项数据结构
* 用于表示一个可被提及的用户或项目
*/
export interface Suggestion {
/** 唯一标识符 */
id: string;
/** 显示标签 */
label: string;
}
Element Plus 也有一个提及组件：Mention 提及 | Element Plus。但这个组件不是富文本。后期无法直接追踪文本中具体提及了哪些人，需要用正则匹配出人名。
