Form 表单

基于 Element Plus Form 增强的表单组件。

表单由input、 radio、 select、 checkbox等控件组成，用以收集、校验、提交数据。

TIP

该组件已升级为弹性布局（flex），替代了旧的浮动布局（float）。

基本用法

最基础的表单包括各种输入表单项，如input、 select、 radio、 checkbox等。

在每一个 Form 组件中，需要使用 bk-form-item 组件作为输入项的容器，也可通过 items 属性以配置化方式定义表单结构。每个表单项支持配置 prop、label 及相关字段属性等选项。

Activity name

Activity zone

please select your zone

Activity time

-

Instant delivery

Activity type

Online activities Promotion activities Offline activities Simple brand exposure

Resources

SponsorVenue

Activity form

Activity name

Activity zone

please select your zone

Activity time

-

Instant delivery

Activity type

Online activitiesPromotion activitiesOffline activitiesSimple brand exposure

Resources

SponsorVenue

Activity form

<template>
  <bk-form :model="form" label-width="auto" style="max-width: 600px">
    <bk-form-item label="Activity name">
      <el-input v-model="form.name" />
    </bk-form-item>
    <bk-form-item label="Activity zone">
      <el-select v-model="form.region" placeholder="please select your zone">
        <el-option label="Zone one" value="shanghai" />
        <el-option label="Zone two" value="beijing" />
      </el-select>
    </bk-form-item>
    <bk-form-item label="Activity time">
      <el-col :span="11">
        <el-date-picker
          v-model="form.date1"
          type="date"
          placeholder="Pick a date"
          style="width: 100%"
        />
      </el-col>
      <el-col :span="2" class="text-center">
        <span class="text-gray-500">-</span>
      </el-col>
      <el-col :span="11">
        <el-time-picker v-model="form.date2" placeholder="Pick a time" style="width: 100%" />
      </el-col>
    </bk-form-item>
    <bk-form-item label="Instant delivery">
      <el-switch v-model="form.delivery" />
    </bk-form-item>
    <bk-form-item label="Activity type">
      <el-checkbox-group v-model="form.type">
        <el-checkbox value="Online activities" name="type"> Online activities </el-checkbox>
        <el-checkbox value="Promotion activities" name="type"> Promotion activities </el-checkbox>
        <el-checkbox value="Offline activities" name="type"> Offline activities </el-checkbox>
        <el-checkbox value="Simple brand exposure" name="type"> Simple brand exposure </el-checkbox>
      </el-checkbox-group>
    </bk-form-item>
    <bk-form-item label="Resources">
      <el-radio-group v-model="form.resource">
        <el-radio value="Sponsor">Sponsor</el-radio>
        <el-radio value="Venue">Venue</el-radio>
      </el-radio-group>
    </bk-form-item>
    <bk-form-item label="Activity form">
      <el-input v-model="form.desc" type="textarea" />
    </bk-form-item>
    <bk-form-item>
      <bk-button type="primary" @click="onSubmit">Create</bk-button>
      <bk-button>Cancel</bk-button>
    </bk-form-item>
  </bk-form>
  <el-divider></el-divider>
  <bk-form :model="form" :items="items" label-width="auto" style="max-width: 600px">
    <bk-form-item>
      <bk-button type="primary" @click="onSubmit">Create</bk-button>
      <bk-button>Cancel</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive } from "vue"
import type { FormItem } from "vue-business-kit"

const items: FormItem[] = [
  {
    label: "Activity name",
    type: "input",
    prop: "name"
  },
  {
    label: "Activity zone",
    type: "select",
    prop: "region",
    componentProps: {
      placeholder: "please select your zone"
    },
    children: [
      { label: "Zone one", value: "shanghai" },
      { label: "Zone two", value: "beijing" }
    ]
  },
  {
    label: "Activity time",
    type: "date-picker",
    prop: "date1",
    componentProps: {
      type: "datetimerange",
      placeholder: "Pick a date",
      style: { width: "100%" }
    }
  },
  {
    label: "Instant delivery",
    type: "switch",
    prop: "delivery"
  },
  {
    label: "Activity type",
    type: "checkbox-group",
    prop: "type",
    children: [
      { label: "Online activities", value: "Online activities" },
      { label: "Promotion activities", value: "Promotion activities" },
      { label: "Offline activities", value: "Offline activities" },
      { label: "Simple brand exposure", value: "Simple brand exposure" }
    ]
  },
  {
    label: "Resources",
    type: "radio-group",
    prop: "resource",
    children: [
      { label: "Sponsor", value: "Sponsor" },
      { label: "Venue", value: "Venue" }
    ]
  },
  {
    label: "Activity form",
    type: "input",
    prop: "desc",
    componentProps: {
      type: "textarea"
    }
  }
]

