Form 表单

强大的表单构建和验证组件，支持配置化表单生成、内置验证规则和灵活的布局方式。

🎮 在线演示

想要查看表单组件的交互效果？请访问 在线演示

组件特性

🎯 配置化

通过配置快速生成表单，减少重复代码

📋 丰富组件

支持多种表单控件和自定义组件

✅ 内置验证

预设常用验证规则，开箱即用

🎨 灵活布局

支持多种布局方式和响应式设计

搜索表单

最常用的搜索表单配置，支持多种搜索条件。支持特殊表单项功能，将标记为 special: true 的表单项以 inline 模式排列在最后，不受普通布局的 span 影响。

查看代码

<template>
  <div>
    <ImForm
      v-model="searchData"
      :form-config="searchFormConfig"
      show-search-buttons
      @search="handleSearch"
      @reset="handleReset"
    />
    
    <div v-if="searchData.keyword" class="mt-4 p-3 bg-gray-50 rounded">
      搜索条件：{{ JSON.stringify(searchData, null, 2) }}
    </div>
  </div>
</template>

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

const searchData = reactive({
  keyword: "",
  status: "",
  category: "",
  createDate: "",
  year: "",
  dateRange: [],
  isVip: false,
  gender: "all"
})

const searchFormConfig = {
  formItems: [
    {
      prop: "keyword",
      label: "关键词",
      type: "input",
      props: {
        placeholder: "请输入关键词搜索",
        clearable: true,
      },
    },
    {
      prop: "status",
      label: "状态",
      type: "select",
      options: [
        { label: "全部", value: "" },
        { label: "启用", value: 1 },
        { label: "禁用", value: 0 },
      ],
      props: {
        clearable: true,
      },
    },
    {
      prop: "category",
      label: "分类",
      type: "select-search",
      options: [
        { label: "前端开发", value: "frontend" },
        { label: "后端开发", value: "backend" },
        { label: "移动开发", value: "mobile" },
        { label: "数据分析", value: "data" },
        { label: "人工智能", value: "ai" },
      ],
      props: {
        clearable: true,
      },
    },
    {
      prop: "createDate",
      label: "创建日期",
      type: "date-picker",
    },
    {
      prop: "year",
      label: "年份",
      type: "date-picker",
      props: {
        type: "year",
        placeholder: "请选择年份",
      },
    },
    {
      prop: "dateRange",
      label: "日期范围",
      type: "date-range",
    },
    {
      prop: "isVip",
      label: "VIP用户",
      type: "checkbox-single",
      checkboxLabel: "仅显示VIP用户",
      special: true, // 特殊表单项，以 inline 模式排列
    },
    {
      prop: "gender",
      label: "性别",
      type: "radio",
      options: [
        { label: "男", value: "male" },
        { label: "女", value: "female" },
        { label: "不限", value: "all" },
      ],
      special: true, // 特殊表单项，以 inline 模式排列
    },
  ],
}

const handleSearch = () => {
  console.log('搜索条件:', searchData)
}

const handleReset = () => {
  console.log('重置表单')
}
</script>

Flex布局表单

支持多列布局的表单，适用于详情页面或编辑表单。

查看代码

<template>
  <div>
    <ImForm
      v-model="formData"
      :form-config="flexFormConfig"
      layout="flex"
      :columns="3"
      show-buttons
      @submit="handleSubmit"
      @cancel="handleCancel"
    />
  </div>
</template>

<script setup>
import { reactive } from 'vue'
import { rules } from 'imtes-ui/utils'

const formData = reactive({
  name: "",
  age: null,
  gender: "",
  phone: "",
  email: "",
  department: "",
  position: "",
  entryDate: "",
  salary: null,
  skills: [],
  dateRange: [null, null],
  description: "",
})

