更新Form说明文档

Aaron
1 parent ddaaa9f3
Showing 1 changed file with 134 additions and 26 deletions Show diff stats
examples/views/docs/component/form.md
 # Form 表单
-不同于常规Form组件，本组件采用配置列表的方式实现表单快速配置
+使用数据配置项列表快速生成一个表单
 ## 基础用法
-配置项list中通过type可以配置任意组件，不受框架限制
+配置项list中通过type可以配置任意表单组件，不受框架约定限制
-::: snippet 使用`list`属性设置数据源，列表项中的`type`指定组件类型，每一项都已设置为**el-form-item**的子组件，通过`rules`配置校验规则
+::: snippet 使用`list`属性设置数据源，其中的`type`指定组件类型，每一项都已设置为**el-form-item**的子组件，通过`rules`配置校验规则，`props`设置组件参数
 ```html
 <template>
-  <eagle-form ref="form" :list="formList" @submit="handleSubmit" @cancel="handleCancel" style="width: 500px;" :showButtonGroup="false"></eagle-form>
+  <eagle-form ref="form" :list="formList" @submit="handleSubmit" @cancel="handleCancel" style="width: 500px;"></eagle-form>
 </template>
 <script>
@@ -18,10 +18,14 @@ export default {
   data() {
     return {
       formList: [
-        { type: 'el-input', key: 'name', label: '名称', rules: [{ required: true, message: '请输入名称' }] },
-        { type: 'eagle-select', key: 'address', label: '住址', props: { dataSource: [{ label: '大街上', value: 'S' }, { label: '小区里', value: 'H' }] } },
-        { type: 'el-input', key: 'postcode', label: '邮编', span: 12, tip: { content: '邮政编码', placement: "left" } },
-        { type: 'el-input', key: 'number', label: '楼栋号', span: 12, visible: (model) => model.address === 'H' },
+        { type: 'el-input', key: 'name', label: '姓名',
+          rules: [{ required: true, message: '请输入姓名' }],
+          props: { placeholder: '姓名' }
+        },
+        { type: 'el-input-number', key: 'age', label: '年龄', span: 12 },
+        { type: 'el-input', key: 'introduce', label: '自我介绍',
+          props: { type: 'textarea', min: 3, placeholder: '100字以内' }
+        },
       ]
     }
   },
@@ -40,11 +44,102 @@ export default {
 :::
+## 事件监听
+
+通常的业务需求中，常常会对表单项进行事件监听，以满足级联等特殊效果
+
+::: snippet 使用`list`属性设置数据源，其中的`on`配置表单项的事件
+
+```html
+<template>
+  <eagle-form ref="form" :list="formList" @submit="handleSubmit" @cancel="handleCancel" style="width: 500px;"></eagle-form>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      formList: [
+        { type: 'el-input', key: 'name', label: '姓名',
+          on: {
+            input(value) {
+              console.log(value);
+            }
+          }
+        },
+        { type: 'el-input-number', key: 'age', label: '年龄', span: 12,
+          on(model) {
+            return {
+              change(value) {
+                console.log(value);
+                if (value < 10) {
+                  model.introduce = `${model.name || '那个谁'}，小孩子不要闹`
+                }
+              }
+            }
+          }
+        },
+        { type: 'el-input', key: 'introduce', label: '自我介绍',
+          props: { placeholder: (model) => `${model.name || '这个人'}的自我介绍` }
+        },
+      ]
+    }
+  },
+  methods: {
+    handleSubmit(value) {
+      console.log(value)
+    },
+    handleCancel() {
+      this.$refs.form.reset()
+      console.log('cancel!')
+    }
+  }
+}
+</script>
+```
+
+:::
+
+## 自定义内容
+
+基本的数据展示并不能满足复杂页面展示需求，因此可以通过**表单项具名插槽**的方式替换对应的展示位
+
+::: snippet 在组件内部通过具名插槽的方式，替换对应内容，列表项具名插槽格式为`item-key`，返回值为model及对应配置项所有参数
+
+```html
+<template>
+  <eagle-form v-model="form" :list="list" :showButtonGroup="false" style="width: 800px;">
+    <template #item-experience="{ model }">
+      <el-badge value="提醒"><el-switch v-model="model.experience"></el-switch></el-badge>
+    </template>
+    <template #item-show="{ key }"><span>form.{{ key }}={{ form }}</span></template>
+  </eagle-form>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      form: {},
+      list: [
+        { type: 'el-input', key: 'name', label: '姓名', span: 12 },
+        { type: 'el-input', key: 'age', label: '年龄', span: 12 },
+        { type: 'el-input', key: 'experience', label: '工作经历' },
+        { type: 'el-input', key: 'show', label: '表单值' },
+      ],
+    }
+  },
+}
+</script>
+```
+
+:::
+
 ## 分组
-对配置项进行分组
+将表单项分组显示
-::: snippet 在配置项属性中设置`group`参数，没有设置分组的配置项默认归为`基本信息`分组
+::: snippet 在配置项属性中设置`group`参数，任意一个数据配置group时开始生效，若没有配置分组则默认归为**基本信息**分组，group可以是一个Object，用于快速配置一些预置的效果
 ```html
 <template>
