Ant Design BorderBeam 线宽控制：lineWidth 参数的取值规则、CSS 变量链路与主题覆盖机制

lineWidth 是 Ant Design BorderBeam（边框流光）组件中控制单条流光粗细的参数：数字按像素处理，默认值为 1px，从版本 6.5.0 开始提供。本文基于官方演示文档 line-width.md 与配套示例代码，结合 BorderBeam.tsx、style/index.ts 的源码实现和测试用例，讲清 lineWidth 从属性传入到最终影响渲染的完整链路，以及它与容器边框宽度、全局主题 token 之间的关系。

演示场景：用 lineWidth 匹配容器边框

官方演示 line-width.tsx 的用法如下：

import React from 'react';
import { BorderBeam, Card } from 'antd';

const App: React.FC = () => (
  <div style={{ width: 360 }}>
    <BorderBeam lineWidth={2}>
      <Card title="Custom line width" style={{ borderWidth: 2 }}>
        Set lineWidth to match the border width of this container.
      </Card>
    </BorderBeam>
  </div>
);

export default App;

这个示例传递了两处信息：

• lineWidth={2}：流光层的宽度被设为 2px；
• 内层 Card 的 borderWidth: 2：容器自身真实边框也是 2px。

两者保持一致是刻意的——流光层会以内缩方式贴合容器边缘，若流光线宽与容器真实边框宽度不一致，视觉上会出现“流光浮在边框外侧”的错位感。组件 API 说明（见 index.zh-CN.md）中对 lineWidth 的定义是：

参数	说明	类型	默认值	版本
lineWidth	流光线宽，数字类型按像素处理	number | string	1px	6.5.0

即 lineWidth 接受 number 或 string：

• 传数字（如 2、3）时按像素处理，等价于 2px；
• 传字符串（如 '0.25rem'、'2px'）时原样生效，因此可以使用 rem、em 等相对单位。

源码链路：lineWidth 如何变成 CSS 变量

在 BorderBeam.tsx 中，组件把 lineWidth 写入一个内联 CSS 变量：

...(isNonNullable(lineWidth) && { [varName('line-width')]: unit(lineWidth) }),

这里 unit() 来自 @ant-design/cssinjs，负责给纯数字自动补 px 后缀——这正是“数字按像素处理”的实现来源；而 isNonNullable 判断保证了不传 lineWidth 时不设置该变量，交由样式层回退到默认值。

样式定义在 style/index.ts 中，流光层（.ant-border-beam）通过该变量控制 padding：

[componentCls]: {
  // Container
  display: 'none',
  position: 'absolute',
  inset: varRef('inset-offset', '0px'),
  borderRadius: 'inherit',
  zIndex: 1,
  overflow: 'hidden',
  pointerEvents: 'none',

  // Border Beam
  padding: varRef('line-width', unit(lineWidth)),
  // ...
}

varRef('line-width', unit(lineWidth)) 的含义是：优先取内联设置的 --ant-border-beam-line-width 变量；若未设置，则回退到主题全局 token lineWidth（Ant Design 默认值为 1，即 1px）。也就是说，“默认值 1px”实际上来自全局主题 token 的回退，而非组件写死的字面量。

从源码结构看，lineWidth 影响的是流光容器的 padding：容器是一个覆盖在子节点上、overflow: hidden 的绝对定位层，内部用 mask 挖空中心区域、只保留边缘一圈可见区域（见 style/index.ts 中的 mask-composite 规则）。padding 增大，被 mask 挖掉的中心区域相应变小，露出的边缘“环形带”就变宽——这就是流光线宽的视觉来源。

流光层如何贴合容器边缘：inset 与边框宽度

lineWidth 只决定流光粗细，流光层与容器边缘的贴合由 inset-offset 变量控制。在 BorderBeam.tsx 中：

const insetOffset = useMemo<string>(() => {
  return isNonNullable(outset) ? getInset(outset) : borderWidth.map<string>(getInset).join(' ');
}, [borderWidth, outset]);

