From 487dd67d7658bc9211eba1bee2c7c111b78b51d2 Mon Sep 17 00:00:00 2001
From: dap <15891557205@163.com>
Date: Fri, 30 Jan 2026 16:02:52 +0800
Subject: [PATCH] =?UTF-8?q?feat(web-antd):=20=E6=96=B0=E5=A2=9E=E8=A1=A8?=
 =?UTF-8?q?=E5=8D=95=E7=BB=84=E4=BB=B6=E6=BC=94=E7=A4=BA=E9=A1=B5=E9=9D=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

添加表单组件基础示例页面，展示 useVbenForm 钩子的各种用法
包含 Input、Select、ApiSelect、DatePicker 等常见表单组件的配置示例
演示远程搜索、API 数据获取、表单值设置等高级功能
---
 .../src/views/演示使用自行删除/form/index.vue | 399 ++++++++++++++++++
 1 file changed, 399 insertions(+)
 create mode 100644 apps/web-antd/src/views/演示使用自行删除/form/index.vue

diff --git a/apps/web-antd/src/views/演示使用自行删除/form/index.vue b/apps/web-antd/src/views/演示使用自行删除/form/index.vue
new file mode 100644
index 00000000..edf49c1c
--- /dev/null
+++ b/apps/web-antd/src/views/演示使用自行删除/form/index.vue
@@ -0,0 +1,399 @@
+<script lang="ts" setup>
+import { h, ref } from 'vue';
+
+import { Page } from '@vben/common-ui';
+
+import { useDebounceFn } from '@vueuse/core';
+import { Button, Card, message, Spin, Tag } from 'antdv-next';
+import dayjs from 'dayjs';
+
+import { useVbenForm, z } from '#/adapter/form';
+import { getAllMenusApi } from '#/api';
+
+const keyword = ref('');
+const fetching = ref(false);
+// 模拟远程获取数据
+function fetchRemoteOptions({ keyword = '选项' }: Record<string, any>) {
+  fetching.value = true;
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      const options = Array.from({ length: 10 }).map((_, index) => ({
+        label: `${keyword}-${index}`,
+        value: `${keyword}-${index}`,
+      }));
+      resolve(options);
+      fetching.value = false;
+    }, 1000);
+  });
+}
+
+const [BaseForm, baseFormApi] = useVbenForm({
+  // 所有表单项共用，可单独在表单内覆盖
+  commonConfig: {
+    // 在label后显示一个冒号
+    colon: true,
+    // 所有表单项
+    componentProps: {
+      class: 'w-full',
+    },
+  },
+  fieldMappingTime: [['rangePicker', ['startTime', 'endTime'], 'YYYY-MM-DD']],
+  // 提交函数
+  handleSubmit: onSubmit,
+  handleValuesChange(_values, fieldsChanged) {
+    message.info(`表单以下字段发生变化：${fieldsChanged.join('，')}`);
+  },
+
+  // 垂直布局，label和input在不同行，值为vertical
+  // 水平布局，label和input在同一行
+  layout: 'horizontal',
+  schema: [
+    {
+      // 组件需要在 #/adapter.ts内注册，并加上类型
+      component: 'Input',
+      // 对应组件的参数
+      componentProps: {
+        placeholder: '请输入用户名',
+      },
+      // 字段名
+      fieldName: 'username',
+      // 界面显示的label
+      label: '字符串',
+      rules: 'required',
+    },
+    {
+      // 组件需要在 #/adapter.ts内注册，并加上类型
+      component: 'ApiSelect',
+      // 对应组件的参数
+      componentProps: {
+        // 菜单接口转options格式
+        afterFetch: (data: { name: string; path: string }[]) => {
+          return data.map((item: any) => ({
+            label: item.name,
+            value: item.path,
+          }));
+        },
+        // 菜单接口
+        api: getAllMenusApi,
+        autoSelect: 'first',
+        allowClear: true,
+      },
+      // 字段名
+      fieldName: 'api',
+      // 界面显示的label
+      label: 'ApiSelect',
+      rules: 'selectRequired',
+    },
+    {
+      component: 'ApiSelect',
+      // 对应组件的参数
+      componentProps: () => {
+        return {
+          api: fetchRemoteOptions,
+          // 禁止本地过滤
+          filterOption: false,
+          // 如果正在获取数据，使用插槽显示一个loading
+          notFoundContent: fetching.value ? undefined : null,
+          // 搜索词变化时记录下来， 使用useDebounceFn防抖。
+          onSearch: useDebounceFn((value: string) => {
+            keyword.value = value;
+          }, 300),
+          // 远程搜索参数。当搜索词变化时，params也会更新
+          params: {
+            keyword: keyword.value || undefined,
+          },
+          showSearch: true,
+        };
+      },
+      // 字段名
+      fieldName: 'remoteSearch',
+      // 界面显示的label
+      label: '远程搜索',
+      renderComponentContent: () => {
+        return {
+          notFoundContent: fetching.value ? h(Spin) : undefined,
+        };
+      },
+      rules: 'selectRequired',
+    },
+    {
+      component: 'ApiTreeSelect',
+      // 对应组件的参数
+      componentProps: {
+        // 菜单接口
+        api: getAllMenusApi,
+        // 菜单接口转options格式
+        labelField: 'name',
+        valueField: 'path',
+        childrenField: 'children',
+      },
+      // 字段名
+      fieldName: 'apiTree',
+      // 界面显示的label
+      label: 'ApiTreeSelect',
+    },
+    {
+      component: 'InputPassword',
+      componentProps: {
+        placeholder: '请输入密码',
+      },
+      fieldName: 'password',
+      label: '密码',
+    },
+    {
+      component: 'InputNumber',
+      componentProps: {
+        placeholder: '请输入',
+      },
+      fieldName: 'number',
+      label: '数字(带后缀)',
+      suffix: () => '¥',
+    },
+    {
+      component: 'IconPicker',
+      fieldName: 'icon',
+      label: '图标',
+    },
+    {
+      colon: false,
+      component: 'Select',
+      componentProps: {
+        allowClear: true,
+        filterOption: true,
+        options: [
+          {
+            label: '选项1',
+            value: '1',
+          },
+          {
+            label: '选项2',
+            value: '2',
+          },
+        ],
+        placeholder: '请选择',
+        showSearch: true,
+      },
+      fieldName: 'options',
+      label: () => h(Tag, { color: 'warning' }, () => '😎自定义：'),
+    },
+    {
+      component: 'RadioGroup',
+      componentProps: {
+        options: [
+          {
+            label: '选项1',
+            value: '1',
+          },
+          {
+            label: '选项2',
+            value: '2',
+          },
+        ],
+      },
+      fieldName: 'radioGroup',
+      label: '单选组',
+    },
+    {
+      component: 'Radio',
+      fieldName: 'radio',
+      label: '',
+      renderComponentContent: () => {
+        return {
+          default: () => ['Radio'],
+        };
+      },
+    },
+    {
+      component: 'CheckboxGroup',
+      componentProps: {
+        name: 'cname',
+        options: [
+          {
+            label: '选项1',
+            value: '1',
+          },
+          {
+            label: '选项2',
+            value: '2',
+          },
+        ],
+      },
+      fieldName: 'checkboxGroup',
+      label: '多选组',
+    },
+    {
+      component: 'Checkbox',
+      fieldName: 'checkbox',
+      label: '',
+      renderComponentContent: () => {
+        return {
+          default: () => ['我已阅读并同意'],
+        };
+      },
+      rules: z
+        .boolean()
+        .refine((v) => v, { message: '为什么不同意？勾上它！' }),
+    },
+    {
+      component: 'Mentions',
+      componentProps: {
+        options: [
+          {
+            label: 'afc163',
+            value: 'afc163',
+          },
+          {
+            label: 'zombieJ',
+            value: 'zombieJ',
+          },
+        ],
+        placeholder: '请输入',
+      },
+      fieldName: 'mentions',
+      label: '提及',
+    },
+    {
+      component: 'Rate',
+      fieldName: 'rate',
+      label: '评分',
+    },
+    {
+      component: 'Switch',
+      componentProps: {
+        class: 'w-auto',
+      },
+      fieldName: 'switch',
+      help: () =>
+        ['这是一个多行帮助信息', '第二行', '第三行'].map((v) => h('p', v)),
+      label: '开关',
+    },
+    {
+      component: 'DatePicker',
+      fieldName: 'datePicker',
+      label: '日期选择框',
+      rules: 'selectRequired',
+    },
+    {
+      component: 'RangePicker',
+      fieldName: 'rangePicker',
+      label: '范围选择器',
+      rules: 'selectRequired',
+    },
+    {
+      component: 'TimePicker',
+      fieldName: 'timePicker',
+      label: '时间选择框',
+      rules: 'selectRequired',
+    },
+    {
+      rules: 'selectRequired',
+      component: 'TreeSelect',
+      componentProps: {
+        allowClear: true,
+        placeholder: '请选择',
+        showSearch: true,
+        treeData: [
+          {
+            label: 'root 1',
+            value: 'root 1',
+            children: [
+              {
+                label: 'parent 1',
+                value: 'parent 1',
+                children: [
+                  {
+                    label: 'parent 1-0',
+                    value: 'parent 1-0',
+                    children: [
+                      {
+                        label: 'my leaf',
+                        value: 'leaf1',
+                      },
+                      {
+                        label: 'your leaf',
+                        value: 'leaf2',
+                      },
+                    ],
+                  },
+                  {
+                    label: 'parent 1-1',
+                    value: 'parent 1-1',
+                  },
+                ],
+              },
+              {
+                label: 'parent 2',
+                value: 'parent 2',
+              },
+            ],
+          },
+        ],
+        treeNodeFilterProp: 'label',
+      },
+      fieldName: 'treeSelect',
+      label: '树选择',
+    },
+  ],
+  // 大屏一行显示3个，中屏一行显示2个，小屏一行显示1个
+  wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
+});
+
+function onSubmit() {}
+
+function handleSetFormValue() {
+  /**
+   * 设置表单值(多个)
+   */
+  baseFormApi.setValues({
+    checkboxGroup: ['1'],
+    datePicker: dayjs('2022-01-01'),
+    files: [
+      {
+        name: 'example.png',
+        status: 'done',
+        uid: '-1',
+        url: 'https://unpkg.com/@vbenjs/static-source@0.1.7/source/logo-v1.webp',
+      },
+    ],
+    mentions: '@afc163',
+    number: 3,
+    options: '1',
+    password: '2',
+    radioGroup: '1',
+    rangePicker: [dayjs('2022-01-01'), dayjs('2022-01-02')],
+    rate: 3,
+    switch: true,
+    timePicker: dayjs('2022-01-01 12:00:00'),
+    treeSelect: 'leaf1',
+    username: '1',
+  });
+
+  // 设置单个表单值
+  baseFormApi.setFieldValue('checkbox', true);
+}
+</script>
+
+<template>
+  <Page
+    content-class="flex flex-col gap-4"
+    description="表单组件基础示例，请注意，该页面用到的参数代码会添加一些简单注释，方便理解，请仔细查看。"
+    title="表单组件"
+  >
+    <template #description>
+      <div class="text-muted-foreground">
+        <p>
+          表单组件基础示例，请注意，该页面用到的参数代码会添加一些简单注释，方便理解，请仔细查看。
+        </p>
+      </div>
+    </template>
+    <template #extra>
+      <DocButton class="mb-2" path="/components/common-ui/vben-form" />
+    </template>
+    <Card title="基础示例">
+      <template #extra>
+        <Button type="primary" @click="handleSetFormValue">设置表单值</Button>
+      </template>
+      <BaseForm />
+    </Card>
+  </Page>
+</template>