Ant Design Cascader 输入框定制指南：深入解析 prefix、suffixIcon 与 expandIcon 的实现原理

Cascader（级联选择框）在 ant-design 中属于 Data Entry 组件，其选择框本身默认只展示一个向下的箭头与占位符。但实际业务中常需要“把部门名称、前置搜索图标放进选择框，或者用更具辨识度的图标替代默认下拉箭头”。本指南以仓库中 components/cascader/demo/suffix.md（对应演示 “Prefix and Suffix”，引入版本标注为 5.22.0）为核心，系统讲解 prefix、suffixIcon、expandIcon 三个定制点的用法、可运行示例，并结合 Cascader 源码 与相关 hooks 剖析其底层实现，帮助你读完即可在自己的表单里完成 Cascader 视觉定制。

1. 示例文档与示例代码定位

在仓库中，每个 Demo 都由 .md 描述文件与同名 .tsx 源码文件成对出现。本主题对应的文件为：

• 描述文件：components/cascader/demo/suffix.md
• 演示源码：components/cascader/demo/suffix.tsx

md 描述文件的中文文案明确了本 Demo 的全部三个定制点：

通过 prefix 自定义前缀，通过 suffixIcon 自定义选择框后缀图标，通过 expandIcon 自定义次级菜单展开图标。

即一个 Demo 同时覆盖了 Cascader 的三个“图标位”：

定制点	作用位置	用途
prefix	选择框内部、文本之前	展示图标/文字等前缀内容
suffixIcon	选择框内部、文本之后	替换默认下拉箭头等后缀内容
expandIcon	下拉面板中次级菜单项右侧	替换默认展开箭头（>）

该 Demo 也被挂在官方组件文档的 Examples 区，见 components/cascader/index.en-US.md 中的 <code src="./demo/suffix.tsx" version="5.22.0">Prefix and Suffix</code>。

2. 直接可用的完整示例代码

components/cascader/demo/suffix.tsx 提供了可直接复制运行的完整实现。它依次演示了 5 种写法：suffixIcon 传图标元素、传字符串、expandIcon 传图标元素、传字符串、以及 prefix 传图标元素：

import React from 'react';
import { SmileOutlined } from '@ant-design/icons';
import type { CascaderProps } from 'antd';
import { Cascader } from 'antd';

interface Option {
  value: string;
  label: string;
  children?: Option[];
}

const options: Option[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [{ value: 'xihu', label: 'West Lake' }],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [{ value: 'zhonghuamen', label: 'Zhong Hua Men' }],
      },
    ],
  },
];

const onChange: CascaderProps<Option>['onChange'] = (value) => {
  console.log(value);
};

const App: React.FC = () => (
  <>
    {/* 1. suffixIcon：传入图标组件替换默认箭头 */}
    <Cascader
      suffixIcon={<SmileOutlined />}
      options={options}
      onChange={onChange}
      placeholder="Please select"
    />
    <br />
    <br />
    {/* 2. suffixIcon：直接传字符串同样可以渲染 */}
    <Cascader
      suffixIcon="ab"
      options={options}
      onChange={onChange}
      placeholder="Please select"
    />
    <br />
    <br />
    {/* 3. expandIcon：自定义下拉面板中次级菜单展开箭头 */}
    <Cascader
      expandIcon={<SmileOutlined />}
      options={options}
      onChange={onChange}
      placeholder="Please select"
    />
    <br />
    <br />
    {/* 4. expandIcon：同样支持字符串 */}
    <Cascader expandIcon="ab" options={options} onChange={onChange} placeholder="Please select" />
    <br />
    <br />
    {/* 5. prefix：在选择框文本前注入自定义内容 */}
    <Cascader
      prefix={<SmileOutlined />}
      options={options}
      onChange={onChange}
      placeholder="Please select"
    />
  </>
);

export default App;

从这段代码可归纳出一个重要结论：三个属性的类型都是 ReactNode，因此既能传入 @ant-design/icons 的图标元素，也能传入普通字符串、数字甚至任意 React 元素，渲染规则完全由 React 的节点渲染逻辑决定。

3. prefix：在选择框内部注入前置内容

3.1 API 定义

在组件官方 API 表中（见 components/cascader/index.en-US.md）：

Property	Description	Type	Default	Version
prefix	The custom prefix	ReactNode	-	5.22.0

要点：

• 默认不渲染任何前缀，prefix 属性自 5.22.0 版本起可用（Demo 标记的引入版本也正是 5.22.0）。
• 内容渲染在输入框内部、选中文本之前。除上述代码中的图标外，也常配合 placeholder 使用，例如在搜索型场景中放一个 SearchOutlined。

