跳转到正文

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 { RForm, useForm } from '@/components'
import { useI18n } from '@/hooks'
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。

属性默认说明
loadingfalse外层 Spin 状态,由调用方开关。
loadingDescription无加载说明。
autocomplete'off'挂载时写到表单 DOM。
submitWhenEnterfalse可动态启用单行输入的 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 源码 · 表单示例