@@ -60,11 +155,13 @@ export default {
   data() {
     return {
       formList: [
-        { type: 'el-input', key: 'name', label: '名称', rules: [{ required: true, message: '请输入名称' }] },
-        { type: 'el-input', key: 'gender', label: '性别', group: { label: '身体状况', icon: 'edit' } },
-        { type: 'eagle-select', key: 'address', label: '住址', props: { dataSource: [{ label: '大街上', value: 'S' }, { label: '小区里', value: 'H' }] }, group: '详细地址' },
-        { type: 'el-input', key: 'postcode', label: '邮编', tip: { content: '邮政编码', placement: "left" }, group: '详细地址' },
-        { type: 'el-input', key: 'number', label: '楼栋号', group: '详细地址' },
+        { type: 'el-input', key: 'name', label: '姓名', rules: [{ required: true, message: '请输入名称' }] },
+        { type: 'el-input-number', key: 'age', label: '年龄', span: 12, group: '健康信息' },
+        { type: 'el-input-number', key: 'weight', label: '体重', span: 12, group: '健康信息' },
+        { type: 'el-input', key: 'experience', label: '简历',
+          group: { key: 'experience', icon: 'edit-outline', label: '工作经历' },
+          props: { type: 'textarea', min: 3 }
+        },
       ]
     }
   }
@@ -76,17 +173,17 @@ export default {
 ## 自定义分组
-有些时候默认的分组样式并不能满足项目需求，因此这里支持自定义
+有些时候默认的分组样式并不能满足项目需求，因此可以通过**表单项具名插槽**的方式替换对应的分组
-::: snippet 使用`Object`对象的方式配置分组信息，并在组件中使用具名插槽`slot`配置分组标题
+::: snippet 在组件内部通过具名插槽的方式，替换对应内容，表头具名插槽格式为`group-key`，返回值包括key及group配置内容
 ```html
 <template>
-  <eagle-form :list="formList" style="width: 500px;">
-    <template #group-not-bad="{ label }">
-      <div style="padding: 10px 0px;border-bottom: 1px dashed #aaa;display: flex;justify-content: space-between;">
-        <span>哎哟 - {{ label }} - 不错哦</span>
-        <el-button size="mini" type="primary">这是一个按钮</el-button>
+  <eagle-form ref="form" :list="formList" :showButtonGroup="false" style="width: 500px;">
+    <template #group-health="{ label }">
+      <div style="padding: 15px 5px;border-bottom: 1px dashed #e8e8e8;display: flex;justify-content: space-between;">
+        <span>{{ label }}</span>
+        <el-button size="mini" plain>体检报告</el-button>
       </div>
     </template>
   </eagle-form>
@@ -97,11 +194,11 @@ export default {
   data() {
     return {
       formList: [
-        { type: 'el-input', key: 'name', label: '名称', group: { label: '不错哦', key: 'not-bad' }, tip: '周某人说的' },
-        { type: 'eagle-select', key: 'address', label: '住址', props: { dataSource: [{ label: '大街上', value: 'S' }, { label: '小区里', value: 'H' }] }, group: '详细地址' },
+        { type: 'el-input', key: 'name', label: '姓名', group: { key: 'base', label: '基本信息' } },
+        { type: 'el-input-number', key: 'age', label: '年龄', group: { key: 'health', label: '健康信息' } },
       ]
     }
-  }
+  },
 }
 </script>
 ```
@@ -116,12 +213,22 @@ export default {
 -|-|-|-|-
 value / v-model |	绑定值 | Object | - | -
 list | 表单项配置列表 | Array | - | []
+formProps | [el-form组件参数](https://element.eleme.cn/#/zh-CN/component/form#form-attributes) | Object | - | {}
+span | 表单项占位 | Number | 0 - 24 | 24
+submitting | 提交按钮加载状态 | Boolean | true/false | false
+submitPure | 纯净提交，设置为true时submit的对象只会包含配置项配置过的字段 | Boolean | true/false | false
+footerStyle | 底部样式 | String, Object | - | -
+params | 用于做动态判断的参数集，用于需要将外部参数应用于具体表单项事件判断的情况 | Object | - | -
+showButtonGroup | 显示按钮组 | Boolean | true/false | false
 ## Methods 方法
 方法名|说明|参数
 -|-|-
 reset | 重置表单 | -
+validate | 校验表单 | -
+getPureModel | 获取以初始list为准的纯净model值 | -
+setModelValue | 设置表单值 | model
 ## Events 事件
@@ -130,6 +237,7 @@ reset | 重置表单 | -
 change | 表单model发生变化时触发 | model对象
 submit | 点击表单提交按钮时触发 | model对象
 cancel | 点击表单取消按钮时触发 | -
+validate | 表单校验成功后触发 | 校验值
 ## List 表单项配置列表
@@ -140,7 +248,7 @@ key | 参数名 | String | - | -
 label | 参数标签 | String | - | -
 props | 组件参数 | Object,Function(model: object)) | - | {}
 style | 组件样式 | Object | - | { width: "100%" }
-on | 组件事件 | Object,Function(model: object) | - | {}
+on | 组件事件，Function时需要返回事件的Object | Object,Function(model: object) | - | {}
 visible | 组件v-if状态 | Boolean,Function(model: object) | - | true
 show | 组件v-show状态 | Boolean,Function(model: object) | - | true
 rules | 组件校验规则 | Object,Array | - | -
1	# Form 表单	1	# Form 表单
2		2
3	-不同于常规Form组件，本组件采用配置列表的方式实现表单快速配置	3	+使用数据配置项列表快速生成一个表单
4		4
5	## 基础用法	5	## 基础用法
6		6
7	-配置项list中通过type可以配置任意组件，不受框架限制	7	+配置项list中通过type可以配置任意表单组件，不受框架约定限制
8		8
9	-::: snippet 使用`list`属性设置数据源，列表项中的`type`指定组件类型，每一项都已设置为el-form-item的子组件，通过`rules`配置校验规则	9	+::: snippet 使用`list`属性设置数据源，其中的`type`指定组件类型，每一项都已设置为el-form-item的子组件，通过`rules`配置校验规则，`props`设置组件参数
10		10
11	```html	11	```html
12	<template>	12	<template>
13	- <eagle-form ref="form" :list="formList" @submit="handleSubmit" @cancel="handleCancel" style="width: 500px;" :showButtonGroup="false"></eagle-form>	13	+ <eagle-form ref="form" :list="formList" @submit="handleSubmit" @cancel="handleCancel" style="width: 500px;"></eagle-form>
14	</template>	14	</template>
15		15
16	<script>	16	<script>
	@@ -18,10 +18,14 @@ export default {		@@ -18,10 +18,14 @@ export default {
18	data() {	18	data() {
19	return {	19	return {
20	formList: [	20	formList: [
21	- { type: 'el-input', key: 'name', label: '名称', rules: [{ required: true, message: '请输入名称' }] },
22	- { type: 'eagle-select', key: 'address', label: '住址', props: { dataSource: [{ label: '大街上', value: 'S' }, { label: '小区里', value: 'H' }] } },
23	- { type: 'el-input', key: 'postcode', label: '邮编', span: 12, tip: { content: '邮政编码', placement: "left" } },
24	- { type: 'el-input', key: 'number', label: '楼栋号', span: 12, visible: (model) => model.address === 'H' },	21	+ { type: 'el-input', key: 'name', label: '姓名',
		22	+ rules: [{ required: true, message: '请输入姓名' }],
		23	+ props: { placeholder: '姓名' }
		24	+ },
		25	+ { type: 'el-input-number', key: 'age', label: '年龄', span: 12 },
		26	+ { type: 'el-input', key: 'introduce', label: '自我介绍',
		27	+ props: { type: 'textarea', min: 3, placeholder: '100字以内' }
		28	+ },
25	]	29	]
26	}	30	}
27	},	31	},
	@@ -40,11 +44,102 @@ export default {		@@ -40,11 +44,102 @@ export default {
40		44
41	:::	45	:::
42		46
		47	+## 事件监听
		48	+
		49	+通常的业务需求中，常常会对表单项进行事件监听，以满足级联等特殊效果
		50	+
		51	+::: snippet 使用`list`属性设置数据源，其中的`on`配置表单项的事件
		52	+
		53	+```html
		54	+<template>
		55	+ <eagle-form ref="form" :list="formList" @submit="handleSubmit" @cancel="handleCancel" style="width: 500px;"></eagle-form>
		56	+</template>
		57	+
		58	+<script>
		59	+export default {
		60	+ data() {
		61	+ return {
		62	+ formList: [
		63	+ { type: 'el-input', key: 'name', label: '姓名',
		64	+ on: {
		65	+ input(value) {
		66	+ console.log(value);
		67	+ }
		68	+ }
		69	+ },
		70	+ { type: 'el-input-number', key: 'age', label: '年龄', span: 12,
		71	+ on(model) {
		72	+ return {
		73	+ change(value) {
		74	+ console.log(value);
		75	+ if (value < 10) {
		76	+ model.introduce = `${model.name \|\| '那个谁'}，小孩子不要闹`
		77	+ }
		78	+ }
		79	+ }
		80	+ }
		81	+ },
		82	+ { type: 'el-input', key: 'introduce', label: '自我介绍',
		83	+ props: { placeholder: (model) => `${model.name \|\| '这个人'}的自我介绍` }
		84	+ },
		85	+ ]
		86	+ }
		87	+ },
		88	+ methods: {
		89	+ handleSubmit(value) {
		90	+ console.log(value)
		91	+ },
		92	+ handleCancel() {
		93	+ this.$refs.form.reset()
		94	+ console.log('cancel!')
		95	+ }
		96	+ }
		97	+}
		98	+</script>
		99	+```
		100	+
		101	+:::
		102	+
		103	+## 自定义内容
		104	+
		105	+基本的数据展示并不能满足复杂页面展示需求，因此可以通过表单项具名插槽的方式替换对应的展示位
		106	+
		107	+::: snippet 在组件内部通过具名插槽的方式，替换对应内容，列表项具名插槽格式为`item-key`，返回值为model及对应配置项所有参数
		108	+
		109	+```html
		110	+<template>
		111	+ <eagle-form v-model="form" :list="list" :showButtonGroup="false" style="width: 800px;">
		112	+ <template #item-experience="{ model }">
		113	+ <el-badge value="提醒"><el-switch v-model="model.experience"></el-switch></el-badge>
		114	+ </template>
		115	+ <template #item-show="{ key }"><span>form.{{ key }}={{ form }}</span></template>
		116	+ </eagle-form>
		117	+</template>
		118	+
		119	+<script>
		120	+export default {
		121	+ data() {
		122	+ return {
		123	+ form: {},
		124	+ list: [
		125	+ { type: 'el-input', key: 'name', label: '姓名', span: 12 },
		126	+ { type: 'el-input', key: 'age', label: '年龄', span: 12 },
		127	+ { type: 'el-input', key: 'experience', label: '工作经历' },
		128	+ { type: 'el-input', key: 'show', label: '表单值' },
		129	+ ],
		130	+ }
		131	+ },
		132	+}
		133	+</script>
		134	+```
		135	+
		136	+:::
		137	+
43	## 分组	138	## 分组
44		139
45	-对配置项进行分组	140	+将表单项分组显示
46		141
47	-::: snippet 在配置项属性中设置`group`参数，没有设置分组的配置项默认归为`基本信息`分组	142	+::: snippet 在配置项属性中设置`group`参数，任意一个数据配置group时开始生效，若没有配置分组则默认归为基本信息分组，group可以是一个Object，用于快速配置一些预置的效果
48		143
49	```html	144	```html
50	<template>	145	<template>
	@@ -60,11 +155,13 @@ export default {		@@ -60,11 +155,13 @@ export default {
60	data() {	155	data() {
61	return {	156	return {
62	formList: [	157	formList: [
63	- { type: 'el-input', key: 'name', label: '名称', rules: [{ required: true, message: '请输入名称' }] },
64	- { type: 'el-input', key: 'gender', label: '性别', group: { label: '身体状况', icon: 'edit' } },
65	- { type: 'eagle-select', key: 'address', label: '住址', props: { dataSource: [{ label: '大街上', value: 'S' }, { label: '小区里', value: 'H' }] }, group: '详细地址' },
66	- { type: 'el-input', key: 'postcode', label: '邮编', tip: { content: '邮政编码', placement: "left" }, group: '详细地址' },
67	- { type: 'el-input', key: 'number', label: '楼栋号', group: '详细地址' },	158	+ { type: 'el-input', key: 'name', label: '姓名', rules: [{ required: true, message: '请输入名称' }] },
		159	+ { type: 'el-input-number', key: 'age', label: '年龄', span: 12, group: '健康信息' },
		160	+ { type: 'el-input-number', key: 'weight', label: '体重', span: 12, group: '健康信息' },
		161	+ { type: 'el-input', key: 'experience', label: '简历',
		162	+ group: { key: 'experience', icon: 'edit-outline', label: '工作经历' },
		163	+ props: { type: 'textarea', min: 3 }
		164	+ },
68	]	165	]
69	}	166	}
70	}	167	}
	@@ -76,17 +173,17 @@ export default {		@@ -76,17 +173,17 @@ export default {
76		173
77	## 自定义分组	174	## 自定义分组
78		175
79	-有些时候默认的分组样式并不能满足项目需求，因此这里支持自定义	176	+有些时候默认的分组样式并不能满足项目需求，因此可以通过表单项具名插槽的方式替换对应的分组
80		177
81	-::: snippet 使用`Object`对象的方式配置分组信息，并在组件中使用具名插槽`slot`配置分组标题	178	+::: snippet 在组件内部通过具名插槽的方式，替换对应内容，表头具名插槽格式为`group-key`，返回值包括key及group配置内容
82		179
83	```html	180	```html
84	<template>	181	<template>
85	- <eagle-form :list="formList" style="width: 500px;">
86	- <template #group-not-bad="{ label }">
87	- <div style="padding: 10px 0px;border-bottom: 1px dashed #aaa;display: flex;justify-content: space-between;">
88	- <span>哎哟 - {{ label }} - 不错哦</span>
89	- <el-button size="mini" type="primary">这是一个按钮</el-button>	182	+ <eagle-form ref="form" :list="formList" :showButtonGroup="false" style="width: 500px;">
		183	+ <template #group-health="{ label }">
		184	+ <div style="padding: 15px 5px;border-bottom: 1px dashed #e8e8e8;display: flex;justify-content: space-between;">
		185	+ <span>{{ label }}</span>
		186	+ <el-button size="mini" plain>体检报告</el-button>
90	</div>	187	</div>
91	</template>	188	</template>
92	</eagle-form>	189	</eagle-form>
	@@ -97,11 +194,11 @@ export default {		@@ -97,11 +194,11 @@ export default {
97	data() {	194	data() {
98	return {	195	return {
99	formList: [	196	formList: [
100	- { type: 'el-input', key: 'name', label: '名称', group: { label: '不错哦', key: 'not-bad' }, tip: '周某人说的' },
101	- { type: 'eagle-select', key: 'address', label: '住址', props: { dataSource: [{ label: '大街上', value: 'S' }, { label: '小区里', value: 'H' }] }, group: '详细地址' },	197	+ { type: 'el-input', key: 'name', label: '姓名', group: { key: 'base', label: '基本信息' } },
		198	+ { type: 'el-input-number', key: 'age', label: '年龄', group: { key: 'health', label: '健康信息' } },
102	]	199	]
103	}	200	}
104	- }	201	+ },
105	}	202	}
106	</script>	203	</script>
107	```	204	```
	@@ -116,12 +213,22 @@ export default {		@@ -116,12 +213,22 @@ export default {
116	-\|-\|-\|-\|-	213	-\|-\|-\|-\|-
117	value / v-model \| 绑定值 \| Object \| - \| -	214	value / v-model \| 绑定值 \| Object \| - \| -
118	list \| 表单项配置列表 \| Array \| - \| []	215	list \| 表单项配置列表 \| Array \| - \| []
		216	+formProps \| [el-form组件参数](https://element.eleme.cn/#/zh-CN/component/form#form-attributes) \| Object \| - \| {}
		217	+span \| 表单项占位 \| Number \| 0 - 24 \| 24
		218	+submitting \| 提交按钮加载状态 \| Boolean \| true/false \| false
		219	+submitPure \| 纯净提交，设置为true时submit的对象只会包含配置项配置过的字段 \| Boolean \| true/false \| false
		220	+footerStyle \| 底部样式 \| String, Object \| - \| -
		221	+params \| 用于做动态判断的参数集，用于需要将外部参数应用于具体表单项事件判断的情况 \| Object \| - \| -
		222	+showButtonGroup \| 显示按钮组 \| Boolean \| true/false \| false
119		223
120	## Methods 方法	224	## Methods 方法
121		225
122	方法名\|说明\|参数	226	方法名\|说明\|参数
123	-\|-\|-	227	-\|-\|-
124	reset \| 重置表单 \| -	228	reset \| 重置表单 \| -
		229	+validate \| 校验表单 \| -
		230	+getPureModel \| 获取以初始list为准的纯净model值 \| -
		231	+setModelValue \| 设置表单值 \| model
125		232
126	## Events 事件	233	## Events 事件
127		234
	@@ -130,6 +237,7 @@ reset \| 重置表单 \| -		@@ -130,6 +237,7 @@ reset \| 重置表单 \| -
130	change \| 表单model发生变化时触发 \| model对象	237	change \| 表单model发生变化时触发 \| model对象
131	submit \| 点击表单提交按钮时触发 \| model对象	238	submit \| 点击表单提交按钮时触发 \| model对象
132	cancel \| 点击表单取消按钮时触发 \| -	239	cancel \| 点击表单取消按钮时触发 \| -
		240	+validate \| 表单校验成功后触发 \| 校验值
133		241
134	## List 表单项配置列表	242	## List 表单项配置列表
135		243
	@@ -140,7 +248,7 @@ key \| 参数名 \| String \| - \| -		@@ -140,7 +248,7 @@ key \| 参数名 \| String \| - \| -
140	label \| 参数标签 \| String \| - \| -	248	label \| 参数标签 \| String \| - \| -
141	props \| 组件参数 \| Object,Function(model: object)) \| - \| {}	249	props \| 组件参数 \| Object,Function(model: object)) \| - \| {}
142	style \| 组件样式 \| Object \| - \| { width: "100%" }	250	style \| 组件样式 \| Object \| - \| { width: "100%" }
143	-on \| 组件事件 \| Object,Function(model: object) \| - \| {}	251	+on \| 组件事件，Function时需要返回事件的Object \| Object,Function(model: object) \| - \| {}
144	visible \| 组件v-if状态 \| Boolean,Function(model: object) \| - \| true	252	visible \| 组件v-if状态 \| Boolean,Function(model: object) \| - \| true
145	show \| 组件v-show状态 \| Boolean,Function(model: object) \| - \| true	253	show \| 组件v-show状态 \| Boolean,Function(model: object) \| - \| true
146	rules \| 组件校验规则 \| Object,Array \| - \| -	254	rules \| 组件校验规则 \| Object,Array \| - \| -