Ant Design主题变量文档：设计 tokens 与开发指南-优快云博客

Ant Design主题变量文档：设计 tokens 与开发指南

【免费下载链接】ant-design An enterprise-class UI design language and React UI library 项目地址: https://gitcode.com/gh_mirrors/antde/ant-design

Ant Design 设计规范和技术上支持灵活的样式定制，以满足业务和品牌上多样化的视觉需求，包括但不限于全局样式（主色、圆角、边框）和指定组件的视觉定制。官方文档详细说明了定制方案：docs/react/customize-theme.zh-CN.md。

设计 Token 体系

在 5.0 版本的 Ant Design 中，设计团队提供了一套全新的定制主题方案。不同于 4.x 版本的 less 和 CSS 变量，有了 CSS-in-JS 的加持后，动态主题的能力也得到了加强，包括但不限于：支持动态切换主题、支持同时存在多个主题、支持针对某个/某些组件修改主题变量等。

Token 三层结构

Design Token 分为 Seed Token、Map Token 和 Alias Token 三部分，形成三层派生关系：

mermaid

Seed Token：所有设计意图的起源，如 colorPrimary、borderRadius 等
Map Token：基于 Seed 派生的梯度变量，如 colorPrimaryBg、colorPrimaryText 等
Alias Token：用于批量控制某些共性组件的样式，基本上是 Map Token 别名

演变过程

Design Token 的演变过程展示了从基础变量到最终应用的完整流程：

THE 0TH POSITION OF THE ORIGINAL IMAGE

快速上手：配置主题

通过 ConfigProvider 组件的 theme 属性，可以轻松配置主题。在升级 v5 后，将默认使用 v5 的主题。

修改主题变量

通过 theme 中的 token 属性，可以修改一些主题变量。部分主题变量会引起其他主题变量的变化，我们把这些主题变量称为 Seed Token。

import { Button, ConfigProvider, Space } from 'antd';
import React from 'react';

const App: React.FC = () => (
  <ConfigProvider
    theme={{
      token: {
        // Seed Token，影响范围大
        colorPrimary: '#00b96b',
        borderRadius: 2,

        // 派生变量，影响范围小
        colorBgContainer: '#f6ffed',
      },
    }}
  >
    <Space>
      <Button type="primary">Primary</Button>
      <Button>Default</Button>
    </Space>
  </ConfigProvider>
);

export default App;

使用预设算法

通过修改算法可以快速生成风格迥异的主题，5.0 版本中默认提供三套预设算法：

默认算法 theme.defaultAlgorithm
暗色算法 theme.darkAlgorithm
紧凑算法 theme.compactAlgorithm

import React from 'react';
import { Button, ConfigProvider, Input, Space, theme } from 'antd';

const App: React.FC = () => (
  <ConfigProvider
    theme={{
      // 单独使用暗色算法
      algorithm: theme.darkAlgorithm,
      
      // 组合使用暗色算法与紧凑算法
      // algorithm: [theme.darkAlgorithm, theme.compactAlgorithm],
    }}
  >
    <Space>
      <Input placeholder="Please Input" />
      <Button type="primary">Submit</Button>
    </Space>
  </ConfigProvider>
);

export default App;

组件级主题定制

除了整体的 Design Token，各个组件也会开放自己的 Component Token 来实现针对组件的样式定制能力，不同的组件之间不会相互影响。

修改组件变量

import React from 'react';
import { ConfigProvider, Button, Space, Input, Divider } from 'antd';

const App: React.FC = () => (
  <>
    <ConfigProvider
      theme={{
        components: {
          Button: {
            colorPrimary: '#00b96b',
            algorithm: true, // 启用算法
          },
          Input: {
            colorPrimary: '#eb2f96',
            algorithm: true, // 启用算法
          }
        },
      }}
    >
      <Space>
        <div style={{ fontSize: 14 }}>开启算法：</div>
        <Input placeholder="Please Input" />
        <Button type="primary">Submit</Button>
      </Space>
    </ConfigProvider>
    <Divider />
    <ConfigProvider
      theme={{
        components: {
          Button: {
            colorPrimary: '#00b96b',
          },
          Input: {
            colorPrimary: '#eb2f96',
          }
        },
      }}
    >
      <Space>
        <div style={{ fontSize: 14 }}>禁用算法：</div>
        <Input placeholder="Please Input" />
        <Button type="primary">Submit</Button>
      </Space>
    </ConfigProvider>
  </>
);

