Form 表单

具有数据收集、校验和提交功能的表单，包含复选框、单选框、输入框、下拉选择框等元素。

何时使用

需要进行数据收集、数据校验、数据提交功能时。

基础用法

默认提供水平布局，data参数用于设置表单数据。

<template>
  <d-form :data="formModel">
    <d-form-item field="name" label="Name" help-tips="This is the plan name." extra-info="Enter a short name that meets reading habits.">
      <d-input v-model="formModel.name" />
    </d-form-item>
    <d-form-item field="description" label="Description">
      <d-textarea v-model="formModel.description" />
    </d-form-item>
    <d-form-item field="select" label="Select">
      <d-select v-model="formModel.select" :options="selectOptions" />
    </d-form-item>
    <d-form-item field="radio" label="Radio">
      <d-radio-group direction="row" v-model="formModel.radio">
        <d-radio value="0">Manual execution</d-radio>
        <d-radio value="1">Daily execution</d-radio>
        <d-radio value="2">Weekly execution</d-radio>
      </d-radio-group>
    </d-form-item>
    <d-form-item field="switch" label="Switch">
      <d-switch v-model="formModel.switch"></d-switch>
    </d-form-item>
    <d-form-item field="executionDay">
      <template #label><span>Execution day</span></template>
      <d-checkbox-group v-model="formModel.executionDay" label="Execution day" direction="row">
        <d-checkbox label="Mon" value="Mon" />
        <d-checkbox label="Tue" value="Tue" />
        <d-checkbox label="Wed" value="Wed" />
        <d-checkbox label="Thur" value="Thur" />
        <d-checkbox label="Fri" value="Fri" />
        <d-checkbox label="Sat" value="Sat" />
        <d-checkbox label="Sun" value="Sun" />
      </d-checkbox-group>
    </d-form-item>
    <d-form-operation class="form-demo-form-operation">
      <d-button variant="solid">提交</d-button>
      <d-button>取消</d-button>
    </d-form-operation>
  </d-form>
</template>

<script>
import { defineComponent, reactive, ref, nextTick } from 'vue';

export default defineComponent({
  setup() {
    let formModel = reactive({
      name: '',
      description: '',
      select: 'Options2',
      radio: '0',
      switch: true,
      executionDay: [],
    });
    const selectOptions = reactive(['Options1', 'Options2', 'Options3']);
    return {
      formModel,
      selectOptions,
    };
  },
});
</script>

<style>
.form-demo-form-operation > * {
  margin-right: 8px;
}
</style>

表单样式

水平排列模式下，label-size可以设置label的宽度，提供sm、md、lg三种大小，分别对应80px、100px、150px，默认为md；label-align可以设置label的对齐方式，可选值为start、center、end，默认为start。

<template>
  <div class="form-btn-groups">
    <div class="form-btn">
      大小：
      <d-radio-group direction="row" v-model="size">
        <d-radio v-for="item in sizeList" :key="item.label" :value="item.value">
          {{ item.label }}
        </d-radio>
      </d-radio-group>
    </div>
    <div class="form-btn">
      对齐方式：
      <d-radio-group direction="row" v-model="align">
        <d-radio v-for="item in alignList" :key="item.label" :value="item.value">
          {{ item.label }}
        </d-radio>
      </d-radio-group>
    </div>
  </div>
  <d-form :data="formModel" :label-size="size" :label-align="align">
    <d-form-item field="name" label="Name">
      <d-input v-model="formModel.name" />
    </d-form-item>
    <d-form-item field="description" label="Description">
      <d-textarea v-model="formModel.description" />
    </d-form-item>
    <d-form-item field="executionDay" label="Execution day">
      <d-checkbox-group v-model="formModel.executionDay" label="Execution day" direction="row">
        <d-checkbox label="Mon" value="Mon" />
        <d-checkbox label="Tue" value="Tue" />
        <d-checkbox label="Wed" value="Wed" />
        <d-checkbox label="Thur" value="Thur" />
        <d-checkbox label="Fri" value="Fri" />
        <d-checkbox label="Sat" value="Sat" />
        <d-checkbox label="Sun" value="Sun" />
      </d-checkbox-group>
    </d-form-item>
    <d-form-operation class="form-demo-form-operation">
      <d-button variant="solid">提交</d-button>
      <d-button>取消</d-button>
    </d-form-operation>
  </d-form>
