Component Default Configuration

FormCreate provides two ways to set component default configurations:

1. Designer Configuration: Set default rules for components when dragged into the designer through the updateDefaultRule configuration option
2. Runtime Configuration: Set common configurations for components during form rendering through the option.global configuration option

Designer Configuration

Set component initialization rules in the designer using updateDefaultRule. This automatically applies default configurations when dragging components into the designer, improving efficiency.

Data Structure

type UpdateDefaultRule = {
    // Component drag rule id, set component initialization rules
    [id: string]: Partial<Omit<Rule, "field" | "children" | "component">> | ((Rule) => void);
}

Note

After defining component default values, it won't affect existing historical data, only components that are newly dragged in will be affected.

Modify Input Component Default Rules

In this example, make the input automatically disabled when dragged in:

<template>
    <fc-designer ref="designer" :config="config"/>
</template>
<script setup>
    const config = {
        updateDefaultRule: {
            input: {
                props: {
                    disabled: true
                }
            }
        }
    }
</script>

Set Select Component Default Options

Make the select component required and preset a default value, such as "Please select":

<template>
    <fc-designer ref="designer" :config="config"/>
</template>
<script setup>
    const config = {
        updateDefaultRule: {
            select: {
                $required: true,
                props: {
                    options: [
                        { label: "Please select", value: "" },
                        { label: "Option 1", value: "option1" },
                        { label: "Option 2", value: "option2" }
                    ]
                }
            }
        }
    }
</script>

Set Textarea Row Count

Set a default row limit in the textarea component:

<template>
    <fc-designer ref="designer" :config="config"/>
</template>
<script setup>
    const config = {
        updateDefaultRule: {
            textarea: {
                props: {
                    rows: 5 // Default row count
                }
            }
        }
    }
</script>

Global Replacement Configuration

Register a parser with formCreate.parser to directly modify rules. Parser is global processing and triggers before options.global, suitable for scenarios requiring forced unified rules.

Important Note

formCreate.parser needs to be registered at application startup, usually written in main.js, not in components.

Basic Usage

Register Parser in main.js:

// main.js
import formCreate from '@form-create/element-ui';

formCreate.parser({
  name: 'upload',
  merge: true,
  init({rule}) {
    // Directly modify the rule itself
    rule.props.action = '/api/upload';
    rule.props.onError = function (r) {
      alert('Unified upload failure handling');
    };
    rule.props.onSuccess = function (file, res) {
      file.url = res.data.url;
    };
  }
});

Usage Example

<template>
  <form-create :rule="rule" v-model:api="fApi" :option="options"/>
</template>

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        // options.global will execute after Parser
        global: {
          upload: {
            props: {
              // If listType is not defined in the rule, this configuration will be applied
              listType: 'picture-card'
            }
          }
        }
      },
      rule: [
        {
          type: 'upload',
          field: 'upload1',
          title: 'Upload Image 1',
          props: {
            // action will be modified by Parser to '/api/upload'
            // onError will be modified by Parser to unified handler function
          }
        },
        {
          type: 'upload',
          field: 'upload2',
          title: 'Upload Image 2',
          props: {
            action: '/custom-upload',  // This will be overwritten by Parser to '/api/upload'
            onError: function (r) {
              console.log('Custom error handling');  // This will be overwritten by Parser
            }
          }
        }
      ]
    }
  }
}
</script>

Data Structure

type Parser = (name: string, parser: ParserConfig) => void;

interface ParserConfig {
    // Whether to merge built-in parsing rules, keep true for built-in components
    merge?: true;
    // Initialize component rule
    init?: (ctx: ParserContext) => void;
}

interface ParserContext {
    // Current component's rule configuration
    rule: Rule;
    // Form API instance
    $api: Api;
}

merge Parameter Description

• When adding parsers for built-in components (such as input, select, etc.), please configure merge: true to avoid overriding system built-in parsing logic.
• Custom extended components can omit this parameter if there is no default parsing logic.

Parser vs options.global

• Parser: Directly modifies the rule itself, executes earliest, suitable for scenarios requiring forced unified rules
• options.global: Applies configuration through merging, executes after Parser, suitable for scenarios requiring flexible configuration

