zk-desktop-ui/docs/components/form.md

ZKTeco UI Components

## Form 表单

由输入框、选择器、单选框、多选框等控件组成，用以收集、校验、提交数据

### 典型表单

包括各种表单项，比如输入框、选择器、开关、单选框、多选框等。

> demo

 在 Form 组件中，每一个表单域由一个 Form-Item 组件构成，表单域中可以放置各种类型的表单控件，包括 Input、Select、Checkbox、Radio、Switch、DatePicker、TimePicker
```html
<zk-form ref="form" :model="form" labzk-width="80px">
  <zk-form-item label="活动名称">
    <zk-input v-model="form.name"></zk-input>
  </zk-form-item>
  <zk-form-item label="活动区域">
    <zk-select v-model="form.region" placeholder="请选择活动区域">
      <zk-option label="区域一" value="shanghai"></zk-option>
      <zk-option label="区域二" value="beijing"></zk-option>
    </zk-select>
  </zk-form-item>
  <zk-form-item label="活动时间">
    <zk-col :span="11">
      <zk-date-picker type="date" placeholder="选择日期" v-model="form.date1" style="width: 100%;"></zk-date-picker>
    </zk-col>
    <zk-col class="line" :span="2">-</zk-col>
    <zk-col :span="11">
      <zk-time-picker type="fixed-time" placeholder="选择时间" v-model="form.date2" style="width: 100%;"></zk-time-picker>
    </zk-col>
  </zk-form-item>
  <zk-form-item label="即时配送">
    <zk-switch on-text="" off-text="" v-model="form.delivery"></zk-switch>
  </zk-form-item>
  <zk-form-item label="活动性质">
    <zk-checkbox-group v-model="form.type">
      <zk-checkbox label="美食/餐厅线上活动" name="type"></zk-checkbox>
      <zk-checkbox label="地推活动" name="type"></zk-checkbox>
      <zk-checkbox label="线下主题活动" name="type"></zk-checkbox>
      <zk-checkbox label="单纯品牌曝光" name="type"></zk-checkbox>
    </zk-checkbox-group>
  </zk-form-item>
  <zk-form-item label="特殊资源">
    <zk-radio-group v-model="form.resource">
      <zk-radio label="线上品牌商赞助"></zk-radio>
      <zk-radio label="线下场地免费"></zk-radio>
    </zk-radio-group>
  </zk-form-item>
  <zk-form-item label="活动形式">
    <zk-input type="textarea" v-model="form.desc"></zk-input>
  </zk-form-item>
  <zk-form-item>
    <zk-button type="primary" @click="onSubmit">立即创建</zk-button>
    <zk-button>取消</zk-button>
  </zk-form-item>
</zk-form>
<script>
  export default {
    data() {
      return {
        form: {
          name: '',
          region: '',
          date1: '',
          date2: '',
          delivery: false,
          type: [],
          resource: '',
          desc: ''
        }
      }
    },
    methods: {
      onSubmit() {
        console.log('submit!');
      }
    }
  }
</script>
```



### 行内表单

当垂直方向空间受限且表单较简单时，可以在一行内放置表单。

> demo

 设置 `inline` 属性可以让表单域变为行内的表单域
```html
<zk-form :inline="true" :model="formInline" class="demo-form-inline">
  <zk-form-item>
    <zk-input v-model="formInline.user" placeholder="审批人"></zk-input>
  </zk-form-item><zk-form-item>
    <zk-select v-model="formInline.region" placeholder="活动区域">
      <zk-option label="区域一" value="shanghai"></zk-option>
      <zk-option label="区域二" value="beijing"></zk-option>
    </zk-select>
  </zk-form-item><zk-form-item>
    <zk-button type="primary" @click="onSubmit">查询</zk-button>
  </zk-form-item>
</zk-form>
<script>
  export default {
    data() {
      return {
        formInline: {
          user: '',
          region: ''
        }
      }
    },
    methods: {
      onSubmit() {
        console.log('submit!');
      }
    }
  }
</script>
```



### 对齐方式

根据具体目标和制约因素，选择最佳的标签对齐方式。

顶部对齐

> demo

 通过设置 `labzk-position` 属性可以改变表单域标签的位置，可选值为 `top`、`left`，当设为 `top` 时标签会置于表单域的顶部
