Ant Design Cascader 组件 changeOnSelect 详解：让父级选项也可即时选中

Cascader（级联选择）是 Ant Design 中处理省市区、公司层级、分类树等多级关联数据的核心组件，它把多级选项放进同一浮层逐级展开，减少选择跳转、提升操作效率。默认情况下 Cascader 只有点到叶子节点才会提交选择，而 changeOnSelect 属性打破了这一限制，允许用户只选中父级选项时即触发 onChange。本文以 change-on-select 示例为主体，结合仓库 API 文档与相关源码，讲解它的交互差异、适用场景与组合用法。

一个示例看懂两种交互

在 components/cascader/demo/change-on-select.tsx 中，使用了省市区风格的选项数据：Zhejiang → Hangzhou → West Lake 与 Jiangsu → Nanjing → Zhong Hua Men，并通过一个布尔属性开启新交互：

import React from 'react';
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: 'Hanzhou',
        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 = () => <Cascader options={options} onChange={onChange} changeOnSelect />;

export default App;

change-on-select.md 对这段演示的说明非常简短，但它精准点出了这种交互的本质——这种交互允许只选中父级选项（Allows the selection of only parent options）。开启 changeOnSelect 后，用户在展开的下拉菜单中点击任意一级的选项（哪怕是仍然带子级的父节点），选择事件都会立即生效：

• 点击 Zhejiang，onChange 立即触发，参数值为 ['zhejiang']；
• 继续展开点选 Hangzhou，回调收到 ['zhejiang', 'hangzhou']；
• 点击叶子节点 West Lake，则收到完整路径 ['zhejiang', 'hangzhou', 'xihu']。

对应示例文档的中英文说明均可在 change-on-select.md 中查看，该示例在组件官方文档的 Examples 区中也被登记为 “Change on select”（见 index.en-US.md）。

为什么需要 changeOnSelect：默认行为回顾

要理解 changeOnSelect 的价值，先要明确 Cascader 的默认选择机制。不给 changeOnSelect 传值（或显式传 false）时，组件遵循"必须选到叶子节点才提交"的规则：点击带 children 的父级选项只会展开下一级菜单、并高亮当前路径，并不会触发 onChange；只有点击到树的末端叶子节点（示例中的 West Lake、Zhong Hua Men），选择才会被写入并回调。

这一默认设计保证了 value 永远是一个"完整且没有歧义"的路径，非常适合像"选择省市→精确到区"这样必须收集最细粒度数据的表单场景。

但在现实业务中存在大量"选择到某一层级即可"的需求，典型的如：

• 电商后台的商品类目筛选：选到一级或二级分类即可执行查询，不必强制点到最末级；
• 组织架构中按部门过滤：总部下挂多个部门，用户只想按顶层部门粗筛；
• 地区数据量大、层级深的场景：强制点到底会给用户带来明显的操作成本。

此时若仍坚持默认行为，用户要么被迫逐级点到底，要么开发者需要自行在 onChange 后做二次处理。changeOnSelect 正是为这类"可随时收手"的层级选择而设计。

API 定义：属性、类型与生效范围

在组件 API 文档 index.zh-CN.md 与 index.en-US.md 中，changeOnSelect 的属性说明一致（en-US 中还提示 "see above demo for details"，即本示例）：

属性	说明	类型	默认值
changeOnSelect	单选时生效（multiple 下始终都可以选择），点选每级菜单选项值都会发生变化	boolean	false

对照 API 文档，可以提炼出几个关键约束：

1. 布尔类型，默认 false，且不是受控可选的枚举值——不需要传对象或函数，一行布尔属性即完成全部配置；
2. 与 multiple 的交互：中文文档明确写明"单选时生效（multiple 下始终都可以选择）"。也就是说，开启 multiple 多选时，勾选父级选项本身就不受限制、天然可用；changeOnSelect 的主要价值体现在单选模式下放行父节点选择；
3. 它影响的是"触发变更的时机"：每次点选每一级菜单的选项值时，value 与 onChange 都会随之更新，而不是等叶子节点才提交。

对应地，onChange 的回调签名为 (value, selectedOptions) => void，其中 value 的类型为 string[] | number[]，是从根到当前选中节点的完整路径数组；第二个参数 selectedOptions 携带这一路径上各节点对应的完整 Option 对象（含 label、disabled 等信息），便于在父级选中的场景下渲染或回显更多字段。示例代码通过 CascaderProps<Option>['onChange'] 复用了组件公开的类型定义，值得在真实项目中沿用——既能保证 options 泛型与回调参数强一致，也便于后续维护。

