表单 Form

用于数据收集、校验和提交，支持表单校验、重置、行内布局、自动校验等功能。

基础用法

表单的基本用法，包含常见表单组件。

vue

<template>
  <bp-form ref="formRef" :model="form" label-position="right" :rules label-width="100px">
    <bp-form-item label="ID" field="id" required>
      <bp-input id="id" v-model="form.id" placeholder="请输入" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="Name" field="name">
      <bp-input v-model="form.name" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="Description" field="description">
      <bp-textarea v-model="form.description" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="Number" field="number">
      <bp-input-number v-model="form.number" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="Sex" field="sex">
      <bp-radio-group v-model="form.sex" style="width: 320px">
        <bp-radio value="male">Male</bp-radio>
        <bp-radio value="female">Female</bp-radio>
      </bp-radio-group>
    </bp-form-item>
    <bp-form-item label="Hobbits" field="hobbits">
      <bp-checkbox-group v-model="form.hobbits" style="width: 320px">
        <bp-checkbox value="test1">test1</bp-checkbox>
        <bp-checkbox value="test2">test2</bp-checkbox>
        <bp-checkbox value="test3">test3</bp-checkbox>
      </bp-checkbox-group>
    </bp-form-item>
    <bp-form-item label="Is Student" field="isStudent">
      <bp-switch v-model="form.isStudent" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="Time" field="createTime">
      <bp-date-picker v-model="form.createTime" style="width: 320px" />
    </bp-form-item>
    <bp-form-item>
      <bp-button type="plain" status="primary" @click="validate">Submit</bp-button>
    </bp-form-item>
  </bp-form>
</template>

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

const form = ref<any>({
  id: "",
  name: "test",
  description: "test description",
  number: 100,
  sex: "male",
  hobbits: ["test1", "test3"],
  isStudent: true,
  createTime: "2024-01-01 12:00:00",
});

const rules = ref<any>({
  id: [{ required: true, message: "请输入ID" }],
});

const formRef = ref<any>(null);
const validate = async () => {
  await formRef.value.validate();
};
</script>

表单校验

通过 rules 属性设置校验规则，调用 validate() 方法触发校验，resetFields() 重置字段值。

vue

<template>
  <bp-form ref="formRef" :model="form" :rules="rules" label-width="100px">
    <bp-form-item label="用户名" field="username" required>
      <bp-input v-model="form.username" placeholder="请输入用户名" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="邮箱" field="email" required>
      <bp-input v-model="form.email" placeholder="请输入邮箱" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="密码" field="password" required>
      <bp-input v-model="form.password" type="password" placeholder="请输入密码" style="width: 320px" />
    </bp-form-item>
    <bp-form-item>
      <div>
        <bp-button status="primary" @click="handleSubmit">提交</bp-button>
        <bp-button type="plain" @click="handleReset" style="margin-left: 8px">重置</bp-button>
      </div>
    </bp-form-item>
  </bp-form>
</template>

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

const form = ref({
  username: "",
  email: "",
  password: "",
});

const rules = ref({
  username: [
    { required: true, message: "请输入用户名" },
    { min: 3, max: 16, message: "用户名长度为 3-16 个字符" },
  ],
  email: [
    { required: true, message: "请输入邮箱" },
    { type: "email", message: "请输入正确的邮箱格式" },
  ],
  password: [
    { required: true, message: "请输入密码" },
    { min: 6, message: "密码至少 6 个字符" },
  ],
});

const formRef = ref<any>(null);

const handleSubmit = async () => {
  const valid = await formRef.value.validate();
  if (valid) {
    alert("提交成功！");
  }
};

const handleReset = () => {
  formRef.value.resetFields();
  formRef.value.clearValidate();
};
</script>

标签位置

通过 label-position 属性设置标签位置，支持 left、right、top 三种。

leftrighttop

vue

<template>
  <div>
    <bp-radio-group v-model="position" type="button" style="margin-bottom: 20px">
      <bp-radio value="left">left</bp-radio>
      <bp-radio value="right">right</bp-radio>
      <bp-radio value="top">top</bp-radio>
    </bp-radio-group>

    <bp-form :model="form" :label-position="position" label-width="80px">
      <bp-form-item label="姓名">
        <bp-input v-model="form.name" style="width: 320px" />
      </bp-form-item>
      <bp-form-item label="邮箱">
        <bp-input v-model="form.email" style="width: 320px" />
      </bp-form-item>
    </bp-form>
  </div>
