Form Configuration (option)

When using FormCreate to generate forms, you can manage form behavior and appearance through global configuration. This guide details how to set global configuration and how to use these configurations to enhance form flexibility and controllability.

Setting Global Configuration

Component Mode

In component mode, pass global configuration through the option property:

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

Global Method

When creating forms using global methods, you can also pass global configuration:

formCreate.create(rule, option)

Example Demo

The following is a simple example showing how to set form behavior using global configuration:

Option Configuration List

The table details various Option configuration properties of the FormCreate component, including global component configuration, event injection, form validation, multi-language support, layout control, and other core functions, helping developers comprehensively customize form behavior and appearance.

Property Name	Type	Default Value	Description
global	{ '*': VNodeRule; [componentName: string]: VNodeRule }	-	Set component default configuration: * is global common configuration, key names support specifying component names (such as input) to override specific component configuration.
injectEvent	Object | Boolean	false	Globally enable event injection (such as onChange), if it's an object, you can customize event names and handling logic.
preview	Boolean	false	Whether to enable preview mode
forceCoverValue	Boolean	false	Whether v-model forcibly overwrites undefined field values (if false, original values of undefined fields are retained).
appendValue	Boolean	false	Whether to retain field values not defined in rules in v-model (if false, these fields are filtered when submitting).
ignoreHiddenFields	Boolean	true	Whether to ignore fields in hidden state when submitting forms (if false, hidden field values are included).
validateOnSubmit	Boolean	true	Control whether to automatically trigger form validation before form submission.
formData	Object	{}	Set form initial values (not two-way binding, only effective during initialization).
language	{ [name: string]: { [id: string]: string } }	-	Configure multi-language content, keys are language names (such as zh-CN), values are text ID and translation key-value pairs.
el	Element	-	Specify DOM element for form mounting (required in non-component mode).
onSubmit	(formData: Object, api: Api) => void	-	Form submit callback, receives form data and API object.
beforeSubmit	(formData: Object, form: {api: Api}) => void| boolean | Promise<any>	-	Triggered before form submission.
beforeFetch	(config: FetchEffectOption, ctx: { api: Api, rule: Rule }) => void	-	Modify request configuration before fetch request (such as adding request headers).
mounted	(api: Api) => void	-	Triggered after form creation is successful, used to get API instance or execute initialization logic.
reload	(api: Api) => void	-	Triggered after form reload (such as after calling api.reload()).
onValidateFail	(e: Object, form: {api: Api}) => void	-	Triggered when form validation fails.
col	Boolean | (ColProps & { show?: Boolean })	true	Configure Col layout component (grid system), show: false can disable layout.
row	Boolean | (RowProps & { show?: Boolean })	true	Configure Row layout component, control form row arrangement.
info	Boolean | (VNodeRule & { show?: Boolean, native?: Boolean, ... })	true	Configure floating hint component, icon can customize icon, align controls alignment direction.
wrap	Boolean | (VNodeRule & FormItemProps & { show?: Boolean })	true	Configure FormItem container style, supports overriding label width, validation hint style, etc.
form	FormProps	-	Set form root component properties (such as labelWidth, size, etc., depends on specific UI framework).
title	Boolean | (VNodeRule & { show?: Boolean, native?: Boolean, ... })	true	Configure form item label (label), native: false can disable native label style.
submitBtn	Boolean | (ButtonProps & { click?: Function, show?: Boolean, ... })	true	Configure submit button, innerText can modify button text, show: false hides button.
resetBtn	Boolean | (ButtonProps & { click?: Function, show?: Boolean, ... })	true	Configure reset button, supports custom click events or hiding button.

UI Framework Configuration

FormCreate supports multiple UI frameworks, and each framework's configuration items are slightly different. The following are global configuration guides for each framework:

• Element Plus Form Global Configuration
• Ant Design Vue Form Global Configuration
• Naive UI Form Global Configuration
• Arco Design Form Global Configuration
• TDesign Form Global Configuration
• Vant UI Form Global Configuration

Examples

Configure Form Styles

Control form styles through form field

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

Configure Form Default Values

Control default values through formData field, priority is lower than 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>

Ignore Hidden Form Component Fields When Submitting Form

Control whether to submit hidden fields when submitting form through ignoreHiddenFields field

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

Disable Default Form Validation Before Form Submission

Control whether to submit hidden fields when submitting form through validateOnSubmit field

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

Component Default Configuration

Configure component common configuration through global field

<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>

Data Structure

The following is an example of the data structure of the Option configuration item in the ElementPlus version:

type Option = {
    //Set component default configuration
    global?: {
      '*':VNodeRule;
      [componentName:string]: VNodeRule;
    };
    //Globally enable event injection
    injectEvent?: Object|Boolean;
    //Whether to enable preview mode
    preview?: Boolean;
    //Whether v-model updates undefined field values
    forceCoverValue?: Boolean;
    //Whether to save fields not in rules in v-model
    appendValue?: Boolean;
    //Whether to ignore fields in hidden state when submitting forms
    ignoreHiddenFields?: Boolean;
    //Control whether to trigger form validation before form submission
    validateOnSubmit?: Boolean;
    //Set form initial values (not two-way binding)
    formData?: Object;
    //Configure form multi-language content
    language: {
        //Language name: {[ID]: text}
        [name: string] : {
            [id: string]: string;
        };
    },
    //Used to specify the DOM element for form mounting. Not needed in component mode.
    el?: Element;
    //Callback function when form is submitted.
    onSubmit?: (formData: Object, api: Api) => void;
    //Callback triggered before fetch request, used to modify request configuration.
    beforeFetch?: (config: FetchEffectOption, form: {
      api: Api,
      rule: Rule
    }) => void;
    //Triggered before form submission
    beforeSubmit?: (formData: Object, form: {
        api: Api
    }) => void | boolean | Promise<any>;
    //Triggered when form validation fails
    onValidateFail?: (e: Object, form: {api: Api}) => void;
    //Callback function after form creation is successful.
    mounted?: (api: Api) => void;
    //Callback function after form reload.
    reload?: (api: Api) => void;
    //Set overall configuration of Col component.
    col?: Boolean | ColProps & {
        show?: Boolean;
    };
    //Set overall configuration of Row component.
    row?: Boolean | RowProps & {
        show?: Boolean;
    };
    //Set configuration of floating hint component.
    info?: Boolean | VNodeRule & {
        show?: Boolean;
        native?: Boolean;
        icon?: string;
        align?: 'left' | 'right';
        info?: string;
    };
    //Set overall configuration of FormItem component.
    wrap?: Boolean | (VNodeRule & FormItemProps & {show?: Boolean});
    //Set overall configuration of form, corresponding to UI framework's form component.
    form?: FormProps;
    //Set configuration of submit button (Button component).
    submitBtn?: Boolean | ButtonProps & {
        click?: Function;
        innerText?: string;
        show?: Boolean;
    };
    //Set configuration of reset button (Button component).
    resetBtn?: Boolean | ButtonProps & {
        click?: Function;
        innerText?: string;
        show?: Boolean;
    };
    //Set configuration of formItem component's label area.
    title?: Boolean | VNodeRule & {
        show?: Boolean;
        native?: Boolean;
        title: string;
    };
}