跳到主要内容

React 学习之旅 5 - 集成 Tailwind、 AntDesign

概述​

本文介绍如何在 React 项目中集成 Tailwind CSS 和 AntDesign，以便快速构建设计规范的用户界面。

DEOM：xiezipei/react-journey/05/my-app-antd-tailwind/

集成组件库 AntDesign​

AntDesign 以下简称：Antd

参考 Antd 最新官网：

先用 Vite 初始化 React 项目：

npm create vite@latest my-app-antd-tailwind -- --template react-swc

按提示，进入项目，安装依赖，略

安装 antd：

npm install antd --save
# 或
npm i antd -S

测试：

import './App.css'
import { Button } from 'antd' // 引入

function App() { 
  return (
    <>
      <div className="App">
        <Button type='primary'>按钮</Button>
      </div>
    </>
  )
}

export default App

集成样式工具 Tailwind​

参考 Tailwind 最新官网：

安装依赖：

npm install tailwindcss @tailwindcss/vite

修改 Vite 配置文件：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import tailwindcss from '@tailwindcss/vite'; // New

// https://vite.dev/config/
export default defineConfig({
    plugins: [
        react(), 
        tailwindcss() // New
    ],
});

引入样式，并修改页面：

/* App.css */
@import "tailwindcss";
import './App.css'
import { Button } from 'antd'

function App() { 
  return (
    <>
      <div className="App">
        {/* 验证 antd */}
        <Button type='primary'>Antd 按钮</Button>
        {/* 验证 tailwind */}
        <h1 class="text-3xl font-bold underline">
          Hello Tailwind!
        </h1>
      </div>
    </>
  )
}

export default App

验证成功：

@layer​

在解决 antd 与 tailwind 兼容问题前先了解什么是 @layer?

@layer 是 CSS 原生特性（Chrome 99+、Firefox 97+ 支持），用于显式控制样式优先级，避免 !important 的滥用：

  • 作用：将样式规则分组到不同的“层级”中，明确层级间的优先级顺序。
  • 优势：比传统选择器权重（如 class、id）更可控，尤其适合组件库与业务样式的隔离

基础语法：

@layer base, components, utilities; /* 定义层级顺序（优先级从左到右递减） */

@layer base {
  button { color: red; } /* 低优先级 */
}

@layer utilities {
  .text-blue { color: blue !important; } /* 高优先级（但受限于层级顺序） */
}

可在 Chrome DevTools 查看：

Antd 5 与 Tailwind 4 兼容​

先 启用 @layer 功能（Antd 版本：>=5.17.0）：

import { StyleProvider } from '@ant-design/cssinjs';
import { ConfigProvider } from 'antd';

export default () => (
    // StyleProvider 开启 layer
    <StyleProvider layer>
        <ConfigProvider>
            <MyApp />
        </ConfigProvider>
    </StyleProvider>
);

然后在 global.css 中，调整 @layer 来控制样式的覆盖顺序，让 antd 置于恰当位置：

@layer theme, base, antd, components, utilities;

@import 'tailwindcss';

添加 tailwind.config.js 文件：

/** @type {import('tailwindcss').Config} */
export default {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [],
  important: true, // 确保 Tailwind 的样式优先级高于其他样式
  corePlugins: {
    preflight: false, // 禁用 Tailwind 的默认样式，避免与 Ant Design 冲突
  },
};

去掉 index.css 中 Button 干扰样式

App.jsx 中验证一下：

// 会被 tw 样式 `bg-amber-700` 覆盖
<Button type='primary' className='bg-amber-700' onClick={showInfoByHook}>Antd 按钮(Hook)</Button>

Antd 5 与 React 19 兼容​

由于 React 19 调整了 react-dom 的导出方式，导致 antd 无法直接使用 ReactDOM.render 方法。

直接使用 antd 会遇到以下问题：

  • 波纹特效无法正常工作
  • Modal、Notification、Message 等组件的静态方法无效

因此需要进行兼容配置处理（使用兼容包）：

安装依赖：

npm install @ant-design/v5-patch-for-react-19 --save

入口处引入：

import '@ant-design/v5-patch-for-react-19';

验证：

function App() { 

  const [messageApi, contextHolder] = message.useMessage();

  const showInfoByHook = () => {
    messageApi.info('Hello, Ant Design!');
  };

  const showInfoByStaticMethod = () => {
    // 需在 main.jsx 引入 import '@ant-design/v5-patch-for-react-19';
    message.info('This is a normal message');
  };

  return (
    <>
      <div className="App">
        {/* 验证 antd */}
        {contextHolder}
        <Button type='primary' onClick={showInfoByHook}>Antd 按钮(Hook)</Button>
        <br /><br />
        <Button type='primary' onClick={showInfoByStaticMethod}>Antd 按钮(静态方法)</Button>
        <br /><br />
        {/* 验证 tailwind */}
        <h1 class="text-3xl font-bold underline">
          Hello Tailwind!
        </h1>
      </div>
    </>
  )
}

无兼容处理，调用静态方法：

资源​

参考​