ant-design Anchor 语义化结构定制：classNames 与 styles 精细样式控制实战指南

本文围绕 ant-design 中 Anchor 组件的 classNames 与 styles 两个语义化定制属性展开，基于官方示例 自定义语义结构的样式和类（6.0.0 起提供），讲解如何用对象/函数形式精准控制 Anchor 的 4 个语义节点（root / item / itemTitle / indicator）的类名与行内样式，并结合 Anchor.tsx、AnchorLink.tsx 与 useMergeSemantic 源码，讲清这些样式属性在组件内部的合并、分发与落地链路，帮助你在不覆盖整个组件样式的前提下完成主题化、条件化与细粒度的样式定制。

背景：为什么需要语义化结构定制

Anchor 组件文档 的核心能力是在页面内跳转到指定锚点并高亮当前区块，其 DOM 由固定前缀类（ant-anchor-wrapper、ant-anchor-link、ant-anchor-link-title、ant-anchor-ink）渲染。如果业务中需要对「锚点容器」「单个链接项」「链接标题」「滑动指示器」分别施加样式，传统的 className + 深度选择器写法耦合严重且难以随组件升级维护。

自 6.0.0 起，Anchor 引入了统一的语义化结构定制能力（与全站其他组件一致的 classNames / styles 规范）：

• classNames：Record<SemanticDOM, string> | (info: { props }) => Record<SemanticDOM, string>，为每个语义节点追加自定义 class，便于在样式文件中编写规则；
• styles：Record<SemanticDOM, CSSProperties> | (info: { props }) => Record<SemanticDOM, CSSProperties>，为每个语义节点注入行内 style，适合动态计算值。

两者均为对象或函数两种形态，函数形态可拿到 { props } 上下文，实现条件化样式。

四个语义节点及其职责

语义结构预览示例 定义了 Anchor 全部 4 个语义节点（均自 6.0.0 起支持），这也是 classNames / styles 的完整键集合：

节点	对应 DOM	职责说明（源自示例注释）	版本
root	锚点容器外层 div	根元素，包含布局定位、内边距、边距、背景色等基础样式	6.0.0
item	每个链接项 div	链接项元素，包含内边距、文字颜色、悬停状态、过渡动画等样式	6.0.0
itemTitle	链接标题 <a>	标题文字元素，包含字体样式、颜色变化、文本装饰、过渡效果等样式	6.0.0
indicator	高亮指示条 <span>（ink）	指示器元素，包含宽度、高度、背景色、位置变化、过渡动画等样式	6.0.0

这些类型的完整定义见 Anchor.tsx：

export type AnchorSemanticType = {
  classNames?: {
    root?: string;
    item?: string;
    itemTitle?: string;
    indicator?: string;
  };
  styles?: {
    root?: React.CSSProperties;
    item?: React.CSSProperties;
    itemTitle?: React.CSSProperties;
    indicator?: React.CSSProperties;
  };
};

export type AnchorSemanticAllType = GenerateSemantic<AnchorSemanticType, AnchorProps>;

其中 GenerateSemantic 会把对象形态与函数形态（(info: { props }) => ...）组合成 classNamesAndFn / stylesAndFn 类型，这也是 AnchorProps['classNames'] / AnchorProps['styles'] 的最终类型来源（见 Anchor.tsx）。

对象形态：静态 class 注入

官方示例 style-class.tsx 先给出了对象形态的用法：

import React from 'react';
import { Anchor, Col, Row } from 'antd';
import type { AnchorProps, GetProp } from 'antd';

// 对象形态：为每个语义节点追加自定义 class
const classNamesObject: AnchorProps['classNames'] = {
  root: 'demo-anchor-root',
  item: 'demo-anchor-item',
  itemTitle: 'demo-anchor-title',
  indicator: 'demo-anchor-indicator',
};

使用时只需把 classNamesObject 传给组件即可。落地位置在源码中可以逐一验证：

• root 与 indicator 直接在 Anchor.tsx 渲染时拼接：mergedClassNames.root 追加到外层容器 div，mergedClassNames.indicator 追加到 ink 指示条 span；
• item 与 itemTitle 则通过 AnchorContext 下发到 AnchorLink.tsx，分别拼接到链接项 div 与标题 <a> 上。

因此你完全可以在全局样式中这样写：