// do not use same name with ref
const form = reactive({
  name: "",
  region: "",
  date1: "",
  date2: "",
  delivery: false,
  type: [],
  resource: "",
  desc: ""
})

const onSubmit = () => {
  console.log("submit!")
}
</script>

隐藏源码

提示

W3C 规范中提到：

当表单中只有一个单行文本输入框时，用户代理应将该字段中的回车视为提交表单的请求。

如需阻止该行为，可在 <bk-form> 上添加 @submit.prevent。

多列布局

当垂直空间受限且表单结构较简单时，可将表单项横向排列。

设置 col-num 属性指定表单布局的列数。

Approved by

Activity zone

Activity zone

Activity time

<template>
  <bk-form :model="formData" :items="items" :col-num="3" class="demo-form-multi">
    <bk-form-item>
      <bk-button type="primary" @click="onSubmit">Query</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive } from "vue"
import type { FormItem } from "vue-business-kit"

const formData = reactive({
  user: "",
  region: "",
  date: ""
})

const items: FormItem[] = [
  {
    label: "Approved by",
    type: "input",
    prop: "user",
    componentProps: {
      placeholder: "Approved by",
      clearable: true
    }
  },
  {
    label: "Activity zone",
    type: "select",
    prop: "region",
    componentProps: {
      placeholder: "Activity zone",
      clearable: true
    },
    children: [
      {
        label: "Zone one",
        value: "shanghai"
      },
      {
        label: "Zone two",
        value: "beijing"
      }
    ]
  },
  {
    label: "Activity time",
    type: "date-picker",
    prop: "date",
    componentProps: {
      placeholder: "Pick a date",
      clearable: true
    }
  }
]

const onSubmit = () => {
  console.log("submit!")
}
</script>

<style>
.demo-form-multi .el-input {
  --el-input-width: 220px;
}

.demo-form-multi .el-select {
  --el-select-width: 220px;
}
</style>

隐藏源码

标签对齐方式

可根据设计需求，选择不同的标签对齐方式。

可在单个表单项中单独设置 label-position，若未设置，则继承 bk-form 的 label-position 配置。

label-position 属性用于设置标签对齐方式，可选值为 top 或 left。设置为 top 时，标签会显示在表单项的顶部。

Form Align

LeftRightTop

Form Item Align

EmptyLeftRightTop

Name

Activity zone

Activity form

<template>
  <bk-form
    :label-position="labelPosition"
    label-width="auto"
    :model="formLabelAlign"
    style="max-width: 600px"
  >
    <bk-form-item label="Form Align" label-position="right">
      <el-radio-group v-model="labelPosition" aria-label="label position">
        <el-radio-button value="left">Left</el-radio-button>
        <el-radio-button value="right">Right</el-radio-button>
        <el-radio-button value="top">Top</el-radio-button>
      </el-radio-group>
    </bk-form-item>
    <bk-form-item label="Form Item Align" label-position="right">
      <el-radio-group v-model="itemLabelPosition" aria-label="item label position">
        <el-radio-button value="">Empty</el-radio-button>
        <el-radio-button value="left">Left</el-radio-button>
        <el-radio-button value="right">Right</el-radio-button>
        <el-radio-button value="top">Top</el-radio-button>
      </el-radio-group>
    </bk-form-item>
    <bk-form-item label="Name" :label-position="itemLabelPosition">
      <el-input v-model="formLabelAlign.name" />
    </bk-form-item>
    <bk-form-item label="Activity zone" :label-position="itemLabelPosition">
      <el-input v-model="formLabelAlign.region" />
    </bk-form-item>
    <bk-form-item label="Activity form" :label-position="itemLabelPosition">
      <el-input v-model="formLabelAlign.type" />
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"
import type { FormItemProps, FormProps } from "vue-business-kit"

const labelPosition = ref<FormProps["labelPosition"]>("right")
const itemLabelPosition = ref<FormItemProps["labelPosition"]>("")

