# Form 表单

使用数据配置项列表快速生成一个表单

## 基础用法

配置项list中通过type可以配置任意表单组件，不受框架约定限制

::: snippet 使用`list`属性设置数据源，其中的`type`指定组件类型，每一项都已设置为**el-form-item**的子组件，通过`rules`配置校验规则，`props`设置组件参数

```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: '姓名',
          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字以内' }
        },
      ]
    }
  },
  methods: {
    handleSubmit(value) {
      console.log(value)
    },
    handleCancel() {
      this.$refs.form.reset()
      console.log('cancel!')
    }
  }
}
</script>
```

:::

## 事件监听

通常的业务需求中，常常会对表单项进行事件监听，以满足级联等特殊效果

::: 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`参数，任意一个数据配置group时开始生效，若没有配置分组则默认归为**基本信息**分组，group可以是一个Object，用于快速配置一些预置的效果

```html
<template>
  <eagle-form :list="formList" style="width: 500px;"></eagle-form>
</template>

<script>
export default {
  data() {
    return {
      formList: [
        { 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 }
        },
      ]
    }
  }
}
</script>
```

:::

## 分组折叠

已经分组的表单可以折叠显示

::: snippet `collapse`配置折叠、`accordion`设置手风琴模式

```html
<template>
  <eagle-form collapse accordion :list="formList" style="width: 500px;"></eagle-form>
</template>

<script>
export default {
  data() {
    return {
      formList: [
        { 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 }
        },
      ]
    }
  }
}
</script>
```

:::

## 自定义分组

有些时候默认的分组样式并不能满足项目需求，因此可以通过**表单项具名插槽**的方式替换对应的分组

::: snippet 在组件内部通过具名插槽的方式，替换对应内容，表头具名插槽格式为`group-key`，返回值包括key及group配置内容

```html
<template>
  <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>
</template>

<script>
export default {
  data() {
    return {
      formList: [
        { type: 'el-input', key: 'name', label: '姓名', group: { key: 'base', label: '基本信息' } },
        { type: 'el-input-number', key: 'age', label: '年龄', group: { key: 'health', label: '健康信息' } },
      ]
    }
  },
}
</script>
```

:::

## API

## Attribute 属性

参数|说明|类型|可选值|默认值
-|-|-|-|-
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 事件

事件名称|说明|回调参数
-|-|-
change | 表单model发生变化时触发 | model对象
submit | 点击表单提交按钮时触发 | model对象
cancel | 点击表单取消按钮时触发 | -
validate | 表单校验成功后触发 | 校验值

## List 表单项配置列表

参数|说明|类型|可选值|默认值
-|-|-|-|-
type | 组件类型 | String | - | el-input
key | 参数名 | String | - | -
label | 参数标签 | String | - | -
props | 组件参数 | Object,Function(model: object)) | - | {}
style | 组件样式 | Object | - | { width: "100%" }
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 | - | -
tip | 组件提示框 | Object,String | - | {}
group | 表单项分组，为**Object**类型时，格式为{ key, icon, label }，key=>分组标识、icon=>Element默认图标名、label=>分组标题 | String,Object | - | -
span | 表单项占位 | Number | 0 - 24 | -