3.2 典型场景

<Cascader
  prefix={<SearchOutlined />}
  options={options}
  placeholder="Please select a region"
/>

从类型系统看，antd 的语义化样式定义中为前缀单独保留了节点：CascaderSemanticType 中同时存在 prefix 与 suffix 两个语义 DOM 字段（见 components/cascader/index.tsx），因此也可配合 classNames={{ prefix: '...' }}、styles={{ prefix: { color: '#1677ff' } }} 对其做细粒度样式定制。

4. suffixIcon：自定义选择框后缀图标

4.1 API 定义

官方 API 表中（见 components/cascader/index.en-US.md）：

Property	Description	Type	Default	Global Config
suffixIcon	The custom suffix icon	ReactNode	-	6.4.0

要点：

• 类型为 ReactNode，传入图标后替换默认的箭头图标；直接传字符串（如示例中的 "ab"）也会被渲染出来。
• 同时可接受 null 用于完全隐藏后缀图标。官方文档指出，旧属性 showArrow 已废弃（deprecated），推荐“需要隐藏箭头时直接设置 suffixIcon={null}”。当前源码中，若同时使用 showArrow 会在开发环境抛出 devUseWarning 的 deprecated 提示（见 components/cascader/index.tsx），提示内容即为“请改用 suffixIcon 设为 null 来隐藏”。

4.2 隐藏箭头与自定义状态图标

{/* 隐藏默认箭头 */}
<Cascader options={options} suffixIcon={null} placeholder="Please select" />

{/* 替换为自定义箭头 */}
<Cascader options={options} suffixIcon={<DownOutlined />} placeholder="Please select" />

4.3 后缀图标位的行为细节

Cascader 选择框本身复用了 Select 系列组件的 useSelectIcons hook（见 components/select/useIcons.tsx），因此后缀区域并不是“只显示一个固定图标”，而是会随状态自动切换，具体逻辑可归纳为：

• 默认（未展开、未搜索）：显示 DownOutlined 下拉箭头；
• 展开且开启搜索：切换为 SearchOutlined 搜索图标；
• 加载中：切换为旋转的 LoadingOutlined（可通过 loadingIcon 覆盖）；
• 表单校验反馈：会追加 hasFeedback 的校验图标；
• 传入自定义 suffixIcon：上述默认分支被跳过，直接渲染你传入的节点；在 suffixIcon 为 null 且无校验反馈、无 showArrow 时，返回 null（见 components/select/useIcons.tsx）。

源码中“是否展示箭头”的判定独立成一个 hook useShowArrow（components/select/useShowArrow.ts）：

export default function useShowArrow(suffixIcon?: ReactNode, showArrow?: boolean) {
  return showArrow !== undefined ? showArrow : suffixIcon !== null;
}

也就是说：suffixIcon !== null 时默认总是展示后缀图标，这与注释里 “If suffixIcon is not equal to null, always show it.” 的描述一致，也是官方建议用 suffixIcon={null} 取代 showArrow={false} 的原因。

5. expandIcon：自定义次级菜单展开图标

5.1 API 定义

官方 API 表中（见 components/cascader/index.en-US.md）：

Property	Description	Type	Default	Version	Global Config
expandIcon	Customize the current item expand icon	ReactNode	-	4.4.0	6.3.0

要点：

• 作用于下拉面板里带子节点的菜单项——即“还有下一级可展开”的选项，而不是选择框本身；
• 传入 ReactNode（图标或字符串均可，见示例）；
• 自 4.4.0 起可用，同时支持通过 ConfigProvider 的 component config 做全局配置（6.3.0 起）。

5.2 实现默认值与 RTL

Cascader 内部把 expandIcon 的合并逻辑收敛在 hook components/cascader/hooks/useIcons.tsx 中：

const defaultLoadingIcon = <LoadingOutlined spin />;
const defaultExpandIcon = <RightOutlined />;
const defaultRtlExpandIcon = <LeftOutlined />;

其合并优先级为：

props.expandIcon ?? ConfigProvider 的 contextExpandIcon ?? (isRtl ? LeftOutlined : RightOutlined)

因此两个细节值得注意：

1. 默认展开箭头是 RightOutlined（>），当组件处于 RTL（direction="rtl"）环境时自动切换为 LeftOutlined（<）；
2. 你传入的 expandIcon 在 RTL 下不会被自动镜像——如果你希望保持箭头方向语义，需要自行处理 RTL 分支。

