设置组件默认配置

FormCreate 提供了两种方式来设置组件的默认配置：

设计器配置：通过 updateDefaultRule 配置项，在设计器中设置组件拖入时的默认规则
渲染时配置：通过 option.global 配置项，在表单渲染时设置组件的公共配置

设计器配置

在设计器中，您可以通过 updateDefaultRule 配置项设置组件的初始化规则。这允许您在拖拽组件到设计器时，自动应用某些默认配置，进而提高用户体验和效率。

数据结构

type UpdateDefaultRule = {
    //组件拖拽组件规则的id, 设置组件的初始化规则
    [id: string]: Partial<Omit<Rule, "field" | "children" | "component">> | ((Rule) => void);
}

注意

定义组件默认值后，不会影响历史已有数据，仅对重新拖入的组件生效。

修改输入框组件的默认规则

在这个示例中，让输入框拖入时自动禁用

vue

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

设置选择框的默认选项

您可以让选择框组件必填并且预设一个默认值，例如“请选择”：

vue

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

设置文本域的行数

您可以在文本域组件中设置默认的行数限制：

vue

<template>
    <fc-designer ref="designer" :config="config"/>
</template>
<script setup>
    const config = {
        updateDefaultRule: {
            textarea: {
                props: {
                    rows: 5 // 默认行数
                }
            }
        }
    }
</script>

全局替换配置

通过 formCreate.parser 注册解析器，可以直接修改规则本身。Parser 是全局处理，会在 options.global 之前触发，适合需要强制统一规则的场景。

重要提示

formCreate.parser 需要在应用启动时注册，通常写在 main.js 中，而不是在组件中。

基本用法

在 main.js 中注册 Parser：

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

formCreate.parser({
  name: 'upload',
  merge: true,
  init({rule}) {
    // 直接修改规则本身
    rule.props.action = '/api/upload';
    rule.props.onError = function (r) {
      alert('统一的上传失败处理');
    };
    rule.props.onSuccess = function (file, res) {
      file.url = res.data.url;
    };
  }
});

使用示例

vue

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

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        // options.global 会在 Parser 之后执行
        global: {
          upload: {
            props: {
              // 如果规则中没有定义 listType，会应用此配置
              listType: 'picture-card'
            }
          }
        }
      },
      rule: [
        {
          type: 'upload',
          field: 'upload1',
          title: '上传图片1',
          props: {
            // action 会被 Parser 修改为 '/api/upload'
            // onError 会被 Parser 修改为统一处理函数
          }
        },
        {
          type: 'upload',
          field: 'upload2',
          title: '上传图片2',
          props: {
            action: '/custom-upload',  // 这个会被 Parser 覆盖为 '/api/upload'
            onError: function (r) {
              console.log('自定义错误处理');  // 这个会被 Parser 覆盖
            }
          }
        }
      ]
    }
  }
}
</script>

数据结构

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

interface ParserConfig {
    // 是否合并内置解析规则, 内置组件请保持 true
    merge?: true;
    // 初始化组件规则
    init?: (ctx: ParserContext) => void;
}

interface ParserContext {
    // 当前组件的规则配置
    rule: Rule;
    // 表单 API 实例
    $api: Api;
}

merge 参数说明

内置组件（如 input、select 等）在添加解析器时，请配置 merge: true，以免覆盖系统内置的解析逻辑。
自定义扩展组件若无默认解析逻辑，可以省略该参数。

Parser vs options.global

Parser：直接修改规则本身，执行时机最早，适合需要强制统一规则的场景
options.global：通过合并方式应用配置，执行时机在 Parser 之后，适合需要灵活配置的场景

如果需要在 Parser 之后再次覆盖配置，可以使用 options.global.deep。

渲染时替换配置

在表单渲染时，通过全局配置中的 global 配置项，可以实现对组件的公共配置。此功能允许您为所有组件设置统一的默认值和行为，从而简化配置和维护工作。

基本用法

