JeeSite 快速开发平台
官方网站
    • 平台简介
    • 架构特点
    • 技术选型
    • 功能介绍
    • 安装部署
    • 常见问题
    • 目录结构
    • 更新日志
    • Vue 文档
    • BPM 文档
    • Cloud 文档
V4 演示
Vue 演示
💖联系
  • 我要提意见、文档纠错
  • JeeSite 代码库, 请⭐Star关注
  • JeeSite Vue 代码库, 请⭐关注
  • Spring Cloud 微服务架构
  • JeeSite 手机端/移动端
  • Flowable 中国式工作流
  • OAauth2 统一认证服务器
  • 政务内外网环境中间件
  • 访问 ThinkGem 官方博客
  • 点击进入,下拉查看动态
官方网站
    • 平台简介
    • 架构特点
    • 技术选型
    • 功能介绍
    • 安装部署
    • 常见问题
    • 目录结构
    • 更新日志
    • Vue 文档
    • BPM 文档
    • Cloud 文档
V4 演示
Vue 演示
💖联系
  • 我要提意见、文档纠错
  • JeeSite 代码库, 请⭐Star关注
  • JeeSite Vue 代码库, 请⭐关注
  • Spring Cloud 微服务架构
  • JeeSite 手机端/移动端
  • Flowable 中国式工作流
  • OAauth2 统一认证服务器
  • 政务内外网环境中间件
  • 访问 ThinkGem 官方博客
  • 点击进入,下拉查看动态
  • 快速了解

  • 开发手册

  • Vue 开发手册

    • Vue 分离版本介绍
    • 快速开始、安装部署
    • 配置参数、主题配置
    • 前端权限、按钮权限
    • BasicForm 表单组件
      • 介绍
      • 使用
        • 最简单示例
        • useForm 示例
      • 属性
        • ColEx 布局类型
        • fieldMapToTime 日期转换
        • FormSchema 控件设置
        • ComponentType 组件类型
      • 自定义组件
        • slot 插槽方式
        • render 函数式
        • 新建组件方式
      • 显示禁用
      • 表单验证
      • 表单插槽
      • 内置组件
        • Select 下拉选择
        • TreeSelect 下拉选择树
        • ListSelect 列表选择树
        • RadioGroup 单选按钮组
        • RadioButtonGroup 单选按钮组
        • CheckboxGroup 复选框组
        • Upload 上传控件
        • RangePicker 日期范围
        • Divider 分隔符
        • FormGroup 子表单
    • BasicTable 表格组件
    • 源码解析、表单列表
    • 常用组件库、Hooks
    • 图标 Icon Svg 组件
    • 国际化、多语言
    • Less CSS 样式库
    • 引入外部依赖
    • 分离版 ★ 常见问题 ★
  • 扩展功能专题

  • 云服务技术架构

  • 技术服务与支持

BasicForm 表单组件、使用方法、属性列表

# 介绍

对 Antdv 的 Form 表单 (opens new window) 组件进行封装,扩展一些常用的功能

v5.1.0 及之前版本:Antdv 2.x Form 表单 (opens new window)

# 使用

# 最简单示例

展示一个最简单表单的示例,只有一个输入框

<template>
  <div class="m-4">
    <BasicForm
      :labelWidth="100"
      :schemas="schemas"
      :showActionButtonGroup="true"
      :submitButtonOptions="{ text: '提交' }"
      :actionColOptions="{ span: 5 }"
      @submit="handleSubmit"
    />
  </div>
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { BasicForm, FormSchema } from '/@/components/Form';
  import { useMessage } from '/@/hooks/web/useMessage';

  const schemas: FormSchema[] = [
    {
      field: 'field',
      component: 'Input',
      label: '字段标签',
      colProps: {
        span: 8,
      },
      defaultValue: '123',
      componentProps: {
        placeholder: '这是一个输入框',
        onChange: (e: ChangeEvent) => {
          console.log('change', e);
        },
      },
    },
  ];

  export default defineComponent({
    components: { BasicForm },
    setup() {
      const { createMessage } = useMessage();
      return {
        schemas,
        handleSubmit: (values: any) => {
          createMessage.success('表单值: ' + JSON.stringify(values));
        },
      };
    },
  });
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# useForm 示例

页面表单推荐使用方法,方便传值和调用内部方法。

<template>
  <div class="m-4">
    <BasicForm @register="register" @submit="handleSubmit" />
  </div>
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { BasicForm, FormSchema, useForm } from '/@/components/Form/index';
  import { useMessage } from '/@/hooks/web/useMessage';

  const schemas: FormSchema[] = [
    {
      field: 'field',
      component: 'Input',
      label: '字段标签',
      colProps: {
        span: 8,
      },
      defaultValue: '123',
      componentProps: {
        placeholder: '这是一个输入框',
        onChange: (e: ChangeEvent) => {
          console.log('change', e.target.value);
        },
      },
    },
  ];

  export default defineComponent({
    components: { BasicForm },
    setup() {
      const { createMessage } = useMessage();
      // 参数 props 内的值可以是 computed 或者 ref 类型
      const [register, methods] = useForm({
        labelWidth: 120,
        schemas,
        showActionButtonGroup: true,
        submitButtonOptions: {
          text: '提交',
        },
        actionColOptions: {
          span: 5,
        },
      });
      return {
        register,
        schemas,
        handleSubmit: (values: any) => {
          // 更新字段值
          values.field = '456';
          methods.setFieldsValue(values);
          // 获取字段值
          const vals = methods.getFieldsValue();
          createMessage.success('表单值: ' + JSON.stringify(vals));
        },
      };
    },
  });
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# register

