@ant6-mode/theme

基于 CMI UI 规范的 Ant Design 主题定制包，兼容 Ant Design 5.x 和 6.x，为项目提供统一的 Design Token、组件主题配置、CSS 样式覆盖和常用布局常量。

本包使用 Ant Design 的 ConfigProvider Token 体系实现换肤，不使用 Ant Design 3/4 的 Less modifyVars 配置方式。

提供内容

| 导出 | 用途 | | --- | --- | | themeConfig | 可直接传给 ConfigProvider 的完整主题配置。 | | ThemeProvider | 已封装的主题 Provider，支持局部 Token 覆盖。 | | modalWidths | 弹窗、抽屉的预设宽度，便于项目内统一控制。 | | seedToken | 品牌主色、功能色、基础字体、圆角等种子 Token。 | | mapTokenOverrides | Map Token 覆盖配置。 | | aliasTokenOverrides | 文字、背景、边框、阴影等语义化 Token 覆盖配置。 | | componentTokens | Button、Form、Table、Modal 等组件级 Token。 | | cmiExtendedColors | CMI 扩展颜色，供业务 CSS 或代码引用。 | | typographyScale | CMI 字阶定义。 | | listPageSpacing、detailPageLayout | 列表页、详情页的布局常量。 |

安装

npm install @ant6-mode/theme

使用方项目应已安装以下运行时依赖：

• Node.js >= 18
• React >= 18
• Ant Design ^5.12.0 或 ^6.0.0

快速开始

在应用根节点引入主题配置和 CSS 覆盖，并通过 Ant Design 的 ConfigProvider 注入主题。

import React from 'react';
import { ConfigProvider } from 'antd';
import { themeConfig } from '@ant6-mode/theme';
import '@ant6-mode/theme/css';

export default function App() {
  return (
    <ConfigProvider theme={themeConfig}>
      <YourApplication />
    </ConfigProvider>
  );
}

也可以使用包内封装的 ThemeProvider：

import React from 'react';
import { ThemeProvider } from '@ant6-mode/theme';
import '@ant6-mode/theme/css';

export default function App() {
  return (
    <ThemeProvider>
      <YourApplication />
    </ThemeProvider>
  );
}

局部覆盖主题

ThemeProvider 支持通过 themeOverrides 在保留默认主题的基础上进行局部覆盖。

import { ThemeProvider } from '@ant6-mode/theme';

export default function App() {
  return (
    <ThemeProvider
      themeOverrides={{
        token: {
          colorPrimary: '#1677ff',
          borderRadius: 6,
        },
        components: {
          Button: {
            primaryShadow: 'none',
          },
        },
      }}
    >
      <YourApplication />
    </ThemeProvider>
  );
}

Umi 4 Max + React 18 + Ant Design 5/6 接入

推荐在 Umi 的运行时入口 src/app.tsx 中全局引入 CSS 覆盖，并用 rootContainer 包裹应用根节点。该方式不依赖 Less 配置，适用于 Umi 4 Max、React 18 和 Ant Design 5/6。

// src/app.tsx
import type { RuntimeConfig } from '@umijs/max';
import { ThemeProvider } from '@ant6-mode/theme';
import '@ant6-mode/theme/css';

export function rootContainer(
  container: React.ReactNode,
  _args: RuntimeConfig,
) {
  return <ThemeProvider>{container}</ThemeProvider>;
}

如果项目已有 ConfigProvider，可不使用 ThemeProvider，而是将 themeConfig 传给现有 Provider：

import { ConfigProvider } from 'antd';
import { themeConfig } from '@ant6-mode/theme';
import '@ant6-mode/theme/css';

export function rootContainer(container: React.ReactNode) {
  return <ConfigProvider theme={themeConfig}>{container}</ConfigProvider>;
}

仅应保留一种根层 ConfigProvider / ThemeProvider 接入方式，避免重复注入主题配置。

在 Umi 配置中接入

如果项目已通过 @umijs/max 的 Ant Design 配置统一管理 ConfigProvider，可在 config/config.ts 中直接使用主题对象，并继续在 src/app.tsx 导入 CSS 覆盖：

