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.
InputTag 标签输入框
在输入框里输入文字、按回车生成标签,用来录入关键词、邮箱等一组短文本。
引入
import { NsInputTag } from '@ns/ui'
基础用法
用 v-model 绑定一个字符串数组。输入文字后按回车添加标签,点标签上的 × 删除;输入框为空时按退格删除最后一个标签。placeholder 只在一个标签都没有时显示。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputTag, NsSpace } from '@ns/ui'
const tags = ref<string[]>(['Vue'])
const empty = ref<string[]>([])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsInputTag v-model="tags" placeholder="按回车添加标签" />
<NsInputTag v-model="empty" placeholder="还没有标签时显示占位文字" />
</NsSpace>
<p style="margin-top: 12px">绑定值:{{ tags }}</p>
</template>
最大数量
max 限制标签个数。达到上限后输入框变成只读,不能再添加,但仍能聚焦并用退格删除。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputTag } from '@ns/ui'
const tags = ref<string[]>(['Vue', 'React'])
</script>
<template>
<NsInputTag v-model="tags" :max="3" placeholder="最多 3 个" />
<p style="margin-top: 12px">已添加 {{ tags.length }} / 3 个</p>
</template>
去重
unique 为 true 时,已经存在的标签不会再添加(按回车没有反应,文字留在输入框里)。默认允许重复,删除时只删点中的那一个。在下面两个输入框里都再输入一次“Vue”试试:
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputTag, NsSpace } from '@ns/ui'
const uniqueTags = ref<string[]>(['Vue'])
const repeatTags = ref<string[]>(['Vue'])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">unique</span>
<NsInputTag v-model="uniqueTags" unique style="width: 320px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">默认</span>
<NsInputTag v-model="repeatTags" style="width: 320px" />
</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>
禁用
disabled 禁用后不能输入,标签上也没有删除按钮。在禁用的 NsForm 里也会被禁用。组件没有只读属性,要只展示一组标签时用禁用状态或 NsTag。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputTag, NsSpace } from '@ns/ui'
const tags = ref<string[]>(['Vue', 'React'])
const empty = ref<string[]>([])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsInputTag v-model="tags" disabled />
<NsInputTag v-model="empty" placeholder="禁用时的占位文字" disabled />
</NsSpace>
</template>
尺寸
size 可选 large、default、small,高度分别是 40、32、24px(标签多了会换行加高),字号 16、14、12px,圆角 8、6、4px,和同尺寸的 NsInput 一致。里面的标签和 NsSelect 多选的标签一样:large 是 24px 高、14px 字、圆角 6px,default 和 small 是 18px 高、12px 字、圆角 4px(和 NsTag 的 default、small 一样大);标签换行时离边框 2px,上下两行相距 4px。放在 NsForm 里且没传 size 时,跟随表单项或表单的尺寸。
下面每一行最后放一个同尺寸的按钮对比高度:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInputTag, NsSpace } from '@ns/ui'
const tags = ref<string[]>(['Vue', 'React'])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsInputTag v-model="tags" size="large" style="width: 320px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsInputTag v-model="tags" style="width: 320px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsInputTag v-model="tags" size="small" style="width: 320px" />
<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>
事件
添加标签后触发 add,参数是新标签;删除后触发 remove,参数是被删的标签。两种情况都会先触发 update:modelValue。输入框获得、失去焦点时触发 focus、blur。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputTag } from '@ns/ui'
const tags = ref<string[]>(['Vue'])
const logs = ref<string[]>([])
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onAdd = (tag: string) => log(`add:${tag}`)
const onRemove = (tag: string) => log(`remove:${tag}`)
</script>
<template>
<NsInputTag
v-model="tags"
@add="onAdd"
@remove="onRemove"
@focus="log('focus')"
@blur="log('blur')"
/>
<p style="margin-top: 12px">最近的事件(新的在前):{{ logs.join(',') || '还没有' }}</p>
</template>
校验状态
组件没有单独的状态属性,出错的样子由所在的 NsFormItem 决定:校验不通过,或者给表单项传了 error 时,边框变成危险色,下面显示错误信息,内部的 <input> 带上 aria-invalid。
<script setup lang="ts">
import { ref } from 'vue'
import { NsForm, NsFormItem, NsInputTag, NsSwitch } from '@ns/ui'
const showError = ref(true)
const tags = ref<string[]>(['Vue'])
</script>
<template>
<NsSwitch v-model="showError" active-text="显示错误" />
<NsForm label-width="80px" style="margin-top: 16px" @submit.prevent>
<NsFormItem label="技能" :error="showError ? '至少填写 2 个标签' : ''">
<NsInputTag v-model="tags" />
</NsFormItem>
</NsForm>
</template>
调用方法
通过 ref 调用 focus()、blur(),或者用 inputRef 直接拿到内部的 <input> 元素。点输入框里空白的地方也会聚焦输入框。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInputTag, NsSpace } from '@ns/ui'
const tagRef = ref<InstanceType<typeof NsInputTag>>()
const tags = ref<string[]>(['Vue'])
const focused = ref(false)
</script>
<template>
<NsInputTag ref="tagRef" v-model="tags" @focus="focused = true" @blur="focused = false" />
<div style="margin-top: 12px">
<NsSpace wrap>
<NsButton @click="tagRef?.focus()">聚焦</NsButton>
<NsButton @click="tagRef?.blur()">失焦</NsButton>
</NsSpace>
</div>
<p style="margin-top: 12px">输入框{{ focused ? '已聚焦' : '没有聚焦' }}</p>
</template>
在表单里使用
放在 NsFormItem 里时,标签变化触发 change 规则,失焦触发 blur 规则;表单项的 label 会关联到输入框。规则里的 required 把空数组当成没填,min、max 按标签个数比较。不需要校验时设 :validate-event="false"。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInputTag } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const model = reactive({ keywords: [] as string[] })
const rules: Record<string, FormRule[]> = {
keywords: [
{ required: true, message: '请至少添加一个关键词', trigger: 'blur' },
{ min: 2, max: 5, message: '关键词 2 到 5 个', trigger: 'change' }
]
}
</script>
<template>
<NsForm :model="model" :rules="rules" @submit.prevent>
<NsFormItem label="关键词" prop="keywords">
<NsInputTag v-model="model.keywords" placeholder="输入后按回车" />
</NsFormItem>
</NsForm>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string[] | [] | 标签列表,支持 v-model |
| max | number | - | 最多几个标签 |
| placeholder | string | - | 占位文字 |
| disabled | boolean | false | 是否禁用 |
| unique | boolean | false | 是否不允许重复标签 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不传时跟随表单,不在表单里时是 'default' |
| validateEvent | boolean | true | 标签变化和失焦时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string[]) | 添加或删除标签后触发 |
| add | (value: string) | 添加标签后触发 |
| remove | (value: string) | 删除标签后触发,参数是被删的标签 |
| focus | (event: FocusEvent) | 输入框获得焦点时触发 |
| blur | (event: FocusEvent) | 输入框失去焦点时触发 |
方法
| 名称 | 类型 | 说明 |
|---|---|---|
| focus | () => void | 让输入框获得焦点 |
| blur | () => void | 让输入框失去焦点 |
| inputRef | HTMLInputElement | 内部的 input 元素 |
类型
import type { InputTagProps, InputTagSize } from '@ns/ui'
type InputTagSize = 'large' | 'default' | 'small'
interface InputTagProps {
modelValue?: string[]
max?: number
placeholder?: string
disabled?: boolean
unique?: boolean
size?: InputTagSize
validateEvent?: boolean
}
注意事项
- 只有按回车才会添加标签;输入法组合中按回车不会添加。
- 添加前会去掉首尾空格,全是空格的内容不会添加。
- 失焦时还没按回车的文字留在输入框里,不会自动变成标签。
- 粘贴
a,b,c只会生成一个标签,不会自动拆分。 - 组件没有插槽。
优化点
- [ ] 支持分隔符自动拆分(粘贴、输入逗号时)
- [ ] 支持失焦时自动添加
- [ ] 支持自定义标签内容