
AI 聊天框里经常要引用一个文件、项目或者人。显示成 @名字 不难,麻烦的是后面:名字改了还能不能找到原对象,退格会不会删掉半个标签,发给后端时又该传什么。
Mentionly 是我为这类输入写的库。输入框里可以同时放普通文字和 mention,选中的对象作为一个整体编辑,提交时得到结构化的内容,而不只是拼好的字符串。
屏幕上的标签与提交的数据
输入一句“请检查 @Alice”,屏幕上看的是名字,程序需要的可能是用户 ID。Mentionly 把二者一起放进 mention:label 用来显示,id 和 data 留给业务使用。
[
{ type: 'text', text: '请检查 ' },
{
type: 'mention',
trigger: '@',
id: 'u1',
label: 'Alice',
data: { kind: 'user', userId: 'u1' }
}
]这是提交结果的一个例子。普通文字仍然能自由编辑,选中的 mention 则是原子实体,不能把名字删一半后还保留原来的对象身份。复制、粘贴、删除和恢复内容,都围绕这份分段数据处理。
触发符可以配置多组。@ 用来找人或文件,#、/ 可以对应其他对象和命令;选中候选项时,业务通过 toData() 固定它所需要的数据。
输入法和异步列表
真正使用时,候选项通常来自搜索接口。输入一个词,马上又改成另一个,前一次请求可能反而更晚返回。因此,查询要有防抖和过期结果处理,也要支持分页继续加载。
中文输入法的组合期同样需要单独处理。拼音还没确认时,不能把半成品当成正式查询,按回车选字也不应该直接提交消息。
候选列表的位置跟随光标,支持通过 portal 放到外层,避免被输入框祖先的 overflow 裁掉。键盘选项、焦点和无障碍关联也一起处理,接入方可以专心画列表样式。
从 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 适配。