// config/config.ts
import { defineConfig } from '@umijs/max';
import { themeConfig } from '@ant6-mode/theme';

export default defineConfig({
  antd: {
    configProvider: {
      theme: themeConfig,
    },
  },
});

// src/app.tsx
import '@ant6-mode/theme/css';

若当前 @umijs/max 版本的 antd 配置类型未提供 configProvider，请使用上面的 rootContainer 方式；它不依赖 Umi 插件的配置能力。

不使用旧版 Less 换肤配置

本包不提供，也不需要以下旧版 Ant Design 3/4 配置：

// 不需要使用
lessOptions: {
  modifyVars: theme,
  javascriptEnabled: true,
}

同样不需要 sass-resources-loader、@import '~package/path.less' 等全局注入方式。样式只需在应用入口引入：

import '@ant6-mode/theme/css';

CSS 变量

主题默认启用 Ant Design CSS 变量模式。运行时生成的变量以 --ant- 为前缀，可在业务 CSS 中引用：

.page-title {
  color: var(--ant-color-text);
  background: var(--ant-color-bg-container);
  border: 1px solid var(--ant-color-border);
}

请在应用入口引入一次 CSS 覆盖文件：

import '@ant6-mode/theme/css';

也可以按需引入单个覆盖文件：

import '@ant6-mode/theme/css/table.css';

Token 使用规则

文字与图标

优先使用语义化 Token，而不是直接写固定颜色值。

| Token | 使用场景 | | --- | --- | | colorText | 标题、正文、字段值。 | | colorTextSecondary | 字段名称、辅助文字。 | | colorTextTertiary | Placeholder、引导语。 | | colorTextQuaternary / colorTextDisabled | 禁用文字。 | | colorPrimary | 链接、主操作、强调信息。 |

文字颜色建议：同一页面通常不超过三种；特殊场景最多四种。具体规则可从 textColorRules 导入。

import { textColorRules } from '@ant6-mode/theme';

console.log(textColorRules.maxColorsPerPage); // 3

背景与交互状态

| Token | 使用场景 | | --- | --- | | colorBgContainer | 卡片、表单等容器背景。 | | colorBgElevated | 弹窗、浮层等抬升容器背景。 | | colorBgLayout | 页面背景。 | | colorFill | 常规浅灰填充。 | | colorFillSecondary / colorPrimaryBg | 主色弱化背景、选中背景。 | | colorFillTertiary | 列表表头、分页默认背景等。 | | colorBgTextHover | 文字型按钮、菜单项等悬停背景。 |

边框与分割线

| Token | 使用场景 | | --- | --- | | colorBorder | 页面卡片、表单控件等轮廓线。 | | colorBorderSecondary | 辅助边框。 | | colorSplit | 分割线。 |

阴影与圆角

| Token | 使用场景 | | --- | --- | | borderRadius | 默认圆角。 | | boxShadow | 弹窗、浮层等抬升对象。 | | boxShadowSecondary | 轻量的局部阴影。 |

颜色色板

Ant Design 会基于 colorPrimary、colorInfo、colorSuccess、colorWarning 和 colorError 自动生成交互态色阶。业务实现应优先选用语义化 Token，例如：

• 主操作：colorPrimary
• 信息提示：colorInfo
• 成功状态：colorSuccess
• 警告状态：colorWarning
• 错误状态：colorError

如需按 CMI 规范使用扩展颜色，可导入 cmiExtendedColors：

import { cmiExtendedColors } from '@ant6-mode/theme';

const selectedBackground = cmiExtendedColors.colorBgSelected;

字阶

通过 typographyScale 使用 CMI 预设字阶，避免在业务中随意定义字号、行高和字重。

import { typographyScale } from '@ant6-mode/theme';

const titleStyle = typographyScale.heading1;
// { fontSize: 18, lineHeight: 26, fontWeight: 500, usage: '内容标题' }

可用级别：

