iov-pro-components 0.0.3

package/docs/components/pro-form.md

@@ -0,0 +1,958 @@
+# 表单 ProForm
+使用 `schema` 的方式构建表单，并支持多样化的数据处理。
+
+## 基础使用
+
+::: demo
+```html
+<template>
+  <iov-pro-form
+    v-model="formData"
+    :items="ITEMS"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input'
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 参数解构
+
+::: demo
+```html
+<template>
+  <iov-pro-space space="12px">
+    <iov-pro-form
+      v-model="formData"
+      :items="ITEMS"
+    />
+    <div style="font-size: 12px;font-weight: bold;">当前表单数据: {{ formData }}</div>
+  </iov-pro-space>
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input'
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION
+        },
+        {
+          label: '日期范围',
+          name: ['startTime', 'endTime'],
+          type: 'date-picker',
+          props: {
+            type: 'daterange'
+          }
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+
+## 支持插槽类型
+
+::: demo
+```html
+<template>
+  <iov-pro-space space="12px">
+    <iov-pro-form
+      v-model="formData"
+      :items="ITEMS"
+    >
+      <template #time-unit>
+        <el-input
+          v-model="formData.time"
+          placeholder="请输入抽烟时长"
+          clearable
+        >
+          <el-select
+            v-model="formData.unit"
+            slot="append"
+            placeholder="请选择单位"
+          >
+            <el-option label="年" value="year" />
+            <el-option label="月" value="month" />
+            <el-option label="日" value="day" />
+          </el-select>
+        </el-input>
+      </template>
+    </iov-pro-form>
+    <div style="font-size: 12px;font-weight: bold;">当前表单数据: {{ formData }}</div>
+  </iov-pro-space>
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input'
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION
+        },
+        {
+          label: '学习时长',
+          name: ['time', 'unit'],
+          type: 'slot',
+          slotName: 'time-unit',
+          value: ['', 'year'],
+          rules: {
+            required: true,
+            validator(rule, value, callback) {
+              if (!value[0]) {
+                callback(new Error('请输入学习时长'))
+              } else {
+                callback()
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 表单项插槽
+
+::: demo
+```html
+<template>
+  <iov-pro-space space="12px">
+    <iov-pro-form
+      v-model="formData"
+      :items="ITEMS"
+    >
+      <template #name-label-slot>
+        姓名 <span style="color: red; font-size: 12px; margin-left: 8px;">请输入真实姓名</span>
+      </template>
+      <template #name-prepend-slot>重要</template>
+    </iov-pro-form>
+  </iov-pro-space>
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input',
+          slots: {
+            formItem: {
+              label: 'name-label-slot'
+            },
+            component: {
+              prepend: 'name-prepend-slot'
+            }
+          }
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 加载下拉数据
+`options` 字段支持 直接赋值 ，函数返回，以及 `Promise` 回调方式。但是数据格式仅支持 `label` ，`value` 形式，如果接口返回非此形式，需要在 `options` 方法中自行转换。
+
+::: demo
+```html
+<template>
+  <iov-pro-form
+    ref="form"
+    v-model="formData"
+    :items="ITEMS"
+  />
+</template>
+
+<script>
+const apiMock = () => {
+  return new Promise((resolve, reject) => {
+    setTimeout(() => {
+      resolve([
+        {
+          label: '江苏省',
+          value: 'jiangsu',
+          children: [
+            { label: '南京市', value: 'nanjing' },
+            { label: '苏州市', value: '苏州' }
+          ]
+        },
+        {
+          label: '安徽省',
+          value: 'anhui',
+          children: [
+            { label: '合肥市', value: 'hefei' },
+            { label: '芜湖', value: 'wuhu' }
+          ]
+        }
+      ])
+    }, 300)
+  })
+}
+
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    const MAN_LINK = [
+      { label: '篮球', value: 1 },
+      { label: '足球', value: 2 }
+    ]
+
+    const WOMEN_LINK = [
+      { label: '羽毛球', value: 3 },
+      { label: '乒乓球', value: 4 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input'
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION
+        },
+        {
+          label: '爱好',
+          name: 'favorite',
+          type: 'select',
+          watch: ['sex'],
+          options({ sex }) {
+            return sex === 1 ? MAN_LINK : WOMEN_LINK
+          }
+        },
+        {
+          label: '籍贯',
+          name: 'location',
+          type: 'cascader',
+          async options() {
+            const list = await apiMock()
+            return list
+          }
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+
+## 数据校验
+
+::: demo
+```html
+<template>
+  <div class="iov-pro-form-demo">
+    <iov-pro-form
+      ref="form"
+      v-model="formData"
+      :items="ITEMS"
+    />
+    <div style="margin-top: 12px; text-align: center;">
+      <el-button round @click="onClearValidate">清除校验</el-button>
+      <el-button type="primary" round @click="onValidate">校验</el-button>
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input',
+          rules: { required: true, message: '请输入姓名', trigger: ['change', 'blur'] }
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION,
+          rules: { required: true, message: '请选择性别', trigger: 'change' }
+        }
+      ]
+    }
+  },
+  methods: {
+    /**
+     * 清除校验
+     */
+    onClearValidate() {
+      this.$refs.form.clearValidate()
+    },
+
+    /**
+     * 触发校验
+     */
+    async onValidate() {
+      await this.$refs.form.validate()
+    }
+  }
+}
+</script>
+```
+:::
+
+## 栅格系统
+
+::: demo
+```html
+<template>
+  <iov-pro-form
+    v-model="formData"
+    :items="ITEMS"
+    :config="{ grid: true, gutter: 12, labelWidth: '40px' }"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    const BOOL_VALUE = [
+      { label: '是', value: true },
+      { label: '否', value: false }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input',
+          span: 12
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          span: 12,
+          options: SEX_OPTION
+        },
+        {
+          label: '最喜欢的体育运动',
+          vif: ({ sex }) => sex === 1,
+          name: 'sport',
+          type: 'input',
+          labelWidth: '120px',
+          span: 12
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+
+## 有条件显示
+
+::: demo
+```html
+<template>
+  <iov-pro-form
+    v-model="formData"
+    :items="ITEMS"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    const BOOL_VALUE = [
+      { label: '是', value: true },
+      { label: '否', value: false }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        { label: '姓名', name: 'name', type: 'input' },
+        { label: '性别', name: 'sex', type: 'select', options: SEX_OPTION },
+        { label: '最喜欢的体育运动', vif: ({ sex }) => sex === 1, name: 'sport', type: 'input' }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+
+## 监听字段变化
+
+::: demo
+```html
+<template>
+  <iov-pro-form
+    v-model="formData"
+    :items="ITEMS"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    const MAN_LINK = [
+      { label: '篮球', value: 1 },
+      { label: '足球', value: 2 }
+    ]
+
+    const WOMEN_LINK = [
+      { label: '羽毛球', value: 3 },
+      { label: '乒乓球', value: 4 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input'
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION
+        },
+        {
+          label: '爱好',
+          watch: ['sex'],
+          name: 'like',
+          type: 'select',
+          options: ({ sex }) => sex === 1 ? MAN_LINK : WOMEN_LINK
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+
+## 监听外部字段变化
+
+::: demo
+```html
+<template>
+  <div class="iov-pro-form-demo">
+    <iov-pro-space space="12px">
+      <div>
+        <iov-pro-sub-title name="外部数据源" />
+        <el-select v-model="dataSource.range" placeholder="请选择年龄范围">
+          <el-option label="低于35岁" :value="true" />
+          <el-option label="高于35岁" :value="false" />
+        </el-select>
+      </div>
+      <div>
+        <iov-pro-sub-title name="表单" />
+        <iov-pro-form
+          v-model="formData"
+          :data-source="dataSource"
+          :items="ITEMS"
+        />
+      </div>
+    </iov-pro-space>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    const MAN_LINK = [
+      { label: '篮球', value: 1 },
+      { label: '足球', value: 2 }
+    ]
+
+    const WOMEN_LINK = [
+      { label: '羽毛球', value: 3 },
+      { label: '乒乓球', value: 4 }
+    ]
+
+    return {
+      formData: {},
+      dataSource: { range: false },
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input'
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION
+        },
+        {
+          label: '爱好',
+          watch: ['sex', 'dataSource.range'],
+          name: 'like',
+          type: 'select',
+          options: {
+            handler({ sex }, dataSource) {
+              if (!dataSource.range) {
+                return [
+                  { label: '钓鱼', value: 5 },
+                  { label: '广场舞', value: 6 }
+                ]
+              }
+              return [0, 1].includes(sex) ? [WOMEN_LINK, MAN_LINK][sex] : []
+            },
+            inject: ['dataSource']
+          }
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+
+## 动态Props
+当组件的状态（比如：`disabled` ）需要根据表单字段中值来控制，则可以使用动态 `Props` 来实现目的。
+
+::: demo
+```html
+<template>
+  <iov-pro-form
+    v-model="formData"
+    :items="ITEMS"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    const WOMEN_LINK = [
+      { label: '羽毛球', value: 3 },
+      { label: '乒乓球', value: 4 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input'
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION,
+          props: {
+            placeholder: '请选择对应的性别',
+            clearable: true
+          }
+        },
+        {
+          label: '爱好',
+          name: 'like',
+          type: 'select',
+          options: WOMEN_LINK,
+          props: ({ sex }) => ({ disabled: sex === 1 })
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 事件监听
+
+::: demo
+```html
+<template>
+  <iov-pro-form
+    v-model="formData"
+    :items="ITEMS"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    const WOMEN_LINK = [
+      { label: '羽毛球', value: 3 },
+      { label: '乒乓球', value: 4 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input',
+          on: {
+            /**
+             * 输入事件
+             */
+            input(val) {
+              alert('当前输入的是：' + val)
+            }
+          }
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION,
+          props: {
+            placeholder: '请选择对应的性别',
+            clearable: true
+          },
+          on: {
+            /**
+             * 改变事件
+             */
+            change(val) {
+              alert('当前选中的是：' + (val === 1 ? '男' : '女'))
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 参数注入
+如果当前需要获取完整表单数据，或者外部数据源数据，或者需要获取表单上下文 `this` 实例或者当前页面上下文 `this` 实例，进行函数调用。则需要注入参数到函数中。可注入的对象有：表单数据（`model`），外部数据源（`dataSource`），表单上下文（`formThis`）以及页面上下文 `this`（`pageThis`）。其中页面上下文需要通过provide方式传递给表单组件，否则，表单组件认为父组件即为页面。
+::: demo
+```html
+<template>
+  <iov-pro-form
+    v-model="formData"
+    :items="ITEMS"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    const WOMEN_LINK = [
+      { label: '羽毛球', value: 3 },
+      { label: '乒乓球', value: 4 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input',
+          props: {
+            disabled: true
+          }
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION,
+          props: {
+            placeholder: '请选择对应的性别',
+            clearable: true
+          },
+          on: {
+            /**
+             * 改变事件
+             */
+            change: {
+              handler(val, pageThis, model) {
+                if (val === 1) {
+                  pageThis.$set(model, 'name', '郭靖')
+                } else if (val === 0) {
+                  pageThis.$set(model, 'name', '黄蓉')
+                } else {
+                  pageThis.$set(model, 'name', '')
+                }
+                pageThis.onConsoleData('当前表单数据为: ' + JSON.stringify(model))
+              },
+              inject: ['pageThis', 'model']
+            }
+          }
+        }
+      ]
+    }
+  },
+  provide() {
+    return {
+      pageThis: this
+    }
+  },
+  methods: {
+    /**
+     * 打印data数据
+     */
+    onConsoleData(message) {
+      this.$message.info(message)
+    }
+  }
+}
+</script>
+```
+:::
+
+
+## 使用全局自定义指令
+使用 `directive` 字段可以使用全局自定义指令，或者 `v-model` 指令的修饰符。其中 `v-model` 指令的修饰符需要传递字符串，例如：`model.trim`, `model.number` 。但是自定义指令需要 `{ name: '指令名称', value: '指令值' }` 格式的数据。如果需要插入多个指令，请传递数组形式。
+::: demo
+```html
+<template>
+  <iov-pro-form
+    v-model="formData"
+    :items="ITEMS"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    const SEX_OPTION = [
+      { label: '男', value: 1 },
+      { label: '女', value: 0 }
+    ]
+
+    const WOMEN_LINK = [
+      { label: '羽毛球', value: 3 },
+      { label: '乒乓球', value: 4 }
+    ]
+
+    return {
+      formData: {},
+      ITEMS: [
+        {
+          label: '姓名',
+          name: 'name',
+          type: 'input',
+          directive: 'model.trim'
+        },
+        {
+          label: '年龄',
+          name: 'age',
+          type: 'input',
+          directive: [
+            'model.trim',
+            { name: 'number', value: 2 }
+          ]
+        },
+        {
+          label: '家庭存款',
+          name: 'money',
+          type: 'input',
+          directive: { name: 'number', value: 2 }
+        },
+        {
+          label: '性别',
+          name: 'sex',
+          type: 'select',
+          options: SEX_OPTION,
+          props: {
+            placeholder: '请选择对应的性别',
+            clearable: true
+          }
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+
+## Attributes
+
+| 参数 | 说明 | 类型 | 可选值 | 默认值 |
+| ------- | ------- | ------- | ------- | ------- |
+| value | 双向绑定的数据 | Object | -  | - |
+| items | 描述项配置,详见下方 Items 配置 | Array | - | - |
+| dataSource | 外部数据源，用于items配置中需要监听的表单外数据 | Object | - | - |
+| config | 表单配置 | Object | - | - |
+
+## Config Attributes
+
+| 参数 | 说明 | 类型 | 可选值 | 默认值 |
+| ------- | ------- | ------- | ------- | ------- |
+| grid | 是否需要栅格系统 | Boolean | -  | - |
+| span | 表单项兜底的栅格的数值，可被表单项栅格配置覆盖 | Number | - | - |
+| gutter | 栅格之间间隔 | Number | - | - |
+| size | 表单输入组件尺寸 | String | medium/small/mini | - |
+| labelPosition | 描述项位置 | String | left/right/top | - |
+| labelWidth | 描述项文案宽度 | Number/String | - | - |
+| disabled | 是否禁用该表单内的所有组件 | Boolean | - | false |
+| inline | 行内表单模式	 | Boolean | - | false |
+
+## Items Attributes
+
+| 参数 | 说明 | 类型 | 可选值 | 默认值 |
+| ------- | ------- | ------- | ------- | ------- |
+| type | 当前使用控件类型，支持自定义组件 | String/vnode | slot/select/input/cascader/date-picker/radio/checkbox等 | - |
+| label | 描述项文案 | String | - | - |
+| labelWidth | 描述项文案宽度 | Number/String | - | - |
+| name | 当前字段名。如果类型为数组，则将数据解构成数组字段 | String/Array | - | - |
+| props | 需要传递给输入组件的属性配置，详见组件库的输入组件入参 | Object/Function | - | - |
+| span | 当前栅格的数值 | Number | 1-24 | 6 |
+| vif | 设置字段是否需要展示 | Boolean/Function | - | - |
+| rules | 设置当前表单项的校验规则 | Object/Array | - | - |
+| directive | 给组件绑定自定义指令 | String/Object/Array | - | - |
+| size | 当前输入组件的尺寸 | String | medium/small/mini | - |
+| options | 输入组件获取的options数据 | Array/Function/Promise | - | - |
+
+## Form Methods
+
+| 方法名 | 说明 | 参数 |
+| ------- | ------- | ------- |
+| validate | 对整个表单进行校验的方法，返回一个 promise | - |
+| clearValidate | 移除表单项的校验结果。传入待移除的表单项的 prop 属性或者 prop 组成的数组，如不传则移除整个表单的校验结果 | Function(props: Array/string) |
+| resetFields | 对整个表单进行重置，将所有字段值重置为初始值并移除校验结果 | - |
+| getOptions | 获取指定字段的下拉数据 | Function(props: Array/string) |