@cimom/vben-core-form-ui v5.6.8

Form UI 组件

Form UI 组件是一个基于 Vue 3 的高度可定制化表单组件，提供了丰富的表单项和布局选项，支持表单验证、联动和动态渲染等功能。

安装

npm install @cimom/vben-core-ui-kit-form-ui

基本使用

<script setup lang="ts">
import { VbenForm } from '@cimom/vben-core-ui-kit-form-ui';
import { ref } from 'vue';
import { z } from 'zod';

const formData = ref({
  username: '',
  password: '',
});

const schema = [
  {
    fieldName: 'username',
    label: '用户名',
    component: 'VbenInput',
    componentProps: {
      placeholder: '请输入用户名',
    },
    rules: z.string().min(3, '用户名至少3个字符'),
    required: true,
  },
  {
    fieldName: 'password',
    label: '密码',
    component: 'VbenInputPassword',
    componentProps: {
      placeholder: '请输入密码',
    },
    rules: z.string().min(6, '密码至少6个字符'),
    required: true,
  },
];

const handleSubmit = (values) => {
  console.log('表单提交:', values);
};

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

<template>
  <VbenForm
    v-model="formData"
    :schema="schema"
    :handle-submit="handleSubmit"
    :handle-reset="handleReset"
  />
</template>

组件属性

VbenForm Props

FormSchema 配置项

FormCommonConfig 公共配置

表单项联动

可以通过 dependencies 属性设置表单项之间的联动关系：

<script setup>
const schema = [
  {
    fieldName: 'type',
    label: '类型',
    component: 'VbenSelect',
    componentProps: {
      options: [
        { label: '类型A', value: 'A' },
        { label: '类型B', value: 'B' },
      ],
    },
  },
  {
    fieldName: 'extraInfo',
    label: '额外信息',
    component: 'VbenInput',
    dependencies: {
      triggerFields: ['type'],
      show: (values) => values.type === 'B',
      required: (values) => values.type === 'B',
    },
  },
];
</script>

使用 API 方法

<script setup>
import { VbenForm, useVbenForm } from '@cimom/vben-core-ui-kit-form-ui';
import { ref } from 'vue';

const formRef = ref(null);
const { formApi } = useVbenForm(formRef);

// 使用表单API
const handleClick = () => {
  // 获取表单值
  const values = formApi.getValues();

  // 设置表单值
  formApi.setValues({ username: 'admin' });

  // 验证表单
  formApi.validate().then((result) => {
    if (result.valid) {
      console.log('表单验证通过');
    }
  });

  // 重置表单
  formApi.reset();
};
</script>

<template>
  <VbenForm ref="formRef" :schema="schema" />
  <button @click="handleClick">操作表单</button>
</template>

可用的表单API方法

示例

基础表单示例

<template>
  <div class="p-4">
    <h2 class="mb-4 text-lg font-bold">基础表单</h2>
    <VbenForm
      v-model="formData"
      :schema="schema"
      :handle-submit="handleSubmit"
      :handle-reset="handleReset"
    />
  </div>
</template>

<script setup lang="ts">
import { VbenForm } from '@cimom/vben-core-ui-kit-form-ui';
import { ref } from 'vue';
import { z } from 'zod';

const formData = ref({
  username: '',
  password: '',
  remember: false,
});

const schema = [
  {
    fieldName: 'username',
    label: '用户名',
    component: 'VbenInput',
    componentProps: {
      placeholder: '请输入用户名',
    },
    rules: z.string().min(3, '用户名至少3个字符'),
    required: true,
  },
  {
    fieldName: 'password',
    label: '密码',
    component: 'VbenInputPassword',
    componentProps: {
      placeholder: '请输入密码',
    },
    rules: z.string().min(6, '密码至少6个字符'),
    required: true,
  },
  {
    fieldName: 'remember',
    label: '记住我',
    component: 'VbenCheckbox',
    defaultValue: false,
  },
];

const handleSubmit = (values) => {
  console.log('表单提交:', values);
};

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

表单布局示例

<template>
  <div class="p-4">
    <h2 class="mb-4 text-lg font-bold">表单布局</h2>
    <div class="mb-4">
      <span class="mr-4">布局方式:</span>
      <label class="mr-2">
        <input type="radio" v-model="layout" value="horizontal" /> 水平
      </label>
      <label>
        <input type="radio" v-model="layout" value="vertical" /> 垂直
      </label>
    </div>
    <VbenForm
      v-model="formData"
      :schema="schema"
      :layout="layout"
      :wrapperClass="wrapperClass"
    />
  </div>
</template>

<script setup lang="ts">
import { VbenForm } from '@cimom/vben-core-ui-kit-form-ui';
import { ref } from 'vue';

const layout = ref('horizontal');
const wrapperClass = ref('grid-cols-1 md:grid-cols-2');

const formData = ref({
  name: '',
  age: '',
  address: '',
  email: '',
});

const schema = [
  {
    fieldName: 'name',
    label: '姓名',
    component: 'VbenInput',
  },
  {
    fieldName: 'age',
    label: '年龄',
    component: 'VbenInput',
  },
  {
    fieldName: 'address',
    label: '地址',
    component: 'VbenInput',
    formItemClass: 'md:col-span-2',
  },
  {
    fieldName: 'email',
    label: '邮箱',
    component: 'VbenInput',
    formItemClass: 'md:col-span-2',
  },
];
</script>