| 级别 | 字号 / 行高 | 典型场景 | | --- | --- | --- | | heading1 | 18 / 26 | 内容标题。 | | heading2 | 14 / 22 | 标题名称、弹窗标题。 | | heading3 | 14 / 22 | 标题型 Tab、列表标题。 | | body | 14 / 22 | 列表、会话、按钮文字。 | | bodyAuxiliary、auxiliary | 12 / 20 | 标签和辅助文字。 | | auxiliarySmall、auxiliaryMinimal | 10 / 12 | 小型标签等。 |

页面布局常量

import {
  approvalCommentTypography,
  detailPageLayout,
  listPageSpacing,
  responsiveBreakpoints,
} from '@ant6-mode/theme';

• listPageSpacing：搜索条件、操作按钮、结果区和分页区域的标准间距。
• detailPageLayout：详情页设计基准、审批区宽度、意见框高度等。
• approvalCommentTypography：审批流评论的字阶和颜色。
• responsiveBreakpoints：列表搜索区、详情页表单的响应式断点。

弹窗与抽屉宽度

使用 modalWidths 统一项目内的 Modal 和 Drawer 尺寸：

import { Modal } from 'antd';
import { modalWidths } from '@ant6-mode/theme';

export function Demo() {
  return (
    <Modal title="测试弹窗" width={modalWidths.md} open>
      内容
    </Modal>
  );
}

| 档位 | 宽度 | | --- | --- | | default | 420px | | xs | 208px | | sm | 480px | | md | 720px | | lg | 816px | | xl | 1008px |

直接使用 ThemeConfig

当项目需要自行组合主题时，可分别导入 Token：

import { ConfigProvider } from 'antd';
import {
  aliasTokenOverrides,
  componentTokens,
  mapTokenOverrides,
  seedToken,
} from '@ant6-mode/theme';

const customTheme = {
  token: {
    ...seedToken,
    ...mapTokenOverrides,
    ...aliasTokenOverrides,
    colorPrimary: '#1677ff',
  },
  components: componentTokens,
  cssVar: {},
};

export function App() {
  return (
    <ConfigProvider theme={customTheme}>
      <YourApplication />
    </ConfigProvider>
  );
}

主要导出

export {
  ThemeProvider,
  themeConfig,
  seedToken,
  mapTokenOverrides,
  aliasTokenOverrides,
  cmiExtendedColors,
  componentTokens,
  typographyScale,
  textColorRules,
  listPageSpacing,
  detailPageLayout,
  approvalCommentTypography,
  responsiveBreakpoints,
  modalWidths,
};

兼容性与限制

• 已通过 Ant Design 5.12.0 与 6.0.0 的 TypeScript 类型检查和构建验证；AntD 5.12.0 同时完成服务端渲染 smoke 检查。运行 AntD 6 的完整 smoke 检查需要 Node.js 18 或更高版本。
• 本包基于 ConfigProvider 的 Design Token 和 CSS 变量机制，不支持 Ant Design 3/4 的 Less modifyVars 换肤方式。
• CSS 覆盖文件使用 Ant Design 默认 .ant-* 类名，因此仅支持默认 prefixCls="ant"。设置自定义 prefixCls 后，Token 主题仍可使用，但 CSS 细节覆盖不保证生效。
• 必须在应用入口全局引入 @ant6-mode/theme/css；只注入 themeConfig 时，Token 生效，但组件细节 CSS 覆盖不会加载。
• CSS 覆盖依赖已测试版本的组件 DOM 结构。升级到新的 Ant Design 主版本或较大次版本后，请重新执行兼容性验证。

双版本验证

# 在隔离目录中安装 Ant Design 5.12.0，执行类型检查、构建与 smoke 检查
npm run test:antd5

# 在隔离目录中安装 Ant Design 6.0.0，执行类型检查与构建
npm run test:antd6

运行 AntD 6 的完整运行时 smoke 检查需要 Node.js >= 18。

说明

• 主题样式应由 Token 驱动，优先使用语义化 Token，避免在业务代码中重复写固定颜色、间距和阴影。
• 组件级样式以 Ant Design 的 Component Token 为准；具体可用字段请参考当前使用版本的 Ant Design 类型提示。
• CSS 覆盖文件用于补充部分组件的细节样式，应在应用入口全局引入一次。