Mention 提及
用于在输入框或文本域中通过触发符号（@、# 等）快速选择并插入提及内容，广泛应用于评论、私信、任务协作等场景。
基础用法
使用 v-model 绑定值，options 配置候选列表。在输入框内输入 @ 即可触发选项面板。
当前值：
头像选项
为 options 中的每个选项添加 avatar 字段，即可在下拉面板中展示头像，配合 description 展示描述信息。
分组选项
设置 group 字段即可将选项按组归类展示，相同 group 值的选项自动合并到同一分组。
多触发符
通过 triggers 指定多个触发字符，如同时支持 @ 提人和 # 打标签。配合 search 事件动态切换选项源。
当前值：
异步加载
监听 search 事件发起网络请求，通过 :loading="true" 显示加载状态，数据返回后更新 options。
文本域模式
设置 type="textarea" 即可在多行文本域中使用提及功能，支持所有提及特性。
自定义过滤
通过 filter-option 属性自定义过滤逻辑，例如支持拼音搜索。设为 false 则禁用过滤显示全部选项。
自定义选项渲染
通过 #option 插槽自定义选项显示内容，插槽参数包含 option 和 keyword。
字数统计
配合 maxlength 和 show-word-limit 属性，实时显示当前输入字数。
禁用状态
设置 disabled 属性禁用组件，禁用状态下既不能输入也不会触发选项面板。
在 Nuxt 中使用
Mention 组件完全兼容 Nuxt 3/4，已在 SSR 环境中经过验证。初始值（modelValue）会在服务端直接渲染为静态文本，触发选项面板等交互在客户端激活后生效。
SSR 注意事项：
- ✅
modelValue绑定的初始文本在服务端正确渲染 - ✅ 禁用、只读状态在服务端即生效
- ✅ 多尺寸、自定义 class 在服务端渲染正常
- ⚠️ 下拉面板、触发选项等交互在客户端 Hydration 后生效
- 💡 配合 Nuxt 的
<ClientOnly>可按需将交互部分降级为纯客户端渲染
SSR 性能建议
在 SSR 场景下，Mention 的初始渲染只包含输入框本身，下拉面板不会被服务端渲染（v-show="false"），因此对首屏性能影响极小。
API
Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | string | '' |
| options | 候选选项列表 | MentionOption[] | [] |
| triggers | 触发字符（可多个） | string[] | ['@'] |
| type | 输入框类型 | 'input' | 'textarea' | 'input' |
| placement | 下拉框弹出方向 | 'top' | 'bottom' | 'bottom' |
| placeholder | 占位文本 | string | — |
| disabled | 是否禁用 | boolean | false |
| readonly | 是否只读 | boolean | false |
| size | 尺寸 | 'large' | 'default' | 'small' | 'default' |
| maxlength | 最大输入长度 | number | — |
| clearable | 是否可清空 | boolean | false |
| show-word-limit | 是否显示字数统计 | boolean | false |
| prefix-icon | 前缀图标 | Component | — |
| suffix-icon | 后缀图标 | Component | — |
| filter-option | 自定义过滤函数，设为 false 禁用过滤 | ((keyword, option) => boolean) | false | — |
| loading | 是否显示加载状态 | boolean | false |
| loading-text | 加载中文字 | string | '加载中...' |
| no-data-text | 无数据文字 | string | '暂无数据' |
| teleported | 是否挂载到 body | boolean | true |
| popper-class | 下拉框自定义 class | string | '' |
| split | 选中后追加的分隔符 | string | ' ' |
| whole-word | 是否以完整词写入 | boolean | false |
| autofocus | 是否自动聚焦 | boolean | false |
| rows | 文本域行数（textarea 有效） | number | 3 |
| debounce | 防抖延迟（ms） | number | 100 |
| validate-event | 是否触发表单校验 | boolean | true |
| theme-overrides | 主题覆盖变量 | ComponentThemeVars | — |
MentionOption
| 字段 | 说明 | 类型 |
|---|---|---|
| value | 唯一标识（必填） | string |
| label | 显示标签 | string |
| disabled | 是否禁用 | boolean |
| avatar | 头像 URL | string |
| description | 描述信息 | string |
| group | 分组名称 | string |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| update:modelValue | 值变化时触发 | (value: string) => void |
| input | 输入时触发 | (value: string) => void |
| change | 失焦时触发 | (value: string) => void |
| focus | 聚焦时触发 | (event: FocusEvent) => void |
| blur | 失焦时触发 | (event: FocusEvent) => void |
| clear | 清空时触发 | () => void |
| search | 触发搜索时触发 | (keyword: string, trigger: string) => void |
| select | 选中选项时触发 | (option: MentionOption, trigger: string) => void |
| open | 下拉框打开时触发 | () => void |
| close | 下拉框关闭时触发 | () => void |
| keydown | 键盘按下时触发 | (event: KeyboardEvent) => void |
Slots
| 插槽名 | 说明 | 作用域参数 |
|---|---|---|
| option | 自定义选项渲染 | { option: MentionOption, keyword: string } |
| empty | 自定义无数据内容 | — |
| loading | 自定义加载内容 | — |
| prefix | 自定义前缀内容 | — |
| suffix | 自定义后缀内容 | — |
Expose
| 属性/方法 | 说明 | 类型 |
|---|---|---|
| ref | 输入框 DOM 元素 | HTMLInputElement | HTMLTextAreaElement |
| wrapperRef | 包裹元素 DOM | HTMLElement |
| focus | 获取焦点 | () => void |
| blur | 失去焦点 | () => void |
| clear | 清空内容 | () => void |
| insertMention | 编程式插入提及 | (option: MentionOption, trigger?: string) => void |
键盘操作
| 按键 | 说明 |
|---|---|
↑ / ↓ | 上下切换高亮选项 |
Enter | 选中当前高亮项 |
Tab | 选中当前高亮项（无高亮则关闭） |
Escape | 关闭下拉面板 |
主题变量
| 变量名 | 说明 | 默认值 |
|---|---|---|
--yh-mention-font-size | 字体大小 | var(--yh-font-size-base) |
--yh-mention-bg-color | 背景颜色 | var(--yh-fill-color-blank) |
--yh-mention-border-color | 边框颜色 | var(--yh-border-color) |
--yh-mention-border-radius | 圆角 | var(--yh-border-radius-base) |
--yh-mention-height-default | 默认高度 | var(--yh-component-size-default) |
--yh-mention-dropdown-shadow | 下拉阴影 | var(--yh-box-shadow-light) |