</template>

<script>
import { defineComponent, reactive, ref } from 'vue';

export default defineComponent({
  setup() {
    const formModel = reactive({
      name: '',
      description: '',
      executionDay: [],
    });
    const size = ref('md');
    const align = ref('start');
    const sizeList = [
      {
        label: 'Small',
        value: 'sm',
      },
      {
        label: 'Middle',
        value: 'md',
      },
      {
        label: 'Large',
        value: 'lg',
      },
    ];
    const alignList = [
      {
        label: 'Start',
        value: 'start',
      },
      {
        label: 'Center',
        value: 'center',
      },
      {
        label: 'End',
        value: 'end',
      },
    ];

    return {
      formModel,
      size,
      sizeList,
      align,
      alignList,
    };
  },
});
</script>

<style>
.form-btn-groups {
  display: flex;
  flex-wrap: wrap;
  margin-bottom: 16px;
}
.form-btn {
  display: flex;
  justify-content: flex-start;
  align-items: center;
  margin-right: 1rem;
}
</style>

垂直排列

设置layout参数为vertical可启用垂直布局，即label在输入控件的上方。

<template>
  <d-form layout="vertical" :data="formModel">
    <d-form-item field="name" label="Name">
      <d-input v-model="formModel.name" />
    </d-form-item>
    <d-form-item field="description" label="Description">
      <d-textarea v-model="formModel.description" />
    </d-form-item>
    <d-form-item field="select" label="Select">
      <d-select v-model="formModel.select" :options="selectOptions" />
    </d-form-item>
    <d-form-item field="radio" label="Radio">
      <d-radio-group direction="row" v-model="formModel.radio">
        <d-radio value="0">Manual execution</d-radio>
        <d-radio value="1">Daily execution</d-radio>
        <d-radio value="2">Weekly execution</d-radio>
      </d-radio-group>
    </d-form-item>
    <d-form-item field="switch" label="Switch">
      <d-switch v-model="formModel.switch"></d-switch>
    </d-form-item>
    <d-form-item field="executionDay" label="Execution day">
      <d-checkbox-group v-model="formModel.executionDay" label="Execution day" direction="row">
        <d-checkbox label="Mon" value="Mon" />
        <d-checkbox label="Tue" value="Tue" />
        <d-checkbox label="Wed" value="Wed" />
        <d-checkbox label="Thur" value="Thur" />
        <d-checkbox label="Fri" value="Fri" />
        <d-checkbox label="Sat" value="Sat" />
        <d-checkbox label="Sun" value="Sun" />
      </d-checkbox-group>
    </d-form-item>
    <d-form-operation class="form-demo-form-operation">
      <d-button variant="solid">提交</d-button>
      <d-button>取消</d-button>
    </d-form-operation>
  </d-form>
</template>

<script>
import { defineComponent, reactive } from 'vue';

export default defineComponent({
  setup() {
    let formModel = reactive({
      name: '',
      description: '',
      select: 'Options2',
      radio: '0',
      switch: true,
      executionDay: [],
    });
    const selectOptions = reactive(['Options1', 'Options2', 'Options3']);

    return {
      formModel,
      selectOptions,
    };
  },
});
</script>

多列表单

搭配Grid栅格布局方案，即可方便的实现多列表单布局效果。

