Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Mentions 提及
在多行文本里输入 @ 等前缀时弹出候选列表,选中后把提及内容插入到光标处。用于评论、消息里提及用户或话题。
引入
import { NsMentions } from '@ns/ui'
基础用法
用 v-model 绑定文本,用 options 传候选项。输入 @ 后弹出列表,用上下键选择,回车或 Tab 选中,Esc 关闭,也可以用鼠标点选。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('')
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
</script>
<template>
<NsMentions v-model="value" :options="users" placeholder="输入 @ 提及用户" />
</template>
选中“张三”后插入的是 @zhangsan :前缀 + 选项的 value + 分隔符。
自定义前缀
prefix 改触发前缀,默认是 @。前缀前面必须是空白或者在开头,下面输入 # 提及话题:
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('')
const topics: MentionsOption[] = [
{ value: '新功能', label: '新功能' },
{ value: '问题反馈', label: '问题反馈' },
{ value: '周报', label: '周报' }
]
</script>
<template>
<NsMentions v-model="value" :options="topics" prefix="#" placeholder="输入 # 提及话题" />
</template>
多个前缀
prefix 传数组时,每个前缀都能触发。用 search 或 select 事件的第二个参数区分是哪个前缀。下面输入 @ 提及用户,输入 # 提及小组:
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('')
const prefix = ref('@')
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
const teams: MentionsOption[] = [
{ value: '前端组', label: '前端组' },
{ value: '测试组', label: '测试组' }
]
const onSearch = (_query: string, p: string) => {
prefix.value = p
}
</script>
<template>
<NsMentions
v-model="value"
:options="prefix === '#' ? teams : users"
:prefix="['@', '#']"
placeholder="输入 @ 提及用户,输入 # 提及小组"
@search="onSearch"
/>
</template>
过滤
默认按输入的文字过滤选项(只匹配 label,不区分大小写)。filterable 设为 false 时始终显示全部选项,适合在 search 事件里自己请求接口:
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('')
const options = ref<MentionsOption[]>([])
// 用 setTimeout 模拟接口,按姓名或拼音查用户
const allUsers: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' },
{ value: 'wangwu', label: '王五' }
]
const searchUsers = (query: string) =>
new Promise<MentionsOption[]>((resolve) => {
setTimeout(() => {
resolve(
allUsers.filter(
(user) => user.label.includes(query) || String(user.value).includes(query)
)
)
}, 300)
})
const handleSearch = async (query: string) => {
options.value = await searchUsers(query)
}
</script>
<template>
<NsMentions
v-model="value"
:options="options"
:filterable="false"
placeholder="输入 @ 后再输入 zhang 或 wang"
@search="handleSearch"
/>
</template>
左边是默认的 filterable,输入 @张 只剩张三;右边 :filterable="false",输入什么都显示全部选项:
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions, NsSpace } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('')
const other = ref('')
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' },
{ value: 'wangwu', label: '王五' }
]
</script>
<template>
<NsSpace wrap>
<NsMentions v-model="value" :options="users" placeholder="过滤(true)" style="width: 240px" />
<NsMentions
v-model="other"
:options="users"
:filterable="false"
placeholder="不过滤(false)"
style="width: 240px"
/>
</NsSpace>
</template>
禁用的选项
选项设 disabled: true 后不出现在下拉列表里(直接隐藏,不显示成灰色)。没有可选的选项时显示“暂无匹配选项”。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('')
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四(已离职)', disabled: true },
{ value: 'wangwu', label: '王五' }
]
</script>
<template>
<NsMentions v-model="value" :options="users" placeholder="输入 @,列表里没有李四" />
</template>
分隔符
选中后会在提及后面追加 split(默认一个空格)。光标后面本来就是分隔符时不再重复追加,光标落在分隔符之后。输入分隔符也会结束当前提及,下拉层随之关闭。
左边是默认的空格,右边是逗号,分别选一个人看插入的内容:
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions, NsSpace } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('')
const comma = ref('')
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
</script>
<template>
<NsSpace wrap>
<NsMentions
v-model="value"
:options="users"
placeholder="split 默认空格"
style="width: 240px"
/>
<NsMentions
v-model="comma"
:options="users"
split=","
placeholder="split 是逗号"
style="width: 240px"
/>
</NsSpace>
<p style="margin-top: 12px">
左边:{{ JSON.stringify(value) }};右边:{{ JSON.stringify(comma) }}
</p>
</template>
行数和自适应高度
rows 指定行数,默认 1 行,可以纵向拖动调整高度。autosize 为 true 时高度跟着内容变化;传 { minRows, maxRows } 可以限制行数范围,内容超过 maxRows 后在框里滚动。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions, NsSpace } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const rows = ref('')
const auto = ref('')
const limited = ref('')
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsMentions v-model="rows" :options="users" :rows="3" placeholder="固定 3 行(rows)" />
<NsMentions v-model="auto" :options="users" autosize placeholder="随内容增高(autosize)" />
<NsMentions
v-model="limited"
:options="users"
:autosize="{ minRows: 2, maxRows: 5 }"
placeholder="2 到 5 行(autosize: { minRows: 2, maxRows: 5 })"
/>
</NsSpace>
</template>
最大长度
maxlength 限制最多能输入几个字。选中选项插入的内容不受它限制。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('')
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
</script>
<template>
<NsMentions v-model="value" :options="users" :maxlength="20" placeholder="最多输入 20 个字" />
<p style="margin-top: 12px">已输入 {{ value.length }} / 20</p>
</template>
弹出位置
placement 是下拉层的位置,默认 bottom-start,共 6 个:top-start、top、top-end、bottom-start、bottom、bottom-end。下拉层对齐的是整个输入框,放不下时自动翻到另一侧。在下面的输入框里输入 @ 看效果:
<script setup lang="ts">
import { reactive } from 'vue'
import { NsMentions, NsSpace } from '@ns/ui'
import type { MentionsOption, MentionsPlacement } from '@ns/ui'
const values = reactive<Record<string, string>>({})
const tops: MentionsPlacement[] = ['top-start', 'top', 'top-end']
const bottoms: MentionsPlacement[] = ['bottom-start', 'bottom', 'bottom-end']
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace v-for="row in [tops, bottoms]" :key="row[0]" wrap>
<NsMentions
v-for="item in row"
:key="item"
v-model="values[item]"
:options="users"
:placement="item"
:placeholder="`输入 @(${item})`"
style="width: 240px"
/>
</NsSpace>
</NsSpace>
</template>
禁用和只读
disabled 禁用后不能编辑;readonly 只读时可以选中、复制文字,但不能修改,光标放进已有的提及里也不会弹出候选列表。在禁用的 NsForm 里也会被禁用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions, NsSpace } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('@zhangsan 请帮忙看一下这个问题')
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsMentions v-model="value" :options="users" disabled />
<NsMentions v-model="value" :options="users" readonly />
</NsSpace>
</template>
尺寸
size 可选 large、default、small,单行时高度分别是 40、32、24px(多行时每行加 24、21、18px),字号 16、14、12px,圆角 8、6、4px,左右内边距 16、12、8px,和同尺寸的 NsInput 一致,文本框部分和同尺寸的 NsTextarea 一样。下拉层的选项跟着变:行高 40、36、28px,字号 16、14、12px,左右内边距 16、12、8px。放在 NsForm 里且没传 size 时,跟随表单项或表单的尺寸。
每一行是一种尺寸,依次是单行的提及、同尺寸的输入框和按钮:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInput, NsMentions, NsSpace } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('')
const text = ref('')
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsMentions
v-model="value"
:options="users"
size="large"
placeholder="输入 @"
style="width: 240px"
/>
<NsInput v-model="text" size="large" placeholder="输入框" style="width: 160px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsMentions v-model="value" :options="users" placeholder="输入 @" style="width: 240px" />
<NsInput v-model="text" placeholder="输入框" style="width: 160px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsMentions
v-model="value"
:options="users"
size="small"
placeholder="输入 @"
style="width: 240px"
/>
<NsInput v-model="text" size="small" placeholder="输入框" style="width: 160px" />
<NsButton size="small">按钮</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
事件
输入 @ 打开候选列表、继续输入查询词时触发 search;选中选项时触发 select,第二个参数是前缀;change 是原生的,文本框失焦且内容有变化时触发;获得、失去焦点时触发 focus、blur。最近的事件显示在下方:
<script setup lang="ts">
import { ref } from 'vue'
import { NsMentions, NsSpace } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const value = ref('')
const logs = ref<string[]>([])
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onSearch = (query: string, prefix: string) => log(`search:“${query}”,前缀 ${prefix}`)
const onSelect = (option: MentionsOption, prefix: string) =>
log(`select:${option.label},前缀 ${prefix}`)
const onChange = (val: string) => log(`change:${val}`)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsMentions
v-model="value"
:options="users"
:prefix="['@', '#']"
placeholder="输入 @ 或 #"
@search="onSearch"
@select="onSelect"
@change="onChange"
@focus="log('focus')"
@blur="log('blur')"
/>
<div class="logs">
<div v-if="logs.length === 0">还没有触发事件</div>
<div v-for="(item, index) in logs" :key="index">{{ item }}</div>
</div>
</NsSpace>
</template>
<style scoped>
.logs {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
调用方法
通过 ref 调用 focus()、blur();textareaRef 是内部的 <textarea> 元素,可以直接调用它的原生方法,例如 select() 选中全部文字。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsMentions, NsSpace } from '@ns/ui'
import type { MentionsOption } from '@ns/ui'
const mentionsRef = ref<InstanceType<typeof NsMentions>>()
const value = ref('@zhangsan 请帮忙看一下')
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsMentions ref="mentionsRef" v-model="value" :options="users" />
<NsSpace wrap>
<NsButton @click="mentionsRef?.focus()">聚焦(focus)</NsButton>
<NsButton @click="mentionsRef?.blur()">失焦(blur)</NsButton>
<NsButton @click="mentionsRef?.textareaRef?.select()"
>选中文字(textareaRef.select)</NsButton
>
</NsSpace>
</NsSpace>
</template>
在表单里使用
放在 NsFormItem 里时,值变化触发 change 规则,失焦触发 blur 规则;表单项的 label 会关联到文本框。不需要校验时设 :validate-event="false"。下面的评论点进去再点出来,就会提示必填:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsMentions, NsMessage, NsSpace } from '@ns/ui'
import type { FormRule, MentionsOption } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive({ comment: '' })
const rules: Record<string, FormRule[]> = {
comment: [
{ required: true, message: '请填写评论', trigger: 'blur' },
{ max: 50, message: '最多 50 个字', trigger: 'change' }
]
}
const users: MentionsOption[] = [
{ value: 'zhangsan', label: '张三' },
{ value: 'lisi', label: '李四' }
]
const submit = async () => {
const result = await formRef.value?.validate()
if (result?.valid) NsMessage.success('校验通过')
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" label-width="80px" style="max-width: 480px">
<NsFormItem label="评论" prop="comment">
<NsMentions
v-model="model.comment"
:options="users"
:rows="3"
placeholder="输入 @ 提及同事"
/>
</NsFormItem>
<NsFormItem>
<NsSpace>
<NsButton type="primary" @click="submit">提交</NsButton>
<NsButton @click="formRef?.resetFields()">重置</NsButton>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | '' | 绑定值,支持 v-model |
| options | MentionsOption[] | [] | 候选项。禁用的选项不显示 |
| prefix | string | string[] | '@' | 触发前缀 |
| split | string | ' ' | 选中后追加在提及后面的分隔符;输入它也会结束当前提及 |
| filterable | boolean | true | 是否按输入的文字过滤选项 |
| placement | 'top' | 'bottom' | 'top-start' | 'bottom-start' | 'top-end' | 'bottom-end' | 'bottom-start' | 下拉层的位置,放不下时自动翻到另一侧 |
| placeholder | string | - | 占位文字 |
| disabled | boolean | false | 是否禁用 |
| readonly | boolean | false | 是否只读 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不传时跟随表单,不在表单里时是 'default' |
| maxlength | number | - | 最大输入长度 |
| rows | number | 1 | 行数 |
| autosize | boolean | { minRows?: number; maxRows?: number } | false | 自适应高度 |
| validateEvent | boolean | true | 值变化和失焦时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string) | 输入或选中选项后触发 |
| change | (value: string) | 文本框失焦且内容有变化时触发(原生 change) |
| focus | (event: FocusEvent) | 获得焦点时触发 |
| blur | (event: FocusEvent) | 失去焦点时触发。点选项不会让文本框失焦 |
| select | (option: MentionsOption, prefix: string) | 选中选项时触发 |
| search | (query: string, prefix: string) | 打开下拉或输入的查询词变化时触发,query 不含前缀 |
方法
| 名称 | 类型 | 说明 |
|---|---|---|
| focus | () => void | 让文本框获得焦点 |
| blur | () => void | 让文本框失去焦点 |
| textareaRef | HTMLTextAreaElement | 内部的 textarea 元素 |
类型
import type { MentionsOption, MentionsPlacement, MentionsSize } from '@ns/ui'
interface MentionsOption {
value: string | number
label: string
disabled?: boolean
}
type MentionsPlacement = 'top' | 'bottom' | 'top-start' | 'bottom-start' | 'top-end' | 'bottom-end'
type MentionsSize = 'large' | 'default' | 'small'
注意事项
- 前缀前面必须是空白或位于开头才会触发,所以邮箱
a@b.com不会弹出列表;中文后面紧跟@(“你好@张”)目前也不会触发。 - 光标移出提及范围(左右键、Home、End、鼠标点击)后下拉自动关闭,移回来会重新打开。输入分隔符或换行会结束提及。
- 禁用的选项直接隐藏,不显示成灰色。
- 只按
label过滤,不匹配value。 - 下拉层对齐的是整个输入框,不跟随光标位置。
- 没有匹配项时,回车照常换行,Tab 照常移走焦点;输入法组合中的按键不会选中选项。
- 组件没有插槽。
优化点
- [ ] 下拉层跟随光标位置
- [ ] 支持自定义选项渲染
- [ ] 支持删除时整体删除一个提及