vue

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

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        global: {
          // 全局配置：所有组件都应用
          '*': {
            props: {
              disabled: true
            }
          },
          // 特定组件配置：只对 upload 组件生效
          upload: {
            props: {
              onError: function (r) {
                alert('上传失败');
              }
            }
          }
        }
      },
      rule: [
        // 表单规则
      ]
    }
  }
}
</script>

配置规则

global 配置支持以下规则：

'*'：通配符，表示所有组件都会应用此配置
组件类型名：如 input、select、upload 等，只对指定类型的组件生效
配置优先级：组件类型配置会覆盖通配符配置，组件规则中的配置会覆盖全局配置

配置合并方式

global 配置支持两种合并方式：

1. 普通配置（默认合并）：

当规则中已存在相同属性时，全局配置不会覆盖规则中的配置，只在规则中没有该属性时才会生效。

global: {
  upload: {
    props: {
      action: '/api/upload',  // 默认上传地址
      onError: function (r) {
        alert('上传失败');
      }
    }
  }
}

2. 深度合并配置（强制覆盖）：

使用 deep 属性，通过点号路径指定要强制覆盖的属性，会强制覆盖规则中的同名属性。

global: {
  upload: {
    deep: {
      'props.action': '/api/upload',  // 强制覆盖规则中的 action
      'props.onError': function (r) {
        alert('上传失败');
      },
      'props.onSuccess': function (file, res) {
        file.url = file.response.url;
      }
    }
  }
}

重要提示

执行顺序：Parser（全局替换配置） → options.global（普通配置） → options.global.deep（深度合并）

普通配置：只在规则中没有对应属性时生效，不会覆盖规则中已存在的属性
深度合并配置：使用 deep 对象，通过点号路径（如 'props.onError'）指定要覆盖的属性，会强制覆盖规则中的同名属性，即使规则中已经定义了该属性

使用示例

1. 设置所有组件的默认禁用状态和 col 布局：

vue

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

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        global: {
          '*': {
            props: {
              disabled: true  // 所有组件默认禁用
            },
            col: {
              span: 12  // 所有组件默认占 12 列（一半宽度）
            }
          }
        }
      },
      rule: [
        {
          type: 'input',
          field: 'input1',
          title: 'input1'
          // 会自动应用 disabled: true 和 col: { span: 12 }
        },
        {
          type: 'input',
          field: 'input2',
          title: 'input2'
          // 会自动应用 disabled: true 和 col: { span: 12 }
        },
        {
          type: 'input',
          field: 'input3',
          title: 'input3',
          col: {
            span: 24  // 覆盖全局配置，占满整行
          }
        }
      ]
    }
  }
}
</script>

2. 设置 upload 组件的上传回调事件（普通配置）：

配置 upload 组件的全局回调事件，使用普通配置方式。这种方式只在规则中没有定义对应回调时才会生效。

vue

<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
            }
          },
          // 普通配置：只在规则中没有对应属性时才会生效
          upload: {
            props: {
              action: '/api/upload',  // 默认上传地址
              onError: function (r) {
                alert('上传失败');
              },
              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: '上传图片',
          value: '',
          col: {
            span: 24
          },
          props: {
            listType: 'picture-card'
            // 如果规则中没有定义 action，会自动应用全局配置的 action: '/api/upload'
            // 如果规则中没有定义 onError，会自动应用全局配置的 onError
            // 如果规则中定义了 onError，则使用规则中的 onError
          }
        },
        {
          type: 'upload',
          field: 'upload2',
          title: '上传文件',
          props: {
            action: '/',
            onError: function (r) {
              console.log('自定义错误处理');  // 这个会覆盖全局配置
            }
            // 因为规则中定义了 onError，全局配置的 onError 不会生效
          }
        }
      ]
    }
  }
}
</script>

3. 强制覆盖规则中的配置（深度合并）：

使用 deep 属性，通过点号路径指定要强制覆盖的属性，可以强制覆盖规则中的同名属性，即使规则中已经定义了该属性。

