Ant Design 渐变按钮实战：用 ConfigProvider 全局配置与 CSS 伪元素实现线性渐变背景

本文以 Ant Design 官方示例 linear-gradient.tsx（渐变按钮 demo）为主体，完整讲解如何在不改动 Button 组件源码的前提下，通过 antd-style 的 createStyles 与 ConfigProvider 的组件级全局配置，为 type="primary" 按钮叠加一层线性渐变背景，并实现 hover 时的渐变淡出交互。读完本文，你可以掌握：渐变图层的 CSS 层叠技巧（::before + inset: -1px）、Ant Design 按钮类名体系（ant-btn-primary 等语义类）的利用方式，以及 ConfigProvider 组件级 className 配置的下发机制。

效果目标

该 demo 对应 components/button/index.zh-CN.md 中注册的「渐变按钮」示例（<code src="./demo/linear-gradient.tsx">渐变按钮</code>），文档描述为："自定义为渐变背景按钮"（Buttons with a gradient background）。

具体效果是：主按钮（primary）表面覆盖一层从 #6253e1（紫）到 #04befe（青）的 135 度线性渐变，鼠标悬停时渐变层透明度过渡到 0，露出下方实色主色按钮；默认按钮（default）不受影响。

完整示例代码

以下代码来自 components/button/demo/linear-gradient.tsx，可直接复制到自己的项目中使用：

import React from 'react';
import { AntDesignOutlined } from '@ant-design/icons';
import { Button, ConfigProvider, Space } from 'antd';
import { createStyles } from 'antd-style';

const useStyle = createStyles(({ cssVar, prefixCls, css }) => ({
  linearGradientButton: css`
    &.${prefixCls}-btn-primary:not([disabled]):not(.${prefixCls}-btn-dangerous) {
      > span {
        position: relative;
      }

      &::before {
        content: '';
        background: linear-gradient(135deg, #6253e1, #04befe);
        position: absolute;
        inset: -1px;
        opacity: 1;
        transition: all ${cssVar.motionDurationSlow};
        border-radius: inherit;
      }

      &:hover::before {
        opacity: 0;
      }
    }
  `,
}));

const App: React.FC = () => {
  const { styles } = useStyle();

  return (
    <ConfigProvider
      button={{
        className: styles.linearGradientButton,
      }}
    >
      <Space>
        <Button type="primary" size="large" icon={<AntDesignOutlined />}>
          Gradient Button
        </Button>
        <Button size="large">Button</Button>
      </Space>
    </ConfigProvider>
  );
};

export default App;

依赖说明：示例使用了 antd-style 的 createStyles。当前仓库 package.json 中已包含 "antd-style": "^4.1.0" 依赖；它提供 cssVar（读取 CSS 变量/主题 token）、prefixCls（自动解析前缀，默认 ant）等注入参数，让样式代码能兼容 ConfigProvider 自定义 prefixCls 的场景。

样式逻辑逐段拆解

1. 选择器：只命中"可用且非危险"的主按钮

&.${prefixCls}-btn-primary:not([disabled]):not(.${prefixCls}-btn-dangerous)

这一行精确圈定了渐变作用域，三个条件缺一不可：

• ant-btn-primary：主按钮类名。在 components/button/Button.tsx 的 classes 组装逻辑中，[${prefixCls}-${mergedType}]: mergedType 会把 type="primary" 映射为 ant-btn-primary 类（注释标明这是为兼容 5.21.0 之前版本的类名约定保留的）。
• :not([disabled])：排除原生 disabled 按钮，避免禁用的主按钮显示成鲜亮的渐变。
• :not(.ant-btn-dangerous)：排除危险主按钮。源码中 [${prefixCls}-dangerous]: danger 会在 danger 属性为真时添加该类，红色危险主按钮叠加紫色渐变会造成严重的视觉冲突。

2. > span { position: relative; }：建立文字图层层级

主按钮的内容包裹在 span 中（源码中 contentNode 由 spaceChildren 处理生成）。将其设为 position: relative 后，span 成为定位上下文，文字内容会渲染在后续的 ::before 伪元素之上，保证渐变覆盖背景但不会盖住文字与图标。