const flexFormConfig = {
  formItems: [
    {
      prop: "name",
      label: "姓名",
      type: "input",
      rules: [{ required: true, message: "请输入姓名", trigger: "blur" }],
      span: 1,
    },
    {
      prop: "age",
      label: "年龄",
      type: "number",
      props: {
        min: 0,
        max: 150,
      },
      span: 1,
    },
    {
      prop: "gender",
      label: "性别",
      type: "select",
      options: [
        { label: "男", value: "male" },
        { label: "女", value: "female" },
      ],
      span: 1,
    },
    {
      prop: "phone",
      label: "手机号",
      type: "input",
      rules: rules.phone,
      span: 1,
    },
    {
      prop: "email",
      label: "邮箱",
      type: "input",
      rules: rules.email,
      span: 1,
    },
    {
      prop: "department",
      label: "部门",
      type: "select-search",
      options: [
        { label: "技术部", value: "tech" },
        { label: "产品部", value: "product" },
        { label: "设计部", value: "design" },
        { label: "运营部", value: "operation" },
        { label: "市场部", value: "market" },
      ],
      span: 1,
    },
    {
      prop: "position",
      label: "职位",
      type: "input",
      span: 1,
    },
    {
      prop: "entryDate",
      label: "入职日期",
      type: "date-picker",
      span: 1,
    },
    {
      prop: "salary",
      label: "薪资",
      type: "number",
      props: {
        min: 0,
        precision: 2,
        step: 1000,
        placeholder: "请输入薪资",
      },
      span: 1,
    },
    {
      prop: "skills",
      label: "技能",
      type: "checkbox",
      options: [
        { label: "Vue.js", value: "vue" },
        { label: "React", value: "react" },
        { label: "Angular", value: "angular" },
        { label: "Node.js", value: "nodejs" },
        { label: "Python", value: "python" },
        { label: "Java", value: "java" },
      ],
      span: 2,
    },
    {
      prop: "dateRange",
      label: "工作时间",
      type: "date-range-custom",
      span: 2,
    },
    {
      prop: "description",
      label: "个人描述",
      type: "textarea",
      props: {
        rows: 3,
        placeholder: "请输入个人描述",
      },
      span: 3,
    },
  ],
}

const handleSubmit = () => {
  console.log('提交数据:', formData)
}

const handleCancel = () => {
  console.log('取消操作')
}
</script>

验证表单

展示各种内置验证规则的使用。

查看代码

<template>
  <div>
    <ImForm
      v-model="validationData"
      :form-config="validationFormConfig"
      show-buttons
      @submit="handleValidationSubmit"
    />
  </div>
</template>

<script setup>
import { reactive } from 'vue'
import { rules } from 'imtes-ui/utils'

const validationData = reactive({
  email: "",
  phone: "",
  idCard: "",
  password: "",
  website: "",
})

const validationFormConfig = {
  formItems: [
    {
      prop: "email",
      label: "邮箱",
      type: "input",
      rules: rules.email,
      props: {
        placeholder: "请输入邮箱地址",
        clearable: true,
      },
    },
    {
      prop: "phone",
      label: "手机号",
      type: "input",
      rules: rules.phone,
      props: {
        placeholder: "请输入手机号",
        clearable: true,
      },
    },
    {
      prop: "idCard",
      label: "身份证号",
      type: "input",
      rules: rules.idCard,
      props: {
        placeholder: "请输入身份证号",
        clearable: true,
      },
    },
    {
      prop: "password",
      label: "密码",
      type: "password",
      rules: rules.password,
      props: {
        placeholder: "请输入密码（至少8位，包含大小写字母和数字）",
        clearable: true,
      },
    },
    {
      prop: "website",
      label: "网站地址",
      type: "input",
      rules: rules.url,
      props: {
        placeholder: "请输入网站地址",
        clearable: true,
      },
    },
  ],
}

const handleValidationSubmit = () => {
  console.log('验证通过，提交数据:', validationData)
}
</script>

表单控件类型

输入类控件

• input - 文本输入框
• password - 密码输入框
• textarea - 多行文本
• number - 数字输入框

选择类控件

• select - 下拉选择
• select-search - 可搜索下拉选择
• radio - 单选按钮组
• checkbox - 多选框组
• checkbox-single - 单个复选框

日期时间类控件

• date-picker - 日期选择器
• date-range - 日期范围选择
• date-range-custom - 自定义日期范围

内置验证规则

使用 rules 工具快速应用常用验证：

import { rules } from 'imtes-ui/utils'

// 邮箱验证
rules.email

// 手机号验证
rules.phone

// 身份证验证
rules.idCard

// 密码验证（至少8位，包含大小写字母和数字）
rules.password

// URL验证
rules.url

API

Form Props

属性	说明	类型	可选值	默认值
model-value / v-model	表单数据对象	object	—	{}
form-config	表单配置	object	—	{}
layout	布局方式	string	default/flex	default
columns	列数（flex布局时有效）	number	—	1
show-search-buttons	是否显示搜索按钮	boolean	—	false
show-buttons	是否显示操作按钮	boolean	—	false

Form Events

事件名	说明	回调参数
search	点击搜索按钮时触发	(formData)
reset	点击重置按钮时触发	—
submit	点击提交按钮时触发	(formData)
cancel	点击取消按钮时触发	—

FormItem 配置

属性	说明	类型	默认值
prop	字段名	string	—
label	标签文本	string	—
type	控件类型	string	input
options	选项数据（select、radio、checkbox）	array	[]
rules	验证规则	array	[]
props	控件属性	object	{}
span	跨列数（flex布局）	number	1
checkboxLabel	单个复选框的标签	string	—
special	是否为特殊表单项（查询表单中inline排列）	boolean	false