组合玩法：懒加载、悬停展开与受控回显

在实际项目中，changeOnSelect 极少单独出现，它通常会与下列特性协同使用：

搭配 loadData 实现"选完即触发"的懒加载

与 changeOnSelect 最经典的组合是动态加载子节点。仓库中的 lazy.tsx 演示即同时使用了 changeOnSelect 与 loadData：选项数据初始只有父级，用户点选某级后通过 loadData 异步拉取下一级并追加到 options。这种模式下 changeOnSelect 的意义在于——即便用户在某层选择后不再继续下钻，选择结果也已经生效，不会因为数据尚未加载完叶子节点而卡住整条选择链路。同时它也为"先选中父级、再按需加载下级"的异步交互留出了操作空间。

关于懒加载还需要注意两点：其一，loadData 需要配合 Option 上的 isLeaf 字段使用（参见文档 Option 定义，false 会强制将节点视为父节点并始终展示展开图标）；其二，根据 API 文档，loadData 无法与 showSearch 同时工作，设计交互时需要避开两者并用的组合。

配合 expandTrigger 改变展开方式

Cascader 默认"点击展开下一级、点击完成选择"；若希望"移入展开下级菜单、点击完成选择"，可通过 expandTrigger="hover" 切换展开触发方式（独立示例见 hover.md）。expandTrigger 的取值为 click | hover，默认 click。将 expandTrigger="hover" 与 changeOnSelect 结合，可以构造出"悬停快速浏览层级、随时单击确认到某一层"的高效筛选体验，尤其适合层级多、路径长的目录树型选择。

受控 value 与回显

changeOnSelect 开启后，value 可能停留在任何层级（如 ['zhejiang']）。组件支持 value 受控与 defaultValue 非受控两种回显方式，value 为 string[] | number[] 路径数组。当接入表单（antd 的 Form）时，value 与 onChange 遵循表单控件约定，配合 displayRender 自定义选中项的展示文案（默认以 / 连接各级 label），即可覆盖"选中省级却想显示中文省名"之类的回显需求。

关键行为边界与注意事项

为了让 changeOnSelect 用得准确，需要记住以下几条边界（均可回溯至 API 文档或源码约束）：

1. 单选 + 默认关闭：它默认只对单选有意义且默认关闭；若业务允许选中任意层级的父节点，必须显式开启，否则父节点点击仅展开不下发。
2. 父节点选中的判定：父节点不一定非要有 children。文档对 Option 的说明指出，isLeaf 字段仅在指定 loadData 时生效，false 会强制节点按父节点处理。也就是说在懒加载场景下，一个"暂无子数据"的节点是否具备展开态由 isLeaf 决定，配置错误会让 changeOnSelect 的点击行为与预期不符。
3. 多选模式不受该属性影响：multiple 下勾选各级节点本就即时生效，无需依赖 changeOnSelect；若你同时使用两者，多选行为不会产生额外变化。
4. onChange 触发频次变高：开启后每一次点选都会触发一次 onChange，当父级选中同样代表一次"已提交"选择时，要注意避免在回调中执行与次数耦合的副作用（如重复发起请求）。实践中通常会结合"点选父级即关闭浮层并查询"的业务语义来消费回调，也可在回调里自行判断选中路径的长度决定后续动作。
5. 与 showSearch 的共存：搜索过滤场景下选择是"搜索后单选某条路径"，changeOnSelect 的逐级即时生效交互通常不再适用，是否需要同时开启应根据产品交互仔细权衡。

小结

changeOnSelect 是 Ant Design Cascader 上一个极其轻量（一个布尔属性）却深刻改变交互语义的开关：它把默认的"必须点到底"放宽为"点选任何一级即可确认"，配合 multiple、loadData、expandTrigger="hover" 与受控 value，能够覆盖类目筛选、部门选择、按需懒加载等大量真实业务场景。想要亲手验证它，可以直接查看 change-on-select.tsx 的完整代码，并将 changeOnSelect 从组件上移除后对比父节点点击行为——默认仅展开、开启后即时回调的差异一目了然。如果你的产品正被"强制选到叶子"困扰，不妨从这一个小属性开始改造。