allinssl/frontend/packages/vue/naive-ui/docs/useForm.md

useForm 使用文档

基本介绍

useForm 是一个基于 Naive UI 的表单构建工具，它提供了一种声明式的方式来创建和管理复杂的表单。通过这个钩子函数，你可以轻松地构建表单、管理表单状态、处理验证和提交等操作。

核心函数

useForm

function useForm<T>(options: UseFormOptions<T>): FormInstanceWithComponent<T>

参数:

• options: 表单配置选项
  • config: 表单配置，定义表单的结构和布局
  • request: 可选，表单提交时调用的请求函数
  • defaultValue: 可选，表单的默认值

返回值:

• component: 表单渲染组件
• example: 当前组件实例 (FormInst)
• data: 响应式表单数据
• loading: 加载状态
• config: 表单配置
• props: 表单属性
• rules: 验证规则
• fetch: 提交方法
• reset: 重置方法
• validate: 验证方法

示例:

const form = useForm({
  config: [...], // 表单配置
  request: async (data) => {
    // 处理表单提交
    return await api.submit(data)
  },
  defaultValue: { name: '', age: 0 }
})

表单项构建函数

useFormInput

创建一个文本输入框表单项。

function useFormInput(
	label: string,
	key: string,
	other?: InputProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• other: 可选，输入框组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 表单项配置对象

useFormTextarea

创建一个多行文本输入框表单项。

function useFormTextarea(
	label: string,
	key: string,
	other?: InputProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemCustomConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• other: 可选，文本域组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 自定义表单项配置对象

useFormPassword

创建一个密码输入框表单项。

function useFormPassword(
	label: string,
	key: string,
	other?: InputProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemCustomConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• other: 可选，密码输入框组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 自定义表单项配置对象

useFormInputNumber

创建一个数字输入框表单项。

function useFormInputNumber(
	label: string,
	key: string,
	other?: InputNumberProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• other: 可选，数字输入框组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 表单项配置对象

useFormSelect

创建一个下拉选择框表单项。

function useFormSelect(
	label: string,
	key: string,
	options: SelectOption[],
	other?: SelectProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• options: 选择项数组
• other: 可选，选择框组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 表单项配置对象

useFormRadio

创建一个单选框组表单项。

function useFormRadio(
	label: string,
	key: string,
	options: RadioOptionItem[],
	other?: RadioProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• options: 单选项数组
• other: 可选，单选框组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 表单项配置对象

useFormCheckbox

创建一个复选框组表单项。

function useFormCheckbox(
	label: string,
	key: string,
	options: CheckboxOptionItem[],
	other?: CheckboxProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• options: 复选项数组
• other: 可选，复选框组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 表单项配置对象

useFormSwitch

创建一个开关表单项。

function useFormSwitch(
	label: string,
	key: string,
	other?: SwitchProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• other: 可选，开关组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 表单项配置对象

useFormDatepicker

创建一个日期选择器表单项。

function useFormDatepicker(
	label: string,
	key: string,
	other?: DatePickerProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• other: 可选，日期选择器组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 表单项配置对象

useFormTimepicker

创建一个时间选择器表单项。

function useFormTimepicker(
	label: string,
	key: string,
	other?: TimePickerProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• other: 可选，时间选择器组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 表单项配置对象

useFormSlider

创建一个滑块表单项。

function useFormSlider(
	label: string,
	key: string,
	other?: SliderProps,
	itemAttrs?: FormItemConfig,
	slot?: { prefix?: Array<() => JSX.Element>; suffix?: Array<() => JSX.Element> },
): FormItemConfig

参数:

• label: 表单项标签
• key: 表单数据字段名
• other: 可选，滑块组件的额外属性
• itemAttrs: 可选，表单项的额外属性
• slot: 可选，前缀和后缀插槽

返回值: 表单项配置对象

useFormSlot

创建一个插槽表单项。

function useFormSlot(key?: string): SlotFormElement

参数:

• key: 可选，插槽名称，默认为 'default'

返回值: 插槽表单元素配置对象

useFormCustom

创建一个自定义渲染的表单项。

function useFormCustom<T extends Record<string, unknown>>(
	render: (formData: Ref<T>, formRef: Ref<FormInst | null>) => JSX.Element,
): FormItemCustomConfig

参数:

• render: 自定义渲染函数，接收表单数据和表单实例引用作为参数

返回值: 自定义表单项配置对象

useFormGroup

创建一个表单项组。

function useFormGroup<T>(group: Record<string, any>[]): FormItemCustomConfig

参数:

• group: 表单项组配置数组

返回值: 自定义表单项配置对象

useFormMore

创建一个"更多配置"展开/折叠控件。

function useFormMore(isMore: Ref<boolean>, content?: string): FormItemCustomConfig

参数:

• isMore: 是否展开的响应式引用
• content: 可选，显示的内容文本

返回值: 自定义表单项配置对象

useFormHelp

创建一个帮助文档表单项。

function useFormHelp(
	options: { content: string | JSX.Element; isHtml?: boolean }[],
	other?: { listStyle?: string },
): FormItemCustomConfig

参数:

• options: 帮助内容配置数组
  • content: 帮助内容文本或JSX元素
  • isHtml: 可选，内容是否为HTML
• other: 可选，其他配置
  • listStyle: 可选，列表样式

返回值: 自定义表单项配置对象

使用示例

import useForm, { useFormHooks } from 'path/to/useForm'

// 解构所有表单钩子函数
const {
  useFormInput,
  useFormSelect,
  useFormRadio,
  // ...其他钩子函数
} = useFormHooks()

// 创建表单实例
const form = useForm({
  config: [
    useFormInput('用户名', 'username', { placeholder: '请输入用户名' }),
    useFormPassword('密码', 'password'),
    useFormSelect('角色', 'role', [
      { label: '管理员', value: 'admin' },
      { label: '用户', value: 'user' }
    ]),
    useFormRadio('性别', 'gender', [
      { label: '男', value: 'male' },
      { label: '女', value: 'female' }
    ]),
    // 使用栅格布局
    {
      type: 'grid',
      cols: 2,
      children: [
        useFormInput('姓', 'firstName'),
        useFormInput('名', 'lastName')
      ]
    },
    // 使用自定义渲染
    useFormCustom((formData) => (
      <div>当前用户名: {formData.value.username}</div>
    ))
  ],
  request: async (data) => {
    // 提交表单数据
    return await api.submitForm(data)
  },
  defaultValue: {
    username: '',
    password: '',
    role: 'user',
    gender: 'male',
    firstName: '',
    lastName: ''
  }
})

// 在组件中使用
// <form.component />

// 提交表单
// await form.fetch()

// 重置表单
// form.reset()

// 验证表单
// const valid = await form.validate()

注意事项

1. 所有表单项都支持通过 itemAttrs 参数配置表单项的属性，如 required、rule 等。
2. 大多数表单项都支持通过 slot 参数配置前缀和后缀插槽。
3. 表单的验证规则可以通过 form.rules.value = { ... } 进行设置。
4. 表单的属性可以通过 form.props.value = { ... } 进行设置。