docs: guide about where config (#38764)

* docs: guide about where config * docs: add diff demo * docs: Add SSR part * docs: add faq
2025-08-06 16:06:28 +08:00 · 2022-11-21 17:27:06 +08:00 · 2022-11-21 17:27:06 +08:00 · a1e14f6165
commit a1e14f6165
parent 91b25d554e
4 changed files with 145 additions and 7 deletions
--- a/docs/react/customize-theme.en-US.md
+++ b/docs/react/customize-theme.en-US.md
@ -215,11 +215,72 @@ const theme = {
 };
 ```

+### Compatible adjustment
+
+Ant Design default using CSS-in-JS with `:where` Selector to reduce priority. If you want to support old browser, you can use `@ant-design/cssinjs` to adjust this behavior (Please note keep version align with antd):
+
+```tsx
+import React from 'react';
+import { StyleProvider } from '@ant-design/cssinjs';
+
+export default () => (
+  <StyleProvider hashPriority="high">
+    <MyApp />
+  </StyleProvider>
+);
+```
+
+It will turn `:where` to class selector:
+
+```diff
+--  :where(.css-bAMboO).ant-btn {
++  .css-bAMboO.ant-btn {
+      color: #fff;
+    }
+```
+
+### Server Side Render (SSR)
+
+Use `@ant-design/cssinjs` to extract style:
+
+```tsx
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';
+
+export default () => {
+  // SSR Render
+  const cache = createCache();
+
+  const html = renderToString(
+    <StyleProvider cache={cache}>
+      <MyApp />
+    </StyleProvider>,
+  );
+
+  // Grab style from cache
+  const styleText = extractStyle(cache);
+
+  // Mix with style
+  return `
+<!DOCTYPE html>
+<html>
+  <head>
+    ${styleText}
+  </head>
+  <body>
+    <div id="root">${html}</div>
+  </body>
+</html>
+`;
+};
+```
+
 ## API

 ### Theme

-| 属性 | 说明 | 类型 | 默认值 |
+| Property | Description | Type | Default |
 | --- | --- | --- | --- |
 | token | Modify Design Token | `AliasToken` | - |
 | inherit | Inherit theme configured in upper ConfigProvider | boolean | true |
@ -228,13 +289,13 @@ const theme = {

 ### OverrideToken

-| 属性 | 说明 | 类型 | 默认值 |
+| Property | Description | Type | Default |
 | --- | --- | --- | --- |
 | `Component` (可以是任意 antd 组件名，如 `Button`) | 用于修改 Component Token 以及覆盖该组件消费的 Alias Token | `ComponentToken & AliasToken` | - |

 ### SeedToken

-| 属性 | 说明 | 类型 | 默认值 |
+| Property | Description | Type | Default |
 | --- | --- | --- | --- |
 | colorPrimary | 品牌主色 | `string` | `#1677ff` |
 | colorSuccess | 成功色 | `string` | `#52c41a` |
@ -271,9 +332,9 @@ const theme = {

 ### MapToken

-> 继承所有 SeedToken 的属性
+> 继承所有 SeedToken 的 Property

-| 属性 | 说明 | 类型 | 默认值 |
+| Property | Description | Type | Default |
 | --- | --- | --- | --- |
 | colorText | 一级文本色 | `string` | `rgba(0, 0, 0, 0.88)` |
 | colorTextSecondary | 二级文本色 | `string` | `rgba(0, 0, 0, 0.65)` |
@ -364,9 +425,9 @@ const theme = {

 ### AliasToken

-> 继承所有 SeedToken 和 MapToken 的属性
+> 继承所有 SeedToken 和 MapToken 的 Property

-| 属性 | 说明 | 类型 | 默认值 |
+| Property | Description | Type | Default |
 | --- | --- | --- | --- |
 | colorFillContent | - | `string` | `rgba(0, 0, 0, 0.06)` |
 | colorFillContentHover | - | `string` | `rgba(0, 0, 0, 0.12)` |
--- a/docs/react/customize-theme.zh-CN.md
+++ b/docs/react/customize-theme.zh-CN.md
@ -215,6 +215,67 @@ const theme = {
 };
 ```

+### 兼容性调整
+
+Ant Design 的 CSS-in-JS 默认通过 `:where` 选择器降低 CSS Selector 优先级。在某些场景下你如果需要支持的旧版游览器，你可以使用 `@ant-design/cssinjs` 取消默认的降权操作（请注意版本保持与 antd 一致）：
+
+```tsx
+import React from 'react';
+import { StyleProvider } from '@ant-design/cssinjs';
+
+export default () => (
+  <StyleProvider hashPriority="high">
+    <MyApp />
+  </StyleProvider>
+);
+```
+
+切换后，样式将从 `:where` 切换为类选择器：
+
+```diff
+--  :where(.css-bAMboO).ant-btn {
++  .css-bAMboO.ant-btn {
+      color: #fff;
+    }
+```
+
+### 服务端渲染
+
+使用 `@ant-design/cssinjs` 将所需样式抽离：
+
+```tsx
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';
+
+export default () => {
+  // SSR Render
+  const cache = createCache();
+
+  const html = renderToString(
+    <StyleProvider cache={cache}>
+      <MyApp />
+    </StyleProvider>,
+  );
+
+  // Grab style from cache
+  const styleText = extractStyle(cache);
+
+  // Mix with style
+  return `
+<!DOCTYPE html>
+<html>
+  <head>
+    ${styleText}
+  </head>
+  <body>
+    <div id="root">${html}</div>
+  </body>
+</html>
+`;
+};
+```
+
 ## API

 ### Theme
--- a/docs/react/faq.en-US.md
+++ b/docs/react/faq.en-US.md
@ -183,6 +183,14 @@ You should only access the API by official doc with ref. Directly access interna

 For historical reasons, the display names of the pop components are not uniform, and both `open` and `visible` are used. This makes the memory cost that non-tsx users encounter when developing. It also leads to ambiguity about what name to choose when adding a feature. So we want to unify the attribute name, you can still use the original `visible` and it will still be backward compatible, but we will remove this attribute from the documentation as of v5.

+## Dynamic style using `:where` selector which not support old browser.
+
+Please ref dynamic theme document [Compatible Adjustment](/docs/react/customize-theme#compatible-adjustment) part.
+
+## How to support SSR？
+
+Please ref dynamic theme document [SSR](/docs/react/customize-theme#server-side-render-ssr) part.
+
 ## How to spell Ant Design correctly?

 - ✅ **Ant Design**: Capitalized with space, for the design language.
--- a/docs/react/faq.zh-CN.md
+++ b/docs/react/faq.zh-CN.md
@ -204,6 +204,14 @@ ConfigProvider.config({

 因为历史原因，弹层类组件展示命名并不统一，出现了 `open` 与 `visible` 都在使用的情况。这使得非 tsx 用户在开发时遭遇的记忆成本。同样导致新增 feature 时选择何种命名的模棱两可。因而我们希望统一该属性命名，你仍然可以使用原本的 `visible` 它仍然会向下兼容，但是从 v5 起我们将从文档中移除该属性。

+## 动态样式有 `:where` 导致旧版游览器不支持怎么办？
+
+请参考动态主题文档 [兼容性调整](/docs/react/customize-theme-cn#兼容性调整) 部分内容。
+
+## 如何支持 SSR？
+
+请参考动态主题文档 [服务端渲染](/docs/react/customize-theme-cn#服务端渲染) 部分内容。
+
 ## 如何正确的拼写 Ant Design？

 - ✅ **Ant Design**：用空格分隔的首字母大写单词，指代设计语言。