borderWidth 来自 useBorderSize.ts 钩子——它通过 getComputedStyle 读取被装饰子节点的上、右、下、左四条边框宽度，并转成负的 inset 值。这样即使容器有 2px 真实边框，流光层也会精确内缩到边框内侧，而不是盖在边框外面。

演示快照（demo.test.ts.snap）验证了这一点，line-width 演示渲染出的流光层样式为：

style="--ant-border-beam-line-width: 2px; --ant-border-beam-inset-offset: -2px -2px -2px -2px;"

即 lineWidth={2} 生成了 --ant-border-beam-line-width: 2px，同时从子节点的 2px 边框推导出四向 -2px 的内缩偏移。这也解释了官方演示为何要求 lineWidth 与 borderWidth 保持一致：前者决定流光带宽度，后者决定流光层贴边位置，两者对齐后流光才能“正好走在边框上”。

如果容器处于会裁剪溢出的环境中，还可以用 outset 参数（number | string）显式指定流光层相对容器边缘的外扩距离；官方文档建议裁剪容器可将其设为 0。

主题级覆盖：通过 ConfigProvider 修改默认线宽

除了逐实例传属性，lineWidth 还可以通过主题配置整体调整。官方演示 component-token.tsx 展示了两种效果并排对比：

<ConfigProvider
  theme={{
    components: {
      BorderBeam: {
        lineWidth: 3,
      },
    },
  }}
>
  <Panel title="Custom line width" desc="Override lineWidth from theme.token." />
</ConfigProvider>

由于组件实例未直接传 lineWidth 属性（内联 CSS 变量不会被设置），流光层回退到主题 token lineWidth: 3，等价于默认 3px。属性优先级高于主题配置：tests/index.test.tsx 中的 should support customizing line width with prop 用例同时设置了 ConfigProvider 主题 lineWidth: 3 和实例属性 lineWidth={5}，断言最终生效的是 5px。

同一测试用例还覆盖了两种取值形态与“清除属性”的行为：

• lineWidth={5} → CSS 变量值为 5px（数字补 px）；
• lineWidth="0.25rem" → 变量值原样为 0.25rem（字符串透传）；
• 重新渲染为不带 lineWidth 的 <BorderBeam> → 变量被移除（''），回退到主题 token 默认值。

实践要点与注意事项

结合文档与源码，使用 lineWidth 时建议关注以下几点：

1. 与容器边框宽度对齐：被装饰容器若有真实 CSS 边框，让 lineWidth 与边框宽度一致（如演示中 lineWidth={2} 配 borderWidth: 2），视觉上最自然；边框宽度不同会导致流光带与边框错位。
2. 默认值来源：不传 lineWidth 时，线宽取全局主题 token lineWidth（Ant Design 默认 1px），修改全局 token 即可影响所有未显式设置的流光。
3. 单位选择：需要随根字号缩放时传字符串（如 '0.25rem'）；普通场景传数字最简洁。
4. 与 outset 的分工：lineWidth 控制流光“多粗”，outset 控制流光层“外扩多远”（默认按子节点实际边框宽度自动内缩），二者共同决定流光的落位。
5. 环境约束：流光效果依赖 offset-path、mask-composite 等现代 CSS 能力，组件用 @supports 探测（见 style/index.ts）；在不支持或命中 prefers-reduced-motion: reduce 时流光会整体隐藏，lineWidth 此时不产生可见效果。

小结

lineWidth 的参数语义在 line-width.md 中一句话讲清：“数字类型按像素处理，默认 1px”。落到实现上，它经由 unit() 归一化后写成内联 CSS 变量 --ant-border-beam-line-width，作用于流光容器的 padding 从而决定边缘可见带的宽度；缺省时回退到主题 token，实例属性优先于 ConfigProvider 配置，number 补 px、string 原样透传——这些行为均有 tests/index.test.tsx 的断言与演示快照作为可验证依据。掌握这条“属性 → CSS 变量 → padding/mask”的链路后，再配合 outset、size、duration 等参数，即可对 BorderBeam 的视觉细节做精确调校。