<template>
  <d-form layout="vertical" :data="formModel">
    <d-row :gutter="16">
      <d-col :span="7">
        <d-form-item field="name" label="Name" help-tips="This is the plan name.">
          <d-input v-model="formModel.name" />
        </d-form-item>
      </d-col>
      <d-col :span="7">
        <d-form-item field="select" label="Select">
          <d-select v-model="formModel.select" :options="selectOptions" />
        </d-form-item>
      </d-col>
      <d-col :span="7">
        <d-form-item field="multiSelect" label="Multiple Select">
          <d-select v-model="formModel.multiSelect" :options="selectOptions" multiple />
        </d-form-item>
      </d-col>
    </d-row>
    <d-row :gutter="16">
      <d-col :span="7">
        <d-form-item field="executionDay" label="Execution day">
          <d-checkbox-group v-model="formModel.executionDay" label="Execution day">
            <d-checkbox label="Mon" value="Mon" />
            <d-checkbox label="Tue" value="Tue" />
            <d-checkbox label="Wed" value="Wed" />
            <d-checkbox label="Thur" value="Thur" />
            <d-checkbox label="Fri" value="Fri" />
            <d-checkbox label="Sat" value="Sat" />
            <d-checkbox label="Sun" value="Sun" />
          </d-checkbox-group>
        </d-form-item>
      </d-col>
      <d-col :span="7">
        <d-form-item field="radio" label="Radio">
          <d-radio-group direction="row" v-model="formModel.radio">
            <d-radio value="0">Manual execution</d-radio>
            <d-radio value="1">Daily execution</d-radio>
            <d-radio value="2">Weekly execution</d-radio>
          </d-radio-group>
        </d-form-item>
      </d-col>
      <d-col :span="7">
        <d-form-item field="switch" label="Switch">
          <d-switch v-model="formModel.switch"></d-switch>
        </d-form-item>
      </d-col>
    </d-row>
    <d-form-operation class="form-demo-form-operation">
      <d-button variant="solid">提交</d-button>
      <d-button>取消</d-button>
    </d-form-operation>
  </d-form>
</template>

<script>
import { defineComponent, reactive, ref } from 'vue';

export default defineComponent({
  setup() {
    const formModel = reactive({
      name: '',
      select: 'Options2',
      multiSelect: ref([]),
      executionDay: [],
      radio: '0',
      switch: true,
    });
    const selectOptions = reactive(['Options1', 'Options2', 'Options3']);

    return { formModel, selectOptions };
  },
});
</script>

尺寸控制

通过size属性可控制所有控件的尺寸。

<template>
  <div class="form-demo-set-form-size">
    尺寸：
    <d-radio-group direction="row" v-model="formSize">
      <d-radio :value="item.value" v-for="item in sizeTypeList" :key="item.value">
        {{ item.label }}
      </d-radio>
    </d-radio-group>
  </div>

  <d-form :data="formModel" :size="formSize">
    <d-form-item field="name" label="Name">
      <d-input v-model="formModel.name" placeholder="请输入" />
    </d-form-item>

    <d-form-item field="search" label="Search">
      <d-search v-model="formModel.search" placeholder="请输入"></d-search>
    </d-form-item>

    <d-form-item field="inputNumber" label="InputNumber">
      <d-input-number v-model="formModel.inputNumber" placeholder="请输入"></d-input-number>
    </d-form-item>

    <d-form-item field="description" label="Description">
      <d-textarea v-model="formModel.description" />
    </d-form-item>

    <d-form-item field="select" label="Select">
      <d-select v-model="formModel.select" :options="selectOptions" />
    </d-form-item>

    <d-form-item field="autoComplete" label="AutoComplete">
      <d-auto-complete :source="source" v-model="formModel.autoComplete"></d-auto-complete>
    </d-form-item>

    <d-form-item field="radio" label="Radio">
      <d-radio-group direction="row" v-model="formModel.radio">
        <d-radio value="0">Manual execution</d-radio>
        <d-radio value="1">Daily execution</d-radio>
        <d-radio value="2">Weekly execution</d-radio>
      </d-radio-group>
    </d-form-item>

    <d-form-item field="switch" label="Switch">
      <d-switch v-model="formModel.switch"></d-switch>
    </d-form-item>

    <d-form-item field="executionDay" label="Execution day">
      <d-checkbox-group v-model="formModel.executionDay" label="Execution day" direction="row">
        <d-checkbox label="Mon" value="Mon" />
        <d-checkbox label="Tue" value="Tue" />
        <d-checkbox label="Wed" value="Wed" />
        <d-checkbox label="Thur" value="Thur" />
        <d-checkbox label="Fri" value="Fri" />
        <d-checkbox label="Sat" value="Sat" />
        <d-checkbox label="Sun" value="Sun" />
      </d-checkbox-group>
    </d-form-item>

    <d-form-item field="datePickerPro" label="Date Picker Pro">
      <d-date-picker-pro v-model="formModel.datePickerPro"></d-date-picker-pro>
    </d-form-item>

    <d-form-item field="timeSelect" label="Time Select">
      <d-time-select v-model="formModel.timeSelect" />
    </d-form-item>

    <d-form-item field="timePicker" label="Time Picker">
      <d-time-picker v-model="formModel.timePicker" placeholder="请选择时间" />
    </d-form-item>

    <d-form-operation class="form-demo-form-operation">
      <d-button variant="solid">提交</d-button>
      <d-button>取消</d-button>
    </d-form-operation>
  </d-form>