vue

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

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        global: {
          upload: {
            // 深度合并配置：使用点号路径指定要覆盖的属性
            deep: {
              'props.action': '/api/upload',  // 强制覆盖规则中的 action
              'props.onError': function (r) {
                alert('统一的上传失败处理');
              },
              'props.onSuccess': function (file, res) {
                file.url = file.response.url;
              }
            }
          }
        }
      },
      rule: [
        {
          type: 'upload',
          field: 'upload1',
          title: '上传图片1',
          props: {
            action: '/old-upload',  // 这个会被全局配置覆盖为 '/api/upload'
            onError: function (r) {
              console.log('规则中的错误处理');  // 这个会被全局配置覆盖
            }
            // 即使规则中定义了 action 和 onError，也会被全局配置覆盖
          }
        },
        {
          type: 'upload',
          field: 'upload2',
          title: '上传图片2',
          props: {
            // 没有定义 action 和 onError，会使用全局配置的 action 和 onError
          }
        }
      ]
    }
  }
}
</script>

4. 为不同组件类型设置不同的默认配置：

vue

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

<script>
export default {
  data() {
    return {
      fApi: {},
      options: {
        global: {
          // 所有组件的公共配置
          '*': {
            col: {
              span: 12
            }
          },
          // input 组件的特定配置
          input: {
            props: {
              clearable: true,
              placeholder: '请输入'
            }
          },
          // select 组件的特定配置
          select: {
            props: {
              clearable: true,
              placeholder: '请选择'
            }
          },
          // textarea 组件的特定配置
          textarea: {
            props: {
              rows: 4,
              placeholder: '请输入内容'
            }
          }
        }
      },
      rule: [
        {
          type: 'input',
          field: 'name',
          title: '姓名'
          // 会自动应用 clearable: true 和 placeholder: '请输入'
        },
        {
          type: 'select',
          field: 'category',
          title: '分类'
          // 会自动应用 clearable: true 和 placeholder: '请选择'
        },
        {
          type: 'textarea',
          field: 'description',
          title: '描述'
          // 会自动应用 rows: 4 和 placeholder: '请输入内容'
        }
      ]
    }
  }
}
</script>

三种配置方式的区别

配置方式	应用场景	生效时机	影响范围	执行顺序
formCreate.parser	全局处理	规则解析时	直接修改规则本身	最先执行
option.global	渲染环境	表单渲染时	通过合并方式应用配置	Parser 之后
updateDefaultRule	设计器环境	组件拖入设计器时	仅影响新拖入的组件	设计器专用

使用建议

Parser 配置：适用于需要强制统一规则、直接修改规则本身的场景，执行时机最早
渲染时配置（option.global）：适用于在运行时统一组件的显示和行为，实现业务逻辑的统一管理
设计器配置（updateDefaultRule）：适用于在设计阶段统一组件的初始状态，提高设计效率

执行顺序：Parser → option.global（普通配置） → option.global.deep（深度合并）

Element UI版本

Ant Design Vue版本

设置组件默认配置

设计器配置

数据结构

修改输入框组件的默认规则

设置选择框的默认选项

设置文本域的行数

全局替换配置

基本用法

使用示例

数据结构

渲染时替换配置

基本用法

配置规则

配置合并方式

使用示例

三种配置方式的区别

设置组件默认配置 ​

设计器配置 ​

数据结构 ​

修改输入框组件的默认规则 ​

设置选择框的默认选项 ​

设置文本域的行数 ​

全局替换配置 ​

基本用法 ​

使用示例 ​

数据结构 ​

渲染时替换配置 ​

基本用法 ​

配置规则 ​

配置合并方式 ​

使用示例 ​

三种配置方式的区别 ​

设置组件默认配置

设计器配置

数据结构

修改输入框组件的默认规则

设置选择框的默认选项

设置文本域的行数

全局替换配置

基本用法

使用示例

数据结构

渲染时替换配置

基本用法

配置规则

配置合并方式

使用示例

三种配置方式的区别