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.
Form 表单
NsForm 包住一组 NsFormItem,负责布局(标签位置、宽度、行内)、统一控件的禁用和尺寸,以及按规则校验、重置数据。NsFormItem 是一行“标签 + 控件 + 错误提示”。库里的 20 种表单控件都已接入,放进表单项后自动跟随表单禁用、尺寸,并在值变化、失焦时触发校验;自己写的控件可以用 useFormItem 接入。
引入
import { NsForm, NsFormItem } from '@ns/ui'
基础用法
model 传表单数据对象,控件用 v-model 绑定它的字段。label 是标签文字,label-width 统一标签宽度(默认 '80px')。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInput } from '@ns/ui'
const model = reactive({ username: '', email: '' })
</script>
<template>
<NsForm :model="model" label-width="100px" @submit.prevent>
<NsFormItem label="用户名">
<NsInput v-model="model.username" />
</NsFormItem>
<NsFormItem label="邮箱">
<NsInput v-model="model.email" />
</NsFormItem>
</NsForm>
</template>
NsForm 渲染的是原生 <form>,没有拦截提交。表单里只有一个单行输入框时,按回车会触发浏览器的默认提交并刷新页面,所以示例里都加了 @submit.prevent。
各种控件
常用的表单控件放进表单项后都能参与校验和重置。下面是一张完整的表单:先点“立即创建”看必填提示,填好后再点;“重置”把所有字段恢复成初始值。
<script setup lang="ts">
import { reactive, ref } from 'vue'
import {
NsButton,
NsCheckbox,
NsCheckboxGroup,
NsDatePicker,
NsForm,
NsFormItem,
NsInput,
NsInputNumber,
NsMessage,
NsRadio,
NsRadioGroup,
NsRate,
NsSelect,
NsSlider,
NsSpace,
NsSwitch,
NsTextarea,
NsTimePicker
} from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const form = reactive({
name: '',
region: '',
period: null as [Date, Date] | null,
startTime: '09:00',
quota: 100,
types: [] as string[],
resource: 'sponsor',
delivery: false,
discount: 20,
priority: 3,
desc: ''
})
const regions = [
{ label: '华东', value: 'east' },
{ label: '华北', value: 'north' },
{ label: '华南', value: 'south' }
]
const rules: Record<string, FormRule[]> = {
name: [
{ required: true, message: '请输入活动名称', trigger: 'blur' },
{ min: 2, max: 20, message: '活动名称 2 到 20 个字', trigger: 'blur' }
],
region: [{ required: true, message: '请选择活动区域', trigger: 'change' }],
period: [{ required: true, message: '请选择活动时间', trigger: 'change' }],
types: [{ type: 'array', required: true, message: '至少选一种活动性质', trigger: 'change' }],
desc: [{ max: 100, message: '活动说明不超过 100 个字', trigger: 'blur' }]
}
const submit = async () => {
const { valid } = await formRef.value!.validate()
if (valid) NsMessage.success('创建成功')
else NsMessage.error('还有字段没填对')
}
</script>
<template>
<NsForm ref="formRef" :model="form" :rules="rules" label-width="100px" @submit.prevent>
<NsFormItem label="活动名称" prop="name">
<NsInput v-model="form.name" />
</NsFormItem>
<NsFormItem label="活动区域" prop="region">
<NsSelect v-model="form.region" :options="regions" placeholder="请选择活动区域" />
</NsFormItem>
<NsFormItem label="活动时间" prop="period">
<NsDatePicker v-model="form.period" type="daterange" />
</NsFormItem>
<NsFormItem label="每天开始" prop="startTime">
<NsTimePicker v-model="form.startTime" format="HH:mm" />
</NsFormItem>
<NsFormItem label="名额" prop="quota">
<NsInputNumber v-model="form.quota" :min="1" :max="1000" />
</NsFormItem>
<NsFormItem label="活动性质" prop="types">
<NsCheckboxGroup v-model="form.types">
<NsCheckbox value="online" label="线上活动" />
<NsCheckbox value="promotion" label="地推活动" />
<NsCheckbox value="offline" label="线下主题活动" />
</NsCheckboxGroup>
</NsFormItem>
<NsFormItem label="特殊资源" prop="resource">
<NsRadioGroup v-model="form.resource">
<NsRadio value="sponsor" label="品牌商赞助" />
<NsRadio value="venue" label="场地免费" />
</NsRadioGroup>
</NsFormItem>
<NsFormItem label="即时配送" prop="delivery">
<NsSwitch v-model="form.delivery" />
</NsFormItem>
<NsFormItem label="折扣(%)" prop="discount">
<NsSlider v-model="form.discount" />
</NsFormItem>
<NsFormItem label="优先级" prop="priority">
<NsRate v-model="form.priority" />
</NsFormItem>
<NsFormItem label="活动说明" prop="desc">
<NsTextarea v-model="form.desc" />
</NsFormItem>
<NsFormItem>
<NsSpace wrap>
<NsButton type="primary" @click="submit">立即创建</NsButton>
<NsButton @click="formRef?.resetFields()">重置</NsButton>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
表单校验
在 NsForm 上传 rules,键是表单项的 prop;表单项写上 prop 才会参与校验。规则的 trigger 决定什么时候自动校验:'blur' 是控件失焦时,'change' 是值变化时,可以写成数组,不写时两种情况都校验。提交前调用 validate() 校验全部表单项,它返回 Promise<{ valid, errors }>,校验不通过也是 resolve,不会 reject。
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsForm, NsFormItem, NsInput, NsButton, NsMessage, NsSpace } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive({ name: '', email: '' })
const rules: Record<string, FormRule[]> = {
name: [{ required: true, message: '请输入用户名', trigger: 'blur' }],
email: [
{ required: true, message: '请输入邮箱', trigger: 'blur' },
{ type: 'email', message: '邮箱格式不对', trigger: ['blur', 'change'] }
]
}
const submit = async () => {
const { valid, errors } = await formRef.value!.validate()
if (!valid) {
// errors 形如 { email: ['邮箱格式不对'] }
NsMessage.error(`没通过的字段:${Object.keys(errors).join('、')}`)
return
}
// 提交 model
NsMessage.success('校验通过')
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules">
<NsFormItem label="用户名" prop="name">
<NsInput v-model="model.name" />
</NsFormItem>
<NsFormItem label="邮箱" prop="email">
<NsInput v-model="model.email" />
</NsFormItem>
<NsFormItem>
<NsSpace wrap>
<NsButton type="primary" @click="submit">提交</NsButton>
<NsButton @click="formRef?.resetFields()">重置</NsButton>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
resetFields() 把字段恢复成表单项挂载时的值(深拷贝,数组、对象也会恢复),并清掉错误提示;clearValidate() 只清错误提示,不动数据。两者都可以只传部分 prop。
校验规则
一个字段可以有多条规则,按顺序执行,遇到第一条不通过就停下,显示它的 message(没写时用默认提示)。
| 规则 | 作用 | 默认提示 |
|---|---|---|
required | 必填。undefined、null、''、[] 算空;false、0 不算空 | 该字段为必填项 |
type | 值的类型:string、number、boolean、array、email、url(以 http(s)😕/ 开头) | 字段类型必须为 xxx |
min、max | 字符串、数组比较长度;数字比较数值大小 | 长度不能小于 n / 不能小于 n 等 |
pattern | 正则,按 String(value) 匹配。带 g、y 标志的正则每次校验前会把 lastIndex 归零 | 格式不正确 |
validator | 自定义校验函数,见下一节 | 校验未通过 |
非必填的字段是空值时,跳过 type、min、max、pattern,只执行 validator。比如“选填,填了就检查格式”的手机号,只写 pattern 不写 required 就行。
下面每个字段用一种规则,点“校验”看全部提示。“网址”“手机号”是选填的,空着能通过,填了才检查格式;“爱好”的最少、最多比较的是数组长度,“年龄”比较的是数值:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import {
NsButton,
NsCheckbox,
NsCheckboxGroup,
NsForm,
NsFormItem,
NsInput,
NsInputNumber,
NsSpace
} from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive({
nickname: '',
username: 'ab',
email: 'abc',
website: '',
phone: '',
age: 12 as number | null,
hobbies: [] as string[]
})
const rules: Record<string, FormRule[]> = {
// required:必填,用默认提示
nickname: [{ required: true }],
// min / max:字符串比较长度
username: [{ min: 3, max: 12, message: '用户名 3 到 12 个字符' }],
// type:email
email: [{ type: 'email', message: '邮箱格式不对' }],
// type:url,选填
website: [{ type: 'url', message: '网址要以 http:// 或 https:// 开头' }],
// pattern,选填
phone: [{ pattern: /^1\d{10}$/, message: '手机号是 1 开头的 11 位数字' }],
// type:number 加 min / max:数字比较数值
age: [
{ required: true, message: '请输入年龄' },
{ type: 'number', min: 18, max: 60, message: '年龄要在 18 到 60 之间' }
],
// type:array 加 min / max:数组比较长度
hobbies: [{ type: 'array', min: 1, max: 2, message: '爱好选 1 到 2 个' }]
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" label-width="80px" @submit.prevent>
<NsFormItem label="昵称" prop="nickname">
<NsInput v-model="model.nickname" placeholder="required" />
</NsFormItem>
<NsFormItem label="用户名" prop="username">
<NsInput v-model="model.username" placeholder="min: 3, max: 12" />
</NsFormItem>
<NsFormItem label="邮箱" prop="email">
<NsInput v-model="model.email" placeholder="type: 'email'" />
</NsFormItem>
<NsFormItem label="网址" prop="website">
<NsInput v-model="model.website" placeholder="type: 'url'(选填)" />
</NsFormItem>
<NsFormItem label="手机号" prop="phone">
<NsInput v-model="model.phone" placeholder="pattern(选填)" />
</NsFormItem>
<NsFormItem label="年龄" prop="age">
<NsInputNumber v-model="model.age" />
</NsFormItem>
<NsFormItem label="爱好" prop="hobbies">
<NsCheckboxGroup v-model="model.hobbies">
<NsCheckbox value="read" label="阅读" />
<NsCheckbox value="sport" label="运动" />
<NsCheckbox value="music" label="音乐" />
</NsCheckboxGroup>
</NsFormItem>
<NsFormItem>
<NsSpace wrap>
<NsButton type="primary" @click="formRef?.validate()">校验</NsButton>
<NsButton @click="formRef?.clearValidate()">清除提示</NsButton>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
触发时机
trigger 写 'blur' 时只在失焦时自动校验,写 'change' 时只在值变化时校验,不写时两种情况都校验。三个输入框都是必填,分别输入几个字再删空、再点到别处,看提示什么时候出现:
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInput } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const model = reactive({ onBlur: '', onChange: '', both: '' })
const rules: Record<string, FormRule[]> = {
onBlur: [{ required: true, message: '失焦时才提示', trigger: 'blur' }],
onChange: [{ required: true, message: '删空的那一刻就提示', trigger: 'change' }],
both: [{ required: true, message: '删空、失焦都会提示' }]
}
</script>
<template>
<NsForm :model="model" :rules="rules" label-width="140px" @submit.prevent>
<NsFormItem label="trigger: 'blur'" prop="onBlur">
<NsInput v-model="model.onBlur" />
</NsFormItem>
<NsFormItem label="trigger: 'change'" prop="onChange">
<NsInput v-model="model.onChange" />
</NsFormItem>
<NsFormItem label="不写 trigger" prop="both">
<NsInput v-model="model.both" />
</NsFormItem>
</NsForm>
</template>
自定义校验
validator(rule, value, callback) 支持四种写法,哪种先给出结果就用哪种:
- 调用
callback():不传参数表示通过,传字符串或Error表示不通过,提示就是它的内容。 - 返回
true/false:false时提示用规则的message。 - 返回 Promise(或写成
async函数):resolve 表示通过,resolve(false) 或 reject 表示不通过;reject 的是Error时提示用它的message。 - 抛错:同 reject。
const rules: Record<string, FormRule[]> = {
// callback 写法:确认密码
confirm: [
{
trigger: 'blur',
validator: (_rule, value, callback) => {
if (value !== model.password) callback(new Error('两次输入的密码不一致'))
else callback()
}
}
],
// Promise 写法:请求接口检查用户名是否被占用
username: [
{
trigger: 'blur',
validator: async (_rule, value) => {
const { exists } = await api.checkUsername(value as string)
if (exists) throw new Error('用户名已被占用')
}
}
],
// 返回 boolean:开关、评分这类 false、0 不算空的控件
agree: [{ validator: (_rule, value) => value === true, message: '请勾选同意', trigger: 'change' }]
}
函数的参数列表里写了 callback(第三个参数)时,组件会等你调用它,忘了调用、也没返回 Promise 或 boolean 的话,这次校验一直不结束。不需要 callback 时就不要声明这个参数。
上面三种写法放在一张注册表单里。检查用户名的接口用 setTimeout 模拟,admin、root 算已被占用:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsCheckbox, NsForm, NsFormItem, NsInput, NsMessage } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive({ username: '', password: '', confirm: '', agree: false })
// 用 setTimeout 模拟检查用户名的接口,500 毫秒后返回
const api = {
checkUsername: (name: string) =>
new Promise<{ exists: boolean }>((resolve) => {
setTimeout(() => resolve({ exists: ['admin', 'root'].includes(name) }), 500)
})
}
const rules: Record<string, FormRule[]> = {
username: [
{ required: true, message: '请输入用户名', trigger: 'blur' },
{
trigger: 'blur',
validator: async (_rule, value) => {
const { exists } = await api.checkUsername(value as string)
if (exists) throw new Error('用户名已被占用')
}
}
],
password: [{ required: true, message: '请输入密码', trigger: 'blur' }],
confirm: [
{
trigger: 'blur',
validator: (_rule, value, callback) => {
if (value !== model.password) callback(new Error('两次输入的密码不一致'))
else callback()
}
}
],
agree: [
{ validator: (_rule, value) => value === true, message: '请勾选同意', trigger: 'change' }
]
}
const submit = async () => {
const { valid } = await formRef.value!.validate()
if (valid) NsMessage.success('注册成功')
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" label-width="90px" @submit.prevent>
<NsFormItem label="用户名" prop="username">
<NsInput v-model="model.username" placeholder="输入 admin 试试" />
</NsFormItem>
<NsFormItem label="密码" prop="password">
<NsInput v-model="model.password" type="password" />
</NsFormItem>
<NsFormItem label="确认密码" prop="confirm">
<NsInput v-model="model.confirm" type="password" />
</NsFormItem>
<NsFormItem prop="agree">
<NsCheckbox v-model="model.agree">我已阅读并同意用户协议</NsCheckbox>
</NsFormItem>
<NsFormItem>
<NsButton type="primary" @click="submit">注册</NsButton>
</NsFormItem>
</NsForm>
</template>
表单项上的规则
NsFormItem 也可以写 rules,和表单 rules 里同名字段的规则合并(表单的在前)。required 属性会覆盖规则里的 required;规则里没有 required 时,相当于补一条 { required },提示用默认文字。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInput } from '@ns/ui'
const model = reactive({ phone: '', nickname: '' })
</script>
<template>
<NsForm :model="model" @submit.prevent>
<NsFormItem
label="手机号"
prop="phone"
:rules="[{ pattern: /^1\d{10}$/, message: '手机号格式不对', trigger: 'blur' }]"
>
<NsInput v-model="model.phone" />
</NsFormItem>
<NsFormItem label="昵称" prop="nickname" required>
<NsInput v-model="model.nickname" />
</NsFormItem>
</NsForm>
</template>
嵌套字段和动态表单项
prop 支持路径:user.name、items[0].value、items.0.value 都可以,校验和重置都按路径读写 model。表单 rules 的键要和 prop 写得一字不差(rules['items.0.value']),动态生成的表单项一般把规则直接写在表单项的 rules 上。
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsForm, NsFormItem, NsInput, NsButton, NsMessage, NsSpace } from '@ns/ui'
import type { FormRule } from '@ns/ui'
let seed = 1
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive({ emails: [{ id: seed, value: '' }] })
const emailRules: FormRule[] = [
{ required: true, message: '请输入邮箱', trigger: 'blur' },
{ type: 'email', message: '邮箱格式不对', trigger: 'blur' }
]
const add = () => model.emails.push({ id: ++seed, value: '' })
const remove = (index: number) => model.emails.splice(index, 1)
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
v-for="(item, index) in model.emails"
:key="item.id"
:label="`邮箱 ${index + 1}`"
:prop="`emails.${index}.value`"
:rules="emailRules"
>
<div class="email-row">
<NsInput v-model="item.value" />
<NsButton @click="remove(index)">删除</NsButton>
</div>
</NsFormItem>
<NsFormItem>
<NsSpace wrap>
<NsButton @click="add">新增一项</NsButton>
<NsButton type="primary" @click="submit">提交</NsButton>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
<style scoped>
.email-row {
display: flex;
gap: var(--ns-spacing-2);
}
</style>
表单项卸载后自动从表单里移除,validate() 不会再校验它;prop 变化时会重新记录初始值并清掉错误提示。
显示服务端返回的错误
表单项的 error 属性有值时,直接显示成错误状态和这段提示,不经过规则。用来显示接口返回的字段错误;改成空字符串或 undefined 后错误消失。
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsInput } from '@ns/ui'
const model = reactive({ username: '' })
const serverError = ref('')
// 用 setTimeout 模拟保存接口,返回字段错误
const api = {
save: (_data: { username: string }) =>
new Promise<{ fieldErrors?: Record<string, string> }>((resolve) => {
setTimeout(() => resolve({ fieldErrors: { username: '用户名已被占用' } }), 500)
})
}
const save = async () => {
const res = await api.save(model)
serverError.value = res.fieldErrors?.username ?? ''
}
</script>
<template>
<NsForm :model="model" @submit.prevent>
<NsFormItem label="用户名" prop="username" :error="serverError">
<NsInput v-model="model.username" @input="serverError = ''" />
</NsFormItem>
<NsFormItem>
<NsButton type="primary" @click="save">保存</NsButton>
</NsFormItem>
</NsForm>
</template>
标签位置
label-position 可选 right(默认,标签右对齐)、left(左对齐)、top(标签在控件上方,这时 label-width 不起作用)、float(浮动标签,见下一节)。切换下面的选项看四种效果,标签长短不一时 left、right 的区别最明显:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsForm, NsFormItem, NsInput, NsSegmented, NsSelect } from '@ns/ui'
import type { FormLabelPosition } from '@ns/ui'
const position = ref<string | number>('right')
const model = reactive({ name: '', region: '', address: '' })
const options = [
{ label: '右对齐(right)', value: 'right' },
{ label: '左对齐(left)', value: 'left' },
{ label: '上方(top)', value: 'top' },
{ label: '浮动(float)', value: 'float' }
]
const regions = [
{ label: '华东', value: 'east' },
{ label: '华北', value: 'north' }
]
</script>
<template>
<NsSegmented v-model="position" :options="options" />
<NsForm
:model="model"
:label-position="position as FormLabelPosition"
label-width="100px"
style="margin-top: 16px"
@submit.prevent
>
<NsFormItem label="名称" prop="name">
<NsInput v-model="model.name" />
</NsFormItem>
<NsFormItem label="活动区域" prop="region">
<NsSelect v-model="model.region" :options="regions" />
</NsFormItem>
<NsFormItem label="详细的收货地址" prop="address">
<NsInput v-model="model.address" />
</NsFormItem>
</NsForm>
</template>
表单项也有 label-position,优先于表单的设置。下面的表单是 right,第二项单独设成 top:
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInput, NsTextarea } from '@ns/ui'
const model = reactive({ title: '', content: '' })
</script>
<template>
<NsForm :model="model" label-width="80px" @submit.prevent>
<NsFormItem label="标题" prop="title">
<NsInput v-model="model.title" />
</NsFormItem>
<NsFormItem label="正文(标签在上方)" prop="content" label-position="top">
<NsTextarea v-model="model.content" :rows="3" />
</NsFormItem>
</NsForm>
</template>
浮动标签
label-position="float":标签放在输入框里当占位文字,获得焦点、有值或下拉面板打开时缩小,浮到上边框上。适合查询条件这类横向排列、放不下标签列的表单(SearchForm 也支持)。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInput, NsSelect } from '@ns/ui'
const model = reactive({ deptName: '', status: '' })
const statusOptions = [
{ label: '正常', value: '0' },
{ label: '停用', value: '1' }
]
</script>
<template>
<NsForm :model="model" label-position="float" inline>
<NsFormItem label="部门名称" prop="deptName">
<NsInput v-model="model.deptName" clearable />
</NsFormItem>
<NsFormItem label="部门状态" prop="status">
<NsSelect v-model="model.status" :options="statusOptions" clearable />
</NsFormItem>
</NsForm>
</template>
- 支持带边框的输入类控件:Input、Textarea、InputNumber、AutoComplete、InputTag、Mentions、Select、Cascader、TreeSelect、DatePicker、TimePicker、IconPicker。其他控件(复选框、单选框、开关、滑块、评分、颜色选择器、上传等)没有可以放标签的输入框,这一项自动按
top排。 - 要写
prop:表单项按prop从model里取值判断有没有值。没写prop时判断不了,标签一直浮在边框上。 - 标签在框里时,控件自己的占位文字先藏起来;获得焦点、标签浮上去以后再显示,可以用占位文字写输入提示,例如“例如:研发部”。
- 这几种情况标签一直浮在边框上,因为框里放不下:日期范围(有两段占位文字)、InputNumber(左边是减号按钮)、带前缀图标的 Input、AutoComplete、DatePicker。
- 获得焦点和面板打开时标签变成主色,校验失败时变成红色,禁用时变淡。
- 单独一项也能用:在
NsFormItem上写label-position="float",覆盖表单的设置;反过来,浮动标签的表单里某一项也可以写label-position="top"。
下面把这几种情况放在一起:第一列是标签在框里、有值后浮起的控件;第二列是标签一直浮在边框上的控件;最后一项是开关,没有输入框,按 top 排。“部门编码”带了校验,输入后删空再点到别处,标签变红。
<script setup lang="ts">
import { reactive } from 'vue'
import {
NsDatePicker,
NsForm,
NsFormItem,
NsInput,
NsInputNumber,
NsSelect,
NsSwitch,
NsTextarea,
NsTimePicker
} from '@ns/ui'
import type { FormRule } from '@ns/ui'
const model = reactive({
deptName: '',
code: '',
status: '',
time: undefined as string | undefined,
remark: '',
count: 10,
date: null as Date | null,
range: null as [Date, Date] | null,
enabled: true
})
const statusOptions = [
{ label: '正常', value: '0' },
{ label: '停用', value: '1' }
]
const rules: Record<string, FormRule[]> = {
code: [{ required: true, message: '请输入部门编码', trigger: 'blur' }]
}
</script>
<template>
<NsForm :model="model" :rules="rules" label-position="float" @submit.prevent>
<div class="float-grid">
<div>
<NsFormItem label="部门名称" prop="deptName">
<NsInput v-model="model.deptName" placeholder="例如:研发部" clearable />
</NsFormItem>
<NsFormItem label="部门编码" prop="code">
<NsInput v-model="model.code" />
</NsFormItem>
<NsFormItem label="部门状态" prop="status">
<NsSelect v-model="model.status" :options="statusOptions" clearable />
</NsFormItem>
<NsFormItem label="上班时间" prop="time">
<NsTimePicker v-model="model.time" format="HH:mm" />
</NsFormItem>
<NsFormItem label="备注" prop="remark">
<NsTextarea v-model="model.remark" />
</NsFormItem>
</div>
<div>
<NsFormItem label="人数" prop="count">
<NsInputNumber v-model="model.count" />
</NsFormItem>
<NsFormItem label="成立日期" prop="date">
<NsDatePicker v-model="model.date" />
</NsFormItem>
<NsFormItem label="考核周期" prop="range">
<NsDatePicker v-model="model.range" type="daterange" />
</NsFormItem>
<NsFormItem label="是否启用" prop="enabled">
<NsSwitch v-model="model.enabled" />
</NsFormItem>
</div>
</div>
</NsForm>
</template>
<style scoped>
.float-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
column-gap: var(--ns-spacing-6);
}
</style>
标签宽度
label-width 可以是 CSS 长度字符串或数字(按 px 算)。设成 'auto' 时,所有标签取最长那个的宽度,控件左边对齐,标签文字变化时会重新计算。表单项自己的 label-width 优先,表单项上写 label-width="auto" 表示这一项按标签实际宽度显示。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInput } from '@ns/ui'
const model = reactive({ name: '', address: '' })
</script>
<template>
<NsForm :model="model" label-width="auto" @submit.prevent>
<NsFormItem label="名称"><NsInput v-model="model.name" /></NsFormItem>
<NsFormItem label="详细的收货地址"><NsInput v-model="model.address" /></NsFormItem>
</NsForm>
</template>
数字写法和表单项单独设置:表单是 :label-width="120"(120px),第二项单独写 60px,第三项写 auto 按自己的文字宽度显示。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInput } from '@ns/ui'
const model = reactive({ a: '', b: '', c: '' })
</script>
<template>
<NsForm :model="model" :label-width="120" @submit.prevent>
<NsFormItem label="跟随表单 120px"><NsInput v-model="model.a" /></NsFormItem>
<NsFormItem label="60px" label-width="60px"><NsInput v-model="model.b" /></NsFormItem>
<NsFormItem label="auto" label-width="auto"><NsInput v-model="model.c" /></NsFormItem>
</NsForm>
</template>
行内表单
inline 为 true 时表单项横向排列,适合放在列表上方的查询条件。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsButton, NsForm, NsFormItem, NsInput, NsMessage, NsSelect } from '@ns/ui'
const query = reactive({ approver: '', region: '' })
const regions = [
{ label: '华东', value: 'east' },
{ label: '华北', value: 'north' },
{ label: '华南', value: 'south' }
]
const search = () => {
const region = regions.find((item) => item.value === query.region)?.label ?? '全部'
NsMessage.info(`查询:审批人“${query.approver || '全部'}”,区域“${region}”`)
}
</script>
<template>
<NsForm :model="query" inline @submit.prevent>
<NsFormItem label="审批人"><NsInput v-model="query.approver" /></NsFormItem>
<NsFormItem label="区域">
<NsSelect v-model="query.region" :options="regions" style="width: 200px" />
</NsFormItem>
<NsFormItem><NsButton type="primary" @click="search">查询</NsButton></NsFormItem>
</NsForm>
</template>
行内表单也能配合其他标签位置。下面是 label-position="top" 的行内表单,“关键字”必填,点进去再点到别处,提示照常显示在控件下方。查询条件要带“查询”“重置”按钮、并且按钮要和控件底边对齐时,用 SearchForm。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsDatePicker, NsForm, NsFormItem, NsInput, NsSelect } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const query = reactive({ keyword: '', status: '', period: null as [Date, Date] | null })
const statusOptions = [
{ label: '待审批', value: 'pending' },
{ label: '已通过', value: 'approved' }
]
const rules: Record<string, FormRule[]> = {
keyword: [{ required: true, message: '请输入关键字', trigger: 'blur' }]
}
</script>
<template>
<NsForm :model="query" :rules="rules" inline label-position="top" @submit.prevent>
<NsFormItem label="关键字" prop="keyword">
<NsInput v-model="query.keyword" style="width: 180px" />
</NsFormItem>
<NsFormItem label="状态" prop="status">
<NsSelect v-model="query.status" :options="statusOptions" style="width: 140px" />
</NsFormItem>
<NsFormItem label="申请时间" prop="period">
<NsDatePicker v-model="query.period" type="daterange" style="width: 260px" />
</NsFormItem>
</NsForm>
</template>
尺寸
表单的 size 统一设置里面控件的尺寸,表单项的 size 可以单独覆盖一行。控件自己写了 size 时以控件为准,也就是 控件 → 表单项 → 表单 → 'default'。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInput, NsInputNumber } from '@ns/ui'
const model = reactive({ name: '', count: 1 })
</script>
<template>
<NsForm :model="model" size="small" @submit.prevent>
<NsFormItem label="名称"><NsInput v-model="model.name" /></NsFormItem>
<NsFormItem label="数量" size="large"><NsInputNumber v-model="model.count" /></NsFormItem>
</NsForm>
</template>
切换 large、default、small,表单里的控件和标签文字一起变。NsButton 不跟随表单的尺寸(也不受表单禁用影响),下面的按钮自己绑定了同一个 size:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import {
NsButton,
NsDatePicker,
NsForm,
NsFormItem,
NsInput,
NsInputNumber,
NsRadio,
NsRadioGroup,
NsSegmented,
NsSelect,
NsSpace,
NsSwitch
} from '@ns/ui'
import type { FormSize } from '@ns/ui'
const size = ref<string | number>('default')
const sizes = [
{ label: '大(large)', value: 'large' },
{ label: '默认(default)', value: 'default' },
{ label: '小(small)', value: 'small' }
]
const model = reactive({
name: '',
region: '',
date: null as Date | null,
count: 1,
type: 'a',
enabled: true
})
const regions = [
{ label: '华东', value: 'east' },
{ label: '华北', value: 'north' }
]
</script>
<template>
<NsSegmented v-model="size" :options="sizes" />
<NsForm
:model="model"
:size="size as FormSize"
label-width="80px"
style="margin-top: 16px"
@submit.prevent
>
<NsFormItem label="名称"><NsInput v-model="model.name" /></NsFormItem>
<NsFormItem label="区域">
<NsSelect v-model="model.region" :options="regions" />
</NsFormItem>
<NsFormItem label="日期"><NsDatePicker v-model="model.date" /></NsFormItem>
<NsFormItem label="数量"><NsInputNumber v-model="model.count" /></NsFormItem>
<NsFormItem label="类型">
<NsRadioGroup v-model="model.type">
<NsRadio value="a" label="类型 A" />
<NsRadio value="b" label="类型 B" />
</NsRadioGroup>
</NsFormItem>
<NsFormItem label="启用"><NsSwitch v-model="model.enabled" /></NsFormItem>
<NsFormItem>
<NsSpace wrap>
<NsButton type="primary" :size="size as FormSize">保存</NsButton>
<NsButton :size="size as FormSize">取消</NsButton>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
禁用
disabled 为 true 时,表单里所有接入的控件都被禁用,标签变成禁用色。表单禁用优先:控件上写 :disabled="false" 也不能单独放开。NsButton 不受表单禁用影响。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInput, NsSwitch } from '@ns/ui'
const model = reactive({ name: '张三', delivery: true })
</script>
<template>
<NsForm :model="model" disabled @submit.prevent>
<NsFormItem label="姓名"><NsInput v-model="model.name" /></NsFormItem>
<NsFormItem label="配送"><NsSwitch v-model="model.delivery" /></NsFormItem>
</NsForm>
</template>
用开关切换整张表单的禁用状态,“备注”上写了 :disabled="false",表单禁用时它也跟着禁用;底部的按钮不受影响:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import {
NsButton,
NsCheckbox,
NsDatePicker,
NsForm,
NsFormItem,
NsInput,
NsMessage,
NsRate,
NsSelect,
NsSpace,
NsSwitch,
NsTextarea
} from '@ns/ui'
const disabled = ref(true)
const model = reactive({
name: '张三',
city: 'sh',
birthday: new Date(1990, 4, 20) as Date | null,
vip: true,
score: 4,
agree: true,
remark: '老客户'
})
const cities = [
{ label: '北京', value: 'bj' },
{ label: '上海', value: 'sh' }
]
</script>
<template>
<NsSpace>
<span>禁用表单</span>
<NsSwitch v-model="disabled" />
</NsSpace>
<NsForm
:model="model"
:disabled="disabled"
label-width="80px"
style="margin-top: 16px"
@submit.prevent
>
<NsFormItem label="姓名"><NsInput v-model="model.name" /></NsFormItem>
<NsFormItem label="城市"><NsSelect v-model="model.city" :options="cities" /></NsFormItem>
<NsFormItem label="生日"><NsDatePicker v-model="model.birthday" /></NsFormItem>
<NsFormItem label="会员"><NsSwitch v-model="model.vip" /></NsFormItem>
<NsFormItem label="评分"><NsRate v-model="model.score" /></NsFormItem>
<NsFormItem label="协议">
<NsCheckbox v-model="model.agree">已签署</NsCheckbox>
</NsFormItem>
<NsFormItem label="备注">
<NsTextarea v-model="model.remark" :disabled="false" />
</NsFormItem>
<NsFormItem>
<NsButton type="primary" @click="NsMessage.info('按钮不受表单禁用影响')">编辑</NsButton>
</NsFormItem>
</NsForm>
</template>
错误提示和必填星号
show-message为false时不显示错误文字,只把控件边框染红。inline-message为true时错误文字显示在控件右侧,默认在下方。- 这两个属性表单项上也有,表单项的优先。
- 有必填规则的表单项,标签前显示红色星号;
hide-required-asterisk可以隐藏。 label-suffix加在每个标签文字后面,比如中文冒号':'。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInput } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const model = reactive({ name: '' })
const rules: Record<string, FormRule[]> = {
name: [{ required: true, message: '请输入用户名', trigger: 'blur' }]
}
</script>
<template>
<NsForm :model="model" :rules="rules" inline-message label-suffix=":" @submit.prevent>
<NsFormItem label="用户名" prop="name"><NsInput v-model="model.name" /></NsFormItem>
</NsForm>
</template>
勾选上面的选项看各自的效果。打开页面时已经校验过一次,两个字段都显示着错误;“备注”这一项单独写了 :show-message="true",表单关掉错误文字后它仍然显示:
<script setup lang="ts">
import { onMounted, reactive, ref } from 'vue'
import { NsCheckbox, NsForm, NsFormItem, NsInput, NsSpace } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const showMessage = ref(true)
const inlineMessage = ref(false)
const hideAsterisk = ref(false)
const withSuffix = ref(false)
const model = reactive({ name: '', remark: '' })
const rules: Record<string, FormRule[]> = {
name: [{ required: true, message: '请输入用户名' }],
remark: [{ required: true, message: '请填写备注' }]
}
onMounted(() => {
formRef.value?.validate()
})
</script>
<template>
<NsSpace wrap>
<NsCheckbox v-model="showMessage">show-message</NsCheckbox>
<NsCheckbox v-model="inlineMessage">inline-message</NsCheckbox>
<NsCheckbox v-model="hideAsterisk">hide-required-asterisk</NsCheckbox>
<NsCheckbox v-model="withSuffix">label-suffix=":"</NsCheckbox>
</NsSpace>
<NsForm
ref="formRef"
:model="model"
:rules="rules"
:show-message="showMessage"
:inline-message="inlineMessage"
:hide-required-asterisk="hideAsterisk"
:label-suffix="withSuffix ? ':' : ''"
style="margin-top: 16px"
@submit.prevent
>
<NsFormItem label="用户名" prop="name">
<NsInput v-model="model.name" style="width: 240px" />
</NsFormItem>
<NsFormItem label="备注" prop="remark" :show-message="true">
<NsInput v-model="model.remark" style="width: 240px" />
</NsFormItem>
</NsForm>
</template>
自定义标签
表单项的 label 插槽可以放任意内容,写了插槽时 label 属性和 label-suffix 都不显示。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsFormItem, NsIcon, NsInput } from '@ns/ui'
const model = reactive({ email: '' })
</script>
<template>
<NsFormItem prop="email">
<template #label> 邮箱 <NsIcon name="help" title="用于接收通知" /> </template>
<NsInput v-model="model.email" />
</NsFormItem>
</template>
单独校验或重置一项
validateField(props) 只校验指定字段,返回值和 validate() 相同。也可以拿到表单项的 ref,调用它自己的 validate()、resetField()、clearValidation()。
await formRef.value?.validateField(['email', 'phone'])
formRef.value?.resetFields('email')
formRef.value?.clearValidate(['email'])
下面两个字段的初始值都不合规。上面一排按钮调用表单的方法,只处理“邮箱”;下面一排调用“手机号”表单项自己的方法:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsInput, NsMessage, NsSpace } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const phoneItemRef = ref<InstanceType<typeof NsFormItem>>()
const model = reactive({ email: 'abc', phone: '123' })
const rules: Record<string, FormRule[]> = {
email: [{ type: 'email', message: '邮箱格式不对' }],
phone: [{ pattern: /^1\d{10}$/, message: '手机号格式不对' }]
}
const validateEmail = async () => {
const { valid } = await formRef.value!.validateField('email')
NsMessage[valid ? 'success' : 'error'](`邮箱${valid ? '通过' : '没通过'}`)
}
const validatePhone = async () => {
const { valid, error } = await phoneItemRef.value!.validate()
NsMessage[valid ? 'success' : 'error'](valid ? '手机号通过' : `手机号:${error}`)
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" label-width="80px" @submit.prevent>
<NsFormItem label="邮箱" prop="email">
<NsInput v-model="model.email" />
</NsFormItem>
<NsFormItem ref="phoneItemRef" label="手机号" prop="phone">
<NsInput v-model="model.phone" />
</NsFormItem>
<NsFormItem>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsButton @click="validateEmail">validateField('email')</NsButton>
<NsButton @click="formRef?.resetFields('email')">resetFields('email')</NsButton>
<NsButton @click="formRef?.clearValidate(['email'])">clearValidate(['email'])</NsButton>
</NsSpace>
<NsSpace wrap>
<NsButton @click="validatePhone">validate()</NsButton>
<NsButton @click="phoneItemRef?.resetField()">resetField()</NsButton>
<NsButton @click="phoneItemRef?.clearValidation()">clearValidation()</NsButton>
</NsSpace>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
校验事件
每个表单项校验完都会触发自己的 validate 事件(参数是 valid、error),表单的 validate 事件还多带一个 prop。失焦、值变化时的自动校验和调用方法时的校验都会触发。在下面的输入框里输入、删空、点到别处,看事件记录:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsForm, NsFormItem, NsInput } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const model = reactive({ name: '', city: '' })
const rules: Record<string, FormRule[]> = {
name: [{ required: true, message: '请输入姓名', trigger: 'blur' }],
city: [{ required: true, message: '请输入城市', trigger: 'change' }]
}
const logs = ref<string[]>([])
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onFormValidate = (prop: string, valid: boolean, error: string | undefined) => {
log(`NsForm validate:${prop},${valid ? '通过' : `没通过(${error})`}`)
}
const onItemValidate = (valid: boolean, error: string | undefined) => {
log(`城市表单项 validate:${valid ? '通过' : `没通过(${error})`}`)
}
</script>
<template>
<NsForm :model="model" :rules="rules" @validate="onFormValidate" @submit.prevent>
<NsFormItem label="姓名" prop="name">
<NsInput v-model="model.name" placeholder="失焦时校验" />
</NsFormItem>
<NsFormItem label="城市" prop="city" @validate="onItemValidate">
<NsInput v-model="model.city" placeholder="值变化时校验" />
</NsFormItem>
</NsForm>
<div class="event-log">
<div v-for="(item, index) in logs" :key="index">{{ item }}</div>
<div v-if="!logs.length">还没有触发事件</div>
</div>
</template>
<style scoped>
.event-log {
margin-top: 12px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
line-height: 1.8;
}
</style>
自定义控件接入表单
自己写的控件用 useFormItem 接入:传入控件自己的 disabled、size、绑定值和 validateEvent,拿回合并后的禁用、尺寸和触发校验的方法。传了 value 就会在值变化时自动触发 change 校验;失焦时自己调用 validate('blur')。inputAttrs(id、aria-invalid、aria-describedby)放在原生 input 上,标签的 for 会指向它;控件允许使用者自己传 id 时,把它作为 id 参数传进来(如 id: () => attrs.id),inputAttrs.id 和标签的 for 就都用使用者的 id。
<script setup lang="ts">
import { useFormItem } from '@ns/ui'
import type { FormSize } from '@ns/ui'
const props = withDefaults(
defineProps<{
modelValue?: string
disabled?: boolean
size?: FormSize
validateEvent?: boolean
}>(),
// size 的默认值必须是 undefined,才能跟随表单
{ modelValue: '', disabled: false, size: undefined, validateEvent: true }
)
const emit = defineEmits<{ 'update:modelValue': [value: string] }>()
const { formDisabled, formSize, validate, inputAttrs } = useFormItem({
disabled: () => props.disabled,
size: () => props.size,
value: () => props.modelValue,
validateEvent: () => props.validateEvent
})
const onInput = (event: Event) => {
emit('update:modelValue', (event.target as HTMLInputElement).value)
}
</script>
<template>
<input
v-bind="inputAttrs"
:class="['my-input', `my-input--${formSize}`]"
:value="modelValue"
:disabled="formDisabled"
@input="onInput"
@blur="validate('blur')"
/>
</template>
根元素不是原生 input(比如 role="switch" 的 div)时,传 labelable: false,把返回的 fieldAttrs(aria-labelledby 等)放在根元素上。值是数组或对象、会被原地修改时传 deep: true。
NsForm Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| model | Record<string, unknown> | - | 表单数据对象。校验从这里按 prop 读值,重置往这里写值 |
| rules | Record<string, FormRule[]> | - | 校验规则,键是表单项的 prop |
| inline | boolean | false | 是否行内表单 |
| labelPosition | 'left' | 'right' | 'top' | 'float' | 'right' | 标签的位置和对齐方式;float 是浮动标签 |
| labelWidth | string | number | '80px' | 标签宽度。数字按 px 算;'auto' 时取所有标签里最宽的 |
| labelSuffix | string | '' | 加在标签文字后面的后缀 |
| hideRequiredAsterisk | boolean | false | 是否隐藏必填项标签前的星号 |
| showMessage | boolean | true | 是否显示错误文字 |
| inlineMessage | boolean | false | 错误文字是否显示在控件右侧 |
| size | 'large' | 'default' | 'small' | - | 表单里控件的尺寸。不传时跟随 NsConfigProvider,都没有时是 'default' |
| disabled | boolean | false | 是否禁用表单里的所有控件 |
NsFormItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| prop | string | - | 字段名,支持 a.b、a[0].b、a.0.b 路径。不写时不参与校验和重置 |
| label | string | - | 标签文字 |
| labelWidth | string | number | - | 这一项的标签宽度,优先于表单的 labelWidth;'auto' 表示按文字实际宽度 |
| labelPosition | 'left' | 'right' | 'top' | 'float' | - | 这一项的标签位置,优先于表单的 labelPosition |
| required | boolean | undefined | 是否必填。不传时按规则判断,传了会覆盖规则里的 required |
| rules | FormRule[] | - | 这一项的规则,和表单 rules 里同名字段的规则合并 |
| error | string | - | 错误提示。有值时直接显示成错误状态,不经过规则 |
| showMessage | boolean | - | 是否显示错误文字。不传时跟随表单 |
| inlineMessage | boolean | - | 错误文字是否显示在控件右侧。不传时跟随表单 |
| size | 'large' | 'default' | 'small' | - | 这一项里控件的尺寸。不传时跟随表单,再跟随 NsConfigProvider |
NsForm Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| validate | (prop: string, valid: boolean, error: string | undefined) | 任何一个表单项校验完成后触发,包括失焦、值变化时的自动校验 |
NsFormItem Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| validate | (valid: boolean, error: string | undefined) | 这一项校验完成后触发 |
NsForm Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsFormItem |
NsFormItem Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 控件 |
| label | - | 自定义标签内容,写了它时 label 和 labelSuffix 不显示 |
NsForm 方法
| 名称 | 类型 | 说明 |
|---|---|---|
| validate | (callback?: FormValidateCallback) => Promise<FormValidateResult> | 校验所有带 prop 的表单项。不通过时也是 resolve,valid 为 false |
| validateField | (props: string | string[], callback?: FormValidateCallback) => Promise<FormValidateResult> | 只校验指定字段 |
| resetFields | (props?: string | string[]) => void | 把字段恢复成初始值并清掉错误提示。不传时处理全部 |
| clearValidate | (props?: string | string[]) => void | 只清掉错误提示。不传时处理全部 |
NsFormItem 方法
| 名称 | 类型 | 说明 |
|---|---|---|
| validate | (trigger?: 'blur' | 'change') => Promise<FormItemValidateResult> | 校验这一项。传 trigger 时只执行这种触发方式的规则 |
| resetField | () => Promise<void> | 恢复初始值,下一个 tick 清掉错误提示 |
| clearValidation | () => void | 清掉错误提示 |
useFormItem
参数(UseFormItemOptions) | 类型 | 说明 |
|---|---|---|
| disabled | MaybeRefOrGetter<boolean | undefined> | 控件自己的 disabled |
| size | MaybeRefOrGetter<FormSize | undefined> | 控件自己的 size,控件的默认值要是 undefined |
| value | () => unknown | 传了就在值变化时触发 change 校验 |
| deep | boolean | 值是数组、对象并会被原地修改时传 true |
| validateEvent | MaybeRefOrGetter<boolean | undefined> | 为 false 时不触发校验 |
| labelable | boolean | 有原生 input / textarea 能被 <label for> 关联时为 true(默认) |
| id | MaybeRefOrGetter<string | undefined> | 使用者在控件上传的 id,一般写 () => attrs.id。有值时 inputAttrs.id 用它,标签的 for 也指向它 |
| 返回值 | 类型 | 说明 |
|---|---|---|
| formDisabled | ComputedRef<boolean> | 控件自己禁用或表单禁用 |
| formSize | ComputedRef<FormSize> | 按 控件 → 表单项 → 表单 → NsConfigProvider → 'default' 取到的尺寸 |
| validate | (trigger: 'blur' | 'change') => void | 触发所在表单项的校验。不在表单项里或 validateEvent 为 false 时什么都不做 |
| inputAttrs | ComputedRef<FormInputAttrs> | 放在原生 input 上:id、aria-invalid、aria-describedby |
| fieldAttrs | ComputedRef<Record<string, unknown>> | 放在 role="xxx" 的根元素上:aria-labelledby、aria-invalid、aria-describedby |
| form | FormContext | undefined | 所在表单的上下文 |
| formItem | FormItemInjection | undefined | 所在表单项的上下文 |
类型
import type {
FormProps,
FormItemProps,
FormRule,
FormSize,
FormLabelPosition,
FormValidateTrigger,
FormValidateResult,
FormItemValidateResult,
FormValidateCallback,
UseFormItemOptions
} from '@ns/ui'
type FormSize = 'large' | 'default' | 'small'
type FormLabelPosition = 'left' | 'right' | 'top' | 'float'
type FormValidateTrigger = 'blur' | 'change'
interface FormRule {
required?: boolean
message?: string
/** 不写时失焦、值变化和手动校验都会执行 */
trigger?: FormValidateTrigger | FormValidateTrigger[]
/** 字符串、数组按长度比较,数字按数值比较 */
min?: number
max?: number
pattern?: RegExp
validator?: (
rule: FormRule,
value: unknown,
callback: (error?: string | Error) => void
) => void | boolean | Promise<unknown>
type?: 'string' | 'number' | 'boolean' | 'email' | 'url' | 'array'
}
interface FormValidateResult {
valid: boolean
/** 没通过的字段和它们的错误提示 */
errors: Record<string, string[]>
}
interface FormItemValidateResult {
valid: boolean
error?: string
}
type FormValidateCallback = (valid: boolean, errors?: Record<string, string[]>) => void
注意事项
validate()不会 reject,校验不通过也是 resolve{ valid: false, errors },要判断valid;不要写成try { await validate() } catch {}。- 用程序修改
model(比如接口回填)也会触发change规则,回填了空值的必填项会立刻显示错误。 resetFields()恢复的是表单项挂载时的值,不是空值。先挂载、后从接口拿到数据时,重置会回到挂载时的初始值。编辑已有数据的表单,可以等数据加载完再渲染表单(v-if),这样回填不会触发校验,重置也会回到加载的数据。- 重置时控件改值引起的
change校验会被拦下,不会刚重置就显示错误。 - 表单禁用时控件的
:disabled="false"不能单独放开某一项。 - 没写
label的表单项(例如放提交按钮的一行)会留出标签列的宽度,和上面的控件左边对齐;标签在上方、浮动标签、行内表单和嵌在别的表单项里的不留。不想留时在这一项上写label-width="0"。 - 只有
prop的表单项参与validate()、resetFields();表单rules的键要和prop一字不差。 - 自定义
validator声明了第三个参数callback却没调用、也没返回 Promise 或 boolean 时,校验一直不结束,validate()也会一直等。 NsForm渲染原生<form>,不拦截提交;只有一个单行输入框时按回车会刷新页面,要加@submit.prevent。- 没有
error插槽,错误提示的内容只能是文字;也没有“校验失败时滚动到第一个错误”的功能。 - 错误提示绝对定位在控件下方,占用表单项的下边距;错误文字很长时可以用
inline-message。 - 浮动标签浮起来后有一半在控件上边框的上面(约 8px),放在没有内边距、又设了
overflow: hidden的容器顶部时会被裁掉,给容器留一点上内边距。 - 浮动标签压住的那一小段边框用
--ns-bg-color(页面底色)遮住,只遮边框那一条,不盖住控件里面。表单放在别的底色上(例如有底色的卡片)时,要把这个变量改成那个底色,否则标签两侧会露出一截不同颜色。
优化点
- [ ] 支持
error插槽,自定义错误提示的内容 - [ ] 支持校验失败时滚动到第一个错误(
scrollToError、scrollToField) - [ ] 支持嵌套表单