# Mentionly

给 AI 输入框用的提及引擎：选中的对象能跟着文字一起编辑和保存

Source: https://works.im0o.top/projects/mentionly/
Date: 2026-02-11
Tags: 开发工具, 编辑器, 结构化引用, TypeScript, 组件开发

## Project links

- [源代码](https://github.com/jz0ojiang/mentionly)
- [Playground](https://im0o.top/mentionly/)


AI 聊天框里经常要引用一个文件、项目或者人。显示成 `@名字` 不难，麻烦的是后面：名字改了还能不能找到原对象，退格会不会删掉半个标签，发给后端时又该传什么。

Mentionly 是我为这类输入写的库。输入框里可以同时放普通文字和 mention，选中的对象作为一个整体编辑，提交时得到结构化的内容，而不只是拼好的字符串。

## 屏幕上的标签与提交的数据

输入一句“请检查 @Alice”，屏幕上看的是名字，程序需要的可能是用户 ID。Mentionly 把二者一起放进 mention：`label` 用来显示，`id` 和 `data` 留给业务使用。

```ts
[
  { type: 'text', text: '请检查 ' },
  {
    type: 'mention',
    trigger: '@',
    id: 'u1',
    label: 'Alice',
    data: { kind: 'user', userId: 'u1' }
  }
]
```

这是提交结果的一个例子。普通文字仍然能自由编辑，选中的 mention 则是原子实体，不能把名字删一半后还保留原来的对象身份。复制、粘贴、删除和恢复内容，都围绕这份分段数据处理。

触发符可以配置多组。`@` 用来找人或文件，`#`、`/` 可以对应其他对象和命令；选中候选项时，业务通过 `toData()` 固定它所需要的数据。

![显示的名字和提交的 ID 属于同一个 mention 对象](https://image.im0o.top/2026/20261117104323026.webp)

## 输入法和异步列表

真正使用时，候选项通常来自搜索接口。输入一个词，马上又改成另一个，前一次请求可能反而更晚返回。因此，查询要有防抖和过期结果处理，也要支持分页继续加载。

中文输入法的组合期同样需要单独处理。拼音还没确认时，不能把半成品当成正式查询，按回车选字也不应该直接提交消息。

候选列表的位置跟随光标，支持通过 portal 放到外层，避免被输入框祖先的 `overflow` 裁掉。键盘选项、焦点和无障碍关联也一起处理，接入方可以专心画列表样式。

![候选项跟随当前输入，迟到的旧查询结果不会覆盖新结果](https://image.im0o.top/2026/20261117104318374.webp "候选项跟随当前输入，迟到的旧查询结果不会覆盖新结果")

## 从 Vue 组件拆到多框架

1.x 主要是 Vue 3 的 `useMention` 和成品输入组件。后来其他界面也需要同样的输入方式，我把触发检测、DOM 编辑、序列化、键盘和输入法处理抽成了不依赖框架的 `@mentionly/core`。

2.0 在这个 core 上提供 Vue、React 和 Svelte 适配。Vue 仍然有可直接使用的 `MentionInput` 与 `MentionList`；React 和 Svelte 提供 headless 接口，输入框和列表由业务自己渲染。原来的 `mentionly` 包继续转发 Vue 版本，旧接入可以逐步迁移。

我也补了 AI SDK 和 MCP 的输出转换，以及随包发布的 `llms.txt`。Agent 帮忙接组件时，可以直接读到当前安装版本的规则，少踩“让框架重新渲染编辑器内部 DOM”这一类接入错误。

这个作品集的输入框也在使用 Mentionly 的 React 适配。

[在线演示](https://im0o.top/mentionly?lang=zh) · [源代码](https://github.com/jz0ojiang/mentionly)

