级联选择 Cascader

指在选择器选项数量较多时，采用多级分类的方式将选项进行分隔。

安装

npm install @arco-design/web-react@2.66.18

在入口引入 @arco-design/web-react/dist/css/arco.css，用 ConfigProvider 设置语言。React 19 项目还需在入口最先引入 @arco-design/web-react/es/_util/react-19-adapter，否则 Message、Modal 等命令式 API 无法渲染。

示例

• 基础：最基础的用法。 默认通过点击展开下一级，可以设置expandTrigger='hover'来控制hover展开下一级
• 允许清除：支持清除。
• 前置标签：通过 addBefore 设置前置标签 (2.41.0)
• 格式化展示选中值：利用renderFormat对显示的内容进行自定义处理。
• 自定义选择框：children 会覆盖默认的选择框。
• 选择即改变：设置属性 changeOnSelect，点击任何一级都可以选择。多选时将会解除父子节点的关联。
• 支持多选：指定mode=multiple，即可使用多选。设置 checkedStrategy 属性设置数据回显方式（2.31.0）。
• 允许搜索：指定showSearch=true，可以输入文本对选项进行搜索。
• 自定义搜索：通过 filterOption 自定义搜索逻辑
• 动态加载：利用loadMore可以进行动态加载数据。 使用动态加载的时候请注意： 1.选项必须设置 isLeaf 来标示是否需要继续加载 2. 如果使用搜索功能，将只对已加载选项执行搜索逻辑。
• 选项禁用：指定 option 的 disabled 为 true，可以禁用该选项
• 受控模式：可以完全控制级联选择。
• 不同尺寸：设置 size 可以使用四种尺寸（mini, small, default, large）的选择器。高度分别对应24px、28px、32px、36px
• 自定义Option：使用 renderOption，可以自定义渲染选项。
• 自定义footer：通过 renderFooter 可以自定义每一层级的footer。
• 展示空数据：showEmptyChildren=true时，当children为[]也会展示下一级空菜单。
• 控制下拉框的展开收起：通过 popupVisible 和 onVisibleChange 控制下拉框的展开和收起。 更多示例可查看Trigger组件文档
• 自定义下拉菜单的展示：使用 dropdownRender 对下拉菜单进行扩展。
• 自定义字段名：通过fieldNames属性指定 label，value，isLeaf，disabled，children 对应的字段。
• 远程搜索：使用 onSearch 自定义搜索逻辑。可以通过 showSearch.panelMode 属性控制是否以搜索面板的形式展示所有可选项。
• 拖拽排序：多选时，指定 dragToSort 属性以允许对已输入的值进行拖拽排序。

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

API

Cascader

extraOptions

export interface extraOptions {
  checked: boolean;
}

FieldNamesType

/**
 * fieldnames 属性类型
 */
export type FieldNamesType = {
  /* Custom field name for label */
  label?: string;
  /** Custom field name for value */
  value?: string;
  /** Custom field name for children */
  children?: string;
  /** Custom field name for disabled  */
  disabled?: string;
  /** Custom field name for isLeaf */
  isLeaf?: string;
};

OptionProps

export interface OptionProps {
  /**
   * @zh 选项的值
   * @en: the value of Option
   *
   */
  value?: string;
  /**
   * @zh 选项文本
   * @en option text
   */
  label?: string;
  /**
   * @zh 是否禁用该选项
   * @en whether to disabled
   */
  disabled?: boolean;
  /**
   * @zh 下一级选项
   * @en next level menu
   */
  children?: OptionProps[];
  /**
   * @zh 是否是叶子节点
   * @en Flag whether it is a leaf node
   */
  isLeaf?: boolean;
  /**
   * @zh 是否禁用复选框选中
   * @en Whether to disable the check box is selected
   * @version 2.21.0
   */
  disableCheckbox?: boolean;
  /**
   * @zh 其他字段
   * @en other fields
   */
  [key: string]: any;
}

InputValueChangeReason

// 造成输入框值改变的原因：用户输入、选项下拉框收起、其他
export type InputValueChangeReason =
  | "manual"
  | "optionListHide"
  | "optionChecked";

ObjectValueType

export type ObjectValueType = {
  value?: any;
  label?: ReactNode;
  closable?: boolean;
};

方法

示例

<Cascader ref={(ref) => (this.select = ref)} />;

this.select.focus();
this.select.blur();