开发预览更新于 2026-05-10

Mention 提及输入

多行文本输入器，输入触发字符（默认 @）弹出候选下拉，键盘 ↑↓ 选择、Enter / Tab 确认。

基础用法

CfMention 在 <textarea> 上叠加触发字符识别。当光标前出现 @ 且后面跟着可选的搜索文本（无空格）时，下拉菜单出现，按当前文本对 options 做大小写不敏感的子串过滤。

候选项命中后，光标位置插入 @<value> —— 替换的是从触发字符到当前光标这一段，不会动后续文本。

背景

<script setup lang="ts">
import { ref } from 'vue';
import { CfMention } from '@chufix-design/vue';

const text = ref('在评论里输入 @ 试试');
const options = [
  { value: 'alice', label: 'Alice 张', description: '前端 · 设计系统' },
  { value: 'bob', label: 'Bob 李', description: '后端 · API 网关' },
  { value: 'carol', label: 'Carol 刘', description: '产品' },
  { value: 'david', label: 'David 王', description: 'QA' },
  { value: 'eve', label: 'Eve 周', description: '运维', disabled: true },
];
</script>

<template>
  <CfMention
    v-model="text"
    :options="options"
    placeholder="输入 @ 触发提及"
  />
</template>

import { useState } from 'react';
import { CfMention } from '@chufix-design/react';

export default function Demo() {
const [text, setText] = useState('');
const options = [
  { value: 'alice', label: 'Alice 张', description: '前端 · 设计系统' },
  { value: 'bob', label: 'Bob 李', description: '后端 · API 网关' },
  // ...
];
return <CfMention value={text} onChange={setText} options={options} />;
}

自定义触发字符

trigger 可改成任意单字符。比如做标签选择就传 #，做命令面板就传 /。下拉菜单的位置和键盘行为完全一致。

背景

<script setup lang="ts">
import { ref } from 'vue';
import { CfMention } from '@chufix-design/vue';

const text = ref('在评论里输入 # 试试');
const tags = [
  { value: 'bug', label: '#bug', description: '缺陷类问题' },
  { value: 'feature', label: '#feature', description: '新功能' },
  { value: 'question', label: '#question', description: '提问 / 讨论' },
  { value: 'docs', label: '#docs', description: '文档变更' },
];
</script>

<template>
  <CfMention
    v-model="text"
    trigger="#"
    :options="tags"
    placeholder="输入 # 选择标签"
  />
</template>

<CfMention
value={text}
onChange={setText}
trigger="#"
options={tags}
placeholder="输入 # 选择标签"
/>

只读 / 禁用

readonly 保留显示但 textarea 不可输入；disabled 灰显且不可聚焦。两种模式下都不会再弹候选下拉。

背景

readonly

@alice 这条只读的评论给你看一眼。

disabled

<script setup lang="ts">
import { CfMention } from '@chufix-design/vue';

const sample = '@alice 这条只读的评论给你看一眼。';
const options = [
  { value: 'alice', label: 'Alice 张' },
  { value: 'bob', label: 'Bob 李' },
];
</script>

<template>
  <div style="display:flex; flex-direction:column; gap: 12px;">
    <div>
      <div style="font-size: 12px; color: var(--fg-3); margin-bottom: 4px;">readonly</div>
      <CfMention :model-value="sample" :options="options" readonly :rows="2" />
    </div>
    <div>
      <div style="font-size: 12px; color: var(--fg-3); margin-bottom: 4px;">disabled</div>
      <CfMention :model-value="sample" :options="options" disabled :rows="2" />
    </div>
  </div>
</template>

<CfMention value={sample} options={options} readonly />
<CfMention value={sample} options={options} disabled />

键盘交互

下拉菜单展开时支持下面这些键位：

按键	行为
`↑` / `↓`	在候选项之间移动高亮
`Enter` / `Tab`	选中当前高亮项
`Esc`	关闭下拉但不插入
普通字符	实时过滤候选
空格	自动关闭下拉（视为提及结束）

disabled 项不会被键盘选中，鼠标点击也会被忽略。

API

属性	类型	默认值	说明
`modelValue` (Vue) / `value` (React)	`string`	`''`	文本内容
`defaultValue`	`string`	`''`	非受控初值
`options`	`MentionOption[]`	`—`	`{ value, label?, description?, disabled? }`
`trigger`	`string`	`'@'`	触发字符（单字符）
`rows`	`number`	`4`	textarea 行数
`placeholder`	`string`	`'输入 @ 触发提及'`	textarea 占位
`disabled` / `readonly`	`boolean`	`false`	整体禁用 / 只读
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	字号
`className`	`string`	`—`	透传到根容器

事件：

onChange(value) / update:modelValue — 文本任意变化
onSelect(option) / select — 选中候选项时触发

类型导出：

interface MentionOption {
  value: string;
  label?: string;
  description?: string;
  disabled?: boolean;
}