Form 表单

介绍

用于数据录入、校验，支持输入框、单选框、复选框、文件上传等类型。

基础用法

通过 model 绑定表单数据对象，通过 prop 绑定表单项字段名。

<vd-form :model="form">
  <vd-form-item label="账号" prop="user">
    <vd-input v-model="form.user" placeholder="请输入账号" clearable />
  </vd-form-item>
  <vd-form-item label="密码" prop="password">
    <vd-input v-model="form.password" type="password" placeholder="请输入密码" clearable />
  </vd-form-item>
</vd-form>

const form = ref<any>({});

标签位置

通过 label-position 属性配置标签位置，支持 left、top 两种方式。

<vd-form :model="form" label-position="top">
  ...
</vd-form>

标签宽度

通过 label-width 属性配置标签宽度，默认 6.2em 宽度。

<vd-form :model="form" label-width="8em">
 ...
</vd-form>

内容对齐方式

通过 body-align 属性配置内容对齐方式，支持 left、center、right 三种方式。

<vd-form :model="form" body-align="right">
 ...
</vd-form>

表单校验

通过 rules 属性配置校验规则，支持 required、pattern、validator 等规则。

<vd-form ref="formRef" :model="form">
  <vd-form-item label="必填" prop="required" required>
    <vd-input v-model="form.required" placeholder="正则校验" clearable />
  </vd-form-item>
  <vd-form-item label="正则" prop="pattern" required :rules="rule.pattern">
    <vd-input v-model="form.pattern" placeholder="正则校验" clearable />
  </vd-form-item>
  <vd-form-item label="函数" prop="validator" required :rules="rule.validator">
    <vd-input v-model="form.validator" placeholder="函数校验" clearable />
  </vd-form-item>
  <vd-form-item label="异步" prop="async" required :rules="rule.async">
    <vd-input v-model="form.async" placeholder="异步函数" clearable />
  </vd-form-item>
</vd-form>
<vd-button type="primary" block :action="handleSubmit">提交</vd-button>

import { timeout } from '@vital-design/shared';

const formRef = shallowRef();
const form = ref<any>({});

const rule = reactive({
  pattern: [
    { pattern: /^[0-9]+$/g, message: '只能是0-9的数字组合' },
  ],
  validator: [
    {
      validator: (value: any) => val.length >= 2,
      message: '至少输入2位字符',
    }
  ],
  async: [
    {
      validator: async (value: any) => {
        await timeout(1000);

        if (value === '123456') {
          return true;
        }

        return '校验失败，请输入123456';
      },
    }
  ],
});

async function handleSubmit() {
  if (!await formRef.value.validate()) {
    return; // 校验失败
  }

  console.log('校验通过');
}

动态表单

同一对象下的表单项，可通过绑定字段路径 prop 来访问对象下的数据。

<vd-form ref="formRef" :model="form">
  <vd-row v-for="(item, index) in form.rows" :key="index" gutter="8" align="center">
    <vd-col span="1">{{ index + 1}}</vd-col>
    <vd-col span="9">
      <vd-form-item :prop="`rows.${index}.name`" required>
        <vd-input v-model="form.rows[index].name" placeholder="请输入姓名" clearable />
      </vd-form-item>
    </vd-col>
    <vd-col span="9">
      <vd-form-item :prop="`rows.${index}.address`" required>
        <vd-input v-model="form.rows[index].address" placeholder="请输入地址" clearable />
      </vd-form-item>
    </vd-col>
    <vd-col span="5">
      <vd-button type="primary" link plain block @click="handleAdd">新增</vd-button>
    </vd-col>
  </vd-row>
</vd-form>
<vd-button type="primary" block @click="handleSubmit">提交</vd-button>

const formRef = shallowRef();

const form = ref<any>({
  rows: [{}],
});

function handleAdd() {
  form.value.rows.push({});
}

async function handleSubmit() {
  if (!await formRef.value.validate()) {
    return; // 校验失败
  }

  console.log('校验通过');
}

API

Form Props

参数	说明	类型	默认值
model	表单数据对象	any	-
rules	表单校验规则	Record<string, FormItemRule[]>	-
borderless	是否不显示内边框	boolean	false
label-width	标签宽度	string	6.2em
label-align	标签对齐方式	'left' | 'center' | 'right'	'left'
label-position	标签位置	'left' | 'top'	'left'
body-align	内容对齐方式	'left' | 'center' | 'right'	'left'
required	是否展示表单必填星号	boolean | 'auto'	'auto'
required-position	表单必填星号展示位置	'left' | 'right'	'left'
validate-first	是否在某一项校验不通过时停止校验	boolean	false
scroller	滚动至表单项时触发的滚动条节点标识名称	string	最近的可y轴滚动的滚动条
scroll-direction	滚动至表单项时的滚动方向	'x' | 'y'	['x', 'y']
scroll-offset-left	滚动至表单项时的水平滚动偏移量	string | number	16
scroll-offset-top	滚动至表单项时的垂直滚动偏移量	string | number	16
scroll-to-error	是否在提交表单且校验不通过时滚动至错误的表单项	boolean	true
error-message	是否在校验不通过时在输入框下方展示错误提示	boolean	true
error-message-align	错误提示文案对齐方式	'left' | 'center' | 'right'	'left'

FormItem Props

参数	说明	类型	默认值
prop	表单对象属性	string	-
value	表单项数据，优先级高于 prop	unknown	-
rules	表单校验规则	FormItemRule[]	-
is-link	是否展示右侧箭头并开启点击反馈	boolean	-
clickable	是否开启点击反馈	boolean	-
left-icon	左侧图标	IconsName	-
right-icon	右侧图标	IconsName	-
label	标签文字	string	-
label-width	标签宽度	string	6.2em
label-align	标签对齐方式	'left' | 'center' | 'right'	'left'
label-position	标签位置	'left' | 'top'	'left'
body-align	内容对齐方式	'left' | 'center' | 'right'	'left'
required	是否展示表单必填星号	boolean | 'auto'	'auto'
required-position	表单必填星号展示位置	'left' | 'right'	'left'
error-message	是否在校验不通过时在输入框下方展示错误提示	boolean	true
error-message-align	错误提示文案对齐方式	'left' | 'center' | 'right'	'left'

代替原始 Props

参数	说明	类型	默认值
custom-id	根节点id	string	-
custom-class	根节点类名	ClassValue	-
custom-style	根节点样式	StyleValue	-

Form Events

事件名	说明	回调参数
click	点击时触发	MouseEvent

FormItem Events

事件名	说明	回调参数
click	点击时触发	MouseEvent
click-left-icon	点击左侧图标时触发	MouseEvent
click-right-icon	点击左侧图标时触发	MouseEvent
click-label	点击标签时触发	MouseEvent
click-value	点击值区域时触发	MouseEvent
click-body	点击内容区域时触发	MouseEvent
click-error-message	点击错误信息时触发	MouseEvent

Form Slots

名称	说明
default	自定义内容

FormItem Slots

名称	说明
default	自定义内容
left-icon	左侧图标
right-icon	右侧图标
label	标签
error-message	错误信息