Antd自定义主题色

学习目标

• 理解 Ant Design 5 自定义主题的核心机制
• 掌握通过 ConfigProvider 的 theme 属性配置主题色
• 学会使用 theme.token.colorPrimary 修改主色调
• 了解 theme.algorithm 切换暗色模式等算法主题
• 掌握 useToken 获取当前主题 token，用于自定义组件配色

常用的主题色

• defaultAlgorithm：默认明亮主题算法
• darkAlgorithm：暗色主题算法，自动切换背景、文字、边框
• compactAlgorithm：紧凑主题算法，适合高密度信息展示

常用的token色

• colorPrimary：主色调，按钮、链接、选中态使用
• colorSuccess / colorWarning / colorError：成功、警告、错误色
• colorTextBase / colorBgBase：文字和背景基础色
• borderRadius：全局圆角基准值

Antd 配置主题色

• App.tsx 里面配置 ConfigProvider 组件

import { RouterProvider } from "react-router-dom";
import router from "@/router/routers";
import EnvBadge from "@/components/common/EnvBadge";
import { ConfigProvider } from "antd";
export default function App() {
  return (
    <ConfigProvider
      theme={{
        token: {
          colorPrimary: "#1D6C0D",
        },
      }}
    >
      <EnvBadge />
      <RouterProvider router={router} />
    </ConfigProvider>
  );
}

• 这个时候你要是页面中引用Button组件.颜色就变了
• 所有 primary 按钮、链接、选中标签等自动变色
• hover、active、disabled 等状态色由算法自动生成
• 不需要手动覆盖每个组件的样式
• 自定义组件如果依赖 colorPrimary，也能通过 useToken 获取
• 实现真正的一站式主题管理

import { Button } from "antd";

function HomePage() {
  return (
    <div>
      <Button type="primary">Primary Button</Button>
    </div>
  );
}

export default HomePage;

暗色主题与算法主题

• darkAlgorithm：暗色主题算法，自动切换背景、文字、边框
• algorithm 决定整套颜色映射规则

import { ConfigProvider, theme } from "antd";
// 一共三种
// defaultAlgorithm 默认明亮主题算法
// darkAlgorithm 暗色主题算法
// compactAlgorithm 紧凑主题算法
const { darkAlgorithm } = theme;
<ConfigProvider
  theme={{
    algorithm: darkAlgorithm,
    token: { colorPrimary: "#1D6C0D" },
  }}
>
  <App />
</ConfigProvider>;

与token的关系

• algorithm 决定 怎么算 （颜色映射规则）

• token 决定 算什么 （输入的种子值，如 colorPrimary: "#1D6C0D" ）

算法组合使用

import { ConfigProvider, theme } from "antd";
const { darkAlgorithm, compactAlgorithm } = theme;
<ConfigProvider
  theme={{
    algorithm: [darkAlgorithm, compactAlgorithm],
    token: { colorPrimary: "#1D6C0D" },
  }}
>
  <App />
</ConfigProvider>;

局部主题与useToken

• 外层 ConfigProvider 定义全局主题
• 内层 ConfigProvider 可以覆盖部分 token，只影响局部组件
• 适合某个模块需要特殊强调色的场景

<ConfigProvider theme={{ token: { colorPrimary: "#1D6C0D" } }}>
  <App />
  <ConfigProvider theme={{ token: { colorPrimary: "#ff4d4f" } }}>
    <SpecialModule />
  </ConfigProvider>
</ConfigProvider>

注意

SpecialModule 及其子组件使用红色主题，App 使用墨绿色主题。

useToken 获取主题 token

• 自定义组件需要跟随主题变化时，不能硬编码颜色
• 使用 useToken Hook 获取当前 ConfigProvider 下的 token 对象
• token 包含 colorPrimary、colorText、colorBg 等所有 Design Token
• 可用于动态设置样式、Canvas 绘图、图表配色等场景

使用示例

import { useToken } from "antd";
const CustomCard = () => {
  const { token } = useToken();
  return (
    <div
      style={{
        backgroundColor: token.colorBgContainer,
        color: token.colorText,
        borderLeft: `4px solid ${token.colorPrimary}`,
      }}
    >
      自定义卡片
    </div>
  );
};

项目实战

• 把主题配置集中到一个文件，如 src/theme/index.ts
• 导出 themeConfig 对象，在 main.tsx 或 App.tsx 中引入
• 不要分散在多个 ConfigProvider 中硬编码颜色
• 主题色值建议用设计规范命名，如 PRIMARY_COLOR
• 为后续支持多主题、主题切换功能预留扩展接口

// src/theme/index.ts
export const themeConfig = {
  token: {
    colorPrimary: "#1D6C0D",
    colorSuccess: "#52c41a",
    colorWarning: "#faad14",
    colorError: "#f5222d",
    borderRadius: 4,
  },
};
// main.tsx
import { themeConfig } from "./theme";
<ConfigProvider theme={themeConfig}>
  <App />
</ConfigProvider>;

主题色与CSSModule结合

• CSS Module 解决样式隔离问题，不负责主题变量
• 自定义组件可用 useToken 动态获取主题色
• 避免在 CSS Module 中写死颜色，导致主题切换后失效

常见错误

• ConfigProvider 没有放在最外层，导致部分组件没有主题上下文
• theme.token 拼写错误，如写成 theme.tokens
• algorithm 切换后自定义组件没有跟随变暗
• useToken 在 ConfigProvider 外部使用，拿到默认 token
• 在 CSS Module 中直接写死颜色，导致主题切换不生效
• 只修改按钮颜色而不配置 ConfigProvider，无法影响整个系统