diff --git a/docs/react/compatible-style.en-US.md b/docs/react/compatible-style.en-US.md index ed5356060e..3243c86fff 100644 --- a/docs/react/compatible-style.en-US.md +++ b/docs/react/compatible-style.en-US.md @@ -5,7 +5,7 @@ order: 1 title: CSS Compatible --- -### Default Style Compatibility +## Default Style Compatibility Ant Design supports the [last 2 versions of modern browsers](https://browsersl.ist/#q=defaults). If you need to be compatible with legacy browsers, please perform downgrade processing according to actual needs: diff --git a/docs/react/css-variables.en-US.md b/docs/react/css-variables.en-US.md deleted file mode 100644 index a4a9d51ac1..0000000000 --- a/docs/react/css-variables.en-US.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -group: - title: Advanced -order: 3 -title: CSS Variables -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. And since `6.0.0`, CSS variable mode has become the default mode. - -## 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 - -## Tips - - -:::warning -CSS variable mode requires a unique key for each theme to ensure style isolation. In React 18, we use `useId` to generate unique keys by default, so you don't have to worry about this issue in React 18. But in React 17 or 16, you need to manually set a unique key for each theme, otherwise the themes will be mixed up. -::: - -```tsx -// React 17 or 16 - - - -``` - -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) - -## Advanced - -### Disable Hash - -Hash is one of the features since Ant Design 5.0. Its function is to calculate a unique hash value for each theme, and use it in the class of the component to isolate the theme style. - -However, after enabling CSS variables, the component styles of the same antd version will not change with the token —— because we use CSS variables to fill in the dynamic parts of the styles. So if there is only one version of antd in your application, you can choose to disable hash to further reduce the total size of the styles: - -```tsx - - - -``` - -### 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 - -With CSS variable mode, the method of modifying the theme is the same as before, refer to [Customize Theme](/docs/react/customize-theme). - -## API - -`cssVar` configuration: - -| Properties | Description | Type | Default | Version | -| --- | --- | --- | --- | --- | -| prefix | Prefix of CSS Variables, same as `prefixCls` of ConfigProvider by default | string | `ant` | 5.12.0 | -| key | The unique key of theme. Automatically set by `useId` in React 18, but need to be set manually in React 17 or 16 | string | `useId` in React 18 | 5.12.0 | diff --git a/docs/react/css-variables.zh-CN.md b/docs/react/css-variables.zh-CN.md deleted file mode 100644 index 6c64b35edc..0000000000 --- a/docs/react/css-variables.zh-CN.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -group: - title: 进阶使用 -order: 3 -title: 使用 CSS 变量 -tag: Updated ---- - -自 `5.12.0` 起，Ant Design 5.x 重新支持了 CSS 变量。与 4.x 版本不同的是，这次我们融合了 CSS-in-JS 的能力，并且将所有 Design Token 纳入了 CSS 变量的管理范畴。而从 `6.0.0` 起，CSS 变量模式已经成为默认模式。 - -## 特性 - -CSS 变量模式为 Ant Design 的样式能力带来了两个重要的提升： - -1. 同一组件在不同主题下的样式可以共享，减少了样式体积 -2. 切换主题时不再需要重新序列化样式，提升了主题切换的性能 - -## 注意 - - -:::warning -CSS 变量模式需要为每一个主题设置独特的 key 来保证样式隔离，在 React 18 中我们使用了 `useId` 来生成唯一的 key，所以在 React 18 中，你可以不用关心这个问题。但是在 React 17 或者 16 中，你需要手动为每一个主题设置一个唯一的 key，否则会导致主题混乱。 -::: - -```tsx -// React 17 or 16 - - - -``` - -审查元素，就可以看到 antd 组件样式中一些原本具体的数值被替换为了 CSS 变量： - -![image](https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*p5NrRJmUNHgAAAAAAAAAAAAADrJ8AQ/original) - -## 进阶使用 - -### 关闭 hash - -hash 是 Ant Design 5.0 以来的特性之一，其功能是为每一份主题计算一个独特的 hash 值，并将其用在组件的 class 上，用于隔离主题样式。 - -但是启用了 CSS 变量之后，相同 antd 版本下的组件样式将不会随着 token 变化而改变 —— 因为我们用 CSS 变量填充了样式中的动态部分。所以如果你的应用中只存在一个版本的 antd，你可以选择关闭 hash 来进一步减小样式体积： - -```tsx - - - -``` - -### 开启 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); -``` - -### 修改主题 - -在 CSS 变量模式下，修改主题的方法与之前无异，参考 [定制主题](/docs/react/customize-theme-cn)。 - -## API - -`cssVar` 目前支持的参数： - -| 属性 | 说明 | 类型 | 默认值 | 版本 | -| --- | --- | --- | --- | --- | -| prefix | CSS 变量的前缀，默认与 ConfigProvider 上配置的 `prefixCls` 相同。 | string | `ant` | 5.12.0 | -| key | 当前主题的唯一识别 key. 在 React 18 中会默认用 `useId` 填充，小于 React 18 的版本需要手动填充。 | string | `useId` in React 18 | 5.12.0 | diff --git a/docs/react/customize-theme.en-US.md b/docs/react/customize-theme.en-US.md index f4c0563e53..b1b6893c89 100644 --- a/docs/react/customize-theme.en-US.md +++ b/docs/react/customize-theme.en-US.md @@ -208,6 +208,33 @@ export default App; ## Advanced +### Zero Runtime {#zero-runtime} + +Starting from 6.0.0, we provide `zeroRuntime` mode to further improve application performance. When enabled, Ant Design will no longer generate component styles at runtime, so you need to manually import the style files. + +```tsx +import 'antd/dist/antd.css'; + +export default () => ( + + + +); +``` + +`antd/dist/antd.css` contains all antd component styles, but does not include hashed className. If you want to import fewer styles, or cannot use the default styles due to configuration changes like `prefix`, we recommend using [@ant-design/static-style-extract](https://github.com/ant-design/static-style-extract) to generate static styles. + +```tsx +import fs from 'fs'; +import { extractStyle } from '@ant-design/static-style-extract'; + +const cssText = extractStyle({ + includes: ['Button'], // Only include Button component styles +}); + +fs.writeFileSync('/path/to/somewhere', cssText); +``` + ### Switch Themes Dynamically In v5, dynamically switching themes is very simple for users, you can dynamically switch themes at any time through the `theme` property of `ConfigProvider` without any additional configuration. @@ -440,8 +467,8 @@ const theme = { | inherit | Inherit theme configured in upper ConfigProvider | boolean | true | | | algorithm | Modify the algorithms of theme | `(token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]` | `defaultAlgorithm` | | | components | Modify Component Token and Alias Token applied to components | `ComponentsConfig` | - | | -| cssVar | CSS Variables Configuration, refer [CSS Variables](/docs/react/css-variables#api) | `boolean \| { prefix?: string; key?: string }` | false | | -| hashed | Component class Hash value, refer [CSS Variables](/docs/react/css-variables#disable-hash) | boolean | true | | +| cssVar | CSS Variables Configuration, refer [cssVar](#css-var) | `boolean \| { prefix?: string; key?: string }` | false | | +| hashed | Style patch on the hash className | boolean | true | | | zeroRuntime | Enable zero-runtime mode, which will not generate style at runtime, need to import additional CSS file | boolean | true | 6.0.0 | ### ComponentsConfig @@ -452,6 +479,13 @@ const theme = { > `algorithm` of component is `false` by default, which means tokens of component will only override global token. When it is set with `true`, the algorithm will be the same as global. You can also pass algorithm or Array of algorithm, and it will override algorithm of global. +### cssVar {#css-var} + +| Property | Description | Type | Default | Version | +| --- | --- | --- | --- | --- | +| prefix | Prefix of CSS variables, same as `prefixCls` configured on ConfigProvider by default | string | `ant` | | +| key | Unique key for current theme, filled with `useId` by default | string | `useId` in React 18 | | + ### SeedToken diff --git a/docs/react/customize-theme.zh-CN.md b/docs/react/customize-theme.zh-CN.md index 4e5ae2986b..30fb2468ff 100644 --- a/docs/react/customize-theme.zh-CN.md +++ b/docs/react/customize-theme.zh-CN.md @@ -208,6 +208,33 @@ export default App; ## 进阶使用 +### 零运行时 zeroRuntime {#zero-runtime} + +自 6.0.0 起，我们提供了 `zeroRuntime` 模式来进一步提升应用性能。开启后，Ant Design 将不再在运行时生成组件样式，所以需要自行引入样式文件。 + +```tsx +import 'antd/dist/antd.css'; + +export default () => ( + + + +); +``` + +`antd/dist/antd.css` 包含了所有 antd 组件的样式，但是不会包含 hashed className。如果你希望引入更少的样式，或者因为修改了 `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); +``` + ### 动态切换 在 v5 中，动态切换主题对用户来说是非常简单的，你可以在任何时候通过 `ConfigProvider` 的 `theme` 属性来动态切换主题，而不需要任何额外配置。 @@ -440,8 +467,8 @@ const theme = { | inherit | 继承上层 ConfigProvider 中配置的主题。 | boolean | true | | | algorithm | 用于修改 Seed Token 到 Map Token 的算法 | `(token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]` | `defaultAlgorithm` | | | components | 用于修改各个组件的 Component Token 以及覆盖该组件消费的 Alias Token | `ComponentsConfig` | - | | -| cssVar | CSS 变量配置，参考[使用 CSS 变量](/docs/react/css-variables-cn#api) | `{ prefix?: string; key?: string }` | false | | -| hashed | 组件 class Hash 值，参考[使用 CSS 变量](/docs/react/css-variables-cn#关闭-hash) | boolean | true | | +| cssVar | CSS 变量配置，参考[cssVar](#css-var) | `boolean \| { prefix?: string; key?: string }` | false | | +| hashed | 将样式添加至 hash className 上 | boolean | true | | | zeroRuntime | 开启零运行时模式，不会在运行时产生样式，需要手动引入 CSS 文件 | boolean | true | 6.0.0 | ### ComponentsConfig @@ -452,6 +479,13 @@ const theme = { > 组件级别的 `algorithm` 默认为 `false`，此时组件 Token 仅仅会覆盖该组件使用的 token，不会进行派生计算。设置为 `true` 时会继承当前全局算法；也可以和全局的 `algorithm` 一样传入一个或多个算法，这将会针对该组件覆盖全局的算法。 +### cssVar {#css-var} + +| 属性 | 说明 | 类型 | 默认值 | 版本 | +| --- | --- | --- | --- | --- | +| prefix | CSS 变量的前缀，默认与 ConfigProvider 上配置的 `prefixCls` 相同 | string | `ant` | | +| key | 当前主题的唯一识别 key，默认用 `useId` 填充 | string | `useId` in React 18 | | + ### SeedToken diff --git a/scripts/build-style.tsx b/scripts/build-style.tsx index 807d8462e6..768d5fb0d8 100644 --- a/scripts/build-style.tsx +++ b/scripts/build-style.tsx @@ -118,9 +118,11 @@ const defaultNode = () => ( function extractStyle(customTheme?: any): string { const cache = createCache(); renderToString( - - {customTheme ? customTheme(defaultNode()) : defaultNode()} - , + + + {customTheme ? customTheme(defaultNode()) : defaultNode()} + + , ); // Grab style from cache