跳到正文

Mention 提及

Mention 是一个在前缀(如 @)之后给出候选项的输入框(或多行文本框)。在开头或空格后输入前缀,会在它下方打开菜单;前缀到光标之间的文字用来过滤选项,选中后插入 前缀 + value + 分隔符。它基于 Input,选项列表和 Select 共用。焦点始终留在输入框上,通过 aria-activedescendant 驱动列表:单行输入框是 WAI-ARIA 组合框模式里的 combobox;多行文本框按 HTML 规范不能设 combobox 角色,保持为多行文本框。

演示

基础用法

输入 @ 会在 @ 处打开菜单。单词中间的前缀(比如邮箱地址)不会打开。输入分隔符(默认是空格)、把光标移出这个提及、按 Escape 或离开输入框都会关闭菜单。禁用项会被跳过。

多行文本

type="textarea" 使用多行文本框,autosize 和 rows 与 Input 相同。菜单在前缀所在的那一行下方打开,文本框滚动后也一样。换行会结束提及。

多个前缀

prefix 可以是数组。onSearch 和 onSelect 会告诉你输入的是哪个前缀,可以按前缀给出不同的选项。

异步搜索

正在输入的提及变化时会调用 onSearch(pattern, prefix),在这里请求选项。loading 时菜单显示加载指示。

键盘

菜单打开时:↑ / ↓ 移动当前项(跳过禁用项,首尾循环);Enter 或 Tab 插入当前项;Escape 关闭菜单,再输入文字会重新打开。其他按键照常编辑文字。只有在有可插入的选项时才会占用 Enter 和 Tab;Mention 先于你的 onKeyDown 处理按键,可以在里面检查 event.defaultPrevented(比如按 Enter 发送消息之前)。

Props

名称类型默认值说明版本
optionsMentionMixedOption[]必填选项 { label, value, disabled? },可以分组 { type: "group", label, key, children }。插入的是 value。未发布
valuestring | nullundefined受控的文字。未发布
defaultValuestring""非受控时的初始文字。未发布
onUpdateValue(value: string) => voidundefined每次编辑和选中后以新文字调用。未发布
prefixstring | string[]"@"开始提及的前缀。未发布
separatorstring" "选中后插在后面;输入它会结束提及。未发布
typetext | textareatext单行输入框或多行文本框。未发布
autosize / rows多行文本框的尺寸,同 Input。未发布
filter(pattern, option) => booleanlabel 或 value 包含选项是否匹配输入的文字(默认不区分大小写)。未发布
onSearch(pattern: string, prefix: string) => voidundefined正在输入的提及变化时调用。未发布
onSelect(option, prefix: string) => voidundefined插入选项后调用。未发布
renderLabel(option) => ReactNodeundefined自定义菜单中的标签。未发布
loadingbooleanfalse菜单显示加载指示而不是选项。未发布
emptyReactNode语言包 “暂无数据”没有匹配的选项时显示。未发布
placeholderstringundefined为空时显示。未发布
sizetiny | small | medium | largemedium高度和字号。未发布
statussuccess | warning | errorundefined边框颜色。未发布
disabledbooleanfalse不可编辑。未发布
placementPopoverPlacementbottom-start菜单相对前缀的位置。未发布
to / zIndex同 Popover。未发布
onFocus / onBlur(event) => voidundefined焦点进入 / 离开输入框。未发布

其他 Input 的 props 会透传:className、style 和 wrapperRef 给带边框的外框;ref、id、aria-*、onKeyDown 等原生属性给 input 或 textarea。Mention 的 prefix 和 loading 取代了 Input 的前缀内容和加载指示。