logoAnt Design

⌘ K
  • 设计
  • 研发
  • 组件
  • 博客
  • 资源
  • 国内镜像
5.25.2
  • Ant Design of React
  • 更新日志
    v5.25.2
  • 如何使用
    • 快速上手
    • 在 Vite 中使用
    • 在 Next.js 中使用
      Updated
    • 在 Umi 中使用
    • 在 Rsbuild 中使用
    • 在 Farm 中使用
    • 使用 Refine
  • 进阶使用
    • 定制主题
    • 样式兼容
    • 服务端渲染
    • 使用 CSS 变量
      New
    • 使用自定义日期库
    • 国际化
    • 通用属性
    • React 19 兼容
      New
  • 迁移
    • 从 v4 到 v5
    • 从 Less 变量到 Design Token
  • 其他
    • 社区精选组件
    • 贡献指南
    • FAQ

使用 CSS 变量

相关资源

Ant Design X
Ant Design Charts
Ant Design Pro
Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Web3
Ant Design Landing-首页模板集
Scaffolds-脚手架市场
Umi-React 应用开发框架
dumi-组件/文档研发工具
qiankun-微前端框架
Ant Motion-设计动效
国内镜像站点 🇨🇳

社区

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design 语雀专栏
Ant Design 知乎专栏
体验科技专栏
seeconf logoSEE Conf-蚂蚁体验科技大会
加入我们

帮助

GitHub
更新日志
常见问题
报告 Bug
议题
讨论区
StackOverflow
SegmentFault

Ant XTech logo更多产品

yuque logo语雀-构建你的数字花园
AntV logoAntV-数据可视化解决方案
Egg logoEgg-企业级 Node.js 框架
Kitchen logoKitchen-Sketch 工具集
Galacean logoGalacean-互动图形解决方案
xtech logo蚂蚁体验科技
主题编辑器
Made with ❤ by
蚂蚁集团和 Ant Design 开源社区

从 5.12.0 起,Ant Design 5.x 重新支持了 CSS 变量。与 4.x 版本不同的是,这次我们融合了 CSS-in-JS 的能力,并且将所有 Design Token 纳入了 CSS 变量的管理范畴。

目前 CSS 变量模式已在 Ant Design 官网上全局开启。

何时使用

CSS 变量模式为 Ant Design 的样式能力带来了两个重要的提升:

  1. 同一组件在不同主题下的样式可以共享,减少了样式体积
  2. 切换主题时不再需要重新序列化样式,提升了主题切换的性能

因此如果你的应用依赖了 Ant Design 的主题能力,那么我们强烈建议你开启 CSS 变量模式。

快速上手

在 ConfigProvider 的 theme 属性中,通过 cssVar 配置来开启 CSS 变量模式。这个配置会被继承,所以希望全局开启 CSS 变量模式的话,只需要在根节点的 ConfigProvider 中配置即可。

WARNING

CSS 变量模式需要为每一个主题设置独特的 key 来保证样式隔离,在 React 18 中我们使用了 useId 来生成唯一的 key,所以在 React 18 中,你可以不用关心这个问题。但是在 React 17 或者 16 中,你需要手动为每一个主题设置一个唯一的 key,否则会导致主题混乱。

tsx
// React 18
<ConfigProvider theme={{ cssVar: true }}>
<App />
</ConfigProvider>
// React 17 or 16
<ConfigProvider theme={{ cssVar: { key: 'app' } }}>
<App />
</ConfigProvider>

开启后审查元素,就可以看到 antd 组件样式中一些原本具体的数值被替换为了 CSS 变量:

image

进阶使用

关闭 hash

hash 是 Ant Design 5.0 以来的特性之一,其功能是为每一份主题计算一个独特的 hash 值,并将其用在组件的 class 上,用于隔离主题样式。

但是启用了 CSS 变量之后,相同 antd 版本下的组件样式将不会随着 token 变化而改变 —— 因为我们用 CSS 变量填充了样式中的动态部分。所以如果你的应用中只存在一个版本的 antd,你可以选择关闭 hash 来进一步减小样式体积:

tsx
<ConfigProvider theme={{ cssVar: true, hashed: false }}>
<App />
</ConfigProvider>

同时我们非常推荐使用 extractStyle 来抽取静态样式,这样会为应用性能带来一定量的提升。

修改主题

在 CSS 变量模式下,修改主题的方法与之前无异,参考 定制主题。

API

cssVar 目前支持的参数:

属性说明类型默认值版本
prefixCSS 变量的前缀,默认与 ConfigProvider 上配置的 prefixCls 相同。stringant5.12.0
key当前主题的唯一识别 key. 在 React 18 中会默认用 useId 填充,小于 React 18 的版本需要手动填充。stringuseId in React 185.12.0