表单全局配置

在使用 FormCreate 生成表单时，可以通过全局配置来管理表单的行为和外观。本文将详细介绍如何设置全局配置，以及如何使用这些配置来增强表单的灵活性和可控性。

设置全局配置

组件模式

在组件模式下，通过 option 属性传递全局配置：

<form-create :option="option"></form-create>

全局方法

在使用全局方法创建表单时，也可以传递全局配置：

formCreate.create(rule, option)

示例演示

以下是一个简单的示例，展示了如何使用全局配置设置表单的行为：

配置项数据结构

属性名	类型	默认值	作用说明
global	{ '*': VNodeRule; [componentName: string]: VNodeRule }	-	设置组件默认配置：* 为全局通用配置，键名支持指定组件名称（如 input）覆盖特定组件配置。
injectEvent	Object | Boolean	false	全局开启事件注入（如 onChange），若为对象可自定义事件名与处理逻辑。
preview	Boolean	false	是否开启预览模式
forceCoverValue	Boolean	false	v-model 是否强制覆盖未定义的字段值（若为 false 则保留未定义字段原值）。
appendValue	Boolean	false	v-model 中是否保留规则中未定义的字段值（若为 false 则提交时过滤这些字段）。
ignoreHiddenFields	Boolean	true	表单提交时是否忽略隐藏状态的字段（若为 false 则包含隐藏字段值）。
validateOnSubmit	Boolean	true	控制表单提交前是否自动触发表单验证。
formData	Object	{}	设置表单初始值（非双向绑定，仅初始化时生效）。
language	{ [name: string]: { [id: string]: string } }	-	配置多语言内容，键为语言名称（如 zh-CN），值为文本ID与翻译键值对。
el	Element	-	指定表单挂载的DOM元素（非组件模式时必填）。
onSubmit	(formData: Object, api: Api) => void	-	表单提交回调，接收表单数据和API对象。
beforeFetch	(config: FetchEffectOption, ctx: { api: Api, rule: Rule }) => void	-	在 fetch 请求前修改请求配置（如添加请求头）。
mounted	(api: Api) => void	-	表单创建成功后触发，用于获取API实例或执行初始化逻辑。
reload	(api: Api) => void	-	表单重载后触发（如调用 api.reload() 后）。
col	Boolean | (ColProps & { show?: Boolean })	true	配置 Col 布局组件（栅格系统），show: false 可禁用布局。
row	Boolean | (RowProps & { show?: Boolean })	true	配置 Row 布局组件，控制表单行的排列方式。
info	Boolean | (VNodeRule & { show?: Boolean, native?: Boolean, ... })	true	配置悬浮提示组件，icon 可自定义图标，align 控制对齐方向。
wrap	Boolean | (VNodeRule & FormItemProps & { show?: Boolean })	true	配置 FormItem 容器样式，支持覆盖标签宽度、校验提示样式等。
form	FormProps	-	设置表单根组件属性（如 labelWidth、size 等，依赖具体UI框架）。
title	Boolean | (VNodeRule & { show?: Boolean, native?: Boolean, ... })	true	配置表单项标签（label），native: false 可禁用原生标签样式。
submitBtn	Boolean | (ButtonProps & { click?: Function, show?: Boolean, ... })	true	配置提交按钮，innerText 可修改按钮文字，show: false 隐藏按钮。
resetBtn	Boolean | (ButtonProps & { click?: Function, show?: Boolean, ... })	true	配置重置按钮，支持自定义点击事件或隐藏按钮。

以下是 ElementPlus 版本中 Option 配置项的数据结构示例：

