跳到正文

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。

Props

名称类型默认值说明版本
abstractbooleanfalse不渲染元素,只提供上下文。设置了 themeMode 或 themeOverrides 时会被忽略并给出警告。未发布
borderedbooleanundefined支持 bordered 的组件的默认值。未发布
clsPrefixstring"p"类名前缀。发布的 CSS 用的是 p,换前缀还需要用新前缀构建 CSS。未发布
componentOptionsRecord<string, Record<string, unknown>> | nullundefined每个组件的默认 props,按组件合并到上层之上。null 表示不再继承。未发布
highlighterCodeHighlighterundefined给 Code 用的 Shiki 高亮器,需加载 codeTheme。Pika 不打包 Shiki,见 Code。undefined 继承上层。未发布
katexEquationRendererundefined给 Equation 用的 KaTeX(import katex from "katex")。Pika 不打包 KaTeX,见 Equation。undefined 继承上层。未发布
localePLocale | nullundefined界面文案。undefined 继承上层;null 重置为 enUS。未发布
namespacestringundefined加到浮层挂载容器上的类名。未发布
portalContainerHTMLElement | nulldocument.body浮层挂载到哪里。未发布
themeMode"light" | "dark"undefined浅色或深色。undefined 继承上层;任何地方都没设置时为 "light"。未发布
themeOverridesRecord<"--p-…", string> | nullundefined写到 Provider 元素上的 CSS 变量,合并到上层之上。null 表示不再继承。未发布

已移除:theme

theme 属性、ThemeName 类型和 Brutal 主题已经移除。这是破坏性变更:从 Provider 上删掉 theme="…",只用 themeMode。data-p-theme 属性也不再存在,作用域样式请改用 [data-p-theme-mode]。

语言

包里自带 enUS 和 zhCN。createLocale(partial, fallback) 用一份完整的语言包把不完整的语言包按命名空间补齐。

tsx
import { ConfigProvider, createLocale, enUS, zhCN } from "@pika-lab/react"; const enGB = createLocale({ name: "en-GB", global: { cancel: "Dismiss" } }, enUS); <ConfigProvider locale={zhCN}>…</ConfigProvider>;