diff --git a/.dumi/theme/common/styles/Common.tsx b/.dumi/theme/common/styles/Common.tsx index c2f9cf7f2b67..2744394b203b 100644 --- a/.dumi/theme/common/styles/Common.tsx +++ b/.dumi/theme/common/styles/Common.tsx @@ -1,77 +1,86 @@ -import { css, Global } from '@emotion/react'; import React from 'react'; +import { css, Global } from '@emotion/react'; import { useTheme } from 'antd-style'; +import { updateCSS } from 'rc-util/lib/Dom/dynamicCSS'; export default () => { const { anchorTop } = useTheme(); + React.useInsertionEffect(() => { + updateCSS(`@layer global, antd;`, 'site-global', { + prepend: true, + }); + }, []); + return ( ); }; diff --git a/.dumi/theme/layouts/GlobalLayout.tsx b/.dumi/theme/layouts/GlobalLayout.tsx index ab1ab33f28c9..c45a6c6881df 100644 --- a/.dumi/theme/layouts/GlobalLayout.tsx +++ b/.dumi/theme/layouts/GlobalLayout.tsx @@ -204,6 +204,7 @@ const GlobalLayout: React.FC = () => { diff --git a/.dumi/theme/plugin.ts b/.dumi/theme/plugin.ts index bb544dc16e60..f30a91caa07b 100644 --- a/.dumi/theme/plugin.ts +++ b/.dumi/theme/plugin.ts @@ -169,7 +169,8 @@ const RoutesPlugin = (api: IApi) => { const matchRegex = / + + + + + + +``` + +#### ✅ Correct + +```html + + + + + + + + + +``` diff --git a/docs/react/compatible-style.zh-CN.md b/docs/react/compatible-style.zh-CN.md index c049085cbe1d..fd0b28e6399d 100644 --- a/docs/react/compatible-style.zh-CN.md +++ b/docs/react/compatible-style.zh-CN.md @@ -11,9 +11,33 @@ Ant Design 支持最近 2 个版本的现代浏览器。如果你需要兼容旧 查看 [`@ant-design/cssinjs`](https://github.com/ant-design/cssinjs#styleprovider). +## `layer` 降权 + +Ant Design 从 `5.17.0` 起支持配置 `layer` 进行统一降权。经过降权后,antd 的样式将始终低于默认的 CSS 选择器优先级,以便于用户进行样式覆盖(请务必注意检查 `@layer` 浏览器兼容性): + +```tsx +import { StyleProvider } from '@ant-design/cssinjs'; + +export default () => ( + + + +); +``` + +antd 的样式会被封装在 `@layer` 中,以降低优先级: + +```diff +++ @layer antd { + :where(.css-bAMboO).ant-btn { + color: #fff; + } +++ } +``` + ## `:where` 选择器 -Ant Design 的 CSS-in-JS 默认通过 `:where` 选择器降低 CSS Selector 优先级,以减少用户升级时额外调整自定义样式的成本,不过 `:where` 语法的[兼容性](https://developer.mozilla.org/en-US/docs/Web/CSS/:where#browser_compatibility)在低版本浏览器比较差。在某些场景下你如果需要支持旧版浏览器(或与 [TailwindCSS 优先级冲突](https://github.com/ant-design/ant-design/issues/38794#issuecomment-1328262525)),你可以使用 `@ant-design/cssinjs` 取消默认的降权操作(请注意版本保持与 antd 一致): +Ant Design 的 CSS-in-JS 默认通过 `:where` 选择器降低 CSS Selector 优先级,以减少用户升级时额外调整自定义样式的成本,不过 `:where` 语法的[兼容性](https://developer.mozilla.org/en-US/docs/Web/CSS/:where#browser_compatibility)在低版本浏览器比较差。在某些场景下你如果需要支持旧版浏览器,你可以使用 `@ant-design/cssinjs` 取消默认的降权操作(请注意版本保持与 antd 一致): ```tsx import { StyleProvider } from '@ant-design/cssinjs'; @@ -147,3 +171,91 @@ root.render( , ); ``` + +## 兼容三方样式库 + +在某些情况下,你可能需要 antd 与其他样式库共存,比如 `Tailwind CSS`、`Emotion`、`styled-components` 等。不同于传统 CSS 方案,这些三方库往往不太容易通过提升 CSS 选择器优先级的方式覆盖 antd 的样式。你可以通过为 antd 配置 `@layer` 降低其 CSS 选择器权重,同时通过合理安排 `@layer` 顺序来解决样式覆盖问题: + +### antd 配置 `@layer` + +```tsx +import { StyleProvider } from '@ant-design/cssinjs'; + +export default () => ( + + + +); +``` + +### TailwindCSS 排布 `@layer` + +在 global.css 中,调整 `@layer` 来控制样式的覆盖顺序。让 `tailwind-base` 置于 `antd` 之前: + +```less +@layer tailwind-base, antd; + +@layer tailwind-base { + @tailwind base; +} +@tailwind components; +@tailwind utilities; +``` + +### reset.css + +如果你使用了 antd 的 `reset.css` 样式,你需要为其也指定 `@layer` 以防止将 antd 降权的样式覆盖: + +```less +@layer reset, antd; + +@import url(reset.css) layer(reset); +``` + +### 其他 CSS-in-JS 库 + +当你为 antd 配置完 `@layer` 后,你不需要为其他的 CSS-in-JS 库做任何额外的配置。你的 CSS-in-JS 已经可以完全覆盖 antd 的样式了。 + +### SSR 场景 + +在 SSR 场景下,样式往往会通过 ` + + + + + + +``` + +#### ✅ 正确的写法 + +```html + + + + + + + + + +``` diff --git a/package.json b/package.json index f58b3d9bb233..0997cae33167 100644 --- a/package.json +++ b/package.json @@ -116,7 +116,7 @@ ], "dependencies": { "@ant-design/colors": "^7.0.2", - "@ant-design/cssinjs": "^1.18.5", + "@ant-design/cssinjs": "^1.19.1", "@ant-design/icons": "^5.3.6", "@ant-design/react-slick": "~1.1.2", "@babel/runtime": "^7.24.1",