framework / eagle-web-toolkit

Download as
Browse Code »

Commit 9802b7996dacbabc7a15ac9922fc6610ad6094db

Authored by Aaron
1 parent ddaaa9f3
Exists in master and in 1 other branch legacy

更新Form说明文档

Showing 1 changed file with 134 additions and 26 deletions   Show diff stats
examples/views/docs/component/form.md
  Diff comments   View file @9802b79
1 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 11 ```html
12 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 14 </template>
15 15  
16 16 <script>
... ... @@ -18,10 +18,14 @@ export default {
18 18 data() {
19 19 return {
20 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 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 144 ```html
50 145 <template>
... ... @@ -60,11 +155,13 @@ export default {
60 155 data() {
61 156 return {
62 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 173  
77 174 ## 自定义分组
78 175  
79   -有些时候默认的分组样式并不能满足项目需求，因此这里支持自定义
  176 +有些时候默认的分组样式并不能满足项目需求，因此可以通过**表单项具名插槽**的方式替换对应的分组
80 177  
81   -::: snippet 使用`Object`对象的方式配置分组信息，并在组件中使用具名插槽`slot`配置分组标题
  178 +::: snippet 在组件内部通过具名插槽的方式，替换对应内容，表头具名插槽格式为`group-key`，返回值包括key及group配置内容
82 179  
83 180 ```html
84 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 187 </div>
91 188 </template>
92 189 </eagle-form>
... ... @@ -97,11 +194,11 @@ export default {
97 194 data() {
98 195 return {
99 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 203 </script>
107 204 ```
... ... @@ -116,12 +213,22 @@ export default {
116 213 -|-|-|-|-
117 214 value / v-model | 绑定值 | Object | - | -
118 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 224 ## Methods 方法
121 225  
122 226 方法名|说明|参数
123 227 -|-|-
124 228 reset | 重置表单 | -
  229 +validate | 校验表单 | -
  230 +getPureModel | 获取以初始list为准的纯净model值 | -
  231 +setModelValue | 设置表单值 | model
125 232  
126 233 ## Events 事件
127 234  
... ... @@ -130,6 +237,7 @@ reset | 重置表单 | -
130 237 change | 表单model发生变化时触发 | model对象
131 238 submit | 点击表单提交按钮时触发 | model对象
132 239 cancel | 点击表单取消按钮时触发 | -
  240 +validate | 表单校验成功后触发 | 校验值
133 241  
134 242 ## List 表单项配置列表
135 243  
... ... @@ -140,7 +248,7 @@ key | 参数名 | String | - | -
140 248 label | 参数标签 | String | - | -
141 249 props | 组件参数 | Object,Function(model: object)) | - | {}
142 250 style | 组件样式 | Object | - | { width: "100%" }
143   -on | 组件事件 | Object,Function(model: object) | - | {}
  251 +on | 组件事件，Function时需要返回事件的Object | Object,Function(model: object) | - | {}
144 252 visible | 组件v-if状态 | Boolean,Function(model: object) | - | true
145 253 show | 组件v-show状态 | Boolean,Function(model: object) | - | true
146 254 rules | 组件校验规则 | Object,Array | - | -
... ...