5.3 与懒加载 loading 图标的分工

当配合 loadData 懒加载时，数据未就绪的节点会显示旋转的 LoadingOutlined（loadingIcon），这是独立于 expandIcon 的状态位。源码中二者被分别解析为 mergedExpandIcon 与 mergedLoadingIcon 后一并传入 RcCascader（见 components/cascader/index.tsx 与 L484-L487）。

6. 组合定制：让三个图标位协同工作

Demo 中三个属性是分别演示的，实际项目里它们可以在一个 Cascader 上同时生效。例如把上述省市区数据结构配合完整定制：

<Cascader
  options={options}
  onChange={onChange}
  placeholder="Please select region"
  prefix={<SmileOutlined />}          // 输入框左侧
  suffixIcon={<SmileOutlined />}      // 输入框右侧（替代默认箭头）
  expandIcon={<SmileOutlined />}      // 下拉面板次级菜单展开箭头
/>

而如果只想保留“可点击展开”却不想让输入框显示任何箭头，推荐写法是：

<Cascader options={options} suffixIcon={null} />

兼容性提示：prefix 需要 antd ≥ 5.22.0，expandIcon 需要 ≥ 4.4.0；若使用较低版本请以实际生效的 API 表为准（以当前仓库文档标注为准，见上文版本列）。

7. 源码级解读：三个属性如何流入最终渲染

把 components/cascader/index.tsx 中与本次定制相关的数据流串联如下，可得到一幅清晰的“图标管线”：

1. props 解构与 context 合并：suffixIcon、expandIcon 等从 props 解构（L207-L246），同时从 useComponentConfig('cascader') 取出全局的 contextExpandIcon、contextSuffixIcon、contextLoadingIcon 等（L248-L261），实现“单组件局部配置优先于 ConfigProvider 全局配置”。
2. 箭头显隐判定：通过 components/select/useShowArrow.ts 计算 showSuffixIcon，规则是“未显式传 showArrow 时，suffixIcon !== null 即展示”。
3. expandIcon / loadingIcon 合并：交给 components/cascader/hooks/useIcons.tsx 处理，处理 RTL 与默认图标兜底。
4. suffixIcon 最终组装：交给 components/select/useIcons.tsx，内部使用 fallbackProp 依次回退到 loadingIcon、搜索图标与 DownOutlined，并处理表单反馈图标共存。
5. 透传底层：最终 expandIcon={mergedExpandIcon}、suffixIcon={mergedSuffixIcon} 等被透传给 @rc-component/cascader（L484-L487），由 rc 层负责实际 DOM 渲染。

另外，从 components/cascader/index.tsx 的类型定义可以看到 suffixIcon?: React.ReactNode 与 expandIcon（继承自 RcCascaderProps）均为可选节点，其中 showArrow 已明确标注 deprecated 并在下个大版本移除；语义样式层的 prefix / suffix 节点（L57-L82）则可作为后续细粒度样式定制的入口。如果需要全局统一替换箭头图标（例如品牌化），建议优先使用 ConfigProvider 的 componentConfig={{ cascader: { suffixIcon: ..., expandIcon: ... } }} 配置，而非逐个组件重复设置。

8. 小结与延伸

属性	渲染位置	传 ReactNode/字符串	隐藏方式	官方文档 API 表
prefix	输入框内部、文本前	✅	不传即可	index.en-US.md
suffixIcon	输入框内部、文本后	✅	传 null（替代已废弃的 showArrow）	index.en-US.md
expandIcon	下拉面板次级菜单项	✅	不传即可，默认 >	index.en-US.md

围绕本主题可继续阅读仓库内的相关资料：

• components/cascader/index.tsx：Cascader 主组件，包含 props 合并、deprecated 警告与语义样式定义；
• components/cascader/hooks/useIcons.tsx：expandIcon/loadingIcon 默认值与 RTL 逻辑；
• components/select/useIcons.tsx：后缀图标、清除图标、移除图标的最终组装逻辑；
• components/cascader/index.zh-CN.md：Cascader 完整中文 API 文档，可查看 prefix、suffixIcon、expandIcon 之外的全部属性；
• components/select/demo：由于 Cascader 与 Select 共享后缀图标逻辑，其中 Select 的 suffix 相关示例也有参考价值。

掌握了 prefix、suffixIcon、expandIcon 三个入口及其“props → context → rc 组件”的合并链路，你就可以在不侵入组件内部实现的前提下，用最少的代码完成 Cascader 视觉语言的统一与差异化定制。