If you need to override configuration again after Parser, you can use options.global.deep.

Runtime Replacement Configuration

During form rendering, use the global configuration option to set common configurations for components. This lets you set unified default values and behaviors for all components, simplifying configuration and maintenance.

Basic Usage

<template>
  <form-create :rule="rule" v-model:api="fApi" :option="options"/>
</template>

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        global: {
          // Global configuration: applies to all components
          '*': {
            props: {
              disabled: true
            }
          },
          // Specific component configuration: only applies to upload component
          upload: {
            props: {
              onError: function (r) {
                alert('Upload failed');
              }
            }
          }
        }
      },
      rule: [
        // Form rules
      ]
    }
  }
}
</script>

Configuration Rules

The global configuration supports the following rules:

• '*': Wildcard, indicating all components will apply this configuration
• Component type name: Such as input, select, upload, etc., only applies to specified component types
• Configuration priority: Component type configuration overrides wildcard configuration, configuration in component rules overrides global configuration

Configuration Merge Methods

The global configuration supports two merge methods:

1. Normal Configuration (Default Merge):

When the same property already exists in the rule, the global configuration will not override the configuration in the rule, only taking effect when the property doesn't exist in the rule.

global: {
  upload: {
    props: {
      action: '/api/upload',  // Default upload address
      onError: function (r) {
        alert('Upload failed');
      }
    }
  }
}

2. Deep Merge Configuration (Force Override):

Use the deep property, specify the property to force override through dot notation path, which will force override the property with the same name in the rule.

global: {
  upload: {
    deep: {
      'props.action': '/api/upload',  // Force override action in rule
      'props.onError': function (r) {
        alert('Upload failed');
      },
      'props.onSuccess': function (file, res) {
        file.url = file.response.url;
      }
    }
  }
}

Important Note

Execution Order: Parser (global replacement configuration) → options.global (normal configuration) → options.global.deep (deep merge)

• Normal Configuration: Only takes effect when the corresponding property doesn't exist in the rule, will not override existing properties in the rule
• Deep Merge Configuration: Use the deep object, specify the property to override through dot notation path (e.g., 'props.onError'), which will force override the property with the same name in the rule, even if the property has already been defined in the rule

Usage Examples

1. Set Default Disabled State and Col Layout for All Components:

<template>
  <form-create :rule="rule" v-model:api="fApi" :option="options"/>
</template>

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        global: {
          '*': {
            props: {
              disabled: true  // All components disabled by default
            },
            col: {
              span: 12  // All components default to 12 columns (half width)
            }
          }
        }
      },
      rule: [
        {
          type: 'input',
          field: 'input1',
          title: 'input1'
          // Will automatically apply disabled: true and col: { span: 12 }
        },
        {
          type: 'input',
          field: 'input2',
          title: 'input2'
          // Will automatically apply disabled: true and col: { span: 12 }
        },
        {
          type: 'input',
          field: 'input3',
          title: 'input3',
          col: {
            span: 24  // Override global configuration, full width
          }
        }
      ]
    }
  }
}
</script>

2. Set Upload Component Upload Callback Events (Normal Configuration):

Configure global callback events for upload components using normal configuration. This method only takes effect when corresponding callbacks are not defined in the rule.

<template>
  <form-create :rule="rule" v-model:api="fApi" :option="options"/>
