diff --git a/docs/react/css-variables.en-US.md b/docs/react/css-variables.en-US.md index 5ab61879cf..2e25c60bd9 100644 --- a/docs/react/css-variables.en-US.md +++ b/docs/react/css-variables.en-US.md @@ -8,20 +8,16 @@ tag: New Since `5.12.0`, Ant Design 5.x enabled CSS variables again. Unlike 4.x, this time we have integrated the capabilities of CSS-in-JS, and all Design Tokens have been included in the management scope of CSS variables. -> Currently, the CSS variable mode has been globally enabled on the official website. +Since `6.0.0`, CSS variable mode has become the default mode. -## When to Use +## Features CSS variable mode brings two important improvements to Ant Design's styling capabilities: 1. The styles of the same component under different themes can be shared, reducing the total size of the styles 2. When switching themes, there is no need to re-serialize the styles, which improves the performance of theme switching -Therefore, if your application depends on Ant Design's theme capabilities, we strongly recommend that you enable the CSS variable mode. - -## Quick Start - -To enable CSS variable mode, use the `cssVar` configuration in the `theme` property of ConfigProvider. This configuration will be inherited, so if you want to enable CSS variable mode globally, you only need to configure it in the root of your application. +## Tips :::warning @@ -29,18 +25,13 @@ CSS variable mode requires a unique key for each theme to ensure style isolation ::: ```tsx -// React 18 - - - - // React 17 or 16 ``` -After enabling it, you can see that some specific values in the antd component styles have been replaced with CSS variables: +You can see that some specific values in the antd component styles have been replaced with CSS variables: ![image](https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*p5NrRJmUNHgAAAAAAAAAAAAADrJ8AQ/original) @@ -58,7 +49,32 @@ However, after enabling CSS variables, the component styles of the same antd ver ``` -By the way, we strongly recommend using [extractStyle](/docs/react/server-side-rendering) to extract static styles, which will bring a certain amount of performance improvement to the application. +### Enable zeroRuntime Mode + +Since 6.0.0, we provide the `zeroRuntime` mode to further improve application performance. After enabling it, Ant Design will no longer generate component styles at runtime, so you need to import the style files yourself. + +```tsx +import 'antd/dist/antd.css'; + +export default () => ( + + + +); +``` + +`antd/dist/antd.css` is the compiled style file of all components. If you want to reduce the size of the styles, or you have modified `prefix` that cannot use the default styles, it is recommended to use [@ant-design/static-style-extract](https://github.com/ant-design/static-style-extract). + +```tsx +import fs from 'fs'; +import { extractStyle } from '@ant-design/static-style-extract'; + +const cssText = extractStyle({ + includes: ['Button'], // Only include style of Button +}); + +fs.writeFileSync('/path/to/somewhere', cssText); +``` ### Customize Theme diff --git a/docs/react/css-variables.zh-CN.md b/docs/react/css-variables.zh-CN.md index eff693b8c9..237cd5a12b 100644 --- a/docs/react/css-variables.zh-CN.md +++ b/docs/react/css-variables.zh-CN.md @@ -3,25 +3,21 @@ group: title: 进阶使用 order: 3 title: 使用 CSS 变量 -tag: New +tag: Updated --- -从 `5.12.0` 起,Ant Design 5.x 重新支持了 CSS 变量。与 4.x 版本不同的是,这次我们融合了 CSS-in-JS 的能力,并且将所有 Design Token 纳入了 CSS 变量的管理范畴。 +自 `5.12.0` 起,Ant Design 5.x 重新支持了 CSS 变量。与 4.x 版本不同的是,这次我们融合了 CSS-in-JS 的能力,并且将所有 Design Token 纳入了 CSS 变量的管理范畴。 -> 目前 CSS 变量模式已在 Ant Design 官网上全局开启。 +自 `6.0.0` 起,CSS 变量模式已经成为默认模式。 -## 何时使用 +## 特性 CSS 变量模式为 Ant Design 的样式能力带来了两个重要的提升: 1. 同一组件在不同主题下的样式可以共享,减少了样式体积 2. 切换主题时不再需要重新序列化样式,提升了主题切换的性能 -因此如果你的应用依赖了 Ant Design 的主题能力,那么我们强烈建议你开启 CSS 变量模式。 - -## 快速上手 - -在 ConfigProvider 的 `theme` 属性中,通过 `cssVar` 配置来开启 CSS 变量模式。这个配置会被继承,所以希望全局开启 CSS 变量模式的话,只需要在根节点的 ConfigProvider 中配置即可。 +## 注意 :::warning @@ -29,18 +25,13 @@ CSS 变量模式需要为每一个主题设置独特的 key 来保证样式隔 ::: ```tsx -// React 18 - - - - // React 17 or 16 ``` -开启后审查元素,就可以看到 antd 组件样式中一些原本具体的数值被替换为了 CSS 变量: +审查元素,就可以看到 antd 组件样式中一些原本具体的数值被替换为了 CSS 变量: ![image](https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*p5NrRJmUNHgAAAAAAAAAAAAADrJ8AQ/original) @@ -53,12 +44,37 @@ hash 是 Ant Design 5.0 以来的特性之一,其功能是为每一份主题 但是启用了 CSS 变量之后,相同 antd 版本下的组件样式将不会随着 token 变化而改变 —— 因为我们用 CSS 变量填充了样式中的动态部分。所以如果你的应用中只存在一个版本的 antd,你可以选择关闭 hash 来进一步减小样式体积: ```tsx - + ``` -同时我们非常推荐使用 [extractStyle](/docs/react/server-side-rendering-cn) 来抽取静态样式,这样会为应用性能带来一定量的提升。 +### 开启 zeroRuntime 模式 + +自 6.0.0 起,我们提供了 `zeroRuntime` 模式来进一步提升应用性能。开启后,Ant Design 将不再在运行时生成组件样式,所以需要自行引入样式文件。 + +```tsx +import 'antd/dist/antd.css'; + +export default () => ( + + + +); +``` + +`antd/dist/antd.css` 包含了所有 antd 组件的样式。如果你希望引入更少的样式,或者因为修改了 `prefix` 等配置无法使用默认的样式,推荐使用 [@ant-design/static-style-extract](https://github.com/ant-design/static-style-extract) 来生成静态样式。 + +```tsx +import fs from 'fs'; +import { extractStyle } from '@ant-design/static-style-extract'; + +const cssText = extractStyle({ + includes: ['Button'], // 只包含 Button 组件的样式 +}); + +fs.writeFileSync('/path/to/somewhere', cssText); +``` ### 修改主题