RForm 与 useForm
RForm 包装 Naive UI Form,并用 Spin 显示提交或查询状态。用 NFormItem.path 匹配 model 的字段,在输入组件上更新值。
tsx
import { RForm, useForm } from '@/components'
import { NButton, NFormItem, NInput } from 'naive-ui'
import { defineComponent } from 'vue'
export default defineComponent({
setup() {
const [register, form] = useForm(
{ name: '' },
{
name: {
key: 'name',
required: true,
message: '请输入姓名',
trigger: 'blur',
},
},
)
const rules = form.formRules()
const submit = async () => {
await form.validate()
console.log(form.formConditionRef.value.name)
}
return () => (
<RForm
onRegister={register}
model={form.formConditionRef.value}
rules={rules}
>
<NFormItem label="姓名" path="name">
<NInput
value={form.formConditionRef.value.name}
onUpdateValue={(name) => form.updateFormCondition({ name })}
/>
</NFormItem>
<NButton onClick={() => void submit().catch(() => {})}>
校验并提交
</NButton>
<NButton onClick={() => form.reset()}>重置</NButton>
</RForm>
)
},
})交互示例
查看示例源码
tsx
import { useI18n } from '@/hooks'
import { RForm, useForm } from '@ray-template/ui/form'
import {
NButton,
NCard,
NDatePicker,
NFlex,
NFormItemGi,
NGrid,
NInput,
NInputNumber,
NRadio,
NRadioGroup,
} from 'naive-ui'
import DemoPage from '../components/DemoPage'
import DemoResult from '../components/DemoResult'
interface FormModel {
name: string | null
age: number | null
gender: string | null
date: number | null
remark: string | null
}
export default defineComponent({
name: 'RFormDemo',
setup() {
const { t } = useI18n('demoDetails')
const rules = computed(() => ({
name: {
required: true,
message: t('form.nameRequired'),
trigger: ['blur', 'change'],
key: 'name',
},
age: {
required: true,
message: t('form.ageRequired'),
trigger: ['blur', 'change'],
type: 'number' as const,
min: 0,
max: 120,
},
date: {
required: true,
message: t('form.dateRequired'),
trigger: ['blur', 'change'],
type: 'number' as const,
},
gender: {
required: true,
message: t('form.genderRequired'),
trigger: 'change',
},
}))
const [
register,
{
validate,
restoreValidation,
validateTargetField,
reset,
formConditionRef: model,
},
] = useForm<FormModel>({
name: null,
age: null,
gender: null,
date: null,
remark: null,
})
const ids = { name: useId(), age: useId(), remark: useId() }
const submission = ref<string>()
const status = ref('form.waiting')
const finish = () => {
submission.value = JSON.stringify(model.value, null, 2)
status.value = 'form.submitted'
}
const submit = async (event: Event) => {
event.preventDefault()
try {
await validate()
finish()
} catch {
submission.value = void 0
status.value = 'form.invalid'
}
}
return () => (
<DemoPage title={t('form.title')} description={t('form.intro')}>
<div class="r-demo-grid">
<NCard title={t('form.profile')}>
<RForm
model={model.value}
rules={rules.value}
onRegister={register}
onSubmit={submit}
submitWhenEnter
onFinish={finish}
>
<NGrid cols="1 480:2" responsive="self" xGap={16}>
<NFormItemGi
label={t('form.name')}
labelProps={{ for: ids.name }}
path="name"
>
<NInput
v-model:value={model.value.name}
inputProps={{ id: ids.name }}
/>
</NFormItemGi>
<NFormItemGi
label={t('form.age')}
labelProps={{ for: ids.age }}
path="age"
>
<NInputNumber
v-model:value={model.value.age}
inputProps={{ id: ids.age }}
min={0}
max={120}
/>
</NFormItemGi>
<NFormItemGi label={t('form.date')} path="date">
<NDatePicker v-model:value={model.value.date} type="date" />
</NFormItemGi>
<NFormItemGi label={t('form.gender')} path="gender">
<NRadioGroup
v-model:value={model.value.gender}
aria-label={t('form.gender')}
>
<NRadio value="female">{t('form.female')}</NRadio>
<NRadio value="male">{t('form.male')}</NRadio>
</NRadioGroup>
</NFormItemGi>
<NFormItemGi
label={t('form.notes')}
labelProps={{ for: ids.remark }}
span={2}
>
<NInput
type="textarea"
v-model:value={model.value.remark}
inputProps={{ id: ids.remark }}
/>
</NFormItemGi>
</NGrid>
<NFlex>
<NButton type="primary" attrType="submit">
{t('form.submit')}
</NButton>
<NButton
onClick={() => {
reset({
name: 'Ray',
age: 28,
gender: 'female',
date: new Date(1998, 6, 12).getTime(),
remark: null,
})
submission.value = void 0
status.value = 'form.waiting'
}}
>
{t('form.sample')}
</NButton>
<NButton
onClick={() => {
void validateTargetField('name')
.then(() => {
status.value = 'form.nameValid'
})
.catch(() => {
status.value = 'form.nameRequired'
})
}}
>
{t('form.validateName')}
</NButton>
<NButton
onClick={() => {
restoreValidation()
status.value = 'form.waiting'
}}
>
{t('form.clear')}
</NButton>
<NButton
onClick={() => {
reset()
submission.value = void 0
status.value = 'form.waiting'
}}
>
{t('form.reset')}
</NButton>
</NFlex>
</RForm>
</NCard>
<NCard title={t('form.payload')}>
<DemoResult
label={t(status.value)}
error={status.value === 'form.invalid'}
>
<pre>{submission.value ?? t('empty')}</pre>
</DemoResult>
</NCard>
</div>
</DemoPage>
)
},
})属性与事件
继承 NForm 的公开属性和 onSubmit 事件,默认插槽传给 NForm。
| 属性 | 默认 | 说明 |
|---|---|---|
loading | false | 外层 Spin 状态,由调用方开关。 |
loadingDescription | 无 | 加载说明。 |
autocomplete | 'off' | 挂载时写到表单 DOM。 |
submitWhenEnter | false | 可动态启用单行输入的 Enter 提交;校验成功后调用 onFinish,加载中或上次提交未结束时忽略重复提交。 |
onFinish | 无 | Enter 校验完成回调。自定义提交按钮要自行调用 validate() 并执行提交。 |
onRegister(inst) | 无 | 挂载后传出 Naive UI Form 实例。接受单函数或回调数组。 |
输入法确认、多行换行、组合框、按钮、修饰键和已被控件 preventDefault() 的 Enter 保留原生行为。键盘提交的校验失败由表单展示;onFinish 的异常交给 Vue 的错误处理。调用 useForm.validate() 仍需处理其 Promise 拒绝。组件没有把 Form 方法直接暴露为模板 ref。
useForm
useForm(model?, rules?) 返回 [register, actions],把 register 绑定给 onRegister。初始化值和规则可用对象或工厂;对象会深拷贝,工厂结果直接使用,建议每次创建新对象。
| 返回项 | 行为 |
|---|---|
formConditionRef | 响应式模型,传给 RForm.model 并用于输入绑定。 |
formModel() / formRules() | 重新取得初始模型和规则。 |
getFormInstance() | 获取已注册实例,未注册或已卸载时抛错。 |
validate(callback?, shouldRuleBeApplied?) | 透传 Naive UI 校验;失败要处理 Promise 拒绝。 |
validateTargetField(key) | 按规则对象的唯一 key 筛选规则,key 不等同于 NFormItem.path。 |
restoreValidation() | 清除当前校验状态,保留输入。 |
updateFormCondition(values) | 浅合并当前模型,不改初始值。 |
reset(values?) | 合并初始值和覆盖值,然后清除校验。动态新增字段不会被自动删除。 |
实例相关方法要在表单挂载并注册后调用。可空字段应在初始模型中显式声明,并为所用输入选用合适的空值。修改嵌套字段时注意更新是浅合并。
组件源码 · useForm 源码 · 表单示例