UseElConfigProvider - 全局配置

组件介绍

UseElConfigProvider 是基于 Element Plus 的el-config-provider二次封装的全局配置组件，旨在为中后台系统提供统一、可配置、易维护的全局组件配置能力，覆盖语言、主题、字典、表格、上传等多维度的全局配置管理，从底层解决多组件配置不一致、重复开发、逻辑分散等问题。

核心亮点

一站式全局配置，多组件联动生效：组件聚合了语言、主题、字典、表格、上传等多维度配置项，且配置可同时作用于 UseElForm、UseElTable、UseCrudTable、UseElUpload 等多个业务组件，无需在每个组件中单独配置，实现 “一处配置，全局生效”。
配置项默认值合理化，降低开发门槛：针对所有配置项设置了符合中后台开发习惯的默认值（如默认中文语言、light 主题、标准字典键值映射等），开发者无需从零配置，仅需在特殊场景下覆盖默认值，大幅降低上手成本。
配置与业务解耦，可复用性强：所有配置项通过 TypeScript 接口严格定义，结构清晰且类型安全，配置对象可抽离为单独文件，在不同项目 / 页面间复用，同时支持动态修改配置，适配不同业务场景的灵活切换。
类型安全加持，减少运行时错误：基于 TypeScript 定义完整的 Props 和子配置接口（如 UploadConfig、DictProps 等），开发阶段即可校验配置项的类型和字段合法性，避免因配置错误导致的运行时问题，提升代码健壮性。

解决痛点

多组件字典配置不统一，解析逻辑重复

痛点：UseElForm、UseElTable 等组件使用字典数据时，每个组件需单独配置字典映射规则（dictMap）、字典属性（dictProps），且字典数据格式转换（如是否转字符串）需重复编写逻辑，不同组件解析规则不一致易导致数据展示异常。
解决方案：通过 UseElConfigProvider 全局配置 dictMap、dictProps、dictDataToString 等字典相关参数，配置同时作用于 UseElForm 和 UseElTable 组件，统一字典解析规则；其中 dictDataToString 针对性解决表格字典数据格式问题，无需在表格组件中重复处理数据类型，确保字典数据解析逻辑全局统一。

表格相关配置分散，跨组件适配成本高

痛点：UseElTable、UseCrudTable 等表格类组件的底部额外高度（如适配分页、操作栏）需在每个表格页面单独配置，不同表格组件的高度适配逻辑不统一，易出现表格滚动异常、布局错位等问题。
解决方案：通过全局配置 tableExtraHeight 统一设置表格底部额外高度，配置同时作用于 UseElTable 和 UseCrudTable 组件，无需在每个表格页面单独调整高度，从全局层面保证表格布局一致性，减少布局适配的重复工作。

上传组件配置碎片化，请求规则不统一

痛点：UseElUpload 上传组件的上传地址、请求头、额外参数等配置需在每个上传场景单独编写，不同页面的上传请求规则（如请求头格式、参数传递方式）不一致，易出现上传失败、权限异常等问题，且配置代码重复率高。
解决方案：通过全局 uploadConfig 配置项统一定义上传的 action、headers、data 等核心参数，所有 UseElUpload 组件默认继承该全局配置，特殊场景仅需局部覆盖，既保证上传请求规则的统一性，又减少 90% 以上的上传配置重复代码。

多语言 / 主题配置分散，全局切换成本高

痛点：原生 el-config-provider 的语言、主题配置需在每个页面单独引入 locale 包、编写切换逻辑，多页面切换语言 / 主题时状态不互通，且不同开发者引入的语言包版本、主题切换方式不一致，导致全局样式 / 语言混乱。
解决方案：组件内置 zh-cn/en 语言包，通过 language 配置一键切换 Element Plus 组件语言；themeMode 配置统一管理全局主题模式，同时通过 Vue 的 provide 机制将配置全局注入，所有子组件可统一读取配置状态，语言 / 主题切换逻辑全局统一，无需在每个页面重复引入语言包或编写切换逻辑。

跨组件配置无统一入口，维护成本高

痛点：语言、主题、字典、表格、上传等配置分散在各个业务组件中，后期需调整全局规则时（如统一修改字典的 label/value 字段、调整表格默认高度），需逐个修改所有相关组件，维护效率低且易遗漏。
解决方案：UseElConfigProvider 作为全局配置的唯一入口，所有跨组件的通用配置均集中在此管理，后期调整全局规则时仅需修改该组件的配置项（或默认值），即可同步生效到所有关联组件，维护成本降低 80% 以上。

使用案例

重要说明：

您若正在使用iVue组件库，建议直接在项目App.vue中使用该组件，统一、优雅解决ElementPlus和iVue组件库全局配置;

切换语言（国际化）仅支持ElementPlus组件的语言切换，不支持业务代码的语言切换，且仅支持中文(zh)/英文(en)语言切换；

切换主题根据当前项目的主题配置进行动态切换，仅支持深色(dark)/浅色(light)主题切换；

所有全局配置项均遵循【局部配置>全局配置】原则;

一般情况下我们建议开启dictDataToString为true的全局配置（默认开启），此处为了演示我们特意将dictDataToString设置为false。

Types

import type { DictMap, DictProps } from '@/types/dict'

/**
 * 上传配置接口
 */
export interface UploadConfig {
  /**
   * 上传地址
   */
  action?: string
  /**
   * 请求头
   */
  headers?: Record<string, unknown>
  /**
   * 上传数据
   */
  data?: Record<string, unknown>
  /**
   * 其他配置项
   */
  [key: string]: any
}

/**
 * props接口
 */
export interface Props {
  /**
   * 语言 默认zh，仅对ElementPlus组件有效
   */
  language?: '' | 'zh' | 'en'
  /**
   * 主题模式 默认light
   */
  themeMode?: '' | 'light' | 'dark'
  /**
   * 字典映射 此处配置同时作用于UseElForm和UseElTable组件
   */
  dictMap?: DictMap
  /**
   * 字典属性 此处配置同时作用于UseElForm和UseElTable组件
   */
  dictProps?: DictProps
  /**
   * 字典数据是否转换为字符串 此处配置仅作用于UseElTable组件的dictMap和tableData的dict数据
   */
  dictDataToString?: boolean
  /**
   * 表格底部额外高度 此处配置同时作用于UseElTable和UseCrudTable组件
   */
  tableExtraHeight?: number
  /**
   * 上传配置 此处配置仅作用于UseElUpload组件
   */
  uploadConfig?: UploadConfig
}

Props

const props = withDefaults(defineProps<Props>(), {
  language: 'zh',
  themeMode: 'light',
  dictMap: () => ({}),
  dictProps: () => ({ value: 'value', label: 'label' }),
  dictDataToString: true,
  tableExtraHeight: 20,
  uploadConfig: () => ({})
} satisfies DefaultsType<Props>)

UseElConfigProvider - 全局配置 ​

组件介绍 ​

核心亮点 ​

解决痛点 ​

使用案例 ​

Types ​

Props ​

UseElConfigProvider - 全局配置

组件介绍

核心亮点

解决痛点

使用案例

Types

Props