</template>

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

const position = ref<"left" | "right" | "top">("right");

const form = ref({
  name: "",
  email: "",
});
</script>

行内布局

通过 layout="inline" 设置行内表单，常用于搜索条件。

vue

<template>
  <bp-form :model="form" layout="inline" label-width="60px">
    <bp-form-item label="姓名">
      <bp-input v-model="form.name" placeholder="请输入" />
    </bp-form-item>
    <bp-form-item label="城市">
      <bp-input v-model="form.city" placeholder="请输入" />
    </bp-form-item>
    <bp-form-item>
      <bp-button status="primary" size="small">查询</bp-button>
    </bp-form-item>
  </bp-form>
</template>

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

const form = ref({
  name: "",
  city: "",
});
</script>

重置与清除

通过 resetFields() 重置为初始值，clearValidate() 清除校验结果。

vue

<template>
  <bp-form ref="formRef" :model="form" :rules="rules" label-width="100px">
    <bp-form-item label="用户名" field="username" required>
      <bp-input v-model="form.username" placeholder="请输入用户名" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="简介" field="bio">
      <bp-textarea v-model="form.bio" placeholder="请输入简介" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="年龄" field="age">
      <bp-input-number v-model="form.age" :min="0" :max="150" style="width: 320px" />
    </bp-form-item>
    <bp-form-item>
      <div>
        <bp-button status="primary" @click="handleValidate">校验</bp-button>
        <bp-button type="plain" @click="handleReset" style="margin-left: 8px">重置</bp-button>
        <bp-button type="plain" status="warning" @click="handleClear" style="margin-left: 8px">清除校验</bp-button>
      </div>
    </bp-form-item>
  </bp-form>
</template>

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

const form = ref({
  username: "张三",
  bio: "这是一段简介",
  age: 25,
});

const rules = ref({
  username: [{ required: true, message: "请输入用户名" }],
});

const formRef = ref<any>(null);

const handleValidate = async () => {
  await formRef.value.validate();
};

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

const handleClear = () => {
  formRef.value.clearValidate();
};
</script>

自动校验与附加功能

通过 FormItem 的 auto-validate 属性在失焦时自动校验，show-colon 显示冒号，width 自定义标签宽度。

vue

<template>
  <bp-form :model="form" :rules="rules" label-width="100px">
    <bp-form-item label="用户名" field="username" required auto-validate>
      <bp-input v-model="form.username" placeholder="输入后失焦触发校验" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="邮箱" field="email" required auto-validate>
      <bp-input v-model="form.email" placeholder="输入后失焦触发校验" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="显示冒号" field="colon" required show-colon>
      <bp-input v-model="form.colon" style="width: 320px" />
    </bp-form-item>
    <bp-form-item label="自定义宽度" field="custom" :width="'120px'">
      <bp-input v-model="form.custom" style="width: 320px" />
    </bp-form-item>
  </bp-form>
</template>

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

const form = ref({
  username: "",
  email: "",
  colon: "",
  custom: "",
});

const rules = ref({
  username: [
    { required: true, message: "请输入用户名" },
    { min: 3, message: "至少 3 个字符" },
  ],
  email: [
    { required: true, message: "请输入邮箱" },
    { type: "email", message: "邮箱格式不正确" },
  ],
});
</script>

Form 属性

model	表单数据对象	Object	-	-
rules	校验规则	Rules	-	-
label-width	标签宽度	StringNumber	80px	-
label-position	标签位置	String	right	-
layout	表单布局	String	vertical	-

FormItem 属性

label	标签文本	String	-	-
field	字段名	String	-	-
required	是否必填	Boolean	-	-
width	标签宽度	StringNumber	-	-
show-colon	是否显示冒号	Boolean	-	-
rules	表单项校验规则	Rules	-	-
auto-validate	失焦自动校验	Boolean	-	-

Form 事件

submit

提交触发

{ isValid: Boolean, model: Object }

Form 方法

validate	表单校验	-	Promise<Boolean>	-
clearValidate	清除校验结果	fields?: string[]	-	-
resetFields	重置字段值	-	-	-

Form 插槽

default

表单内容

FormItem 插槽

default

表单项内容

表单 Form ​

基础用法 ​

表单校验 ​

标签位置 ​

行内布局 ​

重置与清除 ​

自动校验与附加功能 ​

Form 属性 ​

FormItem 属性 ​

Form 事件 ​

Form 方法 ​

Form 插槽 ​

FormItem 插槽 ​