register 用于注册 useForm,如果需要使用 useForm 提供的 api,必须将 register 传入组件的 @register

<template>
  <BasicForm @register="register" @submit="handleSubmit" />
</template>
<script>
  export default defineComponent({
    components: { BasicForm },
    setup() {
      const [register] = useForm();
      return {
        register,
      };
    },
  });
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# methods

getFieldsValue

类型: () => Recordable;

说明: 获取表单值

setFieldsValue

类型: <T>(values: T) => Promise<void>

说明: 设置表单字段值

resetFields

类型: ()=> Promise<any>

说明: 重置表单值

validateFields

类型: (nameList?: NamePath[]) => Promise<any>

说明: 校验指定表单项

validate

类型: (nameList?: NamePath[]) => Promise<any>

说明: 校验整个表单

submit

类型: () => Promise<void>

说明: 提交表单

scrollToField

类型: (name: NamePath, options?: ScrollOptions) => Promise<void>

说明: 滚动到对应字段位置

clearValidate

类型: (name?: string | string[]) => Promise<void>

说明: 清空校验

setProps

提示

设置表单的 props 可以直接在标签上传递,也可以使用 setProps,或者初始化直接写 useForm(props)

类型: (formProps: Partial<FormProps>) => Promise<void>

说明: 设置表单 Props

removeSchemaByFiled

类型: (field: string | string[]) => Promise<void>

说明: 根据 field 删除 Schema

appendSchemaByField

类型: ( schema: FormSchema, prefixField: string | undefined, first?: boolean | undefined ) => Promise<void>

说明: 插入到指定 filed 后面,如果没传指定 field,则插入到最后,当 first = true 时插入到第一个位置

updateSchema

类型: (data: Partial<FormSchema> | Partial<FormSchema>[]) => Promise<void>

说明: 更新表单的 schema, 只更新函数所传的参数

e.g

updateSchema({ field: 'filed', componentProps: { disabled: true } });
updateSchema([
  { field: 'filed', componentProps: { disabled: true } },
  { field: 'filed1', componentProps: { disabled: false } },
]);
1
2
3
4
5

# 属性

温馨提醒

除以下参数外,官方文档内的 props 也都支持,具体可以参考 Antdv Form 表单 (opens new window)

v5.1.0 及之前版本:Antdv 2.x Form 表单 (opens new window)

属性 类型 默认值 可选值 说明
schemas Schema[] - - 表单配置,见下方 FormSchema 配置
submitOnReset boolean true - 重置时是否提交表单
labelCol Partial<ColEx> - - 整个表单通用 LabelCol 配置
wrapperCol Partial<ColEx> - - 整个表单通用 wrapperCol 配置
baseColProps Partial<ColEx> - - 配置所有选子项的 ColProps,不需要逐个配置,子项也可单独配置优先与全局
baseRowStyle object - - 配置所有 Row 的 style 样式
labelWidth number , string - - 扩展 form 组件,增加 label 宽度,表单内所有组件适用,可以单独在某个项覆盖或者禁用
labelAlign string - left,right label 布局
mergeDynamicData object - - 额外传递到子组件的参数 values
autoFocusFirstItem boolean false - 是否聚焦第一个输入框,只在第一个表单项为 input 的时候作用
compact boolean false true/false 紧凑类型表单,减少 margin-bottom
size string default 'default' , 'small' , 'large' 向表单内所有组件传递 size 参数,自定义组件需自行实现 size 接收
disabled boolean false true/false 向表单内所有组件传递 disabled 属性,自定义组件需自行实现 disabled 接收
autoSetPlaceHolder boolean true true/false 自动设置表单内组件的 placeholder,自定义组件需自行实现
autoSubmitOnEnter boolean false true/false 在input中输入时按回车自动提交
rulesMessageJoinLabel boolean false true/false 如果表单项有校验,会自动生成校验信息,该参数控制是否将字段中文名字拼接到自动生成的信息后方
showAdvancedButton boolean false true/false 是否显示收起展开按钮
emptySpan number , Partial<ColEx> 0 - 空白行格,可以是数值或者 col 对象 数
autoAdvancedLine number 3 - 如果 showAdvancedButton 为 true,超过指定行数行默认折叠
alwaysShowLines number 1 - 折叠时始终保持显示的行数
showActionButtonGroup boolean true true/false 是否显示操作按钮(重置/提交)
actionColOptions Partial<ColEx> - - 操作按钮外层 Col 组件配置,如果开启 showAdvancedButton,则不用设置,具体见下方 actionColOptions
showResetButton boolean true - 是否显示重置按钮
resetButtonOptions object - 重置按钮配置 ButtonProps (opens new window)
showSubmitButton boolean true - 是否显示提交按钮
submitButtonOptions object - 确认按钮配置 ButtonProps (opens new window)
resetFunc () => Promise<void> - 自定义重置按钮逻辑() => Promise<void>;
submitFunc () => Promise<void> - 自定义提交按钮逻辑() => Promise<void>;
fieldMapToTime [string, [string, string], string?][] - 用于将表单内时间区域的应设成 2 个字段,见下方说明

