From 9802b7996dacbabc7a15ac9922fc6610ad6094db Mon Sep 17 00:00:00 2001
From: Aaron <427787340@qq.com>
Date: Wed, 28 Aug 2019 10:53:12 +0800
Subject: [PATCH] 更新Form说明文档

---
 examples/views/docs/component/form.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------
 1 file changed, 134 insertions(+), 26 deletions(-)

diff --git a/examples/views/docs/component/form.md b/examples/views/docs/component/form.md
index bfe38e7..203f485 100644
--- a/examples/views/docs/component/form.md
+++ b/examples/views/docs/component/form.md
@@ -1,16 +1,16 @@
 # 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 | - | -
--
libgit2 0.21.0