签入版本
This commit is contained in:
@@ -0,0 +1,240 @@
|
||||
# BasicForm 表单
|
||||
|
||||
:::tip 说明
|
||||
`BasicForm` 位于 `src/components/Form/src/BasicForm.vue`，基于 ElementPlus 的 `el-form` 二次封装，通过 schemas 配置化定义表单字段，支持查询表单和业务表单两种模式。
|
||||
:::
|
||||
|
||||
## 组件架构
|
||||
|
||||
```
|
||||
src/components/Form/
|
||||
├── src/
|
||||
│ ├── BasicForm.vue # 主组件
|
||||
│ ├── props.ts # 属性定义
|
||||
│ ├── helper.ts # 工具函数（placeholder 生成）
|
||||
│ ├── types/form.ts # 类型定义（FormSchema、FormProps）
|
||||
│ └── hooks/
|
||||
│ ├── useFormEvents.ts # 表单事件（submit、reset、validate）
|
||||
│ └── useFormValues.ts # 表单值处理（默认值初始化）
|
||||
└── index.ts # 导出 useForm、FormSchema 等
|
||||
```
|
||||
|
||||
## 查询表单（列表页搜索）
|
||||
|
||||
列表页的搜索区域使用 `useForm` 注册表单：
|
||||
|
||||
```vue
|
||||
<el-card :bordered="false" class="pt-3 mb-3 proCard">
|
||||
<BasicForm @register="register" @submit="handleSubmit" @reset="handleReset" />
|
||||
</el-card>
|
||||
```
|
||||
|
||||
### querySchemas 定义
|
||||
|
||||
```typescript
|
||||
// src/views/system/position/querySchemas.ts
|
||||
|
||||
import { FormSchema } from '@/components/Form/index';
|
||||
|
||||
export const schemas: FormSchema[] = [
|
||||
{
|
||||
field: 'name',
|
||||
component: 'Input',
|
||||
label: '岗位名称',
|
||||
componentProps: {
|
||||
placeholder: '请输入岗位名称',
|
||||
},
|
||||
},
|
||||
{
|
||||
field: 'status',
|
||||
component: 'Select',
|
||||
label: '状态',
|
||||
componentProps: {
|
||||
placeholder: '请选择状态',
|
||||
clearable: true,
|
||||
options: [
|
||||
{ label: '正常', value: '1' },
|
||||
{ label: '禁用', value: '2' },
|
||||
],
|
||||
},
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
### useForm 注册
|
||||
|
||||
```typescript
|
||||
import { schemas } from './querySchemas';
|
||||
import { useForm } from '@/components/Form/index';
|
||||
import { ColProps } from 'element-plus';
|
||||
|
||||
const formParams = reactive({ name: '', status: '' });
|
||||
|
||||
const [register, {}] = useForm({
|
||||
labelWidth: 80,
|
||||
layout: 'horizontal',
|
||||
colProps: { span: 6 } as ColProps,
|
||||
submitOnReset: true,
|
||||
schemas,
|
||||
});
|
||||
|
||||
function handleSubmit(values: Recordable) {
|
||||
handleReset();
|
||||
for (const key in values) { formParams[key] = values[key]; }
|
||||
reloadTable();
|
||||
}
|
||||
|
||||
function handleReset() {
|
||||
for (const key in formParams) { formParams[key] = ''; }
|
||||
}
|
||||
```
|
||||
|
||||
`useForm` 返回 `[register, formActionType]`，`register` 传给 `@register` 事件完成表单绑定。
|
||||
|
||||
## 业务表单（编辑弹窗）
|
||||
|
||||
编辑弹窗中直接使用 `el-form` + `el-form-item` 构建表单：
|
||||
|
||||
```vue
|
||||
<!-- src/views/system/position/edit.vue -->
|
||||
<template>
|
||||
<el-dialog v-model="props.visible" :title="props.positionId ? '编辑' : '新增'" width="500">
|
||||
<el-form class="ls-form" ref="formRef" :model="formData" label-width="80px">
|
||||
<el-form-item
|
||||
label="岗位名称"
|
||||
prop="name"
|
||||
:rules="{ required: true, message: '请输入岗位名称', trigger: 'blur' }"
|
||||
>
|
||||
<el-input v-model="formData.name" placeholder="请输入岗位名称" clearable />
|
||||
</el-form-item>
|
||||
<el-form-item label="岗位状态" prop="status">
|
||||
<el-radio-group v-model="formData.status">
|
||||
<el-radio :value="1">正常</el-radio>
|
||||
<el-radio :value="2">停用</el-radio>
|
||||
</el-radio-group>
|
||||
</el-form-item>
|
||||
<el-form-item label="排序" prop="sort">
|
||||
<el-input-number v-model="formData.sort" />
|
||||
</el-form-item>
|
||||
</el-form>
|
||||
</el-dialog>
|
||||
</template>
|
||||
```
|
||||
|
||||
## BasicForm 内部渲染机制
|
||||
|
||||
`BasicForm.vue` 根据 `schema.component` 动态渲染对应的 ElementPlus 组件：
|
||||
|
||||
```vue
|
||||
<!-- src/components/Form/src/BasicForm.vue 核心逻辑 -->
|
||||
<template v-for="schema in getSchema" :key="schema.field">
|
||||
<!-- Checkbox -->
|
||||
<template v-if="schema.component === 'Checkbox'">
|
||||
<el-checkbox-group v-model="formModel[schema.field]">
|
||||
<el-checkbox v-for="item in schema.componentProps?.options" :value="item.value">
|
||||
{{ item.label }}
|
||||
</el-checkbox>
|
||||
</el-checkbox-group>
|
||||
</template>
|
||||
|
||||
<!-- RadioGroup -->
|
||||
<template v-else-if="schema.component === 'RadioGroup'">
|
||||
<el-radio-group v-model="formModel[schema.field]">
|
||||
<el-radio v-for="item in schema.componentProps?.options" :value="item.value">
|
||||
{{ item.label }}
|
||||
</el-radio>
|
||||
</el-radio-group>
|
||||
</template>
|
||||
|
||||
<!-- Select -->
|
||||
<template v-else-if="schema.component === 'Select'">
|
||||
<el-select v-model="formModel[schema.field]">
|
||||
<el-option v-for="item in schema.componentProps?.options" :value="item.value" :label="item.label" />
|
||||
</el-select>
|
||||
</template>
|
||||
|
||||
<!-- Daterange -->
|
||||
<template v-else-if="schema.component === 'Daterange'">
|
||||
<el-date-picker v-model="formModel[schema.field]" type="daterange" value-format="YYYY-MM-DD" />
|
||||
</template>
|
||||
|
||||
<!-- 其他组件：动态渲染 el-{component} -->
|
||||
<component v-else :is="`el-${schema.component}`" v-model="formModel[schema.field]" />
|
||||
</template>
|
||||
```
|
||||
|
||||
## FormSchema 类型
|
||||
|
||||
```typescript
|
||||
interface FormSchema {
|
||||
field: string; // 字段名
|
||||
label: string; // 标签文本
|
||||
component: string; // 组件类型：Input / Select / RadioGroup / Checkbox / DatePicker 等
|
||||
componentProps?: any; // 组件属性（placeholder、options、clearable 等）
|
||||
required?: boolean; // 是否必填
|
||||
rules?: any[]; // 自定义校验规则
|
||||
defaultValue?: any; // 默认值
|
||||
hidden?: boolean | (({ schema, values, model }) => boolean); // 是否隐藏
|
||||
slot?: string; // 自定义插槽名
|
||||
suffix?: string; // 后缀插槽名
|
||||
labelMessage?: string; // 标签提示信息
|
||||
isFull?: boolean; // 是否全宽
|
||||
type?: string; // 组件子类型
|
||||
}
|
||||
```
|
||||
|
||||
## 表单校验
|
||||
|
||||
```typescript
|
||||
// 手动校验
|
||||
const handleSubmit = async () => {
|
||||
await formRef.value?.validate();
|
||||
// 校验通过，提交数据
|
||||
};
|
||||
|
||||
// 清除校验
|
||||
formRef.value?.clearValidate();
|
||||
```
|
||||
|
||||
Schema 中的 `required: true` 会自动生成必填校验规则，也可以通过 `rules` 自定义：
|
||||
|
||||
```typescript
|
||||
{
|
||||
field: 'name',
|
||||
label: '岗位名称',
|
||||
component: 'Input',
|
||||
rules: [
|
||||
{ required: true, message: '请输入岗位名称', trigger: 'blur' },
|
||||
{ min: 1, max: 150, message: '长度在 1 到 150 个字符', trigger: 'blur' },
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
## 表单赋值
|
||||
|
||||
编辑时需要将行数据赋值给表单：
|
||||
|
||||
```typescript
|
||||
const formData = reactive({ id: '', name: '', status: 1, sort: 0 });
|
||||
|
||||
const setFormData = async () => {
|
||||
const data = await getPositionDetail(props.positionId);
|
||||
for (const key in formData) {
|
||||
if (data[key] != null && data[key] != undefined) {
|
||||
formData[key] = data[key];
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
onMounted(() => {
|
||||
if (props.positionId) setFormData();
|
||||
});
|
||||
```
|
||||
|
||||
:::tip 温馨提示
|
||||
查询表单的字段名需要与后端 `page_like_fields` 和 `page_eq_fields` 对应，确保查询参数能正确传递到后端。`useForm` 返回的 `register` 函数传给 `@register` 事件完成表单绑定，`formActionType` 提供 `setFieldsValue`、`resetFields`、`validate` 等方法。
|
||||
:::
|
||||
|
||||
## 总结
|
||||
|
||||
BasicForm 通过 schemas 配置化定义表单字段，内部根据 `component` 动态渲染对应的 ElementPlus 组件。查询表单使用 `useForm` 注册并绑定 `@submit`/`@reset` 事件，业务表单直接使用 `el-form` + `reactive` 管理数据。支持多种组件类型、表单校验、数据绑定、条件隐藏等能力。
|
||||
Reference in New Issue
Block a user