# ColEx 布局类型

常用属性:span、offset、plus、xs、sm、md、lg、xl、xxl

详细见 src/components/Form/src/types/index.ts (opens new window)

# fieldMapToTime 日期转换

将表单内时间区域的值映射成 2 个字段

如果表单内有时间区间组件,获取到的值是一个数组,但是往往我们传递到后台需要是 2 个字段

useForm({
  fieldMapToTime: [
    // data为时间组件在表单内的字段,startTime,endTime为转化后的开始时间于结束时间
    // 'YYYY-MM-DD'为时间格式,参考moment
    ['datetime', ['startTime', 'endTime'], 'YYYY-MM-DD'],
    // 支持多个字段
    ['datetime1', ['startTime1', 'endTime1'], 'YYYY-MM-DD HH:mm:ss'],
  ],
});

// fieldMapToTime没写的时候表单获取到的值
{
  datetime: [Date(),Date()]
}
//  ['datetime', ['startTime', 'endTime'], 'YYYY-MM-DD'],之后
{
    datetime: [Date(),Date()],
    startTime: '2020-08-12',
    endTime: '2020-08-15',
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# FormSchema 控件设置

属性 类型 默认值 可选值 说明
field string - - 字段名
fieldLabel string - - 字段标签名,如返回 Select、TreeSelect 的标签名
changeEvent string change - 表单更新事件名称
valueField string - value 绑定组件的属性名(一般无需设置)如:v-model:value
labelField string - labelValue 绑定组件的标签属性名(一般无需设置)如:v-model:labelValue
label string - - 标签名
subLabel string - - 二级标签名灰色
helpMessage string , string[] - - 标签名右侧温馨提示
helpComponentProps HelpComponentProps - - 标签名右侧温馨提示组件 props,见下方 HelpComponentProps
labelWidth string , number - - 覆盖统一设置的 labelWidth
disabledLabelWidth boolean false true/false 禁用 form 全局设置的 labelWidth,自己手动设置 labelCol 和 wrapperCol
component ComponentType Input - 组件类型,见下方 ComponentType
componentProps any,()=>{} - - 所渲染的组件的 props
rules ValidationRule[] - - 校验规则,见下方 ValidationRule
required boolean - - 简化 rules 配置,为 true 则转化成 [{required:true}]。2.4.0之前的版本只支持string类型的值
suffix string , number , ((values: RenderCallbackParams) => string / number); - - 组件后面的内容
rulesMessageJoinLabel boolean false - 校验信息是否加入 label
itemProps any - - 参考下方 FormItem
colProps ColEx - - 参考上方 actionColOptions
defaultValue object - - 所渲渲染组件的初始值
defaultLabel object - - 存储编码的显示名称初始值,如 treeCode 和 treeName
isAdvanced boolean - - 是否显示表单,展开和收起按钮
render (renderCallbackParams: RenderCallbackParams) => VNode / VNode[] / string - - 自定义渲染组件
renderColContent (renderCallbackParams: RenderCallbackParams) => VNode / VNode[] / string - - 自定义渲染组件(需要自行包含 formItem)
renderComponentContent (renderCallbackParams: RenderCallbackParams) => any / string - - 自定义渲染组内部的 slot
slot string - - 自定义 slot,渲染组件
colSlot string - - 自定义 slot,渲染组件 (需要自行包含 formItem)
show boolean / ((renderCallbackParams: RenderCallbackParams) => boolean) - - 动态判断当前组件是否显示,css 控制,不会删除 dom
ifShow boolean / ((renderCallbackParams: RenderCallbackParams) => boolean) - - 动态判断当前组件是否显示,js 控制,会删除 dom
dynamicDisabled boolean / ((renderCallbackParams: RenderCallbackParams) => boolean) - - 动态判断当前组件是否禁用
dynamicRules boolean / ((renderCallbackParams: RenderCallbackParams) => boolean) - - 动态判返当前组件你校验规则

RenderCallbackParams

export interface RenderCallbackParams {
  schema: FormSchema;
  values: any;
  model: any;
  field: string;
}
1
2
3
4
5
6

componentProps

  • 当值为对象类型时,该对象将作为component所对应组件的的 props 传入组件

  • 当值为一个函数时候

参数有 4 个

schema: 表单的整个 schemas

formActionType: 操作表单的函数。与 useForm 返回的操作函数一致

formModel: 表单的双向绑定对象,这个值是响应式的。所以可以方便处理很多操作

tableAction: 操作表格的函数,与 useTable 返回的操作函数一致。注意该参数只在表格内开启搜索表单的时候有值,其余情况为null,

  • 简单例子,值改变的时候操作表格或者修改表单内其他元素的值,实现组件联动:
{
  component: 'Input',
  componentProps: ({ schema, tableAction, formActionType, formModel }) => {
    return {
      // xxxx props
      onChange: (e: ChangeEvent) => {
        const { reload } = tableAction
        reload()
        // or
        formModel.xxx = '123'
      }
    };
  },
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

HelpComponentProps

export interface HelpComponentProps {
  maxWidth: string;
  // 是否显示序号
  showIndex: boolean;
  // 文本列表
  text: any;
  // 颜色
  color: string;
  // 字体大小
  fontSize: string;
  icon: string;
  absolute: boolean;
  // 定位
  position: any;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# ComponentType 组件类型

表单组件的组件类型 src/components/Form/src/componentMap.ts (opens new window)

export type ComponentType =
  | 'Input'
  | 'InputGroup'
  | 'InputPassword'
  | 'InputSearch'
  | 'InputTextArea'
  | 'InputNumber'
  | 'InputCountDown'
  | 'Select'
  | 'TreeSelect'
  | 'RadioButtonGroup'
  | 'RadioGroup'
  | 'Checkbox'
  | 'CheckboxGroup'
  | 'AutoComplete'
  | 'Cascader'
  | 'DatePicker'
  | 'MonthPicker'
  | 'RangePicker'
  | 'WeekPicker'
  | 'TimePicker'
  | 'Switch'
  | 'StrengthMeter'
  | 'Upload'
  | 'IconPicker'
  | 'Render'
  | 'Slider'
  | 'Rate'
  | 'None'
  | 'Divider'
  | 'FormGroup';
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

详细用法,可看本文:内置组件

# 自定义组件

ComponentType 内置组件,无法满足所有需求,这是你可以自定义渲染组件内容

# slot 插槽方式

自定义渲染内容

提示

使用插槽自定义表单域时,请注意 Antdv 有关 FormItem 的 相关说明 (opens new window)。

v5.1.0 及之前版本:Antdv 2.x Form 表单 (opens new window)

<template>
  <div class="m-4">
    <BasicForm @register="register">
      <template #customSlot="{ model, field }">
        <a-input v-model:value="model[field]" />
      </template>
    </BasicForm>
  </div>
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { BasicForm, FormSchema, useForm } from '/@/components/Form';
  export default defineComponent({
    name: 'FormDemo',
    components: { BasicForm },
    setup() {
      const schemas: FormSchema[] = [
        {
          field: 'field1',
          component: 'Input',
          defaultValue: '123',
          label: '字段1',
          slot: 'customSlot',
        },
      ];
      const [register] = useForm({
        labelWidth: 100,
        actionColOptions: {
          span: 24,
        },
        schemas,
      });
      return {
        register,
      };
    },
  });
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# render 函数式

自定义渲染内容

<template>
  <div class="m-4">
    <BasicForm @register="register" @submit="handleSubmit" />
  </div>
</template>
<script lang="ts">
  import { defineComponent, h } from 'vue';
  import { BasicForm, FormSchema, useForm } from '/@/components/Form/index';
  import { useMessage } from '/@/hooks/web/useMessage';
  import { Input } from 'ant-design-vue';
  const schemas: FormSchema[] = [
    {
      field: 'field1',
      component: 'Input',
      label: '字段1',
      colProps: {
        span: 8,
      },
      rules: [{ required: true }],
      // 通过函数渲染一个 Input
      render: ({ model, field }) => {
        return h(Input, {
          placeholder: '请输入',
          value: model[field],
          onChange: (e: ChangeEvent) => {
            model[field] = e.target.value;
          },
        });
      },
    },
    {
      field: 'field2',
      component: 'Input',
      label: '字段2',
      colProps: {
        span: 8,
      },
      rules: [{ required: true }],
      // 指定 Input 的 slot
      renderComponentContent: () => {
        return {
          suffix: () => 'suffix',
        };
      },
    },
  ];
  export default defineComponent({
    components: { BasicForm },
    setup() {
      const { createMessage } = useMessage();
      const [register, { setProps }] = useForm({
        labelWidth: 100,
        schemas,
        showActionButtonGroup: true,
        submitButtonOptions: {
          text: '提交',
        },
        actionColOptions: {
          span: 8,
        },
      });
      return {
        register,
        schemas,
        handleSubmit: (values: any) => {
          createMessage.success('表单值: ' + JSON.stringify(values));
        },
        setProps,
      };
    },
  });
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

# 新建组件方式

方式 1

在 src/components/Form/src/componentMap.ts (opens new window) 内,添加需要的组件,并在上方 ComponentType 添加相应的类型 key

这种写法适用与适用频率较高的组件

componentMap.set('componentName', 组件);
// ComponentType
export type ComponentType = xxxx | 'componentName';
1
2
3

方式 2

使用 useComponentRegister 进行注册

这种写法只能在当前页使用,页面销毁之后会从 componentMap 删除相应的组件

import { useComponentRegister } from '/@/components/Form';
import { StrengthMeter } from '@/components/StrengthMeter';
useComponentRegister('StrengthMeter', StrengthMeter);
1
2
3

提示

方式 2 出现的原因是为了减少打包体积,如果某个组件体积很大,用方式 1 的话可能会使首屏体积增加

# 显示禁用

自定义表单控件的:显示/禁用(ifShow/show/dynamicDisabled)

区别:ifShow 是否渲染组件;show 正常渲染组件,确定是否显示(display: none)

<template>
  <div class="m-4">
    <BasicForm @register="register" />
  </div>
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { BasicForm, FormSchema, useForm } from '/@/components/Form/index';
  const schemas: FormSchema[] = [
    {
      field: 'field1',
      component: 'Input',
      label: '字段1',
      colProps: {
        span: 8,
      },
      show: ({ values }) => {
        return !!values.field5;
      },
    },
    {
      field: 'field2',
      component: 'Input',
      label: '字段2',
      colProps: {
        span: 8,
      },
      ifShow: ({ values }) => {
        return !!values.field6;
      },
    },
    {
      field: 'field3',
      component: 'DatePicker',
      label: '字段3',
      colProps: {
        span: 8,
      },
      dynamicDisabled: ({ values }) => {
        return !!values.field7;
      },
    },
  ];

  export default defineComponent({
    components: { BasicForm },
    setup() {
      const [register, { setProps }] = useForm({
        labelWidth: 120,
        schemas,
        actionColOptions: {
          span: 24,
        },
      });
      return {
        register,
        schemas,
        setProps,
      };
    },
  });
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

# 表单验证

{
  label: t('员工工号'),
  field: 'employee.empNo',
  component: 'Input',
  componentProps: {
    maxlength: 32,
  },
  required: false, // 如果只是必填,可以这样简写,否则使用 rules
  rules: [
    // 是否必填
    { required: false },
    // 长度校验
    { min: 4, max: 20, message: t('请输入长度在 4 到 20 个字符之间') },
    // 邮箱校验
    { type: 'email', message: t('请填写正确的邮箱地址') }
    // 正则表达式校验
    { pattern: /^[\u0391-\uFFE5\w]+$/, message: t('不能输入特殊字符') },
    // 自定义验证,举例:远程验证工号是否存在
    {
      validator(_rule, value) {
        return new Promise((resolve, reject) => {
          if (!value || value === '') return resolve();
          checkEmpNo(record.value.employee?.empNo || '', value)
            .then((res) => (res ? resolve() : reject(t('员工工号已存在'))))
            .catch((err) => reject(err.message || t('验证失败')));
        });
      },
    },
    // 高级示例:跨字段校验,如:密码与确认密码是否相同
    {
      field: 'newPassword',
      label: '新密码',
      component: 'StrengthMeter',
      componentProps: {
        placeholder: '新密码',
      },
      rules: [
        {
          required: true,
          message: '请输入新密码',
        },
      ],
    },
    {
      field: 'confirmNewPassword',
      label: '确认密码',
      component: 'InputPassword',
      dynamicRules: ({ values }) => {
        return [
          {
            required: true,
            validator: (_, value) => {
              if (!value) {
                return Promise.reject('密码不能为空');
              }
              if (value !== values.newPassword) {
                return Promise.reject('两次输入的密码不一致!');
              }
              return Promise.resolve();
            },
          },
        ];
      },
    },
  ],
  ifShow: () => op.value === 'add' || op.value === 'edit',
},
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
参数 说明 类型 默认值
trigger 校验触发的时机 'blur' 'change'
enum 枚举类型 string -
len 字段长度 number -
max 最大长度 number -
message 校验文案 string -
min 最小长度 number -
pattern 正则表达式校验 RegExp -
required 是否必选 boolean false
transform 校验前转换字段值 function(value) => transformedValue:any -
type 内建校验类型,可选项 string 'string'
validator 自定义校验(注意,callback 必须被调用) function(rule, value, callback) -
whitespace 必选时,空格是否会被视为错误 boolean false

更多:Antdv Form 校验规则 (opens new window)   v5.1.0 及之前版本:Antdv 2.x Form 校验规则 (opens new window)

更多高级用法可研究 async-validator (opens new window)。

# 表单插槽

Slots

名称 说明
formHeader 表单顶部区域
formFooter 表单底部区域
submitBefore 提交按钮前
resetBefore 重置按钮前
advanceBefore 展开按钮前
advanceAfter 展开按钮后

# 内置组件

# Select 下拉选择

在 Antdv 的 Select 选择器 (opens new window) 基础之上封装,支持:字典数据、远程API数据。

v5.1.0 及之前版本:Antdv 2.x Select 选择器 (opens new window)

# 使用

const schemas: FormSchema[] = [
  {
    label: '下拉框',
    field: 'testSelect',
    component: 'Select',
    componentProps: {
      // 数据源1:固定数据
      options: [
        { label: '选项1', value: '11' },
        { label: '选项2', value: '22' },
      ],
      // 数据源2:动态数据
      // api: testDataSelectApi
      // params: {},
      // 数据源3:字典数据
      // dictType: 'sys_menu_type',
      allowClear: true,
      mode: 'multiple', // 多选
    },
  },
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 属性

属性 类型 默认值 说明
value object - 控件值(双向绑定)
labelValue object - 控件值的标签,如 treeCode和treeName
labelInValue boolean false 是否同时返回 labelValue(双向绑定)
options OptionsItem[] [] 下拉框选项,不启用 api 的时候,固定值可以使用
api ()=>Promise<{ label: string; value: string; disabled?: boolean }[]> - 数据接口,接受一个 Promise 对象
params object - 接口参数。此属性改变时会自动重新加载接口数据
resultField string - 接口返回的字段,如果接口返回数组,可以不填。支持x.x.x格式
immediate boolean false 是否立即请求接口,否则将在第一次点击时候触发请求
dictType string - 字典类型的下拉框,设置字典类型
mode boolean true 模式为多选或标签('multiple'

其它属性:Antdv Select 属性 (opens new window)   v5.1.0 及之前版本:Antdv 2.x Select 属性 (opens new window)

OptionsItem

属性 类型 默认值 说明
label object - 选项显示标签
value object - 选项值
disabled boolean - 是否禁止选择

# TreeSelect 下拉选择树

在 antdv 的 TreeSelect 选择器 (opens new window) 基础之上封装,支持:字典数据、远程API数据。

v5.1.0 及之前版本:Antdv 2.x TreeSelect 选择器 (opens new window)

# 使用

const schemas: FormSchema[] = [
  {
    label: '用户选择',
    field: 'testUser.userCode',
    fieldLabel: 'testUser.userName',
    component: 'TreeSelect',
    componentProps: {
      // 数据源1:固定数据
      treeDataSimpleMode: false,
      treeData: [
        {
          id: '1',
          name: 'tree 1',
          disabled: true,
          children: [
            { id: '1-1', name: 'tree 1-1' },
            { id: '1-2', name: 'tree 1-2' },
          ],
        },
        {
          id: '2',
          name: 'tree 2',
          disabled: true,
          children: [
            { id: '2-1', name: 'tree 2-1' },
            { id: '2-2', name: 'tree 2-2' },
          ],
        },
      ],
      // 数据源2:动态数据
      // api: officeTreeData,
      // params: { isLoadUser: true, userIdPrefix: '' },
      // canSelectParent: false,
      // 数据源3:字典数据
      // dictType: 'sys_menu_type',
      allowClear: true,
    },
  },
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# 属性

属性 类型 默认值 说明
value object - 控件值(双向绑定)
labelValue object - 控件值的标签,如 treeCode和treeName
labelInValue boolean false 是否同时返回 labelValue(双向绑定)
treeData TreeDataItem[] [] 下拉框选项,不启用 api 的时候,固定值可以使用
api ()=>Promise<{ label: string; value: string; disabled?: boolean }[]> - 数据接口,接受一个 Promise 对象
params object - 接口参数。此属性改变时会自动重新加载接口数据
resultField string - 接口返回的字段,如果接口返回数组,可以不填。支持x.x.x格式
immediate boolean false 是否立即请求接口,否则将在第一次点击时候触发请求
dictType string - 字典类型的下拉框,设置字典类型
treeCheckable boolean - 是否多选
treeDataSimpleMode boolean true 是否ztree格式 { id, pId, name }
canSelectParent boolean true 是否可以选择父级

其它属性:Antdv TreeSelect 属性 (opens new window)   v5.1.0 及之前版本:Antdv 2.x TreeSelect 属性 (opens new window)

# ListSelect 列表选择树

列表选择,展现为可搜索的输入选择框,点击后弹出对话框,体现列表形式选择数据。

相比 TreeSelect 性能更好,支持大数据,异步加载组件和数据。

# 使用

const schemas: FormSchema[] = [
  {
    label: '列表选择',
    field: 'customCode',
    fieldLabel: 'customName',
    component: 'ListSelect',
    componentProps: {
      // 内置列表选择类型:
      // 1)userSelect:用户选择;
      // 2)empUserSelect:员工选择(含组织机构信息)
      // 3)自定义,详见下一节
      selectType: 'userSelect',
    },
  },
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 扩展选择 selectType

上面介绍了,默认内置列表选择类型,本节主要介绍如何自定义业务选择。

  1. 复制 /src/components/ListSelect/src/selectType/userSelect.ts 文件
  2. 到当前目录下,重命名为 customSelect.ts 该文件名为 ListSelect 的 selectType 参数值
  3. 修改 customSelect.ts 文件内容,自定义您的业务选择列表的 searchForm 和 tableColumns
  4. 修改 export default 中的 itemCode 和 itemName 为选择后返回的字段名
  5. 用法:
const schemas: FormSchema[] = [
  {
    label: '用户选择',
    field: 'userCode',
    fieldLabel: 'userName',
    component: 'ListSelect',
    componentProps: {
      // 指定自定义的选择类型
      selectType: 'customSelect',
    },
  },
];
1
2
3
4
5
6
7
8
9
10
11
12

# 属性

属性 类型 默认值 说明
value object - 控件值(双向绑定)
labelValue object - 控件值的标签,如 treeCode和treeName
selectType string userSelect 选择类型:userSelect:用户选择;empUserSelect:员工选择(含组织机构信息);可自定义
itemCode string - 列表选择数据,回显和设置的字段编码属性名(优先级高于 userSelect.ts 里定义的 itemCode)
itemName string - 列表选择数据,回显和设置的字段显示名称属性名(优先级高于 userSelect.ts 里定义的 itemName)
checkbox boolean false 是否多选
allowInput boolean true 是否允许输入
readonly boolean true 是否只读

# RadioGroup 单选按钮组

在 Antdv 的 Radio 单选框 (opens new window) 基础之上封装,支持:字典数据。

v5.1.0 及之前版本:Antdv 2.x Radio 选择器 (opens new window)

# 使用

const schemas: FormSchema[] = [
  {
    label: '按钮组',
    field: 'menuType',
    component: 'RadioGroup',
    componentProps: {
      // 数据源1:固定数据
      options: [
        { label: '选项1', value: '11' },
        { label: '选项2', value: '22' },
      ],
      // 数据源2:字典数据
      // dictType: 'sys_menu_type',
    },
  },
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 属性

属性 类型 默认值 说明
value object - 控件值(双向绑定)
options OptionsItem[] [] 下拉框选项,不启用 api 的时候,固定值可以使用
dictType string - 字典类型的下拉框,设置字典类型

# RadioButtonGroup 单选按钮组

在 Antdv 的 Radio 单选框 (opens new window) 基础之上封装,支持:字典数据。

v5.1.0 及之前版本:Antdv 2.x Radio 选择器 (opens new window)

# 使用

const schemas: FormSchema[] = [
  {
    label: '按钮组',
    field: 'menuType',
    component: 'RadioButtonGroup',
    componentProps: {
      // 数据源1:固定数据
      options: [
        { label: '选项1', value: '11' },
        { label: '选项2', value: '22' },
      ],
      // 数据源2:字典数据
      // dictType: 'sys_menu_type',
    },
  },
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 属性

属性 类型 默认值 说明
value object - 控件值(双向绑定)
options OptionsItem[] [] 下拉框选项,不启用 api 的时候,固定值可以使用
dictType string - 字典类型的下拉框,设置字典类型

# CheckboxGroup 复选框组

在 Antdv 的 Checkbox 多选框 (opens new window) 基础之上封装,支持:字典数据。

v5.1.0 及之前版本:Antdv 2.x Checkbox 多选框 (opens new window)

# 使用

const schemas: FormSchema[] = [
  {
    label: '按钮组',
    field: 'menuType',
    component: 'CheckboxGroup',
    componentProps: {
      // 数据源1:固定数据
      options: [
        { label: '选项1', value: '11' },
        { label: '选项2', value: '22' },
      ],
      // 数据源2:字典数据
      // dictType: 'sys_menu_type',
    },
  },
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 属性

属性 类型 默认值 说明
value object - 控件值(双向绑定)
options OptionsItem[] [] 下拉框选项,不启用 api 的时候,固定值可以使用
dictType string - 字典类型的下拉框,设置字典类型

# Upload 上传控件

支持表单附件上传和编辑表格附件上传,可参考:testData/form.vue (opens new window)

# 使用

表单附件上传:

const inputFormSchemas: FormSchema[] = [
  {
    label: t('图片上传'),
    field: 'dataMap',
    component: 'Upload',
    componentProps: {
      loadTime: computed(() => record.value.__t),
      bizKey: computed(() => record.value.id),
      bizType: 'testData_image',
      uploadType: 'image',
    },
    colProps: { lg: 24, md: 24 },
  },
  {
    label: t('文件上传'),
    field: 'dataMap',
    component: 'Upload',
    componentProps: {
      loadTime: computed(() => record.value.__t),
      bizKey: computed(() => record.value.id),
      bizType: 'testData_file',
      uploadType: 'all',
    },
    colProps: { lg: 24, md: 24 },
  },
];
// 不可缺少,放在设置 record.value 代码后,用于更新上传列表
record.value = (res.testData || {}) as TestData;
record.value.__t = new Date().getTime();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

编辑表格附件上传:

<template>
  <BasicTable>
    <template #testDataChildUpload="{ record: childRecord }">
      <BasicUpload
        v-model:value="childRecord.dataMap"
        :bizKey="childRecord.id"
        :bizType="'testDataChild_file'"
        :uploadType="'all'"
        :loadTime="record.__t"
      />
    </template>
  </BasicTable>
</template>
<script lang="ts" setup>
  const testDataChildColumns: BasicColumn[] = [
    {
      title: t('文件上传'),
      dataIndex: 'upload',
      width: 160,
      align: 'left',
      // 个性化列,可定义插槽(如样式,增加控件等)
      slots: { customRender: 'testDataChildUpload' }, // 5.1.0 及之前
      slot: 'testDataChildUpload', // 5.2.0+ (Antdv 3.x 不再使用 slots)
    },
  ]);
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 属性

属性 类型 默认值 说明
value string[] - 已上传的文件列表,支持v-model
showPreviewNumber boolean true 是否显示预览数量
emptyHidePreview boolean false 没有上传文件时是否隐藏预览
helpText string - 帮助文本
maxSize number 2 单个文件最大体积,单位 M
maxNumber number Infinity 最大上传数量,Infinity 则不限制
accept string[] - 限制上传格式,可使用文件后缀名(点号可选)或MIME字符串,优先级高于 uploadType 。例如 ['.doc,','docx','application/msword','image/*']
multiple boolean - 开启多文件上传
uploadParams any - 上传携带的参数
checkmd5 boolean true 是否启用秒传(标准版/专业版)
api Fn - 上传接口,为上面配置的接口
bizKey object - 当前表单主键值
bizType string - 关联业务类型
uploadType UploadType all 上传文件类型(可选值:image、media、file、all)
loadTime number - 加载时间戳,此为监听属性,方便刷新文件列表数据

UploadType

可选值 限定格式
image .gif,.bmp,.jpeg,.jpg,.ico,.png,.tif,.tiff
media .flv,.swf,.mkv,webm,.mid,.mov,.mp3,.mp4,.m4v,.mpc,.mpeg,
.mpg,.swf,.wav,.wma,.wmv,.avi,.rm,.rmi,.rmvb,.aiff,.asf,.ogg,.ogv
file .doc,.docx,.rtf,.xls,.xlsx,.csv,.ppt,.pptx,.pdf,.vsd,.txt,
.md,.xml,.rar,.zip,7z,.tar,.tgz,.jar,.gz,.gzip,.bz2,.cab,.iso
all 以上所有

# 事件

事件 回调参数 返回值 说明
change (fileList)=>void 文件列表内容改变触发事件
delete (record)=>void 在上传列表中删除文件的事件

# RangePicker 日期范围

使用 Antdv 的 DatePicker 日期选择框 (opens new window) 组件,常用于搜索栏的日期范围查询条件。

v5.1.0 及之前版本:Antdv 2.x DatePicker 日期选择框 (opens new window)

const searchForm: FormProps = {
  baseColProps: { lg: 6, md: 8 },
  labelWidth: 90,
  schemas: [
    {
      label: t('创建时间'),
      field: 'dateRange',
      component: 'RangePicker',
      componentProps: {},
    },
  ],
  // 定义自动转换规则[ [ 日期控件定义字段名, [ 开始日期查询参数, 结束日期查询参数 ] ] ]
  fieldMapToTime: [['dateRange', ['beginDate', 'endDate']]],
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Divider 分隔符

使用 Antdv 的 Divider 分割线 (opens new window) 组件。Divider 类型用于在 schemas 中占位,将会渲染成一个分割线(始终占一整行的版面),可以用于较长表单的版面分隔。请只将 Divider 类型的 schema 当作一个分割线,而不是一个常规的表单字段。

v5.1.0 及之前版本:Antdv 2.x Divider 分割线 (opens new window)

  • 仅在 showAdvancedButton 为 false 时才显示(也就是说如果启用了表单收起和展开功能时不会显示)
  • 使用 schema 中的 label 以及 helpMessage 来渲染分割线中的提示内容或标题
  • 使用 componentProps 来设置除 type 之外的属性,如:dashed是否虚线、orientation标题的位置
const inputFormSchemas: FormSchema[] = [
  {
    label: '',
    field: 'detailInfo',
    component: 'Divider',
    colProps: { lg: 24, md: 24 },
  },
];
1
2
3
4
5
6
7
8

# FormGroup 子表单

FormGroup类型与Divider类似,将会渲染成一个带表单子标题的分割线(占一整行的版面)不是一个常规的表单字段。

const inputFormSchemas: FormSchema[] = [
  {
    label: t('详细信息'),
    field: 'detailInfo',
    component: 'FormGroup',
    colProps: { lg: 24, md: 24 },
  },
];
1
2
3
4
5
6
7
8
进入 JeeSite 源码仓库页面,点击右上角 ⭐ Star 加星关注。

← 前端权限、按钮权限 BasicTable 表格组件→

联系我们:s.jeesite.com  |  微信号:jeesitex  |  邮箱:jeesite@163.com
© 2013-2023 济南卓源软件有限公司 版权所有 | Theme Vdoing

关注 JeeSite 公众号,了解最新动态

  • 跟随系统
  • 浅色模式
  • 深色模式
  • 阅读模式