export default App;

默认情况下，所有组件变量都仅仅是覆盖，不会基于 Seed Token 计算派生变量。在 >= 5.8.0 版本中，组件变量支持传入 algorithm 属性，可以开启派生计算或者传入其他算法。

进阶使用技巧

动态切换主题

在 v5 中，动态切换主题对用户来说是非常简单的，你可以在任何时候通过 ConfigProvider 的 theme 属性来动态切换主题，而不需要任何额外配置。

import { Button, ConfigProvider, Space, Input, ColorPicker, Divider } from 'antd';
import React from 'react';

const App: React.FC = () => {
  const [primary, setPrimary] = React.useState('#1677ff');

  return (
    <>
      <ColorPicker showText value={primary} onChangeComplete={(color) => setPrimary(color.toHexString())} />
      <Divider />
      <ConfigProvider
        theme={{
          token: {
            colorPrimary: primary,
          },
        }}
      >
        <Space>
          <Input placeholder="Please Input" />
          <Button type="primary">Submit</Button>
        </Space>
      </ConfigProvider>
    </>
  );
}

export default App;

局部主题（嵌套主题）

可以嵌套使用 ConfigProvider 来实现局部主题的更换。在子主题中未被改变的 Design Token 将会继承父主题。

import React from 'react';
import { Button, ConfigProvider, Space } from 'antd';

const App: React.FC = () => (
  <ConfigProvider
    theme={{
      token: {
        colorPrimary: '#1677ff',
      },
    }}
  >
    <Space>
      <Button type="primary">Theme 1</Button>
      <ConfigProvider
        theme={{
          token: {
            colorPrimary: '#00b96b',
          },
        }}
      >
        <Button type="primary">Theme 2</Button>
      </ConfigProvider>
    </Space>
  </ConfigProvider>
);

export default App;

使用 Design Token

如果你希望使用当前主题下的 Design Token，我们提供了 useToken 这个 hook 来获取 Design Token。

import React from 'react';
import { Button, theme } from 'antd';

const { useToken } = theme;

const App: React.FC = () => {
  const { token } = useToken();

  return (
    <div
      style={{
        backgroundColor: token.colorPrimaryBg,
        padding: token.padding,
        borderRadius: token.borderRadius,
        color: token.colorPrimaryText,
        fontSize: token.fontSize,
      }}
    >
      使用 Design Token
    </div>
  );
};

export default App;

静态消费（如 less）

当你需要非 React 生命周期消费 Token 变量时，可以通过静态方法 getDesignToken 将其导出：

import { theme } from 'antd';

const { getDesignToken } = theme;

const globalToken = getDesignToken();

如果需要将其应用到静态样式编译框架，如 less 可以通过 less-loader 注入：

{
  loader: "less-loader",
  options: {
    lessOptions: {
      modifyVars: mapToken,
    },
  },
}

调试主题

我们提供了帮助用户调试主题的工具：主题编辑器

你可以使用此工具自由地修改 Design Token，以达到你对主题的期望。

API 参考

Theme

属性	说明	类型	默认值
token	用于修改 Design Token	`AliasToken`	-
inherit	继承上层 ConfigProvider 中配置的主题。	boolean	true
algorithm	用于修改 Seed Token 到 Map Token 的算法	`(token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]`	`defaultAlgorithm`
components	用于修改各个组件的 Component Token 以及覆盖该组件消费的 Alias Token	`ComponentsConfig`	-
cssVar	开启 CSS 变量	`boolean \\| { prefix?: string; key?: string }`	false
hashed	组件 class Hash 值	boolean	true

SeedToken

完整的 SeedToken 定义可以在项目源码中查看：组件主题定义

Ant Design主题变量文档：设计 tokens 与开发指南