</template>

<script>
import { defineComponent, reactive, ref } from 'vue';

export default defineComponent({
  setup() {
    const sizeTypeList = [
      {
        label: 'Small',
        value: 'sm',
      },
      {
        label: 'Middle',
        value: 'md',
      },
      {
        label: 'Large',
        value: 'lg',
      },
    ];
    const formSize = ref('md');

    let formModel = reactive({
      name: '',
      search: '',
      inputNumber: 1,
      description: '',
      select: '',
      autoComplete: '',
      radio: '0',
      switch: true,
      executionDay: [],
      datePickerPro: '',
      timeSelect: '',
      timePicker: '',
    });

    const selectOptions = reactive(['Options1', 'Options2', 'Options3']);
    const source = ref(['C#', 'C', 'C++']);

    return {
      sizeTypeList,
      formSize,
      formModel,
      source,
      selectOptions,
    };
  },
});
</script>

<style>
.form-demo-set-form-size {
  display: flex;
  align-items: center;
  margin-bottom: 16px;
}

.form-demo-form-operation > * {
  margin-right: 8px;
}
</style>

表单校验

<template>
  <d-form ref="formRef" layout="vertical" :data="formData" :rules="rules" :pop-position="['right']">
    <d-form-item
      field="username"
      :rules="[{ required: true, message: '用户名不能为空', trigger: 'blur' }]"
      :show-feedback="false"
      label="用户名"
    >
      <d-input v-model="formData.username" />
    </d-form-item>
    <d-form-item field="userInfo" label="用户信息">
      <d-textarea v-model="formData.userInfo"></d-textarea>
    </d-form-item>
    <d-form-item field="age" label="年龄">
      <d-input v-model="formData.age" />
    </d-form-item>
    <d-form-item field="select" label="Select">
      <d-select v-model="formData.select" :options="selectOptions" allow-clear />
    </d-form-item>
    <d-form-item field="autoComplete" label="AutoComplete">
      <d-auto-complete :source="source" v-model="formData.autoComplete"></d-auto-complete>
    </d-form-item>
    <d-form-item field="radio" label="Radio">
      <d-radio-group direction="row" v-model="formData.radio">
        <d-radio value="0">Manual execution</d-radio>
        <d-radio value="1">Daily execution</d-radio>
        <d-radio value="2">Weekly execution</d-radio>
      </d-radio-group>
    </d-form-item>
    <d-form-item field="executionDay" label="Execution day">
      <d-checkbox-group v-model="formData.executionDay" label="Execution day" direction="row">
        <d-checkbox label="Mon" value="Mon" />
        <d-checkbox label="Tue" value="Tue" />
        <d-checkbox label="Wed" value="Wed" />
        <d-checkbox label="Thur" value="Thur" />
        <d-checkbox label="Fri" value="Fri" />
        <d-checkbox label="Sat" value="Sat" />
        <d-checkbox label="Sun" value="Sun" />
      </d-checkbox-group>
    </d-form-item>
    <d-form-item field="datePickerPro" label="Date Picker Pro">
      <d-date-picker-pro v-model="formData.datePickerPro"></d-date-picker-pro>
    </d-form-item>
    <d-form-item field="rangeDatePickerPro" label="Range Date Picker Pro">
      <d-range-date-picker-pro v-model="formData.rangeDatePickerPro"></d-range-date-picker-pro>
    </d-form-item>
    <d-form-operation class="form-operation-wrap">
      <d-button variant="solid" @click="onClick">提交</d-button>
      <d-button @click="onClear">清除校验结果</d-button>
      <d-button @click="onReset">重置</d-button>
    </d-form-operation>
  </d-form>
</template>

<script>
import { defineComponent, reactive, ref, watch } from 'vue';

export default defineComponent({
  setup() {
    const formRef = ref(null);
    const formData = reactive({
      username: '',
      userInfo: '',
      age: '',
      select: 'Options2',
      autoComplete: '',
      executionDay: ['Tue'],
      radio: '',
      datePickerPro: '',
      rangeDatePickerPro: ['', ''],
    });
    const selectOptions = reactive(['Options1', 'Options2', 'Options3']);
    const source = ref(['C#', 'C', 'C++']);
    const checkAge = (rule, value, callback) => {
      if (!value) {
        return callback(new Error('年龄不能为空'));
      }
      setTimeout(() => {
        if (value < 18) {
          return callback(new Error('年龄不能小于18'));
        } else {
          callback();
        }
      }, 1000);
    };

    const checkRangeDatePickerPro = (rule, value, callback) => {
      if (!value || (!value[0] && !value[1])) {
        return callback(new Error('请选择日期范围'));
      } else if (!value[0]) {
        return callback(new Error('请选择开始日期'));
      } else if (!value[1]) {
        return callback(new Error('请选择结束日期'));
      } else {
        return callback();
      }
    };

    const rules = {
      username: [{ min: 3, max: 6, message: '用户名需不小于3个字符，不大于6个字符', trigger: 'change' }],
      userInfo: [{ required: true, message: '用户信息不能为空', trigger: 'blur' }],
      age: [{ validator: checkAge }],
      select: [{ required: true, message: '请选择', trigger: 'change' }],
      autoComplete: [{ required: true, message: '请选择', trigger: 'change' }],
      executionDay: [{ type: 'array', required: true, message: '请至少选择一个执行时间', trigger: 'change' }],
      radio: [{ required: true, message: '请选择', trigger: 'change' }],
      datePickerPro: [{ type: 'object', required: true, message: '请选择日期', trigger: 'change' }],
      rangeDatePickerPro: [
        { validator: checkRangeDatePickerPro },
        { type: 'array', required: true, message: '请选择日期范围', trigger: 'change' },
      ],
    };

    const onClick = () => {
      formRef.value.validate((isValid, invalidFields) => {
        console.log(isValid);
        console.log(invalidFields);
      });
    };

    const onClear = () => {
      formRef.value.clearValidate();
    };

    const onReset = () => {
      formRef.value.resetFields();
    };

    return { formRef, formData, selectOptions, source, rules, onClick, onClear, onReset };
  },
});
</script>

<style>
.form-operation-wrap > * {
  margin-right: 8px;
}
</style>

Form 参数

参数名	类型	默认值	说明	跳转 demo
data	`object`	{}	必选，表单数据	基础用法
layout	Layout	'horizontal'	可选，设置表单的排列方式	垂直排列
label-size	LabelSize	'md'	可选，设置 label 的宽度，默认为 100px，sm 对应 80px，lg 对应 150px	表单样式
label-align	LabelAlign	'start'	可选，设置水平布局方式下，label 对齐方式	表单样式
rules	FormRules	--	可选，设置表单的校验规则	表单校验
message-type	MessageType	'popover'	可选，设置校验信息的提示方式
pop-position	PopPosition	['right','bottom']	可选，消息显示为 popover 时，popover 弹出方向
validate-on-rule-change	`boolean`	false	可选，是否在 rules 改变后立即触发一次验证
show-feedback	`boolean`	false	可选，是否展示校验结果反馈图标
disabled	`boolean`	false	可选，是否禁用该表单内的所有组件。
size	FormSize	--	可选，用于控制该表单内组件的尺寸
hide-required-mark	`boolean`	false	可选，是否隐藏所有表单项的必选标记
style-type	StyleType	'default'	可选，设置表单为灰色表单
append-to-body-scroll-strategy	AppendToBodyScrollStrategy	'reposition'	可选，消息显示为 popover 时，滚动时 popover 处理策略，默认策略跟随宿主移动；`close`为滚动时关闭
require-position	`string`	'left'	可选，必填型号的位置，可选值为`left`和`right`

Form 事件

事件名	回调参数	说明
validate	`Function(field: string, isValid: boolean, message: string) => void`	表单项被校验后触发

Form 方法

方法名	类型	说明	跳转 Demo
validate	`(callback?: FormValidateCallback) => Promise`	表单校验函数	表单校验
validateFields	`(fields: string[], callback?: FormValidateCallback) => Promise`	校验指定字段
resetFields	`(fields: string[]) => void`	重置表单项的值，并移除校验结果
clearValidate	`(fields: string[]) => void`	清除校验结果，参数为需要清除的表单项`field`，默认清除全部

Form 插槽

插槽名	说明
default	包裹整个表单内容

FormItem 参数

参数名	类型	默认值	说明	跳转 demo
label	`string`	''	可选，表单项的名称	基础用法
field	`string`	''	可选，指定验证表单需验证的字段，验证表单时必选该属性	基础用法
required	`boolean`	false	可选，表单选项是否必填
rules	FormRuleItem \| FormRuleItem[]	--	可选，表单项的校验规则	表单校验
message-type	MessageType	--	可选，用法同父组件`message-type`参数，优先级高于父组件，默认继承父组件的值
pop-position	PopPosition	--	可选，用法同父组件`pop-position`参数，优先级高于父组件，默认继承父组件的值
show-feedback	`boolean`	--	可选，是否展示校验结果反馈图标，优先级高于父组件，默认继承父组件的值
help-tips	`string \|`helptips	''	可选，表单项帮助指引提示内容，空字符串表示不设置提示内容。可传入对象类型的参数来自定义提示内容的样式、展开方向等	基础用法
extra-info	`string`	''	可选，附件信息，一般用于补充表单选项的说明	基础用法
feedback-status	FeedbackStatus	--	可选，手动指定当前 control 状态反馈

FormItem 方法

方法名	类型	说明
resetField	`() => void`	重置表单项的值，并移除校验结果
clearValidate	`() => void`	清除校验结果
validate	`(trigger: string) => Promise`	表单校验函数

FormItem 插槽

插槽名	说明
default	包裹单个表单项的输入控件
label	标签位置显示的内容
extraInfo	自定义表单项额外信息

Form 类型定义

Layout

type Layout = 'horizontal' | 'vertical';

LabelSize

type LabelSize = 'sm' | 'md' | 'lg';

LabelAlign

type LabelAlign = 'start' | 'center' | 'end';

FormRules

type FormRules = Partial<Record<string, Array<FormRuleItem>>>;

MessageType

type MessageType = 'popover' | 'text' | 'none';

PopPosition

type PopPosition =
  | 'top'
  | 'right'
  | 'bottom'
  | 'left'
  | 'top-start'
  | 'top-end'
  | 'right-start'
  | 'right-end'
  | 'bottom-start'
  | 'bottom-end'
  | 'left-start'
  | 'left-end';

FormSize

type FormSize = 'sm' | 'md' | 'lg';

FormValidateCallback

ValidateFieldsError类型参考async-validator。

type FormValidateCallback = (isValid: boolean, invalidFields?: ValidateFieldsError) => void;

StyleType

type StyleType = 'default' | 'gray';

AppendToBodyScrollStrategy

type AppendToBodyScrollStrategy = 'close' | 'reposition';

FormItem 类型定义

FormRuleItem

RuleItem类型参考async-validator。

interface FormRuleItem extends RuleItem {
  trigger?: Array<string>;
}

FeedbackStatus

type FeedbackStatus = 'success' | 'error' | 'pending';

HelpTips

interface HelpTips {
  content: string; // 提示内容
  position?: PopPosition[]; // 展开方向
  trigger?: 'hover' | 'click'; // 触发方式
  popType?: string; // 提示类型
}

Contributors

EditableSelect 可输入下拉选择框

Input 输入框

Form 表单 #

何时使用 #

基础用法 #

表单样式 #

垂直排列 #

多列表单 #

尺寸控制 #

表单校验 #

Form 参数 #

Form 事件 #

Form 方法 #

Form 插槽 #

FormItem 参数 #

FormItem 方法 #

FormItem 插槽 #

Form 类型定义 #

Layout #

LabelSize #

LabelAlign #

FormRules #

MessageType #

PopPosition #

FormSize #

FormValidateCallback #

StyleType #

AppendToBodyScrollStrategy #

FormItem 类型定义 #

FormRuleItem #

FeedbackStatus #

HelpTips #