在 Vue 中实现输入框@人功能

核心是利用 tiptap 的 mention 插件实现。@人名 显示蓝色，普通文字显示黑色。

这个组件导出的是 HTML 格式的富文本，而不是纯文本。

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>

一些工具类型。

typescript 复制代码

/** 可能是 Promise 的类型 */
export type MaybePromise<T> = T | Promise<T>;

/**
 * 提及选项数据结构
 * 用于表示一个可被提及的用户或项目
 */
export interface Suggestion {
  /** 唯一标识符 */
  id: string;
  /** 显示标签 */
  label: string;
}

Element Plus 也有一个提及组件：Mention 提及 | Element Plus。但这个组件不是富文本。后期无法直接追踪文本中具体提及了哪些人，需要用正则匹配出人名。