Mentions

输入并引用用户或对象。中文惯用名：提及。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.mentions`
名称	Mentions
二级分类	数据录入（`data-entry`）
用途	输入并引用用户或对象
描述	中文惯用名：提及。

预览

静态结构：Mentions 为相对定位容器包裹 shadcn Textarea（data-slot="mentions"）；输入 trigger 字符（缺省 @）且光标在其后无空白查询串时，下方弹出候选浮层（data-slot="mentions-popup"，绝对定位下拉列表），按查询串过滤候选的 label / value；↑/↓ 移动高亮、Enter 或点击选中后在光标处插入 `trigger + value + 空格` 并复位光标，Esc 或失焦关闭。onChange 传出完整字符串。Form 内声明 name 时外层包 FieldShell（label + 校验错误）。

DSL 结构

DslNode

{
  "type": "Mentions",
  "props": {
    "name": "comment",
    "trigger": "@",
    "rows": 3,
    "placeholder": "输入 @ 提及成员",
    "options": [
      {
        "label": "陈晨",
        "value": "chenchen"
      },
      {
        "label": "林晚",
        "value": "linwan"
      }
    ]
  }
}

何时用

何时使用

多行输入中引用用户或对象：评论 @ 人、任务指派、文档引用。
候选集合固定（同事列表、资源列表），输入触发字符即时过滤选择。

何时不用

纯文本多行输入无引用需求：使用 Textarea。
只需要从候选中选一个值而不需要内联文本：使用 Select / Combobox。
需要富文本样式（加粗、链接等）：Mentions 是纯文本 textarea，使用富文本组件。

变体

变体	视觉形态	适用场景
缺省 @ 提及	输入 @ 弹候选浮层，选中插入 @value + 空格	评论、消息中提及成员
trigger 自定义触发符	按自定义字符触发（如 # 引用话题）	对象引用、话题标签等场景
rows 多行高度	textarea 行数可调	长文本输入（评论正文、描述）
disabled 禁用	textarea 禁用	只读回显或流程未就绪

API 属性

属性	类型	默认值	说明
`name`	`string`	—	字段名；在 Form 内声明即自动成为表单项
`label`	`string`	—	表单项标签（FieldShell 呈现）
`rules`	`FieldRule[]`	—	校验规则
`options`	`MentionOption[]`	[]	候选列表（{ label, value }；按查询串过滤 label / value）
`trigger`	`string`	'@'	触发字符
`rows`	`number`	—	文本域行数
`placeholder`	`string`	—	空态提示文案
`value`	`string`	—	受控值（完整字符串）；Form 内作为字段初始值
`disabled`	`boolean`	false	禁用输入
`onChange`	`(value: string) => void`	—	输入变化事件，传出完整字符串（DSL 语义值）
`className`	`string`	—	根节点 class（Form 内为 form-item 容器，独立渲染时为控件包裹节点）
`style`	`CSSProperties`	—	根节点内联样式（同 className 的挂载规则）

使用规范

值始终是完整纯文本字符串；选中候选插入 trigger + value + 空格，value 即落库文本，解析提及由调用方按 trigger 规则提取。
候选 value 不应含空白：查询串含空白即视为提及结束，value 带空格会导致插入后无法回认。
options 的 label 用于展示与过滤，value 用于插入；二者语义分清（如 label 显示姓名、value 插入账号）。
候选为空时不弹浮层；保证 options 已加载再让用户输入，避免「输入 @ 无反应」。
键盘操作完整：↑/↓ 高亮、Enter 选中、Esc 关闭；不要额外劫持这些按键。

正例

✓ 评论输入：options 为团队成员（label 姓名 / value 账号），输入 @ 过滤，选中插入「@zhangsan 」。
✓ 话题引用：trigger 设为 #，输入 # 引用话题对象。
✓ Form 内声明 name + 必填 rules，评论为空时提交提示。

反例

✕ 用 Mentions 做单值选择（应使用 Select / Combobox，Mentions 产出的是整段文本）。
✕ 候选 value 含空格，插入后立即被视为提及结束，无法回认解析。
✕ 期望组件自动发通知给被 @ 的人（组件只产出文本，通知逻辑由调用方实现）。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。