```html
<zk-form labzk-position="top" :model="formStacked" class="demo-form-stacked">
  <zk-form-item label="名称">
    <zk-input v-model="formStacked.name"></zk-input>
  </zk-form-item>
  <zk-form-item label="活动区域">
    <zk-input v-model="formStacked.region"></zk-input>
  </zk-form-item>
  <zk-form-item label="活动展开形式">
    <zk-input v-model="formStacked.type"></zk-input>
  </zk-form-item>
</zk-form>
<script>
  export default {
    data() {
      return {
        formStacked: {
          name: '',
          region: '',
          type: ''
        }
      };
    }
  }
</script>
```



右对齐

> demo

 通过设置 `labzk-position` 属性可以改变表单域标签的位置，默认不设置的情况下标签是右对齐的
```html
<zk-form :model="formAlignRight" labzk-width="80px">
  <zk-form-item label="活动名称">
    <zk-input v-model="formAlignRight.name"></zk-input>
  </zk-form-item>
  <zk-form-item label="推广地">
    <zk-input v-model="formAlignRight.region"></zk-input>
  </zk-form-item>
  <zk-form-item label="活动形式">
    <zk-input v-model="formAlignRight.type"></zk-input>
  </zk-form-item>
</zk-form>
<script>
  export default {
    data() {
      return {
        formAlignRight: {
          name: '',
          region: '',
          type: ''
        }
      };
    }
  }
</script>
```



左对齐

> demo

 通过设置 `labzk-position` 属性可以改变表单域标签的位置，可选值为 `top`、`left`，当设为 `left` 时标签会变为左对齐
```html
<zk-form :model="formAlignLeft" labzk-position="left" labzk-width="80px">
  <zk-form-item label="活动名称">
    <zk-input v-model="formAlignLeft.name"></zk-input>
  </zk-form-item>
  <zk-form-item label="推广地">
    <zk-input v-model="formAlignLeft.region"></zk-input>
  </zk-form-item>
  <zk-form-item label="活动形式">
    <zk-input v-model="formAlignLeft.type"></zk-input>
  </zk-form-item>
</zk-form>
<script>
  export default {
    data() {
      return {
        formAlignLeft: {
          name: '',
          region: '',
          type: ''
        }
      };
    }
  }
</script>
```



### 表单验证

在防止用户犯错的前提下，尽可能让用户更早地发现并纠正错误。

