RForm and useForm
RForm wraps Naive UI Form and uses a spinner for submission or loading. Match NFormItem.path to the model field and update the value from the input.
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: 'Enter a name',
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="Name" path="name">
<NInput
value={form.formConditionRef.value.name}
onUpdateValue={(name) => form.updateFormCondition({ name })}
/>
</NFormItem>
<NButton onClick={() => void submit().catch(() => {})}>
Validate and submit
</NButton>
<NButton onClick={() => form.reset()}>Reset</NButton>
</RForm>
)
},
})Interactive example
View example source
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>
)
},
})Props and events
The component inherits public NForm props and onSubmit and forwards the default slot to NForm.
| Prop | Default | Description |
|---|---|---|
loading | false | Caller-controlled outer spinner. |
loadingDescription | None | Loading description. |
autocomplete | 'off' | Written to the form element on mount. |
submitWhenEnter | false | Can be enabled dynamically for single-line input. Successful validation calls onFinish. Repeated submissions are ignored while loading or while a prior submission is pending. |
onFinish | None | Called after Enter-triggered validation succeeds. Custom submit buttons should call validate() and perform the submission. |
onRegister(inst) | None | Provides the Naive UI Form instance after mount. Accepts a callback or array. |
Enter keeps its native behavior for IME confirmation, multiline input, comboboxes, buttons, modifier keys, and controls that already called preventDefault(). The form displays validation failures from keyboard submission. Vue error handling receives exceptions from onFinish. Handle rejected useForm.validate() promises. Access Form instance methods through the registration hook.
useForm
useForm(model?, rules?) returns [register, actions]. Bind register to onRegister. Initial values and rules can be objects or factories. Objects are deep-cloned. Factory results are used directly, so return a new object each time.
| Return value | Behavior |
|---|---|
formConditionRef | Reactive model for RForm.model and input bindings. |
formModel() / formRules() | Get fresh initial model and rules. |
getFormInstance() | Get the registered instance. Throws before registration or after unmount. |
validate(callback?, shouldRuleBeApplied?) | Forwards Naive UI validation. Handle rejection on failure. |
validateTargetField(key) | Selects rules by their unique key, which can differ from NFormItem.path. |
restoreValidation() | Clears validation and retains input. |
updateFormCondition(values) | Shallow-merges the current model and keeps initial values. |
reset(values?) | Merges initial values with overrides and clears validation. Dynamically added fields remain. |
Call instance methods after the form mounts and registers. Declare nullable fields in the initial model and use an empty value appropriate for each input. When updating nested fields, account for the shallow merge.