Arco Design Cascader 基础用法完全指南:从 options 数据到展开交互的源码级解析
Arco Design Cascader 基础用法完全指南:从 options 数据到展开交互的源码级解析
本文以 Arco Design(React 版)组件库中的
Cascader级联选择器「基础用法」示例文档(components/Cascader/demo/basic.md)为主线,系统讲解级联选择器的数据组织方式、默认点击展开与expandTrigger="hover"悬停展开两种交互模式,并结合仓库源码(cascader.tsx、interface.ts、panel/list.tsx 等)剖析其底层实现原理。读完本文,你将能独立搭建一个可运行的级联选择器,并理解展开触发、状态回显、清除与校验态背后的实现机制。
一、Cascader 基础用法概览
在选项数量较多、且选项本身具有多级分类关系时(典型如省市区三级地址),级联选择器(Cascader)通过多级联动菜单将选项逐层分隔,让用户逐级选择。Arco Design 中 Cascader 组件的入口定义在 components/Cascader/index.tsx,对外暴露组件与 NodeProps 类型;完整参数类型定义见 components/Cascader/interface.ts。
「基础用法」演示了两种最常用的场景:
| 场景 | 关键配置 | 交互行为 |
|---|---|---|
| 默认模式 | 不传 expandTrigger(默认 click) |
点击当前选项后展开下一级菜单 |
| 悬停展开 | expandTrigger="hover" |
鼠标悬停(hover)到当前选项即展开下一级菜单 |
两条 Cascader 均基于同一份四层嵌套的 options 数据(北京 → 北京市 → 朝阳区 → 大屯里;上海 → 上海市 → 黄浦区)。第二个演示还展示了 status 校验态(error / warning)与 allowClear 清除能力。
二、options 数据结构的组织方式
级联选择器的一切交互都围绕 options 这一嵌套数组展开。基础示例中的数据如下:
import { Cascader, Space } from '@arco-design/web-react';
const options = [
{
value: 'beijing',
label: 'Beijing',
children: [
{
value: 'Beijing',
label: 'Beijing',
children: [
{
value: 'chaoyang',
label: 'Chaoyang',
children: [
{
value: 'datunli',
label: 'Datunli',
},
],
},
],
},
],
},
{
value: 'shanghai',
label: 'Shanghai',
children: [
{
value: 'shanghaishi',
label: 'Shanghai',
children: [
{
value: 'huangpu',
label: 'Huangpu',
},
],
},
],
},
];
每个节点支持的核心字段(见 interface.ts 的 OptionProps 定义):
value:选项的值(string),构成最终选中值路径的组成部分;label:选项文本,用于菜单项与选择框回显;children:下一级选项数组,存在即代表该节点有子级;disabled:是否禁用该选项;isLeaf:是否叶子节点(动态加载场景下尤为关键);disableCheckbox:多选时是否禁用复选框(2.21.0 引入);[key: string]: any:允许附加任意自定义字段。
当 children 为空数组或不存在时,该节点即视为叶子节点。基础示例中 datunli、huangpu 就是典型的叶子节点,点击它们才会触发完整的选中与回填。
字段名映射 fieldNames
默认情况下组件按 label / value / children / disabled / isLeaf 这几个字段名读取数据。如果你的接口数据使用其他字段名(例如 id、name、child),可以通过 fieldNames 重映射,类型定义在 interface.ts:
<Cascader
fieldNames={{ label: 'name', value: 'id', children: 'child' }}
options={options}
/>
仓库默认字段名常量定义在 cascader.tsx:
export const DefaultFieldNames = {
label: 'label',
value: 'value',
isLeaf: 'isLeaf',
children: 'children',
disabled: 'disabled',
};
三、两种展开交互:click 与 hover
expandTrigger 用于设置展开下一级菜单的方式,取值 'click' | 'hover',默认值为 click(见 cascader.tsx 的 defaultProps)。
3.1 默认模式:点击展开
不设置 expandTrigger 时,用户需要逐级点击节点来展开下一级菜单,这是最稳妥、误触率最低的交互方式,适合层级较深或需要精确操作的场景(如行政区划选择)。
3.2 hover 模式:悬停展开
<Cascader
placeholder="Hover to expand"
expandTrigger="hover"
style={{ width: 300, marginBottom: 20 }}
options={options}
/>
设置 expandTrigger="hover" 后,鼠标悬停到某个选项上,其子级菜单即自动展开。该交互在面板源码 panel/list.tsx 中有清晰的实现证据——每个选项的 onMouseEnter 事件中判断触发方式:
onMouseEnter={() => {
if (option.disabled) {
return;
}
if (props.expandTrigger === 'hover') {
setActiveNode(option);
!option.isLeaf && loadData(option);
}
}}
即:在 hover 模式下,悬停即把该节点设为 activeNode,若节点非叶子且配置了 loadMore 还会触发动态加载。同时,cascader.tsx 中还会为 popup 容器追加 arco-cascader-popup-trigger-hover 样式类,便于样式层区分两种模式。
而默认的 click 模式下,同一 onMouseEnter 分支不会命中,只有点击节点(onClickOption)才会推进 activeNode、展开下一级。
3.3 两种模式的联动细节
从源码看,expandTrigger 还影响下拉面板的收起时机(cascader.tsx):单选场景下,当选中项的最后一个节点是叶子节点,或者「changeOnSelect 且 expandTrigger === 'hover'」时,选择完成后面板会自动收起。也就是说 hover 模式下配合 changeOnSelect,用户只需逐级悬停并点击即可快速完成选择,交互效率更高。
四、状态回显与选中值格式
4.1 选中值的路径结构
Cascader 的 value 类型为 (string | string<a href="https://link.gitcode.com/i/48284a8678eff2b724354ae913ee376f" target="_blank">])[]:单选用 string[] 表示从根到叶的路径(如 ['beijing', 'Beijing', 'chaoyang', 'datunli']),多选时则是多个这样的路径组成的数组。onChange 回调签名如下([interface.ts):
onChange?: (
value: (string | string[])[],
selectedOptions,
extra: { dropdownVisible?: boolean }
) => void;
其中 selectedOptions 为选中项对应的节点数据(含路径上各级节点的 OptionProps),方便业务侧直接读取 label 等字段。
4.2 选择框回显格式
默认情况下,选择框会以「 / 」连接路径上每一级的 label 进行回显(见 cascader.tsx 的 renderText),例如 Beijing / Beijing / Chaoyang / Datunli。测试用例 test/index.test.tsx 也验证了这一行为:
expect(wrapper.querySelector('.arco-cascader-view-value')).toHaveTextContent('上海 / 上海市');
如需自定义展示格式,可通过 renderFormat 定制:
<Cascader
renderFormat={(values) => values.join('-')}
options={options}
/>
4.3 数据层实现:Store 与 Node
选中状态并非直接散落在组件各处,而是由一个内存态的数据模型统一管理:
- base/node.ts 中的
Node类把每一条options原始数据包装成带_level(层级)、_index(同级索引)、_checked(选中)、_halfChecked(半选)、parent、pathValue、pathLabel等内部状态的节点; - base/store.ts 中的
Store类负责建树、按值设置选中状态、查找节点、按 label 搜索等核心逻辑。
例如 Node 在初始化时(base/node.ts)会自底向上累积出完整路径:
pathValue: parent ? [...parent.pathValue, nodeValue] : [nodeValue],
pathLabel: parent ? [...parent.pathLabel, nodeLabel] : [nodeLabel],
_level: parent ? parent._level + 1 : 0,
面板每展开一级菜单,实际上就是沿着 activeNode 的 getPathNodes() 取各级 children 渲染成多列(panel/list.tsx):
const menus = (() => {
const list = [options];
const pathNodes = activeNode ? activeNode.getPathNodes() : [];
pathNodes.forEach((option) => {
option && option.children && list.push(option.children);
});
return list;
})();
这也是「级联多列联动」这一视觉形态的源码级解释。
五、校验状态 status 与清除 allowClear
基础示例的第二组 Cascader 展示了两个实用属性:
<Cascader
status="error"
allowClear
placeholder="Please select ..."
style={{ width: 300, marginBottom: 20 }}
options={options}
/>
<Cascader
status="warning"
allowClear
placeholder="Hover to expand"
expandTrigger="hover"
style={{ width: 300, marginBottom: 20 }}
options={options}
/>
5.1 status:错误 / 警告校验态
status 取值 'error' | 'warning'(2.45.0 引入,见 interface.ts 与 README.zh-CN.md 的 API 表)。它让选择框边框呈现对应的语义色,常用于表单校验反馈场景,比如「必选项未选择时显示 error 态」。历史上有过 error 布尔属性,但已被废弃并建议迁移到 status="error"。
5.2 allowClear:一键清除
allowClear 允许在已有选中值时显示清除按钮,点击后清空选中值。清除逻辑在 cascader.tsx:
- 单选:直接
handleChange([])清空; - 多选:保留被禁用节点(
disabled的节点不可被清除),清除其余选中项; - 清除后触发
onClear(visible)回调,参数为当前下拉框展开状态。
测试用例 test/index.test.tsx 验证了默认值回显与点击清除后视图清空的行为。
六、完整基础示例:一段可运行的 Demo
将前文要点整合,一个完整的「基础用法」示例可以这样组织(与 basic.md 保持一致,并加入受控写法示意):
import React, { useState } from 'react';
import { Cascader, Space } from '@arco-design/web-react';
const options = [
{
value: 'beijing',
label: 'Beijing',
children: [
{
value: 'Beijing',
label: 'Beijing',
children: [
{
value: 'chaoyang',
label: 'Chaoyang',
children: [
{ value: 'datunli', label: 'Datunli' },
],
},
],
},
],
},
{
value: 'shanghai',
label: 'Shanghai',
children: [
{
value: 'shanghaishi',
label: 'Shanghai',
children: [
{ value: 'huangpu', label: 'Huangpu' },
],
},
],
},
];
const App = () => {
const [value, setValue] = useState();
return (
<Space size="large" wrap>
{/* 默认点击展开下一级 */}
<Cascader
placeholder="Please select ..."
style={{ width: 300 }}
options={options}
/>
{/* hover 展开下一级 */}
<Cascader
placeholder="Hover to expand"
expandTrigger="hover"
style={{ width: 300 }}
options={options}
/>
{/* 受控 + 错误态 + 可清除 */}
<Cascader
status="error"
allowClear
placeholder="Please select ..."
style={{ width: 300 }}
options={options}
value={value}
onChange={(v) => setValue(v)}
/>
</Space>
);
};
export default App;
七、基础场景下的常用配置参考
结合 README.zh-CN.md 与 interface.ts,基础使用中最常配合的属性还有:
| 属性 | 类型 / 默认值 | 说明 |
|---|---|---|
placeholder |
string |
选择框占位文字 |
style / className |
CSSProperties / string | string[] |
容器样式与类名 |
defaultValue |
(string | string[])[] |
非受控默认选中值 |
value / onChange |
见上文 | 受控选中值与变更回调 |
disabled |
boolean |
整体禁用 |
size |
'mini' | 'small' | 'default' | 'large' |
四种尺寸,高度分别对应 24px / 28px / 32px / 36px |
changeOnSelect |
boolean |
点击任意一级即改变值(多选时解除父子关联) |
mode="multiple" |
'multiple' |
多选模式,配合 checkedStrategy('parent' | 'child')定制回填方式 |
showSearch |
boolean | object |
单选可搜索;对象形式可配置 panelMode、retainInputValue、renderOption 等 |
loadMore |
(pathValue, level) => Promise<T[]> |
动态加载下一级数据 |
fieldNames |
FieldNamesType |
自定义字段映射 |
popupVisible / defaultPopupVisible |
boolean |
控制下拉框展开收起 |
notFoundContent |
ReactNode |
无数据/无搜索结果时的占位内容 |
需要特别留意的是 options 默认值为 <a href="https://link.gitcode.com/i/b5ce2485aa5179fbc5561026f81334e3" target="_blank">]([cascader.tsx),数据未传入时面板渲染为空态提示(panel/list.tsx 与 cascader.tsx 的 renderEmpty 逻辑)。
八、更进一步的扩展场景
基础用法之上,Arco Design 的 Cascader 还提供了一整套进阶能力,仓库 components/Cascader/demo/ 下有对应的独立示例可继续查阅:
- multiple.md:多选 +
checkedStrategy回填策略; - search.md:
showSearch关键字搜索(搜索结果面板实现见 panel/search-panel.tsx,默认按 label 匹配,filterOption可自定义搜索逻辑); - change_on_select.md:任意层级即选即改;
- loadmore.md:动态加载(需在选项上标明
isLeaf); - control.md:完全受控用法;
- visible.md:
popupVisible与onVisibleChange控制下拉框展开收起; - filedNames.md、filter_option.md、render_option.md 等:字段映射、自定义搜索与自定义渲染。
测试基准方面,test/index.test.tsx 覆盖了面板展开收起(onVisibleChange)、路径选中回显、changeOnSelect、清除、多选与 checkedStrategy、fieldNames、loadMore 及自定义 icons 等关键行为,是理解组件契约的最佳参考。
总结
「基础用法」看似简单,背后却是一套完整的树形数据模型与多列联动渲染机制:
options提供嵌套数据,fieldNames支持字段映射;expandTrigger决定点击还是悬停展开下一级,其交互差异可在 panel/list.tsx 的onMouseEnter/onClickOption分支中精确对应;- 选中值以路径数组组织,选择框按「 / 」拼接各级 label 回显,
Store/Node数据模型负责选中态与半选态的一致性维护; status与allowClear补齐了表单校验与内容清除两大高频诉求。
从这一基础示例出发,再配合多选、搜索、动态加载等进阶能力,即可应对绝大多数多级分类选择场景。