const formLabelAlign = reactive({
  name: "",
  region: "",
  type: ""
})
</script>

隐藏源码

表单校验

表单组件支持数据校验功能，帮助快速发现并修正输入错误。

只需为 bk-form 组件添加 rules 属性并传入校验规则，并将表单项的 prop 属性设置为需要验证的特殊键值即可。校验规则参见 async-validator。

Activity name

Activity zone

Activity zone

Activity count

Activity count

Activity time

-

Instant delivery

Activity location

Home

Company

School

Activity type

Online activities Promotion activities Offline activities Simple brand exposure

Resources

SponsorshipVenue

Activity form

<template>
  <bk-form
    ref="ruleFormRef"
    style="max-width: 600px"
    :model="ruleForm"
    :rules="rules"
    label-width="auto"
  >
    <bk-form-item label="Activity name" prop="name">
      <el-input v-model="ruleForm.name" />
    </bk-form-item>
    <bk-form-item label="Activity zone" prop="region">
      <el-select v-model="ruleForm.region" placeholder="Activity zone">
        <el-option label="Zone one" value="shanghai" />
        <el-option label="Zone two" value="beijing" />
      </el-select>
    </bk-form-item>
    <bk-form-item label="Activity count" prop="count">
      <el-select-v2 v-model="ruleForm.count" placeholder="Activity count" :options="options" />
    </bk-form-item>
    <bk-form-item label="Activity time" required>
      <el-col :span="11">
        <bk-form-item prop="date1">
          <el-date-picker
            v-model="ruleForm.date1"
            type="date"
            aria-label="Pick a date"
            placeholder="Pick a date"
            style="width: 100%"
          />
        </bk-form-item>
      </el-col>
      <el-col class="text-center" :span="2">
        <span class="text-gray-500">-</span>
      </el-col>
      <el-col :span="11">
        <bk-form-item prop="date2">
          <el-time-picker
            v-model="ruleForm.date2"
            aria-label="Pick a time"
            placeholder="Pick a time"
            style="width: 100%"
          />
        </bk-form-item>
      </el-col>
    </bk-form-item>
    <bk-form-item label="Instant delivery" prop="delivery">
      <el-switch v-model="ruleForm.delivery" />
    </bk-form-item>
    <bk-form-item label="Activity location" prop="location">
      <el-segmented v-model="ruleForm.location" :options="locationOptions" />
    </bk-form-item>
    <bk-form-item label="Activity type" prop="type">
      <el-checkbox-group v-model="ruleForm.type">
        <el-checkbox value="Online activities" name="type"> Online activities </el-checkbox>
        <el-checkbox value="Promotion activities" name="type"> Promotion activities </el-checkbox>
        <el-checkbox value="Offline activities" name="type"> Offline activities </el-checkbox>
        <el-checkbox value="Simple brand exposure" name="type"> Simple brand exposure </el-checkbox>
      </el-checkbox-group>
    </bk-form-item>
    <bk-form-item label="Resources" prop="resource">
      <el-radio-group v-model="ruleForm.resource">
        <el-radio value="Sponsorship">Sponsorship</el-radio>
        <el-radio value="Venue">Venue</el-radio>
      </el-radio-group>
    </bk-form-item>
    <bk-form-item label="Activity form" prop="desc">
      <el-input v-model="ruleForm.desc" type="textarea" />
    </bk-form-item>
    <bk-form-item>
      <bk-button type="primary" @click="submitForm(ruleFormRef)"> Create </bk-button>
      <bk-button @click="resetForm(ruleFormRef)">Reset</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"
import type { FormInstance, FormRules } from "vue-business-kit"

interface RuleForm {
  name: string
  region: string
  count: string
  date1: string
  date2: string
  delivery: boolean
  location: string
  type: string[]
  resource: string
  desc: string
}

const ruleFormRef = ref<FormInstance>()
const ruleForm = reactive<RuleForm>({
  name: "Hello",
  region: "",
  count: "",
  date1: "",
  date2: "",
  delivery: false,
  location: "",
  type: [],
  resource: "",
  desc: ""
})

const locationOptions = ["Home", "Company", "School"]

