np-form Form

A configuration-driven form that dynamically generates the form through columns, simple to use and highly extensible.

Basic Usage

Form fields are mainly configured with label, key, type to set the form label, form field and field type. More config depends on the props of the actual type once type is set.

浏览器不支持，请手动复制 basic.en.vue

<template>
  <div>
    {{ data }}
    <np-form v-model="data" :option="option" />
  </div>
</template>
<script setup lang="ts">
import type { FormOption } from 'naive-plus'
import { ref, h } from 'vue'

type User = {
  fullName?: string
  tel?: number
  age?: number
  gender?: 'man' | 'woman'
  hobby?: Array<'Sing' | 'Dance' | 'Rap'>
}

const data = ref<User>({
  hobby: ['Sing'],
})

const option: FormOption<User> = {
  onSubmit: async form => {
    console.log('Submitted', form)
    await new Promise<void>(resolve => setTimeout(() => resolve(), 1200))
  },
  onReset: form => {
    console.log('Reset', form)
  },
  columns: [
    {
      label: 'Name',
      key: 'fullName',
    },
    {
      label: 'Phone',
      key: 'tel',
      type: 'number',
    },
    {
      label: 'Age',
      key: 'age',
      // type declares the inner component, e.g. number uses naive-ui's n-input[type=number]
      type: 'number',
      // props passed to the inner component; see InputProps of naive-ui
      props: {
        min: 0,
        max: 99,
      },
      // slots passed to the inner component; see InputSlots of naive-ui
      slots: {
        suffix: () => [h('span', null, 'years')],
      },
    },
    {
      label: 'Gender',
      key: 'gender',
      type: 'radio',
      defaultValue: 'man',
      options: [
        { label: 'Male', value: 'man' },
        { label: 'Female', value: 'woman' },
      ],
    },
    {
      label: 'Hobbies',
      key: 'hobby',
      type: 'checkbox',
      options: ['Sing', 'Dance', 'Rap'],
    },
  ],
}
</script>

Component Configuration

Props

Prop	Description	Type	Default
option	Configuration	FormOption	-

Methods

After getting the form instance via ref, you can imperatively call the following methods. See Imperative Methods.

Method	Description	Type
submit	Submit the form manually	() => Promise<void>
reset	Reset the form and trigger onReset	() => Promise<void>
validateFields	Validate the given fields, supports __ prefix matching	(fields: string | string[]) => Promise<void>

Types

The component exports the following type definitions:

import type { FormOption } from 'naive-plus'

FormOption

Prop	Description	Type	Default
columns	Form fields	Array<FormColumn>	-
onSubmit	Submit event	(data)=>Promise<void>	-
onReset	Reset event	(data)=>Promise<void>	-
props	Form props	object	-
grid	Grid layout config, see Grid Layout	object	-

FormColumn

Prop	Description	Type	Default
label	Field label	string / VNode	-
key	Form field name	string	-
type	Form field type	string / (data)=>VNode	-
defaultValue	Default value	any	-
options	Dictionary options, e.g. checkbox, select, etc.	Array<any> / ()=>Promise<Array<any>>	-
props	Component props, passed through to the actual component	object	-
formItemProps	Form item props, passed through to n-form-item-gi; supports span / offset	object	-

Global Defaults

Use NpConfigProvider to configure enterSubmitMode / grid / props and the default column of every form item. The same config in option always wins.

<np-config-provider
  :component-options="{
    Form: {
      enterSubmitMode: 'all',
      grid: { cols: 24, xGap: 12 },
      props: { labelWidth: 100 },
      column: { formItemProps: { labelWidth: 100 }, props: { size: 'small' } },
    },
  }"
>
  <np-form v-model="data" :option="option" />
</np-config-provider>