type Option = {
    //设置组件默认配置
    global?: {
      '*':VNodeRule;
      [componentName:string]: VNodeRule;
    };
    //全局开启事件注入
    injectEvent?: Object|Boolean;
    //是否开启预览模式
    preview?: Boolean;
    //v-model是否更新未定义的字段值
    forceCoverValue?: Boolean;
    //v-model中是否保存不在规则中的字段
    appendValue?: Boolean;
    //表单提交时是否忽略表单中隐藏状态的字段
    ignoreHiddenFields?: Boolean;
    //控制是否在表单提交前触发表单验证
    validateOnSubmit?: Boolean;
    //设置表单的初始值（非双向绑定）
    formData?: Object;
    //配置表单多语言内容
    language: {
        //语言名称: {[ID]: 文字}
        [name: string] : {
            [id: string]: string;
        };
    },
    //用于指定表单挂载的 DOM 元素。在组件模式下无需设置。
    el?: Element;
    //表单提交时的回调函数。
    onSubmit?: (formData: Object, api: Api) => void;
    //在 fetch 请求前触发的回调，用于修改请求配置。
    beforeFetch?: (config: FetchEffectOption, form: {
      api: Api,
      rule: Rule
    }) => void;
    //表单创建成功后的回调函数。
    mounted?: (api: Api) => void;
    //表单重载后的回调函数。
    reload?: (api: Api) => void;
    //设置 Col 组件的整体配置。
    col?: Boolean | ColProps & {
        show?: Boolean;
    };
    //设置 Row 组件的整体配置。
    row?: Boolean | RowProps & {
        show?: Boolean;
    };
    //设置悬浮提示组件的配置。
    info?: Boolean | VNodeRule & {
        show?: Boolean;
        native?: Boolean;
        icon?: string;
        align?: 'left' | 'right';
        info?: string;
    };
    //设置 FormItem 组件的整体配置。
    wrap?: Boolean | (VNodeRule & FormItemProps & {show?: Boolean});
    //设置表单的整体配置，对应 UI 框架的表单组件。
    form?: FormProps;
    //设置提交按钮（Button 组件）的配置。
    submitBtn?: Boolean | ButtonProps & {
        click?: Function;
        innerText?: string;
        show?: Boolean;
    };
    //设置重置按钮（Button 组件）的配置。
    resetBtn?: Boolean | ButtonProps & {
        click?: Function;
        innerText?: string;
        show?: Boolean;
    };
    //设置 formItem 组件的 label 区域的配置。
    title?: Boolean | VNodeRule & {
        show?: Boolean;
        native?: Boolean;
        title: string;
    };
}

UI框架配置

FormCreate 支持多个 UI 框架，每个框架的配置项略有不同。以下是各个框架的全局配置指南：

• Element Plus 表单全局配置
• Ant Design Vue 表单全局配置
• Naive UI 表单全局配置
• Arco Design 表单全局配置
• TDesign 表单全局配置
• Vant UI 表单全局配置

示例

配置表单样式

通过 form 字段控制在表单的样式

<template>
    <div>
        <form-create :option="options"/>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const options = ref({
        form:  {
            labelPosition: 'top',
            labelWidth: '150px'
        },
    })
</script>

配置表单默认值

通过 formData 字段控制的默认值, 优先级小于 v-model

<template>
    <div>
        <form-create :option="options"/>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const options = ref({
        formData: {
            goods_name: 'default value'
        }
    })
</script>

表单提交时忽略隐藏的表单组件字段

通过 ignoreHiddenFields 字段控制在表单提交时是否提交隐藏的字段

<template>
    <div>
        <form-create :option="options"/>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const options = ref({
        ignoreHiddenFields: true,
    })
</script>

关闭表单提交前的默认表单验证

通过 validateOnSubmit 字段控制在表单提交时是否提交隐藏的字段

<template>
    <div>
        <form-create :option="options"/>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const options = ref({
        validateOnSubmit: true,
    })
</script>

组件默认配置

通过 global 字段配置组件的公共配置

<template>
    <div>
        <form-create :option="options"/>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const options = ref({
         global: {
             upload: {
                 props: {
                     headers: {
                        token: getToken()  
                     },
                     onSuccess(file, res) {
                         file.url = res.data.url
                     }
                 }
             }
         },
    })
</script>