生态与帮助 · Tailwind
搭配使用
更优雅地使用 TailwindCSS 与 Semi

注意


本页将提供 TailwindCSS (支持 v3 和 v4) 等原子类样式库与 Semi 共同使用时遇到的一些问题的最佳实践。
这些问题在其他组件库与 Tailwind 共同使用时候也会经常遇到,但 Semi 提供了官方解决方案,建议按照本文说明,正确配置项目。
注意
Semi 不依赖任何第三方样式库,没有安装 Tailwind 一样可以运行,如果你没有使用 Tailwind 等原子类库,可忽略以下内容

1. 解决样式覆盖优先级问题

问题表现

在组件中使用部分原子类时没有效果 或 组件库样式异常。

原因分析

使用 Tailwind 时,Tailwind 通过 className 对 dom 进行样式修改,同样作用于 Semi 组件库。同时 Tailwind 默认开启了 Preflight 来重置浏览器默认样式。
已启用 Preflight 的项目通常无需再引入 reset-css。重复引入其他全局 reset 并不能解决样式优先级冲突;如果手动禁用了 Preflight,请根据项目需要选择重置方案。
此时根据你项目的配置和入口的 import,有两种可能:
  1. Tailwind 比 Semi 的样式先引入,Semi 优先级更高
  2. Semi 样式 比 Tailwind 先引入,Tailwind 优先级更高
如果是 1,则会出现 Tailwind 在添加某些原子类时,如果组件样式已经定义了某个 css 属性,原子类的优先级比 Semi 优先级低,此时原子类失效。 例如在 1 的前提下,对 Button 组件设置 padding,会出现失效的情况。
如果是 2,因为 Tailwind 优先级较高,其对浏览器默认样式覆盖的 Preflight 会同时覆盖掉 Semi 的样式。 例如在 2 的前提下,light 的 Button 的背景色会被覆盖为 transparent,导致样式表现异常。

解决方案

无论 Tailwind 和 组件库哪一方优先级高,都会出现问题,因此解决方式在于正确处理 Tailwind 样式中 Preflight 和用户需要的原子类的优先级相对于组件库优先级的关系。
1. 开启 Semi 插件 (>= 2.59.0)
2. 在项目中的配置文件中
  • webpack 用户:在 webpack.config.js 引入 Semi webpack 插件并开启 cssLayer
  • rspack 用户:在 rspack.config.js 引入 Semi webpack 插件并开启 cssLayer
  • Vite 用户:安装 @douyinfe/semi-vite-plugin(>= 2.98.0),在现有 React 项目的 Vite 配置中开启 cssLayer。该插件处理 Semi 样式,不代替 Tailwind 自身的构建配置。
Tailwind v4 使用 @tailwindcss/vite 时,配置如下:
Tailwind v3 保留项目已有的 Tailwind PostCSS 配置,不安装或使用 @tailwindcss/vite,Vite 配置为:
以上两种 Vite 配置都需要继续按下一节设置对应 Tailwind 版本的 Layer 顺序和入口 CSS。若还需接入主题包,可在同一个 semiTheming 配置中增加 theme 等选项,详见定制主题。
使用其他构建工具的用户,可参照原理自行对 Semi 的 CSS 进行 Layer 包裹。
3. 修改 Tailwind 入口配置
选择你的 Tailwind 版本
Tailwind v3 和 v4 的配置方式不同,请根据你使用的版本选择对应的配置方式。
必须保证生产环境的 CSS 层顺序
以下入口 import 顺序在大多数项目中可以保证最终的 CSS 顺序,但最终应以生产构建产物和浏览器中的实际样式为准。Layer 顺序声明必须在任何首次声明这些层的样式之前生效,才能保证普通样式声明的优先级为 Preflight 低于 Semi、Semi 低于工具类。仅开启 `cssLayer`,或仅在源码中把 import 写在第一行,并不能覆盖所有生产分块和 CSS 提取场景。配置后请按下方“检查生产构建产物”一节验证。
Tailwind v4 配置方式:
层顺序需要包含 Tailwind 默认的 components 层,确保它位于 utilities 之前。否则 Tailwind 后续声明 components 时会将其追加到已知层的末尾,导致该层中的自定义组件样式反过来覆盖工具类。
  1. 创建一个 CSS 文件(如 semi-layer.css),内容如下:
  1. 在项目的 JS 入口文件(如 main.tsx、App.tsx 或 index.js)的最顶部,在所有其他 import 语句之前,import 这个文件:
重要
在源码入口中,semi-layer.css 应在任何包含 @import "tailwindcss"; 的 CSS 文件和任何 Semi 组件的 import 之前引入,建议放在入口文件的第一行;同时仍需确保生产产物中,Layer 顺序声明位于相关层的样式之前。

Tailwind v3 配置方式:
Tailwind v3 入口的 CSS 通常是包含了下面三行的文件
将其修改为(直接复制)
并在项目的 JS 入口文件(即 App.tsx 或 index.js)处最上方 import 上面修改的文件。(通常一个 Tailwind 项目对于上面文件的 import 已经处理好,只要将该 import 语句提到所有 import 语句前即可)
4. 检查生产构建产物(Tailwind v3 / v4 均适用)
完成配置后,请运行项目的生产构建和产物预览,不能仅以开发模式正常或构建成功作为验证依据:
  1. 检查生成的 HTML 中 <link rel="stylesheet"> / <style> 的顺序,以及对应 CSS 文件中的内容顺序,确认完整的 Layer 顺序声明出现在相关层第一次被声明之前。这里指文档和样式表中的层叠顺序,不是网络请求完成的先后。
  2. 如果使用 manualChunks、共享依赖分块或其他 CSS 提取配置,Semi 的 CSS 可能被提到入口 CSS 之前。例如,先出现 @layer semi { ... }、再出现 @layer theme, base, semi, components, utilities;,后者无法重新排列已经注册的 semi 层,Preflight 就可能反过来覆盖 Semi。即使最终只生成一个 CSS 文件,也需检查文件内部的声明顺序。
  3. 在生产预览中同时检查默认组件样式和工具类覆盖效果,例如 Button 的背景、padding 是否正常,以及显式设置的 padding 工具类是否仍然生效。
如果入口 import 无法保证生产顺序,可以将 Layer 顺序声明放在 HTML <head> 中所有其他样式之前,先建立层顺序;保留原有 Tailwind 入口 CSS 和 Semi 插件的 cssLayer 配置。例如,Tailwind v4 的 Vite 项目可以在 index.html 中添加:
Tailwind v3 则将上述 <style> 中的声明替换为:
如果项目启用了严格的 Content Security Policy(CSP),请为内联样式配置允许的 nonce/hash,或使用确保最先加载的独立样式表,并再次检查生产产物顺序;不要为了该声明关闭 CSP。
兼容低版本浏览器
CSS Layer 要求浏览器版本高于 Chromium 99 (兼容性表格),如果你的网站需要低版本浏览器访问,需要添加 CSS Layer 的 Polyfill,请参考此 Polyfill 的 PostCSS 插件文档

原理

通过 CSS Layer 特性,实现不同来源的样式的优先级设置。
插件将编译生成的 Semi 组件及主题样式包裹在 @layer semi { ... } 中;Tailwind 的各种样式层则由项目单独配置。
另外,我们配置了各种 Layer 的优先级顺序:
上述 CSS 的含义为,base(含 Preflight)优先级最低,Semi 次之,用户设置的原子类样式(padding-[xxx] 等)优先级最高,这样即可解决上面遇到的问题。

2.解决在 Tailwind 原子类中使用 Semi Token 的问题 (可选)

Tailwind 支持用户配置自己的 Token 来实现主题。同时 Semi 也提供了自己的主题方案与对应 Token 如果想在项目中直接使用 Semi Token,例如将一个 span 的文字颜色设置为 --semi-color-text-0 来实现亮暗色的颜色自动切换与主题保持一致,需要单独设置 css color: var(--semi-color-text-0),很不方便。
Semi 提供了 Tailwind 的主题配置文件,用于将 Semi 的 Token 映射为原子类 Token,上述需求可以直接给 span 设置 text-semi-color-text-0 即可。
选择你的 Tailwind 版本
Tailwind v3 和 v4 的主题配置方式不同,请根据你使用的版本选择对应的配置方式。
Tailwind v4 配置方式:
在你的 Tailwind 入口 CSS 文件中(包含 @import "tailwindcss"; 的文件),添加 @theme 配置:
配置后即可使用如 text-semi-color-text-0、bg-semi-color-primary、rounded-semi-border-radius-small 等原子类。

Tailwind v3 配置方式:
在 Tailwind 配置中 (即 tailwind.config.js) 配置以下内容即可: