Ant Design Badge 组件 offset 属性详解：自定义徽标位置偏移的用法与源码实现

本篇围绕 Ant Design Badge 组件官方示例「自定义位置偏移」展开，讲清 offset 属性 [left, top] 的语义、生效边界，并深入 Badge 源码 与 样式定义，说明偏移值是如何映射为真实 CSS、在 RTL 布局下如何保持正确，以及测试用例对其行为的验证，帮助你在复杂布局中精确微调徽标与状态点的位置。

一、offset 的官方定义：[left, top] 偏移格式

官方示例文档 offset.md 对这一能力的描述非常简洁：

设置状态点的位置偏移，格式为 [left, top]，表示状态点距默认位置左侧、上方的偏移量。

对应到组件 API（见 index.zh-CN.md 的 Badge 参数表）：

参数	说明	类型	默认值
offset	设置状态点的位置偏移	[number, number]	-

需要注意两个边界：该参数没有默认值，不传则徽标保持默认位置；在 ConfigProvider 的全局组件配置中不支持通过 componentSize/component config 统一注入（API 表中全局配置列标记为 ×），只能在单个 Badge 上按需设置。

官方示例 offset.tsx 完整代码如下：

import React from 'react';
import { Avatar, Badge } from 'antd';

const App: React.FC = () => (
  <Badge count={5} offset={[10, 10]}>
    <Avatar shape="square" size="large" />
  </Badge>
);

export default App;

这里 [10, 10] 表示：将徽标从默认位置向左偏移 10、向上偏移 10（视觉上即徽标向右、向下挪动，远离头像角落）。该示例在组件文档页注册为「自定义位置偏移」演示（index.zh-CN.md 中的 <code src="./demo/offset.tsx">自定义位置偏移</code>）。

二、源码解析：offset 如何被映射为 CSS 样式

1. 类型定义比文档更宽松

文档中 offset 标注为 [number, number]，但从 Badge.tsx 的 BadgeProps 定义看：

offset?: [number | string, number | string];

两个位置都额外允许 string。这一点在实现上是有意义的：marginTop 等 CSS 属性本身接受带单位的字符串（如 '10px'），源码对垂直偏移是直接透传的（见下文）。

2. offsetStyle：偏移值的 CSS 映射核心

真正的映射逻辑集中在 Badge.tsx 第 127-138 行：

const offsetStyle = useMemo<React.CSSProperties | undefined>(() => {
  if (!offset) {
    return undefined;
  }

  const horizontalOffset = Number.parseInt(offset[0] as string, 10);

  return {
    marginTop: offset[1],
    insetInlineEnd: -horizontalOffset,
  };
}, [offset]);

从这段实现可以确认三个关键事实：

1. offset[1]（top）→ marginTop：垂直偏移通过 marginTop 直接加到徽标元素上，直接透传，因此支持 number 或 string；
2. offset[0]（left）→ insetInlineEnd 取负值：水平偏移被 Number.parseInt 解析后取负，作用于逻辑属性 insetInlineEnd。取负的物理含义是：默认徽标贴住容器内联末端（右侧），将其向内（向左，即远离右上角）推；
3. 水平偏移只做整数解析：Number.parseInt(offset[0], 10) 意味着传入字符串时只取整数部分；而垂直偏移不做解析，原样透传。

offsetStyle 以 [offset] 作为 useMemo 依赖，只有 offset 引用变化才会重新计算。

3. 基准定位：为什么偏移是「相对默认位置」

offset 生效的前提是徽标有一个默认锚点。查看 style/index.ts 第 239-244 行，计数徽标、小圆点（dot）与自定义计数节点的公共定位规则为：

[`${componentCls}-count, ${componentCls}-dot, ${numberPrefixCls}-custom-component`]: {
  position: 'absolute',
  top: 0,
  insetInlineEnd: 0,
  transform: 'translate(50%, -50%)',
  transformOrigin: '100% 0%',
  // ...
}

即默认位置是子元素右上角：绝对定位、贴住顶部与内联末端，再通过 translate(50%, -50%) 让徽标中心恰好落在角点上。理解了这一点，offset 的语义就自洽了——它是在这个基准位置之上的增量位移，而非绝对坐标。

三、两种渲染模式下 offsetStyle 的应用路径

Badge 有两类渲染形态，offsetStyle 的注入位置不同（均可在 Badge.tsx 中验证）：

1. 包裹模式（有 children，显示 count / dot）

在第 287-290 行，偏移样式先于语义化样式合并进指标元素：

let scrollNumberStyle: React.CSSProperties = {
  ...offsetStyle,
  ...mergedStyles.indicator,
};

offsetStyle 最终通过 ScrollNumber 的 style 属性应用到真正渲染的计数/圆点元素上。这意味着 offset 影响的是右上角那个圆点本身，而不是外层 .ant-badge 容器。

2. 独立状态点模式（无 children，status + text）

当没有子元素且设置了 status/color 时，组件走状态点分支（第 241-257 行），此时 offsetStyle 被合并到根节点的 style 上：

<span
  ref={ref}
  {...restProps}
  className={badgeClassName}
  style={{ ...offsetStyle, ...mergedStyles.root }}
>

这正是示例文档中说「设置状态点的位置偏移」的原因——该模式下的独立状态点没有右上角锚点概念，偏移直接体现在其行内布局位置上。

3. 样式优先级

在包裹模式的整体 mergedStyle 中（第 140-143 行），合并顺序为：

{ ...offsetStyle, ...contextStyle, ...style }

也就是说，来自 ConfigProvider 的 contextStyle 和组件自身的 style prop 中若声明了同名属性（如 marginTop），会覆盖 offset 产生的偏移量。需要精确控制时，建议二选一，避免同属性打架。语义化的 styles.indicator（5.7.0+）则会在更晚的位置合并，可视为对指标元素最细粒度的覆盖手段。

四、RTL 支持：逻辑属性保证偏移方向随文字方向翻转

注意源码使用的不是 right，而是逻辑属性 insetInlineEnd。在 LTR 布局中 insetInlineEnd 等价于 right，而在 RTL 布局下它自动指向左侧——因此徽标锚点会镜像到左上角，偏移方向也随之正确翻转，无需业务侧做任何适配。

这一点有专门的回归测试。index.test.tsx 第 13-19 行 将带 offset 的 Badge 纳入了 RTL 快照测试：

rtlTest(() => (
  <Badge count={5} offset={[10, 10]}>
    <a href="#" className="head-example">
      head
    </a>
  </Badge>
));

五、测试对边界场景的验证

仓库测试中还覆盖了 count 为自定义 ReactNode 时 offset 依然生效的场景（index.test.tsx 第 146 行起，对应 issue #13694）：

it('should support offset when count is a ReactNode', () => {
  const { asFragment } = render(
    <Badge count={<span className="custom" style={{ color: '#f5222d' }} />} offset={[10, 20]}>
      <a href="#" className="head-example">
        head
      </a>
    </Badge>,
  );
  // ...
});

在 Badge.tsx 第 203-207 行 可以看到其支撑逻辑：当 count 是一个 React 元素时，组件会克隆该元素并注入 mergedStyle（其中包含 offsetStyle），保证自定义计数节点同样遵循偏移设置。此外，semantic.test.tsx 中的语义结构测试也以 offset={[8, 8]} 配合 styles.indicator 验证了两种偏移手段可以共存。

六、实践要点小结

结合源码与官方示例，使用 offset 时的可操作结论如下：

• 取值语义：offset={[left, top]} 是相对默认锚点（子元素右上角、徽标中心贴角）的增量偏移；数值越大徽标离角落越远，top 为负值可将徽标向角上推；
• 垂直偏移支持字符串：offset[1] 原样透传给 marginTop，可写 '12px' 这类带单位值；水平偏移经 parseInt 处理，按数值使用；
• 影响对象是徽标本体：包裹模式下偏移作用于 count/dot 元素而非外层容器，不会撑开或移动子元素布局；
• 与 style 的优先级：style 和 ConfigProvider 上下文中的 marginTop/insetInlineEnd 会覆盖 offset 的计算结果，同属性不要重复设置；
• RTL 无需额外处理：实现基于 insetInlineEnd 逻辑属性并配有 RTL 快照测试，偏移方向自动跟随文字方向。

以上所有行为均可在 components/badge/Badge.tsx、components/badge/style/index.ts 与 components/badge/tests/index.test.tsx 中逐行核对。