.demo-anchor-root { padding: 8px; }        /* 作用在根容器 */
.demo-anchor-item { min-height: 32px; }    /* 作用在每个链接项 */
.demo-anchor-title { letter-spacing: 0.5px; }
.demo-anchor-indicator { background: #f5222d; }

函数形态：基于 props 的条件化行内样式

示例的第二部分演示了函数形态的 styles，依据 direction 属性动态返回不同样式（摘自 style-class.tsx）：

const stylesFn: AnchorProps['styles'] = (info): GetProp<AnchorProps, 'styles', 'Return'> => {
  // info.props 为 Anchor 的 props，可读取 direction 等任意受控属性
  if (info.props.direction === 'vertical') {
    return {
      root: {
        backgroundColor: 'rgba(255,251,230,0.5)',
        height: '100vh',
      },
    };
  }
  return {};
};

函数形态的关键能力是 info.props：回调参数携带组件完整的 props（源码中 mergedProps 会把实际生效的 direction 一并注入，见 Anchor.tsx），因此「竖排 Anchor 才给根容器加背景色」「RTL 布局时调整指示器」这类条件样式无需外部 useEffect 手动操作 DOM。

完整的组合用法（摘自同一示例）：

<Anchor
  replace
  items={items}
  styles={stylesFn}            /* 函数形态行内样式 */
  classNames={classNamesObject} /* 对象形态 class */
/>

注：示例中 replace 表示点击锚点时用 history.replaceState 替换 URL 中的 #hash 而非 push（见 AnchorLink.tsx），与样式定制相互独立，可自由取舍。

源码机制：从属性到 DOM 的合并链路

classNames / styles 从传入到落到节点上，经过三步，均可在源码中查证：

1. 解析：函数形态被调用求值。 useMergeSemantic 中的 resolveStyleOrClass 判断取值是否为函数，是则传入 { props } 调用，否则原样使用：

export const resolveStyleOrClass = (value: T | ((config: any) => T), info: { props: any }) => {
  return isFunction(value) ? value(info) : value;
};

2. 合并：多来源按优先级叠加。 Anchor.tsx 中，ConfigProvider 的组件级配置（contextClassNames / contextStyles）在前、组件自身 classNames / styles 在后参与合并；同时 style 属性会被 useSemanticRootStyle 提升为 root 节点的样式一并参与合并：

const [mergedClassNames, mergedStyles] = useMergeSemantic<
  AnchorSemanticAllType['classNames'],
  AnchorSemanticAllType['styles'],
  AnchorProps
>([contextClassNames, classNames], [contextStyles, contextStyleRoot, styles, styleRoot], {
  props: mergedProps,
});

合并规则（见 mergeClassNames / mergeStyles）：

• class 采用 clsx 字符串拼接（不互相覆盖），后写的来源追加在后；
• 行内 style 采用对象浅展开（{ ...acc[key], ...cur[key] }），同一节点上后合并的来源按 key 覆盖先前的来源；
• root 的行内样式最终会覆盖容器的 maxHeight（maxHeight 在展开 mergedStyles.root 之前写入，见 Anchor.tsx），因此你可以通过 root 样式调整高度策略。

3. 分发：root/indicator 就地渲染，item/itemTitle 走 Context。 root、indicator 在 Anchor.tsx 直接渲染；item、itemTitle 则随 AnchorContext 的 classNames / styles 字段下发给每个 AnchorLink，由链接项自行消费。这意味着语义定制对嵌套子级（items 中的 children）同样生效——每个子链接都会读取同一份合并结果。

与设计 Token 的分工：何时用哪种定制方式

Anchor 同时支持两条样式定制通道，官方示例各有对应：

• 组件 Token（全局主题通道）：通过 ConfigProvider theme.components.Anchor 修改如 linkPaddingBlock、linkPaddingInlineStart 等设计变量，其消费点见 style/index.ts（如 linkPaddingBlock 默认 token.paddingXXS、linkPaddingInlineStart 默认 token.padding），演示见 component-token.tsx。适合随主题批量调整间距、颜色体系。
• classNames / styles（单实例语义通道）：只影响当前组件实例的指定语义节点，适合局部特化（如某个文档页 Anchor 需要独立背景、某条指示器换色）。

从源码结构看，二者互不冲突：Token 驱动的是基础类（ant-anchor-*）内的样式值，语义化定制在其上追加 class 或行内 style，行内样式优先级更高，因此先用 Token 建立主题基线、再用 classNames/styles 做实例级特化是推荐的组合方式。

完整示例与验证路径

完整可运行示例见 style-class.tsx：左侧 3 个 100vh 的锚点区块（#part-1 ~ #part-3），右侧 Col span={8} 中放置 <Anchor replace items={items} styles={stylesFn} classNames={classNamesObject} />，竖排模式下根容器呈现半透明米黄背景。相关文档与代码索引：

• 组件文档与 Semantic DOM 定义：components/anchor/index.zh-CN.md
• 示例描述文件（本文主体来源）：components/anchor/demo/style-class.md
• 示例实现：components/anchor/demo/style-class.tsx
• 语义节点说明：components/anchor/demo/_semantic.tsx
• 合并工具：components/_util/hooks/useMergeSemantic/index.ts

落地时的几个注意点：

1. 函数返回值要完整：函数形态返回的节点对象中未包含的节点即视为「无自定义样式」，不会继承对象形态中其他节点的值，条件分支里建议显式返回 {}（如示例 direction !== 'vertical' 分支）；
2. class 与 style 各司其职：静态规则用 classNames（便于媒体查询、hover 等伪类场景），动态计算值用 styles（行内优先级最高）；
3. ConfigProvider 可全站兜底：contextClassNames / contextStyles 优先级低于组件自身属性，适合在应用级统一约定 Anchor 的语义类名；
4. 若锚点跳转后 :target 伪类不生效，属于 5.25.0+ 版本 pushState/replaceState 方案的已知行为，可参照 Anchor 文档 FAQ 手动构造完整 URL 解决。