树选择 TreeSelect

可以对树形结构数据进行选择。

安装

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 无法渲染。

示例

• 基础用法：最简单的用法。
• 设置 value 格式：labelInValue 为 true 时，value 格式为： { label: string, value: string }。
• 自定义渲染：单选下通过 renderFormat 可自定义渲染展示
• 前置标签：通过 addBefore 设置前置标签 (2.41.0)
• 通过数据生成树结构：通过传入 treeData 数据生成树结构。
• 受控模式：受控模式。
• 动态加载：可以通过 loadMore 进行动态加载。此时可设置 isLeaf 来标示叶子节点。
• 搜索：设置 showSearch=true 启用搜索功能。动态加载时候只能在已加载数据中进行搜索。默认的关键字搜索是从value字段匹配。也可以传入 filterTreeNode自定义过滤方式。
• 远程搜索：当传入 onSearch 为函数时，启用自定义搜索，可以从远程加载数据。
• 不同尺寸：设置 size 可以使用四种尺寸（small, default, large, huge）的选择器。高度分别对应 24px、32px、36px、40px。
• 自定义显示：设置 triggerElement 可以自定义显示。
• 多选：多选
• 复选框多选：可以通过设置 treeCheckable 属性开启复选框勾选。
• 定制回填方式：可以通过treeCheckStrategy属性定制回填方式。
• 扩展下拉菜单：使用 dropdownRender 对下拉菜单进行自由扩展。
• 控制下拉框的展开收起：默认展开下拉框。通过 popupVisible 和 onVisibleChange 控制下拉框的展开和收起。 例如以下 demo，在鼠标移出下拉框和弹出框的时候触发 onVisibleChange，参数为 false，收起下拉框。 具体 onVisibleChange 的触发事件可查看Trigger组件文档
• 自定义 TreeData 的字段名称：通过 fieldNames 字段可以自定义 TreeData 的字段名。
• 虚拟列表：通过指定 treeProps.virtualListProps 来开启虚拟列表，在大量数据时获得高性能表现。
• 拖拽排序：多选时，指定 dragToSort 属性以允许对已输入的值进行拖拽排序。

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

API

TreeSelect

LabelValue

export type LabelValue = {
  label: ReactNode;
  value: string;
  disabled?: boolean;
};

FieldNamesType

export type FieldNamesType = {
  key?: string;
  title?: string;
  disabled?: string;
  children?: string;
  isLeaf?: string;
  disableCheckbox?: string;
  checkable?: string;
};

TreeSelectDataType

export type TreeSelectDataType = TreeDataType & {
  value?: string;
};

TreeDataType

export type TreeDataType = NodeProps & {
  key?: string;
  _index?: number;
  children?: TreeDataType[];
  [key: string]: any;
};

InputValueChangeReason

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

ObjectValueType

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