mirror of
https://gitee.com/mirrors/AllinSSL.git
synced 2026-03-13 18:10:53 +08:00
【初始化】前端工程项目
This commit is contained in:
chudong
472
frontend/packages/naive-ui/docs/useForm.md
Normal file
472
frontend/packages/naive-ui/docs/useForm.md
Normal file
@@ -0,0 +1,472 @@
|
||||
# useForm 使用文档
|
||||
|
||||
## 基本介绍
|
||||
|
||||
`useForm` 是一个基于 Naive UI 的表单构建工具，它提供了一种声明式的方式来创建和管理复杂的表单。通过这个钩子函数，你可以轻松地构建表单、管理表单状态、处理验证和提交等操作。
|
||||
|
||||
## 核心函数
|
||||
|
||||
### useForm
|
||||
|
||||
```typescript
|
||||
function useForm<T>(options: UseFormOptions<T>): FormInstanceWithComponent<T>
|
||||
```
|
||||
|
||||
**参数**:
|
||||
|
||||
- `options`: 表单配置选项
|
||||
- `config`: 表单配置，定义表单的结构和布局
|
||||
- `request`: 可选，表单提交时调用的请求函数
|
||||
- `defaultValue`: 可选，表单的默认值
|
||||
|
||||
**返回值**:
|
||||
|
||||
- `component`: 表单渲染组件
|
||||
- `example`: 当前组件实例 (FormInst)
|
||||
- `data`: 响应式表单数据
|
||||
- `loading`: 加载状态
|
||||
- `config`: 表单配置
|
||||
- `props`: 表单属性
|
||||
- `rules`: 验证规则
|
||||
- `fetch`: 提交方法
|
||||
- `reset`: 重置方法
|
||||
- `validate`: 验证方法
|
||||
|
||||
**示例**:
|
||||
|
||||
```typescript
|
||||
const form = useForm({
|
||||
config: [...], // 表单配置
|
||||
request: async (data) => {
|
||||
// 处理表单提交
|
||||
return await api.submit(data)
|
||||
},
|
||||
defaultValue: { name: '', age: 0 }
|
||||
})
|
||||
```
|
||||
|
||||
## 表单项构建函数
|
||||
|
||||
### useFormInput
|
||||
|
||||
创建一个文本输入框表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个多行文本输入框表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个密码输入框表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个数字输入框表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个下拉选择框表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个单选框组表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个复选框组表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个开关表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个日期选择器表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个时间选择器表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个滑块表单项。
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
创建一个插槽表单项。
|
||||
|
||||
```typescript
|
||||
function useFormSlot(key?: string): SlotFormElement
|
||||
```
|
||||
|
||||
**参数**:
|
||||
|
||||
- `key`: 可选，插槽名称，默认为 'default'
|
||||
|
||||
**返回值**: 插槽表单元素配置对象
|
||||
|
||||
### useFormCustom
|
||||
|
||||
创建一个自定义渲染的表单项。
|
||||
|
||||
```typescript
|
||||
function useFormCustom<T extends Record<string, unknown>>(
|
||||
render: (formData: Ref<T>, formRef: Ref<FormInst | null>) => JSX.Element,
|
||||
): FormItemCustomConfig
|
||||
```
|
||||
|
||||
**参数**:
|
||||
|
||||
- `render`: 自定义渲染函数，接收表单数据和表单实例引用作为参数
|
||||
|
||||
**返回值**: 自定义表单项配置对象
|
||||
|
||||
### useFormGroup
|
||||
|
||||
创建一个表单项组。
|
||||
|
||||
```typescript
|
||||
function useFormGroup<T>(group: Record<string, any>[]): FormItemCustomConfig
|
||||
```
|
||||
|
||||
**参数**:
|
||||
|
||||
- `group`: 表单项组配置数组
|
||||
|
||||
**返回值**: 自定义表单项配置对象
|
||||
|
||||
### useFormMore
|
||||
|
||||
创建一个"更多配置"展开/折叠控件。
|
||||
|
||||
```typescript
|
||||
function useFormMore(isMore: Ref<boolean>, content?: string): FormItemCustomConfig
|
||||
```
|
||||
|
||||
**参数**:
|
||||
|
||||
- `isMore`: 是否展开的响应式引用
|
||||
- `content`: 可选，显示的内容文本
|
||||
|
||||
**返回值**: 自定义表单项配置对象
|
||||
|
||||
### useFormHelp
|
||||
|
||||
创建一个帮助文档表单项。
|
||||
|
||||
```typescript
|
||||
function useFormHelp(
|
||||
options: { content: string | JSX.Element; isHtml?: boolean }[],
|
||||
other?: { listStyle?: string },
|
||||
): FormItemCustomConfig
|
||||
```
|
||||
|
||||
**参数**:
|
||||
|
||||
- `options`: 帮助内容配置数组
|
||||
- `content`: 帮助内容文本或JSX元素
|
||||
- `isHtml`: 可选，内容是否为HTML
|
||||
- `other`: 可选，其他配置
|
||||
- `listStyle`: 可选，列表样式
|
||||
|
||||
**返回值**: 自定义表单项配置对象
|
||||
|
||||
## 使用示例
|
||||
|
||||
```typescript
|
||||
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 = { ... }` 进行设置。
|
||||
Reference in New Issue
Block a user