> demo

 Form 组件提供了表单验证的功能，只需要通过 `rule` 属性传入约定的验证规则，并 Form-Item 的 `prop` 属相设置为需校验的字段名即可。校验规则参见 [async-validator](https://github.com/yiminghe/async-validator)
```html
<zk-form :model="ruleForm" :rules="rules" ref="ruleForm" labzk-width="100px" class="demo-ruleForm">
  <zk-form-item label="活动名称" prop="name">
    <zk-input v-model="ruleForm.name"></zk-input>
  </zk-form-item>
  <zk-form-item label="活动区域" prop="region">
    <zk-select v-model="ruleForm.region" placeholder="请选择活动区域">
      <zk-option label="区域一" value="shanghai"></zk-option>
      <zk-option label="区域二" value="beijing"></zk-option>
    </zk-select>
  </zk-form-item>
  <zk-form-item label="活动时间" required>
    <zk-col :span="11">
      <zk-form-item prop="date1">
        <zk-date-picker type="date" placeholder="选择日期" v-model="ruleForm.date1" style="width: 100%;"></zk-date-picker>
      </zk-form-item>
    </zk-col>
    <zk-col class="line" :span="2">-</zk-col>
    <zk-col :span="11">
      <zk-form-item prop="date2">
        <zk-time-picker type="fixed-time" placeholder="选择时间" v-model="ruleForm.date2" style="width: 100%;"></zk-time-picker>
      </zk-form-item>
    </zk-col>
  </zk-form-item>
  <zk-form-item label="即时配送">
    <zk-switch on-text="" off-text="" v-model="ruleForm.delivery"></zk-switch>
  </zk-form-item>
  <zk-form-item label="活动性质" prop="type">
    <zk-checkbox-group v-model="ruleForm.type">
      <zk-checkbox label="美食/餐厅线上活动" name="type"></zk-checkbox>
      <zk-checkbox label="地推活动" name="type"></zk-checkbox>
      <zk-checkbox label="线下主题活动" name="type"></zk-checkbox>
      <zk-checkbox label="单纯品牌曝光" name="type"></zk-checkbox>
    </zk-checkbox-group>
  </zk-form-item>
  <zk-form-item label="特殊资源" prop="resource">
    <zk-radio-group v-model="ruleForm.resource">
      <zk-radio label="线上品牌商赞助"></zk-radio>
      <zk-radio label="线下场地免费"></zk-radio>
    </zk-radio-group>
  </zk-form-item>
  <zk-form-item label="活动形式" prop="desc">
    <zk-input type="textarea" v-model="ruleForm.desc"></zk-input>
  </zk-form-item>
  <zk-form-item>
    <zk-button type="primary" @click="handleSubmit">立即创建</zk-button>
    <zk-button @click="handleReset">重置</zk-button>
  </zk-form-item>
</zk-form>
<script>
  export default {
    data() {
      return {
        ruleForm: {
          name: '',
          region: '',
          date1: '',
          date2: '',
          delivery: false,
          type: [],
          resource: '',
          desc: ''
        },
        rules: {
          name: [
            { required: true, message: '请输入活动名称', trigger: 'blur' },
            { min: 3, max: 5, message: '长度在 3 到 5 个字符', trigger: 'blur' }
          ],
          region: [
            { required: true, message: '请选择活动区域', trigger: 'change' }
          ],
          date1: [
            { type: 'date', required: true, message: '请选择日期', trigger: 'change' }
          ],
          date2: [
            { type: 'date', required: true, message: '请选择时间', trigger: 'change' }
          ],
          type: [
            { type: 'array', required: true, message: '请至少选择一个活动性质', trigger: 'change' }
          ],
          resource: [
            { required: true, message: '请选择活动资源', trigger: 'change' }
          ],
          desc: [
            { required: true, message: '请填写活动形式', trigger: 'blur' }
          ]
        }
      };
    },
    methods: {
      handleReset() {
        this.$refs.ruleForm.resetFields();
      },
      handleSubmit(ev) {
        this.$refs.ruleForm.validate((valid) => {
          if (valid) {
            alert('submit!');
          } else {
            console.log('error submit!!');
            return false;
          }
        });
      }
    }
  }
</script>
```



### 自定义校验规则

> demo

 这个例子中展示了如何使用自定义验证规则来完成密码的二次验证
```html
<zk-form :model="ruleForm2" :rules="rules2" ref="ruleForm2" labzk-width="100px" class="demo-ruleForm">
  <zk-form-item label="密码" prop="pass">
    <zk-input type="password" v-model="ruleForm2.pass" auto-complete="off"></zk-input>
  </zk-form-item>
  <zk-form-item label="确认密码" prop="checkPass">
    <zk-input type="password" v-model="ruleForm2.checkPass" auto-complete="off"></zk-input>
  </zk-form-item>
  <zk-form-item label="年龄" prop="age">
    <zk-input v-model="ruleForm2.age"></zk-input>
  </zk-form-item>
  <zk-form-item>
    <zk-button type="primary" @click="handleSubmit2">提交</zk-button>
    <zk-button @click="handleReset2">重置</zk-button>
  </zk-form-item>
</zk-form>
<script>
  export default {
    data() {
      var checkAge = (rule, value, callback) => {
        var age = parseInt(value, 10);

        setTimeout(() => {
          if (!Number.isInteger(age)) {
            callback(new Error('请输入数字值'));
          } else{
            if (age < 18) {
              callback(new Error('必须年满18岁'));
            } else {
              callback();
            }
          }
        }, 1000);
      };
      var validatePass = (rule, value, callback) => {
        if (value === '') {
          callback(new Error('请输入密码'));
        } else {
          if (this.ruleForm2.checkPass !== '') {
            this.$refs.ruleForm2.validateField('checkPass');
          }
          callback();
        }
      };
      var validatePass2 = (rule, value, callback) => {
        if (value === '') {
          callback(new Error('请再次输入密码'));
        } else if (value !== this.ruleForm2.pass) {
          callback(new Error('两次输入密码不一致!'));
        } else {
          callback();
        }
      };
      return {
        ruleForm2: {
          pass: '',
          checkPass: '',
          age: ''
        },
        rules2: {
          pass: [
            { required: true, message: '请输入密码', trigger: 'blur' },
            { validator: validatePass }
          ],
          checkPass: [
            { required: true, message: '请再次输入密码', trigger: 'blur' },
            { validator: validatePass2 }
          ],
          age: [
            { required: true, message: '请填写年龄', trigger: 'blur' },
            { validator: checkAge, trigger: 'change' }
          ]
        }
      };
    },
    methods: {
      handleReset2() {
        this.$refs.ruleForm2.resetFields();
      },
      handleSubmit2(ev) {
        this.$refs.ruleForm2.validate((valid) => {
          if (valid) {
            alert('submit!');
          } else {
            console.log('error submit!!');
            return false;
          }
        });
      }
    }
  }
</script>
```



### 动态增减表单项

> demo

 除了在 Form 组件上一次性传递所有的验证规则外还可以在单个的表单域上传递属性的验证规则
```html
<zk-form :model="dynamicForm" :rules="dynamicRule" ref="dynamicForm" labzk-width="100px" class="demo-dynamic">
  <zk-form-item prop="email" label="邮箱">
    <zk-input v-model="dynamicForm.email"></zk-input>
  </zk-form-item>
  <zk-form-item
    v-for="(domain, index) in dynamicForm.domains"
    :label="'域名' + index"
    :key="domain.key"
    :prop="'domains:' + index"
    :rules="{
      type: 'object', required: true,
      fields: {
        value: { required: true, message: '域名不能为空', trigger: 'blur' }
      }
    }"
  >
    <zk-input v-model="domain.value"></zk-input><zk-button @click.native.prevent="removeDomain(domain)">删除</zk-button>
  </zk-form-item>
  <zk-form-item>
    <zk-button type="primary" @click="handleSubmit3">提交</zk-button>
    <zk-button @click="addDomain">新增域名</zk-button>
  </zk-form-item>
</zk-form>
<script>
  export default {
    data() {
      return {
        dynamicForm: {
          domains: [{
            key: 1,
            value: ''
          }],
          email: ''
        },
        dynamicRule: {
          email: [
            { required: true, message: '请输入邮箱地址', trigger: 'blur' },
            { type: 'email', message: '请输入正确的邮箱地址', trigger: 'blur,change' }
          ]
        }
      };
    },
    methods: {
      handleSubmit3(ev) {
        this.$refs.ruleForm.validate((valid) => {
          if (valid) {
            alert('submit!');
          } else {
            console.log('error submit!!');
            return false;
          }
        });
      },
      removeDomain(item) {
        var index = this.dynamicForm.domains.indexOf(item)
        if (index !== -1) {
          this.dynamicForm.domains.splice(index, 1)
        }
      },
      addDomain() {
        this.dynamicForm.domains.push({
          key: this.dynamicForm.domains.length,
          value: ''
        });
      }
    }
  }
</script>
```



### Form Attributes

| 参数      | 说明          | 类型      | 可选值                           | 默认值  |
|---------- |-------------- |---------- |--------------------------------  |-------- |
| model   | 表单数据对象 | object      |                  —                |  — |
| rules    | 表单验证规则 | object | — | — |
| inline    | 行内表单模式 | boolean | — | false |
| labzk-position | 表单域标签的位置 | string |  right/left/top            | right |
| labzk-width | 表单域标签的宽度，所有的 form-item 都会继承 form 组件的 labelWidth 的值 | string | — | — |
| labzk-suffix | 表单域标签的后缀 | string | — | — |

### Form Methods

| 方法名      | 说明          |
|---------- |-------------- |
| validate(cb) | 对整个表单进行校验的方法 |
| validateField(prop, cb) | 对部分表单字段进行校验的方法 |
| resetFields | 对整个表单进行重置，将所有字段值重置为空并移除校验结果 |

### Form-Item Attributes

| 参数      | 说明          | 类型      | 可选值                           | 默认值  |
|---------- |-------------- |---------- |--------------------------------  |-------- |
| prop    | 表单域 model 字段 | string    | 传入 Form 组件的 `model` 中的字段 | — |
| label | 标签文本 | string | — | — |
| labzk-width | 表单域标签的的宽度，例如 '50px' | string |       —       | — |
| required | 是否必填，如不设置，则会根据校验规则自动生成 | bolean | — | false |