ConfigProvider 全局配置
import { DEFAULT_CONFIG_CONTEXT, DefaultRenderEmpty } from '@apollo-design/ui';为应用或特性子树提供当前主题、语言、尺寸、禁用、方向和组件默认配置。
代码演示
前缀 #
默认类名前缀是 apollo，发布 CSS 仅包含该前缀。设置自定义前缀会更新 DOM 名称；样式需要构建期生成。
本示例的 prefix-cls.css 预先由 genComponentCss('empty', 'brand') 生成，作为静态文件引入。运行时只切换类名，不生成样式表。图标前缀独立由 iconPrefixCls 控制。
语言包 #
locale 的替换、深更新和撤回保留业务节点。示例在 Empty 与 Pagination 上显示当前语言，同时保留输入草稿。
useLocale(name) 返回两个 ComputedRef，脚本用 .value。没有 Provider 时语言码为 undefined；分片浅合并，缺失字段回退 en_US。global.clear 在 en_US / zh_CN 有 Apollo 文案，其它语言沿用默认回退。
组件级配置 #
精确别名 empty / divider / spin / form 与 components map 共用当前配置链。map 的键和字段以各组件支持的配置为准，不等于自动应用全部组件 props。
嵌套时不同组件名继承，同名配置整体替换；直接别名优先于同名 map 项，组件自身显式 props 最优先。示例同时展示 Empty / Divider 的语义样式与 components.button.shape。
尺寸与全局禁用 #
componentSize 与 componentDisabled 是两条独立的 context（与 antd 同），
下游用 useSize() / useDisabled() / useConfig() 读取。
两条判据不同，不能统一（这是最容易写错的地方）：
| 开关 | 判据 | 为什么 |
|---|---|---|
componentSize |
componentSize || 父级 |
未设置就继承 |
componentDisabled |
componentDisabled ?? 父级 |
false 必须能显式关闭父级的 true |
⚠️ 返回值是 ComputedRef（要 .value），不是 antd 那样的裸值 ——
裸值在 Vue 里等于把配置在 setup 期定死（差异 D27）。
主题 #
theme 支持 token、algorithm（单个或数组）、components、cssVarPrefix 和 inherit。示例使用显式 section 宿主，让完整内容与 Alias 变量在 SSR 同树；原生宿主 attrs/style 按原生规则合并。
默认无宿主时客户端向实际原生根投射变量，SSR 直接原生槽根可序列化；opaque 组件或纯文本需要显式宿主才能获得完整服务端 CSS 作用域。算法切换与 useTheme().config 可写 Ref 保留业务草稿，外部主题变更会恢复外部配置。组件令牌由各组件消费者落地，不在运行时生成 CSS 选择器。
布局方向 #
通过 direction 切换整棵子树的 LTR / RTL 排列方向，输入框、按钮与间距会同步响应。
组件尺寸 #
使用 componentSize 统一设置子树内 Input、Button 等组件的尺寸，下拉框可实时切换 small / middle / large。
读取配置 #
在 ConfigProvider 内部调用 useConfig() 读取 componentSize 与 componentDisabled，并用外部下拉框和开关实时验证上下文同步。
见 demo/：前缀、语言、组件配置、尺寸与禁用、主题、动态尺寸、方向和 useConfig，共 8 个示例。
API
Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| scopeTag | 可选的原生作用域宿主；省略时不增加包装节点。选择符合 HTML / SVG 内容模型的标签 | ConfigProviderScopeTag |
— |
| prefixCls | 组件 DOM 类名前缀；自定义前缀需配套静态 CSS | string |
'apollo' |
| iconPrefixCls | 图标前缀，独立于组件前缀 | string |
'apollo-icon' |
| getPopupContainer | 浮层容器；函数随配置更新读取 | (trigger?: HTMLElement) => HTMLElement | ShadowRoot |
— |
| getTargetContainer | Affix / Anchor 等滚动感知组件的目标解析器 | () => HTMLElement | Window |
— |
| renderEmpty | 空状态内容工厂；返回 null、undefined、false 或空字符串可有意留空 |
RenderEmptyHandler，返回 VNodeChild |
各消费者的默认空状态 |
| locale | 当前语言包；替换、深更新及撤回不会重挂业务内容 | Locale |
继承，分片缺失时回退英文 |
| componentSize | 控件默认尺寸；组件自己的 size 优先 |
'small' | 'medium' | 'middle' | 'large' |
继承 |
| componentDisabled | 默认禁用；子级或组件显式 false 可覆盖父级 true |
boolean |
false |
| direction | 布局方向 | 'ltr' | 'rtl' |
继承 |
| virtual | 支持虚拟滚动的消费者的默认开关 | boolean |
true |
| variant | 输入、选择和表单控件的默认形态 | 'outlined' | 'borderless' | 'filled' | 'underlined' |
继承 |
| popupMatchSelectWidth | Select / TreeSelect / Cascader 等的浮层宽度默认值；局部配置优先 | boolean |
消费者默认值 |
| theme | 主题预设、明暗模式、用户/组件令牌、算法及 CSS 变量前缀 | ConfigProviderThemeConfig |
继承 |
| warning | 开发告警行为；strict: false 聚合弃用告警 |
{ strict?: boolean } |
{} |
| components | 按各组件契约声明的默认配置，以消费者名称为键；不会自动应用任意组件 prop | Record<string, ComponentConfigLike> |
— |
| divider | Divider 的精确配置别名 | DividerConfig |
— |
| empty | Empty 的精确配置别名 | EmptyConfig |
— |
| spin | Spin 的精确配置别名 | SpinConfig |
— |
| form | 已接入 Form 的默认配置，含校验消息、必填标记、冒号、标签及语义样式等 | FormConfig |
— |
继承与内容
本层 undefined 回落到父级；撤回先前设置的值也会回落。components 按组件名合并，同名组件配置整体替换；divider / empty / spin / form 精确别名覆盖同名 map 项，组件自己的显式 prop 最优先。
theme.token 按键合并，theme.components 按组件名和令牌键合并；inherit: false 重置父级令牌和组件令牌，保留外层 CSS 变量前缀。表单校验消息按默认数据、父 FormProvider、本地语言和当前有效 form 配置合并；components.form.validateMessages 与 form.validateMessages 共用同一通道。
theme.preset 接受公开 ThemePreset 对象；内置预设分别从 @apollo-design/theme/presets/default、mono、material3 导入。mode 为 light/dark/system，与预设独立。预设基础配置及当前明暗配置先合并，用户 Seed 再进入算法，用户 Alias 和组件令牌保持最终优先。局部显式 algorithm 保留其原有完整链并替代继承 mode；局部 mode 替代继承 algorithm。此组件默认继承原始配置；基础包的 ThemeProvider 保留显式空主题重置，需 inherit:true 才继承。活跃 Provider 在 mounted 后跟随系统偏好并释放监听，SSR 的 system 默认亮色。完整变量由当前 Provider 投影，不必为 Mono 加载默认 tokens.css；UI 结构样式仍需引入。
默认插槽接收完整 Vue 内容，支持条件内容和多根。没有业务 emits、v-model 或 expose。默认无宿主时 Provider 的 class / style / id / 原生监听器等 attrs 不落到子节点；显式设置 scopeTag 时 attrs 落到该原生宿主，原生 style 优先于主题变量。scopeTag 是结构选择，改变标签遵循 Vue 原生根替换语义；切换 theme / locale 等配置不会改变内容的逻辑树。
主题、SSR 与样式
默认保持 renderless，主题变量在客户端投射到实际原生根，包括动态根和 Portal 内容；不会移动或重建业务节点。原生根自己的 CSS 变量声明优先，卸载或撤回时释放自己的写入并恢复原值。
SSR 会在直接原生槽根上序列化当前 Alias 变量。无法从外部自动给不透传 attrs 的 opaque 组件或纯文本建立服务端 CSS 作用域；需要完整首帧样式时，显式提供符合内容模型的宿主，例如 <ConfigProvider scope-tag="section" :theme="theme">。表格可用 <table><ConfigProvider scope-tag="tbody"><tr>…</tr></ConfigProvider></table>；默认无宿主也可以安全地位于既有 tbody、ul、select 或 SVG 内。水合时使用相同配置和内容。
静态 CSS 通过变量响应主题，不在运行时生成选择器。发布 CSS 默认只有 apollo 前缀；本页前缀 Demo 单独引入了构建期生成的 brand CSS。theme.cssVarPrefix 改变变量名，需要消费者样式使用相同名字。组件令牌由相应消费者写入和使用，不等于全库所有任意键均有视觉效果。
废弃属性
| 旧名 | 新名 |
|---|---|
| autoInsertSpaceInButton | components.button.autoInsertSpace |
| dropdownMatchSelectWidth | popupMatchSelectWidth |
静态方法与 composable
| 名称 | 说明 |
|---|---|
| ConfigProvider.ConfigContext | InjectionKey<ConfigContextValue>，可用于 inject；常规读取使用 useConfigContext() |
| ConfigProvider.config / setGlobalConfig | 模块级设置器，传 { prefixCls?, iconPrefixCls?, theme? }，返回 void；静态 Modal 等按其消费链读取，不能替代应用内响应式 props |
| ConfigProvider.useConfig / useConfig | 返回 componentDisabled、componentSize 两个 ComputedRef |
| useDirection / useThemeConfig | 当前方向 / 主题配置的 ComputedRef；无活跃主题源时后者为 undefined |
| useComponentConfig(name) | 当前组件配置的惰性视图，在 render / computed 中读取；setup 解构原始值会保存快照 |
@apollo-design/locale 的 useLocale(name) 统一返回 [ComputedRef<分片>, ComputedRef<语言码>]，脚本中读 .value，模板会解包。主题包 useTheme().config 是可深写的实例 Ref：赋值替换当前有效配置，深写不修改父级或 props；外部主题源变化时重新以外部配置为准。
当前开发版移除了没有消费者的 csp、wave、popupOverflow 和 theme.prefixCls，以及旧 useLocaleReactive 双通道；见集中迁移记录。
最近的显式 ThemeProvider 也属于当前主题来源，包括空配置 {} 的默认主题重置。嵌套 ConfigProvider 会在所属原生根投影该来源；没有显式来源时保留纯 CSS 变量继承。