3. ::before 渐变层：核心技巧

&::before {
  content: '';
  background: linear-gradient(135deg, #6253e1, #04befe);
  position: absolute;
  inset: -1px;
  opacity: 1;
  transition: all ${cssVar.motionDurationSlow};
  border-radius: inherit;
}

• position: absolute; inset: -1px;：渐变层向四周各外扩 1px，正好"吃掉"按钮 1px 的边框区域，让渐变呈现为完整的实色表面（边框被渐变覆盖），视觉上更饱满。
• border-radius: inherit;：继承按钮根元素的圆角，避免渐变矩形四角溢出圆角范围。
• transition: all ${cssVar.motionDurationSlow};：cssVar.motionDurationSlow 是 Ant Design 主题系统的 CSS 变量，对应通用 map token motionDurationSlow。从源码看，components/theme/themes/shared/genCommonMapToken.ts 中该 token 由 ${(motionBase + motionUnit * 3).toFixed(1)}s 计算得出，而 components/theme/themes/seed.ts 中默认 motionUnit: 0.1、motionBase: 0，因此默认值为 0.3s。相比写死 0.3s，使用 token 能让渐变动效跟随用户主题（如暗色主题、自定义 motion 配置）自动调整。

4. hover 交互：渐变淡出而非切换颜色

&:hover::before {
  opacity: 0;
}

悬停时不是更换渐变，而是把渐变层透明度过渡到 0，底层实色 primary 背景显现。这样 hover 过渡只涉及 opacity，由浏览器合成器加速，性能开销远低于过渡 background 颜色本身。

为什么用 ConfigProvider 的组件级配置下发

示例没有把 styles.linearGradientButton 直接写到 <Button className=...> 上，而是这样注入：

<ConfigProvider
  button={{
    className: styles.linearGradientButton,
  }}
>

这是 Ant Design 5.x 引入的组件级全局配置能力（组件 Token / componentConfig）。从 components/button/Button.tsx 的实现可以看到其落地链路：

1. 组件内部通过 useComponentConfig('button') 读取上下文配置，其中就包含 className: contextClassName；
2. 在最终渲染时，clsx(...) 的类名列表末尾依次拼入了 className（本按钮自身）、rootClassName 和 contextClassName（来自 ConfigProvider 的全局类名）；
3. 因此只要处于该 ConfigProvider 作用域内的所有 <Button> 都会自动带上渐变样式类，而选择器本身已经把范围限制为 primary 按钮，<Button size="large">Button</Button>（默认按钮）自然不受影响。

相比逐按钮传 className，这种方式适合"整站/整页统一品牌化"的场景，一处配置、全局生效，且作用域可通过嵌套多个 ConfigProvider 灵活裁剪。

适用前提与限制

• 该示例依赖 antd 的 Button、ConfigProvider、Space 组件与 antd-style 包，以及 @ant-design/icons 中的 AntDesignOutlined 图标；
• 渐变只作用于 type="primary" 且非 disabled、非 danger 的按钮；若你的项目同时使用 color / variant 新 API（如 color="primary" variant="solid"），源码中该写法同样会映射为 primary 语义，可参考 components/button/index.zh-CN.md 中 FAQ「类型和颜色与变体如何选择」了解 type 与 color/variant 的映射关系；
• 若需要调整渐变角度、色值或动效时长，直接修改 linear-gradient(135deg, ...) 与 cssVar.motionDurationSlow 即可；
• ConfigProvider 的 button.className 会下发到作用域内所有 Button 实例，若只想作用于局部页面，请把 ConfigProvider 包裹范围收窄到对应子树，而不是挂到应用根部。

小结

这个渐变按钮示例展示了 Ant Design 定制样式的典型路径：利用组件源码稳定的语义类名（ant-btn-primary / ant-btn-dangerous）编写外部样式，用 CSS 伪元素叠加装饰层，通过主题 token（motionDurationSlow）保持动效一致性，再用 ConfigProvider 的组件级配置实现批量下发。整条链路不需要 fork 或修改 antd 源码，升级组件版本时样式依然兼容，是品牌化定制中成本最低、可维护性最高的做法。