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.
DynamicInput 动态录入
录入一组数量不定的数据:每行右侧有“+”“-”按钮,可以随时插入、删除,也可以上移、下移调整顺序。适合填多个网址、请求参数、联系人这类列表。
引入
import { NsDynamicInput } from '@ns/ui'
基础用法
v-model 绑定一个数组,一项对应一行。默认的 preset="input" 每行一个文本框,值是字符串数组。点某一行的“+”在这一行下面插入一个空行,点“-”删除这一行。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput, NsSpace } from '@ns/ui'
const cities = ref(['北京', '上海'])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsDynamicInput v-model="cities" placeholder="请输入城市" />
<span>绑定值:{{ cities }}</span>
</NsSpace>
</template>
键值对
preset="pair" 每行键、值两个文本框,值是 { key, value } 数组,常用来录入请求参数、请求头、环境变量。key-placeholder、value-placeholder 改两个文本框的占位文字。改键或值时只替换这两个属性,这一行上的其他属性(比如 id)会保留。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput, NsSpace } from '@ns/ui'
import type { DynamicInputPair } from '@ns/ui'
const params = ref<DynamicInputPair[]>([
{ key: 'page', value: '1' },
{ key: 'size', value: '20' }
])
const headers = ref<DynamicInputPair[]>([{ key: 'Accept', value: 'application/json' }])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsDynamicInput v-model="params" preset="pair" />
<span>请求参数:{{ params }}</span>
<NsDynamicInput
v-model="headers"
preset="pair"
key-placeholder="请求头名称"
value-placeholder="请求头的值"
/>
<span>请求头:{{ headers }}</span>
</NsSpace>
</template>
自定义行
两种预设不够用时,在默认插槽里写每一行的内容。插槽参数:
value:这一行的值;index:这一行的下标,从 0 开始。update(newValue):用新值替换这一行。remove():删除这一行(受min和禁用限制)。size、disabled:组件当前的尺寸和禁用状态,传给行里的控件,它们就能跟着组件一起变。
自定义行时要传 on-create,返回新增一行时的初始值,参数是新行的下标。每次都返回一个新对象,不要返回同一个对象,否则几行会共用它。
下面是联系人列表,每行是姓名、手机号和关系。行的值是对象,可以直接 v-model="value.name" 改它的属性。插槽内容在一行里横排,几个控件之间自动留出间距;文本框默认占满剩下的宽度,选择框用 style 给了固定宽度。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput, NsInput, NsSelect, NsSpace } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
interface Contact {
name: string
phone: string
relation?: string
}
const relations: SelectOption[] = [
{ label: '父母', value: 'parent' },
{ label: '配偶', value: 'spouse' },
{ label: '子女', value: 'child' },
{ label: '朋友', value: 'friend' }
]
const contacts = ref<Contact[]>([{ name: '张三', phone: '13800000000', relation: 'friend' }])
const createContact = (): Contact => ({ name: '', phone: '', relation: undefined })
</script>
<template>
<NsSpace direction="vertical" fill>
<NsDynamicInput v-model="contacts" :on-create="createContact">
<template #default="{ value, index }">
<NsInput
v-model="value.name"
placeholder="姓名"
:aria-label="`第 ${index + 1} 位联系人的姓名`"
/>
<NsInput
v-model="value.phone"
placeholder="手机号"
:aria-label="`第 ${index + 1} 位联系人的手机号`"
/>
<NsSelect
v-model="value.relation"
:options="relations"
placeholder="关系"
:aria-label="`第 ${index + 1} 位联系人的关系`"
style="width: 120px; flex: none"
/>
</template>
</NsDynamicInput>
<span>绑定值:{{ contacts }}</span>
</NsSpace>
</template>
行的值是数字、字符串这类基本类型时不能直接改属性,要用 update 替换整行。下面每行是一个数字输入框:
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput, NsInputNumber, NsSpace } from '@ns/ui'
const prices = ref<(number | undefined)[]>([99, 199])
const total = () => prices.value.reduce<number>((sum, price) => sum + (price ?? 0), 0)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsDynamicInput v-model="prices" :on-create="() => undefined">
<template #default="{ value, index, update }">
<NsInputNumber
:model-value="value"
:min="0"
:aria-label="`第 ${index + 1} 个价格`"
style="flex: 1"
@update:model-value="update"
/>
</template>
</NsDynamicInput>
<span>绑定值:{{ prices }},合计 {{ total() }} 元</span>
</NsSpace>
</template>
空状态和文字
一行都没有时显示一个虚线的“添加一项”按钮,add-text 改它的文字。placeholder 改 input 预设文本框的占位文字。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput, NsSpace } from '@ns/ui'
const empty = ref<string[]>([])
const sites = ref<string[]>([])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsDynamicInput v-model="empty" />
<NsDynamicInput v-model="sites" add-text="添加网址" placeholder="https://" />
<span>网址:{{ sites }}</span>
</NsSpace>
</template>
最少最多行数
min 是最少几行,行数等于它时“-”按钮禁用;max 是最多几行,行数等于它时所有“+”按钮禁用。min 默认 0,max 不传时不限制。组件不会自动补齐到 min 行,需要的话初始值就给够行数。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput, NsSpace } from '@ns/ui'
const atLeastOne = ref(['只剩一行时不能删'])
const upToThree = ref(['第 1 个', '第 2 个'])
</script>
<template>
<NsSpace direction="vertical" fill>
<span>min = 1:</span>
<NsDynamicInput v-model="atLeastOne" :min="1" />
<span>max = 3(已有 {{ upToThree.length }} 个):</span>
<NsDynamicInput v-model="upToThree" :max="3" />
</NsSpace>
</template>
排序
show-sort-button 在每行右侧加上移、下移按钮,第一行不能上移,最后一行不能下移。移动后焦点跟着这一行走,用键盘连续按回车可以一直移动。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput, NsSpace } from '@ns/ui'
const steps = ref(['打开冰箱门', '把大象放进去', '关上冰箱门'])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsDynamicInput v-model="steps" show-sort-button />
<span>顺序:{{ steps.join(' → ') }}</span>
</NsSpace>
</template>
尺寸
size 可选 large、default、small,文本框和按钮的高度分别是 40、32、24px,和同尺寸的输入框、按钮一致。不传时跟随所在的 NsFormItem、NsForm,再没有就跟随 NsConfigProvider。自定义行时用插槽参数 size 把尺寸传给行里的控件。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput, NsSpace } from '@ns/ui'
const large = ref(['large'])
const normal = ref([{ key: 'size', value: 'default' }])
const small = ref(['small'])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsDynamicInput v-model="large" size="large" show-sort-button />
<NsDynamicInput v-model="normal" preset="pair" show-sort-button />
<NsDynamicInput v-model="small" size="small" show-sort-button />
</NsSpace>
</template>
禁用
disabled 后文本框和所有按钮都禁用,不能增删、移动,方法调用也不执行。放在禁用的 NsForm 里也会禁用。自定义行时用插槽参数 disabled 禁用行里的控件。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput, NsInput, NsSpace, NsSwitch } from '@ns/ui'
const disabled = ref(true)
const tags = ref(['不能改', '也不能增删'])
const empty = ref<string[]>([])
const people = ref([{ name: '张三' }, { name: '李四' }])
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSwitch v-model="disabled" active-text="禁用" />
<NsDynamicInput v-model="tags" :disabled="disabled" show-sort-button />
<NsDynamicInput v-model="empty" :disabled="disabled" />
<NsDynamicInput v-model="people" :disabled="disabled" :on-create="() => ({ name: '' })">
<template #default="{ value, disabled: rowDisabled }">
<NsInput v-model="value.name" :disabled="rowDisabled" placeholder="姓名" />
</template>
</NsDynamicInput>
</NsSpace>
</template>
在表单里校验
逐行校验
NsFormItem 的 prop 支持数组路径,contacts.0.name 和 contacts[0].name 都可以。在插槽里给每个控件包一层 NsFormItem,prop 按下标拼出路径,规则写在它的 rules 上(表单 rules 的键要和 prop 一字不差,动态的行不方便写在那里)。这样每一行单独校验、单独显示错误,validate() 返回的错误也按路径列出。
外层的 NsFormItem 校验整个数组,下面用 required 要求至少一位联系人。整个组件是外层表单项的一个控件:值变化(包括行里的输入)时触发外层的 change 规则,焦点离开整个组件时触发 blur 规则,在行之间切换焦点不触发。
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsDynamicInput, NsForm, NsFormItem, NsInput, NsSpace } from '@ns/ui'
import type { FormRule } from '@ns/ui'
interface Contact {
name: string
phone: string
}
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive({ contacts: [{ name: '', phone: '' }] as Contact[] })
const result = ref('')
const listRules: FormRule[] = [{ required: true, message: '至少添加 1 位联系人' }]
const nameRules: FormRule[] = [{ required: true, message: '请输入姓名', trigger: 'blur' }]
const phoneRules: FormRule[] = [
{ required: true, message: '请输入手机号', trigger: 'blur' },
{ pattern: /^1\d{10}$/, message: '手机号是 1 开头的 11 位数字', trigger: 'blur' }
]
const createContact = (): Contact => ({ name: '', phone: '' })
const submit = async () => {
const { valid, errors } = await formRef.value!.validate()
result.value = valid ? '校验通过' : `有错误的字段:${Object.keys(errors).join('、')}`
}
</script>
<template>
<NsForm ref="formRef" :model="model" @submit.prevent>
<NsFormItem label="联系人" prop="contacts" :rules="listRules">
<NsDynamicInput v-model="model.contacts" :on-create="createContact" show-sort-button>
<template #default="{ value, index }">
<NsFormItem :prop="`contacts.${index}.name`" :rules="nameRules" style="flex: 1">
<NsInput v-model="value.name" placeholder="姓名" />
</NsFormItem>
<NsFormItem :prop="`contacts.${index}.phone`" :rules="phoneRules" style="flex: 1">
<NsInput v-model="value.phone" placeholder="手机号" />
</NsFormItem>
</template>
</NsDynamicInput>
</NsFormItem>
<NsFormItem>
<NsSpace wrap>
<NsButton type="primary" @click="submit">提交</NsButton>
<NsButton @click="formRef?.clearValidate()">清除校验</NsButton>
<span>{{ result }}</span>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
整体校验
只需要检查整个数组时(比如不能有空项、不能重复),把规则写在外层的 NsFormItem 上,用 validator 拿到整个数组判断,行里不用再包 NsFormItem。下面输入、增删时都会重新校验:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsDynamicInput, NsForm, NsFormItem, NsMessage } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive({ emails: ['admin@example.com', ''] })
const emailRules: FormRule[] = [
{ required: true, message: '至少填 1 个邮箱' },
{
validator: (_rule, value, callback) => {
const list = value as string[]
if (list.some((email) => !email.trim())) callback('有空着的邮箱')
else if (list.some((email) => !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))) {
callback('有邮箱格式不对')
} else if (new Set(list).size !== list.length) callback('邮箱不能重复')
else callback()
}
}
]
const submit = async () => {
const { valid } = await formRef.value!.validate()
if (valid) NsMessage.success(`共 ${model.emails.length} 个邮箱,校验通过`)
}
</script>
<template>
<NsForm ref="formRef" :model="model" @submit.prevent>
<NsFormItem label="通知邮箱" prop="emails" :rules="emailRules">
<NsDynamicInput v-model="model.emails" :max="5" placeholder="name@example.com" />
</NsFormItem>
<NsFormItem>
<NsButton type="primary" @click="submit">提交</NsButton>
</NsFormItem>
</NsForm>
</template>
事件
增删、移动时依次发出 update:modelValue 和 add、remove、move。只改行里的值时只发 update:modelValue。点下面的按钮看记录:
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput, NsSpace } from '@ns/ui'
const items = ref(['苹果', '香蕉'])
const logs = ref<string[]>([])
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onAdd = (index: number, value: string) =>
log(`add:在第 ${index + 1} 行新增,初始值 ${JSON.stringify(value)}`)
const onRemove = (index: number, value: string) =>
log(`remove:删除第 ${index + 1} 行,值是 ${JSON.stringify(value)}`)
const onMove = (from: number, to: number) => log(`move:第 ${from + 1} 行移到第 ${to + 1} 行`)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsDynamicInput
v-model="items"
show-sort-button
@add="onAdd"
@remove="onRemove"
@move="onMove"
/>
<span>绑定值:{{ items }}</span>
<div class="logs">
<div v-for="(item, i) in logs" :key="i">{{ item }}</div>
<div v-if="logs.length === 0">还没有事件</div>
</div>
</NsSpace>
</template>
<style scoped>
.logs {
padding: var(--ns-spacing-2) var(--ns-spacing-3);
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
background: var(--ns-fill-color-light);
border-radius: var(--ns-border-radius);
}
</style>
无障碍和按钮文字
每个按钮都是原生 <button>,能用 Tab 聚焦、回车或空格触发,并带有“删除第 2 项”这样的无障碍名称,鼠标悬停时也显示这段文字。预设的文本框带“第 2 项”“第 2 项的键”这样的名称。
点按钮后焦点会放到合适的位置:插入后聚焦新行的第一个输入框;删除后聚焦顶上来的那一行的“-”按钮(删光了就聚焦“添加一项”);移动后焦点跟着这一行走。
labels 改这些文字,只传要改的几项,{index} 会换成从 1 开始的行号。可改的项见下面的类型 DynamicInputLabels。把鼠标移到下面的按钮上看看:
<script setup lang="ts">
import { ref } from 'vue'
import { NsDynamicInput } from '@ns/ui'
const emails = ref(['a@example.com', 'b@example.com'])
</script>
<template>
<NsDynamicInput
v-model="emails"
show-sort-button
add-text="添加邮箱"
:labels="{
item: '第 {index} 个邮箱',
insert: '在第 {index} 个邮箱后添加',
remove: '删除第 {index} 个邮箱',
moveUp: '第 {index} 个邮箱上移',
moveDown: '第 {index} 个邮箱下移'
}"
/>
</template>
用方法操作
通过 ref 调用 add、remove、move、focus。它们和点按钮一样受 min、max、禁用限制,没执行时返回 false;同样会发出 add、remove、move 事件。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsDynamicInput, NsMessage, NsSpace } from '@ns/ui'
import type { DynamicInputExpose } from '@ns/ui'
const listRef = ref<DynamicInputExpose<string>>()
const items = ref(['第一项', '第二项', '第三项'])
const addToTop = () => listRef.value?.add(0, `新的一项 ${items.value.length + 1}`)
const removeLast = () => {
if (!listRef.value?.remove(items.value.length - 1)) NsMessage.warning('至少保留 1 行')
}
const moveFirstToEnd = () => listRef.value?.move(0, items.value.length - 1)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton @click="addToTop">在开头插入</NsButton>
<NsButton @click="removeLast">删除最后一行</NsButton>
<NsButton @click="moveFirstToEnd">第一行移到最后</NsButton>
<NsButton @click="listRef?.focus(1)">聚焦第 2 行</NsButton>
</NsSpace>
<NsDynamicInput ref="listRef" v-model="items" :min="1" />
</NsSpace>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | T[] | [] | 绑定值,一项对应一行,支持 v-model |
| preset | 'input' | 'pair' | 'input' | 内置的行内容:input 每行一个文本框(字符串数组),pair 每行键、值两个文本框({ key, value } 数组)。写了默认插槽时只决定新增行的默认值 |
| onCreate | (index: number) => T | — | 新增一行时调用,返回这一行的初始值,index 是新行的下标。不传时 input 是 '',pair 是 { key: '', value: '' } |
| min | number | 0 | 最少几行,行数等于它时“-”按钮禁用 |
| max | number | — | 最多几行,行数等于它时“+”按钮禁用;不传时不限制 |
| showSortButton | boolean | false | 显示上移、下移按钮 |
| size | 'large' | 'default' | 'small' | — | 尺寸。不传时跟随 FormItem、Form、ConfigProvider,都没有时是 default |
| disabled | boolean | false | 是否禁用。在禁用的表单里也会禁用 |
| placeholder | string | '请输入' | input 预设文本框的占位文字 |
| keyPlaceholder | string | '请输入键' | pair 预设键文本框的占位文字 |
| valuePlaceholder | string | '请输入值' | pair 预设值文本框的占位文字 |
| addText | string | '添加一项' | 一行都没有时显示的按钮文字 |
| labels | Partial<DynamicInputLabels> | — | 按钮和预设文本框的无障碍名称(按钮也用作悬停提示),只传要改的几项,{index} 换成行号 |
| validateEvent | boolean | true | 值变化、焦点离开组件时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: T[]) | 值变化时触发,参数是新数组(不会改原来的数组) |
| add | (index: number, value: T) | 新增一行后触发,index 是新行的下标,value 是它的初始值 |
| remove | (index: number, value: T) | 删除一行后触发,index 是被删行原来的下标,value 是它的值 |
| move | (from: number, to: number) | 移动一行后触发,从下标 from 移到 to |
Slots
| 插槽 | 参数 | 说明 |
|---|---|---|
| default | { value, index, update, remove, size, disabled } | 每一行的内容,写了以后不再显示预设的文本框。参数说明见类型 DynamicInputSlotProps |
方法
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| add | (index?: number, value?: T) | boolean | 在 index 处插入一行,不传时加在最后;value 不传时用 on-create 或预设的默认值 |
| remove | (index: number) | boolean | 删除第 index 行 |
| move | (from: number, to: number) | boolean | 把第 from 行移到 to |
| focus | (index?: number) | — | 聚焦第 index 行(默认第 0 行)的第一个输入框;一行都没有时聚焦“添加一项”按钮 |
add、remove、move 受 min、max、禁用限制,下标越界或没执行时返回 false。
类型
import type {
DynamicInputSize,
DynamicInputPreset,
DynamicInputPair,
DynamicInputLabels,
DynamicInputProps,
DynamicInputEmits,
DynamicInputSlotProps,
DynamicInputExpose
} from '@ns/ui'
interface DynamicInputPair {
key: string
value: string
}
interface DynamicInputLabels {
insert: string // “+”按钮,默认 '在第 {index} 项下方插入'
remove: string // “-”按钮,默认 '删除第 {index} 项'
moveUp: string // 上移按钮,默认 '上移第 {index} 项'
moveDown: string // 下移按钮,默认 '下移第 {index} 项'
item: string // input 预设的文本框,默认 '第 {index} 项'
key: string // pair 预设的键文本框,默认 '第 {index} 项的键'
value: string // pair 预设的值文本框,默认 '第 {index} 项的值'
}
interface DynamicInputSlotProps<T> {
value: T // 这一行的值
index: number // 这一行的下标,从 0 开始
update: (value: T) => void // 用新值替换这一行
remove: () => void // 删除这一行(受 min 和禁用限制)
size: DynamicInputSize // 组件当前的尺寸
disabled: boolean // 组件当前是否禁用
}
注意事项
- 组件是受控的:显示的是
v-model的值,增删、移动、输入都发出新数组,不改原来的数组。没绑v-model(或只传model-value)时点按钮不会有变化。 - 行的值是对象时,插槽里可以直接改它的属性(
v-model="value.name"),改的就是绑定数组里的那个对象;值是字符串、数字时要用update替换。 - 组件按行维护内部的 key,增删、移动时输入框跟着行走,所以值重复也没关系。直接改数组(
push、整个替换)也能正确显示。 on-create是属性,不是事件:它的返回值就是新行的初始值。新增一行后发出的事件叫add。- 逐行校验时,删除或移动行会让后面几行的下标变化,这几行表单项的
prop随之改变,它们当前显示的错误会被清掉,下次校验时重新检查。resetFields()时外层表单项把整个数组恢复成初始值。 - 外层表单项出错时,它会把里面所有输入框的边框都标红;只想标出某一行时用逐行校验。
- 外层表单项的
label-position="float"(浮动标签)不适合这个组件,标签会浮在第一行的输入框里,用top或默认的right。 - 写在
NsDynamicInput上的class、style、aria-*等属性加在根元素上。根元素是role="group",在有标签的表单项里用aria-labelledby关联标签。