Arco Design Cascader 基础用法完全指南:从 options 数据到展开交互的源码级解析

原创2026-10-12 14:48:561,328 阅读
文章标签:UI组件前端设计系统

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/ 下有对应的独立示例可继续查阅:

测试基准方面,test/index.test.tsx 覆盖了面板展开收起(onVisibleChange)、路径选中回显、changeOnSelect、清除、多选与 checkedStrategy、fieldNames、loadMore 及自定义 icons 等关键行为,是理解组件契约的最佳参考。

总结

「基础用法」看似简单,背后却是一套完整的树形数据模型与多列联动渲染机制:

  • options 提供嵌套数据,fieldNames 支持字段映射;
  • expandTrigger 决定点击还是悬停展开下一级,其交互差异可在 panel/list.tsx 的 onMouseEnter / onClickOption 分支中精确对应;
  • 选中值以路径数组组织,选择框按「 / 」拼接各级 label 回显,Store / Node 数据模型负责选中态与半选态的一致性维护;
  • status 与 allowClear 补齐了表单校验与内容清除两大高频诉求。

从这一基础示例出发,再配合多选、搜索、动态加载等进阶能力,即可应对绝大多数多级分类选择场景。

登录后查看全文
arco-design