--- group: title: 进阶使用 order: 1 order: 0 title: 定制主题 tag: Updated --- Ant Design 设计规范和技术上支持灵活的样式定制,以满足业务和品牌上多样化的视觉需求,包括但不限于全局样式(主色、圆角、边框)和指定组件的视觉定制。 在 5.0 版本的 Ant Design 中,我们提供了一套全新的定制主题方案。不同于 4.x 版本的 less 和 CSS 变量,有了 CSS-in-JS 的加持后,动态主题的能力也得到了加强,包括但不限于: 1. 支持动态切换主题; 2. 支持同时存在多个主题; 3. 支持针对某个/某些组件修改主题变量; 4. ... ## 配置主题 在 5.0 版本中我们把影响主题的最小元素称为 **Design Token**。通过修改 Design Token,我们可以呈现出各种各样的主题或者组件。通过在 `ConfigProvider` 中传入 `theme` 属性,可以配置主题。在升级 v5 后,将默认使用 v5 的主题. :::warning `ConfigProvider` 对 `message.xxx`、`Modal.xxx`、`notification.xxx` 等静态方法不会生效,原因是在这些方法中,antd 会通过 `ReactDOM.render` 动态创建新的 React 实体。其 context 与当前代码所在 context 并不相同,因而无法获取 context 信息。 当你需要 context 信息(例如 ConfigProvider 配置的内容)时,可以通过 `Modal.useModal` 方法返回 modal 实体以及 contextHolder 节点,将其插入到你需要获取 context 位置即可。也可通过 [App 包裹组件](/components/app-cn) 简化 useModal 等方法需要手动植入 contextHolder 的问题。 ::: ### 修改主题变量 通过 `theme` 中的 `token` 属性,可以修改一些主题变量。部分主题变量会引起其他主题变量的变化,我们把这些主题变量成为 Seed Token。 ```sandpack const sandpackConfig = { autorun: true, }; import { Button, ConfigProvider, Space } from 'antd'; import React from 'react'; const App: React.FC = () => ( ); export default App; ``` ### 使用预设算法 通过修改算法可以快速生成风格迥异的主题,5.0 版本中默认提供三套预设算法,分别是: - 默认算法 `theme.defaultAlgorithm` - 暗色算法 `theme.darkAlgorithm` - 紧凑算法 `theme.compactAlgorithm` 你可以通过 `theme` 中的 `algorithm` 属性来切换算法,并且支持配置多种算法,将会依次生效。 ```sandpack const sandpackConfig = { dark: true, }; import React from 'react'; import { Button, ConfigProvider, Input, Space, theme } from 'antd'; const App: React.FC = () => ( ); export default App; ``` ### 修改组件变量 除了整体的 Design Token,各个组件也会开放自己的 Component Token 来实现针对组件的样式定制能力,不同的组件之间不会相互影响。同样地,也可以通过这种方式来覆盖组件的其他 Design Token。 :::info{title=组件级别的主题算法} 默认情况下,所有组件变量都仅仅是覆盖,不会基于 Seed Token 计算派生变量。 在 `>= 5.8.0` 版本中,组件变量支持传入 `algorithm` 属性,可以开启派生计算或者传入其他算法。 ::: ```sandpack import React from 'react'; import { ConfigProvider, Button, Space, Input, Divider } from 'antd'; const App: React.FC = () => ( <>
开启算法:
禁用算法:
); export default App; ``` ### 禁用动画 antd 默认内置了一些组件交互动效让企业级页面更加富有细节,在一些极端场景可能会影响页面交互性能,如需关闭动画可以 `token` 中的 `motion` 修改为 `false`: ```sandpack import React from 'react'; import { Switch, ConfigProvider, Space, Checkbox, Radio, Row, Col } from 'antd'; export default () => { const [checked, setChecked] = React.useState(false); React.useEffect(() => { const id = setInterval(() => { setChecked((prev) => !prev); }, 1000); return () => { clearInterval(id); }; }, []); const nodes = ( Checkbox Radio ); return ( {nodes} {nodes} ); }; ``` ## 进阶使用 ### 动态切换 在 v5 中,动态切换主题对用户来说是非常简单的,你可以在任何时候通过 `ConfigProvider` 的 `theme` 属性来动态切换主题,而不需要任何额外配置。 ```sandpack import { Button, ConfigProvider, Space, Input, ColorPicker, Divider } from 'antd'; import React from 'react'; const App: React.FC = () => { const [primary, setPrimary] = React.useState('#1677ff'); return ( <> setPrimary(color.toHexString())} /> ); } export default App; ``` ### 局部主题(嵌套主题) 可以嵌套使用 `ConfigProvider` 来实现局部主题的更换。在子主题中未被改变的 Design Token 将会继承父主题。 ```sandpack import React from 'react'; import { Button, ConfigProvider, Space } from 'antd'; const App: React.FC = () => ( ); export default App; ``` ### 使用 Design Token 如果你希望使用当前主题下的 Design Token,我们提供了 `useToken` 这个 hook 来获取 Design Token。 ```sandpack import React from 'react'; import { Button, theme } from 'antd'; const { useToken } = theme; const App: React.FC = () => { const { token } = useToken(); return (
使用 Design Token
); }; export default App; ``` ### 静态消费(如 less) 当你需要非 React 生命周期消费 Token 变量时,可以通过静态方法 `getDesignToken` 将其导出: ```jsx import { theme } from 'antd'; const { getDesignToken } = theme; const globalToken = getDesignToken(); ``` `getDesignToken` 和 ConfigProvider 一样,支持传入 `theme` 属性,用于获取指定主题的 Design Token。 ```tsx import { createRoot } from 'react-dom/client'; import type { ThemeConfig } from 'antd'; import { theme } from 'antd'; const { getDesignToken, useToken } = theme; const config: ThemeConfig = { token: { colorPrimary: '#1890ff', }, }; // 通过静态方法获取 const globalToken = getDesignToken(config); // 通过 hook 获取 const App = () => { const { token } = useToken(); return null; }; // 渲染示意 createRoot(document.getElementById('#app')).render( , ); ``` 如果需要将其应用到静态样式编译框架,如 less 可以通过 less-loader 注入: ```jsx { loader: "less-loader", options: { lessOptions: { modifyVars: mapToken, }, }, } ``` 兼容包提供了变量转换方法用于转成 v4 的 less 变量,如需使用[点击此处](/docs/react/migration-v5)查看详情。 ### 调试主题 我们提供了帮助用户调试主题的工具:[主题编辑器](/theme-editor-cn) 你可以使用此工具自由地修改 Design Token,以达到您对主题的期望。 ## 基本概念 在 Design Token 中我们提供了一套更加贴合设计的三层结构,将 Design Token 拆解为 Seed Token、Map Token 和 Alias Token 三部分。这三组 Token 并不是简单的分组,而是一个三层的派生关系,由 Seed Token 派生 Map Token,再由 Map Token 派生 Alias Token。在大部分情况下,使用 Seed Token 就可以满足定制主题的需要。但如果您需要更高程度的主题定制,您需要了解 antd 中 Design Token 的生命周期。 ### 演变过程 ![token](https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*uF3kTrY4InUAAAAAAAAAAAAAARQnAQ) ### 基础变量(Seed Token) Seed Token 意味着所有设计意图的起源。比如我们可以通过改变 `colorPrimary` 来改变主题色,antd 内部的算法会自动的根据 Seed Token 计算出对应的一系列颜色并应用: ```tsx const theme = { token: { colorPrimary: '#1890ff', }, }; ``` ### 梯度变量(Map Token) Map Token 是基于 Seed 派生的梯度变量。定制 Map Token 推荐通过 `theme.algorithm` 来实现,这样可以保证 Map Token 之间的梯度关系。也可以通过 `theme.token` 覆盖,用于单独修改一些 map token 的值。 ```tsx const theme = { token: { colorPrimaryBg: '#e6f7ff', }, }; ``` ### 别名变量(Alias Token) Alias Token 用于批量控制某些共性组件的样式,基本上是 Map Token 别名,或者特殊处理过的 Map Token。 ```tsx const theme = { token: { colorLink: '#1890ff', }, }; ``` ### 基本算法(algorithm) 基本算法用于将 Seed Token 展开为 Map Token,比如由一个基本色算出一个梯度色板,或者由一个基本的圆角算出各种大小的圆角。算法可以单独使用,也可以任意地组合使用,比如可以将暗色算法和紧凑算法组合使用,得到一个暗色和紧凑相结合的主题。 ```tsx import { theme } from 'antd'; const { darkAlgorithm, compactAlgorithm } = theme; const theme = { algorithm: [darkAlgorithm, compactAlgorithm], }; ``` ## API ### Theme | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | token | 用于修改 Design Token | `AliasToken` | - | | inherit | 继承上层 ConfigProvider 中配置的主题。 | boolean | true | | algorithm | 用于修改 Seed Token 到 Map Token 的算法 | `(token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]` | `defaultAlgorithm` | | components | 用于修改各个组件的 Component Token 以及覆盖该组件消费的 Alias Token | `ComponentsConfig` | - | ### ComponentsConfig | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `Component` (可以是任意 antd 组件名,如 `Button`) | 用于修改 Component Token 以及覆盖该组件消费的 Alias Token | `ComponentToken & AliasToken & { algorithm: boolean \| (token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]}` | - | > 组件级别的 `algorithm` 默认为 `false`,此时组件 Token 仅仅会覆盖该组件使用的 token,不会进行派生计算。设置为 `true` 时会继承当前全局算法;也可以和全局的 `algorithm` 一样传入一个或多个算法,这将会针对该组件覆盖全局的算法。 ### SeedToken ### MapToken > 继承所有 SeedToken 的属性 ### AliasToken > 继承所有 SeedToken 和 MapToken 的属性 ## FAQ ### 为什么 `theme` 从 `undefined` 变为对象或者变为 `undefined` 时组件重新 mount 了? 在 ConfigProvider 中我们通过 `DesignTokenContext` 传递 context,`theme` 为 `undefined` 时不会套一层 Provider,所以从无到有或者从有到无时 React 的 VirtualDOM 结构变化,导致组件重新 mount。解决方法:将 `undefined` 替换为空对象 `{}` 即可。