const rules = reactive<FormRules<RuleForm>>({
  name: [
    { required: true, message: "Please input Activity name", trigger: "blur" },
    { min: 3, max: 5, message: "Length should be 3 to 5", trigger: "blur" }
  ],
  region: [
    {
      required: true,
      message: "Please select Activity zone",
      trigger: "change"
    }
  ],
  count: [
    {
      required: true,
      message: "Please select Activity count",
      trigger: "change"
    }
  ],
  date1: [
    {
      type: "date",
      required: true,
      message: "Please pick a date",
      trigger: "change"
    }
  ],
  date2: [
    {
      type: "date",
      required: true,
      message: "Please pick a time",
      trigger: "change"
    }
  ],
  location: [
    {
      required: true,
      message: "Please select a location",
      trigger: "change"
    }
  ],
  type: [
    {
      type: "array",
      required: true,
      message: "Please select at least one activity type",
      trigger: "change"
    }
  ],
  resource: [
    {
      required: true,
      message: "Please select activity resource",
      trigger: "change"
    }
  ],
  desc: [{ required: true, message: "Please input activity form", trigger: "blur" }]
})

const submitForm = async (formEl: FormInstance | undefined) => {
  if (!formEl) return
  await formEl.elFormRef?.validate((valid, fields) => {
    if (valid) {
      console.log("submit!")
    } else {
      console.log("error submit!", fields)
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.elFormRef?.resetFields()
}

const options = Array.from({ length: 10000 }).map((_, idx) => ({
  value: `${idx + 1}`,
  label: `${idx + 1}`
}))
</script>

隐藏源码

自定义校验规则

本示例展示如何自定义校验规则，实现双密码一致性验证。

此处使用 status-icon 属性，通过图标直观展示校验结果。

Password

Confirm

Age

<template>
  <bk-form
    ref="ruleFormRef"
    style="max-width: 600px"
    :model="ruleForm"
    :rules="rules"
    label-width="auto"
    status-icon
    class="demo-ruleForm"
  >
    <bk-form-item label="Password" prop="pass">
      <el-input v-model="ruleForm.pass" type="password" autocomplete="off" />
    </bk-form-item>
    <bk-form-item label="Confirm" prop="checkPass">
      <el-input v-model="ruleForm.checkPass" type="password" autocomplete="off" />
    </bk-form-item>
    <bk-form-item label="Age" prop="age">
      <el-input v-model.number="ruleForm.age" />
    </bk-form-item>
    <bk-form-item>
      <bk-button type="primary" @click="submitForm(ruleFormRef)"> Create </bk-button>
      <bk-button @click="resetForm(ruleFormRef)">Reset</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"

import type { FormInstance, FormRules } from "vue-business-kit"

const ruleFormRef = ref<FormInstance>()

const checkAge = (rule: any, value: any, callback: any) => {
  if (!value) {
    return callback(new Error("Please input the age"))
  }
  setTimeout(() => {
    if (!Number.isInteger(value)) {
      callback(new Error("Please input digits"))
    } else {
      if (value < 18) {
        callback(new Error("Age must be greater than 18"))
      } else {
        callback()
      }
    }
  }, 1000)
}

const validatePass = (rule: any, value: any, callback: any) => {
  if (value === "") {
    callback(new Error("Please input the password"))
  } else {
    if (ruleForm.checkPass !== "") {
      if (!ruleFormRef.value) return
      ruleFormRef.value.elFormRef?.validateField("checkPass")
    }
    callback()
  }
}
const validatePass2 = (rule: any, value: any, callback: any) => {
  if (value === "") {
    callback(new Error("Please input the password again"))
  } else if (value !== ruleForm.pass) {
    callback(new Error("Two inputs don't match!"))
  } else {
    callback()
  }
}

const ruleForm = reactive({
  pass: "",
  checkPass: "",
  age: ""
})

const rules = reactive<FormRules<typeof ruleForm>>({
  pass: [{ validator: validatePass, trigger: "blur" }],
  checkPass: [{ validator: validatePass2, trigger: "blur" }],
  age: [{ validator: checkAge, trigger: "blur" }]
})

const submitForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.elFormRef?.validate((valid) => {
    if (valid) {
      console.log("submit!")
    } else {
      console.log("error submit!")
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.elFormRef?.resetFields()
}
</script>

隐藏源码

提示

自定义校验的回调函数必须被调用，否则会导致校验流程卡死。高级用法参考 async-validator。

动态增减表单项

除了在表单组件上一次性传入所有校验规则外，也可针对单个表单项动态添加或删除校验规则。

Email

Domain0

<template>
  <bk-form
    ref="formRef"
    :model="dynamicValidateForm"
    label-width="auto"
    style="max-width: 600px"
    class="demo-dynamic"
  >
    <bk-form-item
      prop="email"
      label="Email"
      :rules="[
        {
          required: true,
          message: 'Please input email address',
          trigger: 'blur'
        },
        {
          type: 'email',
          message: 'Please input correct email address',
          trigger: ['blur', 'change']
        }
      ]"
    >
      <el-input v-model="dynamicValidateForm.email" />
    </bk-form-item>
    <bk-form-item
      v-for="(domain, index) in dynamicValidateForm.domains"
      :key="domain.key"
      :label="'Domain' + index"
      :prop="'domains.' + index + '.value'"
      :rules="{
        required: true,
        message: 'domain can not be null',
        trigger: 'blur'
      }"
    >
      <el-input v-model="domain.value" />
      <bk-button class="mt-2" @click.prevent="removeDomain(domain)"> Delete </bk-button>
    </bk-form-item>
    <bk-form-item>
      <bk-button type="primary" @click="submitForm(formRef)">Submit</bk-button>
      <bk-button @click="addDomain">New domain</bk-button>
      <bk-button @click="resetForm(formRef)">Reset</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"

import type { FormInstance } from "vue-business-kit"

const formRef = ref<FormInstance>()
const dynamicValidateForm = reactive<{
  domains: DomainItem[]
  email: string
}>({
  domains: [
    {
      key: 1,
      value: ""
    }
  ],
  email: ""
})

interface DomainItem {
  key: number
  value: string
}

const removeDomain = (item: DomainItem) => {
  const index = dynamicValidateForm.domains.indexOf(item)
  if (index !== -1) {
    dynamicValidateForm.domains.splice(index, 1)
  }
}

const addDomain = () => {
  dynamicValidateForm.domains.push({
    key: Date.now(),
    value: ""
  })
}

const submitForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.elFormRef?.validate((valid) => {
    if (valid) {
      console.log("submit!")
    } else {
      console.log("error submit!")
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.elFormRef?.resetFields()
}
</script>

隐藏源码

数字类型校验

数字类型校验需要在输入框的 v-model 绑定上添加 .number 修饰符，该修饰符由 Vue 提供，用于将输入的字符串值转换为数字类型。

age

<template>
  <bk-form
    ref="formRef"
    style="max-width: 600px"
    :model="numberValidateForm"
    label-width="auto"
    class="demo-ruleForm"
  >
    <bk-form-item
      label="age"
      prop="age"
      :rules="[
        { required: true, message: 'age is required' },
        { type: 'number', message: 'age must be a number' }
      ]"
    >
      <el-input v-model.number="numberValidateForm.age" type="text" autocomplete="off" />
    </bk-form-item>
    <bk-form-item>
      <bk-button type="primary" @click="submitForm(formRef)">Submit</bk-button>
      <bk-button @click="resetForm(formRef)">Reset</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"

import type { FormInstance } from "vue-business-kit"

const formRef = ref<FormInstance>()

const numberValidateForm = reactive({
  age: ""
})

const submitForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.elFormRef?.validate((valid) => {
    if (valid) {
      console.log("submit!")
    } else {
      console.log("error submit!")
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.elFormRef?.resetFields()
}
</script>

隐藏源码

TIP

当一个表单项嵌套在另一个表单项中时，其标签宽度会被设为 0。如有需要，可在该嵌套的表单项上手动设置 label-width。

尺寸控制

表单内的所有组件会默认继承表单的 size 属性，表单项也单独提供 size 属性用于控制尺寸。

若不想让某个组件继承表单/表单项的尺寸，可单独为该组件设置 size 属性覆盖继承值。

largedefaultsmall

LeftRightTop

Activity name

Activity zone

please select your zone

Activity time

-

Activity type

Online activities Promotion activities

Resources

SponsorVenue

<template>
  <div>
    <el-radio-group v-model="size" aria-label="size control">
      <el-radio-button value="large">large</el-radio-button>
      <el-radio-button value="default">default</el-radio-button>
      <el-radio-button value="small">small</el-radio-button>
    </el-radio-group>
    <el-radio-group v-model="labelPosition" aria-label="position control">
      <el-radio-button value="left">Left</el-radio-button>
      <el-radio-button value="right">Right</el-radio-button>
      <el-radio-button value="top">Top</el-radio-button>
    </el-radio-group>
  </div>
  <br />
  <bk-form
    style="max-width: 600px"
    :model="sizeForm"
    label-width="auto"
    :label-position="labelPosition"
    :size="size"
  >
    <bk-form-item label="Activity name">
      <el-input v-model="sizeForm.name" />
    </bk-form-item>
    <bk-form-item label="Activity zone">
      <el-select v-model="sizeForm.region" placeholder="please select your zone">
        <el-option label="Zone one" value="shanghai" />
        <el-option label="Zone two" value="beijing" />
      </el-select>
    </bk-form-item>
    <bk-form-item label="Activity time">
      <el-col :span="11">
        <el-date-picker
          v-model="sizeForm.date1"
          type="date"
          aria-label="Pick a date"
          placeholder="Pick a date"
          style="width: 100%"
        />
      </el-col>
      <el-col class="text-center" :span="1" style="margin: 0 0.5rem">-</el-col>
      <el-col :span="11">
        <el-time-picker
          v-model="sizeForm.date2"
          aria-label="Pick a time"
          placeholder="Pick a time"
          style="width: 100%"
        />
      </el-col>
    </bk-form-item>
    <bk-form-item label="Activity type">
      <el-checkbox-group v-model="sizeForm.type">
        <el-checkbox-button value="Online activities" name="type">
          Online activities
        </el-checkbox-button>
        <el-checkbox-button value="Promotion activities" name="type">
          Promotion activities
        </el-checkbox-button>
      </el-checkbox-group>
    </bk-form-item>
    <bk-form-item label="Resources">
      <el-radio-group v-model="sizeForm.resource">
        <el-radio border value="Sponsor">Sponsor</el-radio>
        <el-radio border value="Venue">Venue</el-radio>
      </el-radio-group>
    </bk-form-item>
    <bk-form-item>
      <bk-button type="primary" @click="onSubmit">Create</bk-button>
      <bk-button>Cancel</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"

import type { ComponentSize, FormProps } from "vue-business-kit"

const size = ref<ComponentSize>("default")
const labelPosition = ref<FormProps["labelPosition"]>("right")

const sizeForm = reactive({
  name: "",
  region: "",
  date1: "",
  date2: "",
  delivery: false,
  type: [],
  resource: "",
  desc: ""
})

function onSubmit() {
  console.log("submit!")
}
</script>

<style>
.el-radio-group {
  margin-right: 12px;
}
</style>

隐藏源码

无障碍访问

当表单项内仅包含单个输入控件（如输入框、选择器、复选框等）时，表单项的标签会自动关联到该输入控件。若包含多个输入控件，表单项会被赋予 WAI-ARIA 的 group 角色，此时需要开发者自行为每个输入控件添加辅助标签。

"Full Name" label is automatically attached to the input:

Full Name

"Your Information" serves as a label for the group of inputs.
You must specify labels on the individal inputs. Placeholders are not replacements for using the "label" attribute.

Your Information

<template>
  <bk-form label-position="left" label-width="auto" style="max-width: 600px">
    <el-space fill>
      <el-alert type="info" show-icon :closable="false">
        <p>"Full Name" label is automatically attached to the input:</p>
      </el-alert>
      <bk-form-item label="Full Name">
        <el-input v-model="formAccessibility.fullName" />
      </bk-form-item>
    </el-space>
    <el-space fill>
      <el-alert type="info" show-icon :closable="false">
        <p>
          "Your Information" serves as a label for the group of inputs. <br />
          You must specify labels on the individal inputs. Placeholders are not replacements for
          using the "label" attribute.
        </p>
      </el-alert>
      <bk-form-item label="Your Information">
        <el-row :gutter="20">
          <el-col :span="12">
            <el-input
              v-model="formAccessibility.firstName"
              aria-label="First Name"
              placeholder="First Name"
            />
          </el-col>
          <el-col :span="12">
            <el-input
              v-model="formAccessibility.lastName"
              aria-label="Last Name"
              placeholder="Last Name"
            />
          </el-col>
        </el-row>
      </bk-form-item>
    </el-space>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive } from "vue"

const formAccessibility = reactive({
  fullName: "",
  firstName: "",
  lastName: ""
})
</script>

隐藏源码

Form API

Form 属性

属性名	说明	类型	默认值
items	表单项配置数组，每个项可指定类型、组件属性（componentProps）、子项等	array	—
colNum	多列表单布局的列数	number	1

Element Plus Form 原生属性

属性名	说明	类型	默认值
model	表单数据对象	object	—
rules	表单校验规则	object	—
inline	是否行内表单（推荐使用 col-num 属性替代）	boolean	false
label-position	标签的位置，可选值为 left / right / top，设置为 left 或 right 时，需同时设置 label-width	enum	right
label-width	标签的宽度，例如 50px，支持 auto，所有直接子表单项会继承该值	string / number	''
label-suffix	标签的后缀文本	string	''
hide-required-asterisk	是否隐藏必填字段标签旁的红色星号	boolean	false
require-asterisk-position	星号的位置，可选值为 left / right	enum	left
show-message	是否显示校验错误信息	boolean	true
inline-message	是否将校验错误信息以行内形式展示	boolean	false
status-icon	是否显示校验状态图标	boolean	false
validate-on-rule-change	是否在 rules 属性变化时触发校验	boolean	true
size	控制表单内组件的尺寸，可选值为 large / default / small	enum	—
disabled	是否禁用表单内所有组件，设置为 true 时会覆盖内部组件的 disabled 属性	boolean	false
scroll-to-error	校验失败时，是否自动滚动到第一个错误表单项	boolean	false
scroll-into-view-options	校验失败滚动到错误项时，传递给 scrollIntoView 的配置项，参考 scrollIntoView	object / boolean	true

FormItem

继承所有 Element Plus FormItemProps 属性，并新增以下增强功能：

属性名	说明	类型	默认值
type required	表单项组件类型（例如：'input'、'select'、'radio'）	string	—
componentProps	传递给底层组件的额外属性	object	—
children	用于复杂布局的嵌套表单项配置	array	—

Form 事件

Element Plus Form 原生事件

事件名	说明	类型
validate	表单项校验触发的事件	Function

Form 插槽

Element Plus Form 原生插槽

插槽名	说明	子标签
default	自定义默认内容	FormItem

Form Exposes

Element Plus Form Exposes

名称	说明	类型
validate	校验整个表单，接收回调函数或返回 Promise	Function
validateField	校验指定的表单项	Function
resetFields	重置指定的表单项，清除校验结果	Function
scrollToField	滚动到指定的表单项	Function
clearValidate	清除所有或指定表单项的校验提示	Function
fields	获取所有表单项的上下文	array
getField	获取指定表单项的上下文	Function

FormItem API

FormItem 属性

Element Plus FormItem 原生属性

属性名	说明	类型	默认值
prop	表单模型字段，支持嵌套路径（如 a.b.0 或 ['a', 'b', '0']），在使用 validate / resetFields 方法时，该属性是必填的	string / string[]	—
label	标签文本	string	—
label-position	标签的位置，可选值为 left / right / top，设置为 left 或 right 时需指定 label-width，默认继承表单的 label-position	enum	''
label-width	标签的宽度，例如 50px，支持 auto	string / number	—
required	是否为必填字段，若不设置，则由校验规则自动判断	boolean	—
rules	表单项的校验规则，参考 FormItemRule，高级用法参考 async-validator	object	—
error	手动设置表单项的错误提示信息，设置后会立即触发校验错误状态并显示该信息	string	—
show-message	是否显示校验错误信息	boolean	true
inline-message	是否以行内形式展示校验错误信息	boolean	false
size	控制表单项内组件的尺寸，可选值为 large / default / small	enum	—
for	原生 label 标签的 for 属性，用于关联表单控件	string	—
validate-status	表单项的校验状态，可选值为 error / validating / success / ''	enum	—

FormItemRule

Element Plus FormItemRule 原生配置

名称	说明	类型	默认值
trigger	校验触发方式	enum	—

提示

若不想通过输入事件触发校验，可在对应的输入类组件（<el-input>、<el-radio>、<el-select> 等）上设置 validate-event 为 false。

FormItem 插槽

Element Plus FormItem 原生插槽

插槽名	说明	类型
default	表单项的内容	—
label	自定义标签内容	object
error	自定义校验错误提示	object

FormItem Exposes

Element Plus FormItem Exposes

名称	说明	类型
size	表单项的尺寸	object
validateMessage	校验提示信息	object
validateState	校验状态	object
validate	校验当前表单项	Function
resetField	重置当前表单项，清除校验	Function
clearValidate	清除当前表单项的校验状态	Function