</template>

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        onSubmit: (formData) => {
          alert(JSON.stringify(formData));
        },
        global: {
          '*': {
            props: {
              disabled: true
            },
            col: {
              span: 12
            }
          },
          // Normal configuration: only takes effect when corresponding property doesn't exist in rule
          upload: {
            props: {
              action: '/api/upload',  // Default upload address
              onError: function (r) {
                alert('Upload failed');
              },
              onSuccess: function (file, res) {
                file.url = file.response.url;
              }
            }
          }
        }
      },
      rule: [
        {
          type: 'input',
          field: 'input1',
          title: 'input1'
        },
        {
          type: 'input',
          field: 'input2',
          title: 'input2'
        },
        {
          type: 'input',
          field: 'input3',
          title: 'input3',
          col: {
            span: 24
          }
        },
        {
          type: 'input',
          field: 'input4',
          title: 'input4',
          col: {
            span: 24
          }
        },
        {
          type: 'upload',
          field: 'upload',
          title: 'Upload Image',
          value: '',
          col: {
            span: 24
          },
          props: {
            listType: 'picture-card'
            // If action is not defined in rule, global configuration's action: '/api/upload' will be applied automatically
            // If onError is not defined in rule, global configuration's onError will be applied automatically
            // If onError is defined in rule, the onError in rule will be used
          }
        },
        {
          type: 'upload',
          field: 'upload2',
          title: 'Upload File',
          props: {
            action: '/',
            onError: function (r) {
              console.log('Custom error handling');  // This will override global configuration
            }
            // Because onError is defined in rule, global configuration's onError will not take effect
          }
        }
      ]
    }
  }
}
</script>

3. Force Override Configuration in Rules (Deep Merge):

Use the deep property, specify properties to force override through dot notation paths, which can force override properties with the same name in rules, even if those properties have already been defined in the rules.

<template>
  <form-create :rule="rule" v-model:api="fApi" :option="options"/>
</template>

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        global: {
          upload: {
            // Deep merge configuration: use dot notation paths to specify properties to override
            deep: {
              'props.action': '/api/upload',  // Force override action in rule
              'props.onError': function (r) {
                alert('Unified upload failure handling');
              },
              'props.onSuccess': function (file, res) {
                file.url = file.response.url;
              }
            }
          }
        }
      },
      rule: [
        {
          type: 'upload',
          field: 'upload1',
          title: 'Upload Image 1',
          props: {
            action: '/old-upload',  // This will be overwritten by global configuration to '/api/upload'
            onError: function (r) {
              console.log('Error handling in rule');  // This will be overwritten by global configuration
            }
            // Even if action and onError are defined in rule, they will be overwritten by global configuration
          }
        },
        {
          type: 'upload',
          field: 'upload2',
          title: 'Upload Image 2',
          props: {
            // action and onError are not defined, will use global configuration's action and onError
          }
        }
      ]
    }
  }
}
</script>

4. Set Different Default Configurations for Different Component Types:

<template>
  <form-create :rule="rule" v-model:api="fApi" :option="options"/>
</template>

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        global: {
          // Common configuration for all components
          '*': {
            col: {
              span: 12
            }
          },
          // Specific configuration for input components
          input: {
            props: {
              clearable: true,
              placeholder: 'Please enter'
            }
          },
          // Specific configuration for select components
          select: {
            props: {
              clearable: true,
              placeholder: 'Please select'
            }
          },
          // Specific configuration for textarea components
          textarea: {
            props: {
              rows: 4,
              placeholder: 'Please enter content'
            }
          }
        }
      },
      rule: [
        {
          type: 'input',
          field: 'name',
          title: 'Name'
          // Will automatically apply clearable: true and placeholder: 'Please enter'
        },
        {
          type: 'select',
          field: 'category',
          title: 'Category'
          // Will automatically apply clearable: true and placeholder: 'Please select'
        },
        {
          type: 'textarea',
          field: 'description',
          title: 'Description'
          // Will automatically apply rows: 4 and placeholder: 'Please enter content'
        }
      ]
    }
  }
}
</script>

Differences Between Three Configuration Methods

Configuration Method	Application Scenario	Effective Timing	Scope of Impact	Execution Order
formCreate.parser	Global processing	When rules are parsed	Directly modifies rule itself	Executes first
option.global	Rendering environment	During form rendering	Applies configuration through merging	After Parser
updateDefaultRule	Designer environment	When components are dragged into designer	Only affects newly dragged components	Designer-specific

Usage Recommendations

• Parser Configuration: Suitable for scenarios requiring forced unified rules and directly modifying rule itself, executes earliest
• Runtime Configuration (option.global): Suitable for unifying component display and behavior at runtime, achieving unified management of business logic
• Designer Configuration (updateDefaultRule): Suitable for unifying component initial state at design stage, improving design efficiency

Execution Order: Parser → option.global (normal configuration) → option.global.deep (deep merge)