ConfigProvider 全局配置
在应用根部附近放一个 ConfigProvider,统一设置它下面所有 Pika 组件共用的东西:浅色或深色模式、主题覆盖、内置文案的语言、组件默认属性,以及浮层挂载到哪里。某一部分页面要不一样(比如深色的侧边栏),就在那里再嵌套一个。不放 ConfigProvider 时组件也能工作,用的是默认值。
ConfigProvider 为它下面的所有 Pika 组件提供配置:主题模式、主题覆盖、语言、组件默认值、类名前缀,以及浮层挂载到哪里。每个字段都会合并到最近的上层 Provider 之上,所以 Provider 可以嵌套。
#演示
#嵌套的主题作用域
Pika 有浅色和深色两种模式。默认是浅色,没有任何 Provider 设置模式时也是浅色。设置了 themeMode 或 themeOverrides 的 Provider 会开一个主题作用域:在自己的元素上写入 data-p-theme-mode="light" 或 "dark",下面的 token 跟随这个模式。作用域可以嵌套:这里浅色作用域里嵌了一个深色作用域。
#主题覆盖
themeOverrides 把 CSS 变量写到 Provider 的元素上。从被覆盖的基础 token 推导出来的 token 会跟着变。
#切换语言
locale 设置 Provider 下面所有组件的界面文案。在 zhCN 和 enUS 之间切换:加载中的按钮和 Spinner 会用所选语言向读屏软件播报状态。语言包里缺的字段回落到 enUS。
- Button loading label
- Spinner label
#Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
abstract | boolean | false | 不渲染元素,只提供上下文。设置了 themeMode 或 themeOverrides 时会被忽略并给出警告。 | 未发布 |
bordered | boolean | undefined | 支持 bordered 的组件的默认值。 | 未发布 |
clsPrefix | string | "p" | 类名前缀。发布的 CSS 用的是 p,换前缀还需要用新前缀构建 CSS。 | 未发布 |
componentOptions | Record<string, Record<string, unknown>> | null | undefined | 每个组件的默认 props,按组件合并到上层之上。null 表示不再继承。 | 未发布 |
highlighter | CodeHighlighter | undefined | 给 Code 用的 Shiki 高亮器,需加载 codeTheme。Pika 不打包 Shiki,见 Code。undefined 继承上层。 | 未发布 |
katex | EquationRenderer | undefined | 给 Equation 用的 KaTeX(import katex from "katex")。Pika 不打包 KaTeX,见 Equation。undefined 继承上层。 | 未发布 |
locale | PLocale | null | undefined | 界面文案。undefined 继承上层;null 重置为 enUS。 | 未发布 |
namespace | string | undefined | 加到浮层挂载容器上的类名。 | 未发布 |
portalContainer | HTMLElement | null | document.body | 浮层挂载到哪里。 | 未发布 |
themeMode | "light" | "dark" | undefined | 浅色或深色。undefined 继承上层;任何地方都没设置时为 "light"。 | 未发布 |
themeOverrides | Record<"--p-…", string> | null | undefined | 写到 Provider 元素上的 CSS 变量,合并到上层之上。null 表示不再继承。 | 未发布 |
#已移除:theme
theme 属性、ThemeName 类型和 Brutal 主题已经移除。这是破坏性变更:从 Provider 上删掉 theme="…",只用 themeMode。data-p-theme 属性也不再存在,作用域样式请改用 [data-p-theme-mode]。
#语言
包里自带 enUS 和 zhCN。createLocale(partial, fallback) 用一份完整的语言包把不完整的语言包按命名空间补齐。
import { ConfigProvider, createLocale, enUS, zhCN } from "@pika-lab/react";
const enGB = createLocale({ name: "en-GB", global: { cancel: "Dismiss" } }, enUS);
<ConfigProvider locale={zhCN}>…</ConfigProvider>;