TreeSelect 树选择器

用于多层级树形数据的结构化展示与选取，如文件夹、组织架构、地区分类。

何时使用

需要以树形下拉方式选择层级数据时。

基础用法

最简单的用法，默认为单选模式。

<script setup lang="ts">
import { ref } from "vue";
import { TreeSelect } from "@reglow/reui";

const value = ref("");
const treeData = [
  {
    label: "亚洲",
    value: "Asia",
    key: "0",
    children: [
      {
        label: "中国",
        value: "China",
        key: "0-0",
        children: [
          { label: "北京", value: "Beijing", key: "0-0-0" },
          { label: "上海", value: "Shanghai", key: "0-0-1" },
        ],
      },
      { label: "日本", value: "Japan", key: "0-1" },
    ],
  },
  {
    label: "北美洲",
    value: "NA",
    key: "1",
    children: [
      { label: "美国", value: "USA", key: "1-0" },
      { label: "加拿大", value: "Canada", key: "1-1" },
    ],
  },
];
</script>

<template>
  <TreeSelect v-model="value" :tree-data="treeData" class="w-[260px]" />
</template>

导入

import { TreeSelect } from "@reglow/reui";
import type { TreeNodeData } from "@reglow/reui";

更多示例

多选

设置 multiple 进行多选，所有子项被选中时自动勾选父项。

<script setup lang="ts">
import { ref } from "vue";

const value = ref<string[]>([]);
</script>

<template>
  <TreeSelect v-model="value" :tree-data="treeData" multiple class="w-[260px]" />
</template>

只渲染叶子节点

设置 leafOnly 只展示叶子节点，回调参数也仅返回叶子节点值。

<template>
  <TreeSelect
    v-model="value"
    :tree-data="treeData"
    multiple
    leaf-only
    class="w-[260px]"
  />
</template>

限制标签展示数量

通过 maxTagCount 限制标签数量，超出部分以 +N 展示。

<template>
  <TreeSelect
    v-model="value"
    :tree-data="treeData"
    multiple
    :max-tag-count="2"
    class="w-[260px]"
  />
</template>

设置 showRestTagsPopover 后，hover +N 显示完整标签列表。

<template>
  <TreeSelect
    v-model="value"
    :tree-data="treeData"
    multiple
    :max-tag-count="2"
    show-rest-tags-popover
    class="w-[260px]"
  />
</template>

可搜索

设置 filterTreeNode 开启搜索，默认对 label 值进行搜索。

<template>
  <TreeSelect
    v-model="value"
    :tree-data="treeData"
    filter-tree-node
    class="w-[260px]"
  />
</template>

仅展示匹配结果

设置 showFilteredOnly 只展示匹配节点。

<template>
  <TreeSelect
    :tree-data="treeData"
    filter-tree-node
    show-filtered-only
    class="w-[260px]"
  />
</template>

搜索框位置

通过 searchPosition 设置搜索框位置：dropdown（默认）或 trigger。

<template>
  <!-- 搜索框在下拉面板中 -->
  <TreeSelect :tree-data="treeData" filter-tree-node search-position="dropdown" class="w-[260px]" />

  <!-- 搜索框在触发器中 -->
  <TreeSelect :tree-data="treeData" filter-tree-node search-position="trigger" class="w-[260px]" />
</template>

远程搜索

设置 remote 启用远程搜索，输入时触发 search 回调。

<script setup lang="ts">
import { ref } from "vue";

const value = ref("");
const treeData = ref([]);
const loading = ref(false);

const onSearch = (inputValue: string) => {
  if (!inputValue) {
    treeData.value = [];
    return;
  }
  loading.value = true;
  // 模拟远程请求
  setTimeout(() => {
    treeData.value = [
      { label: `${inputValue} - 结果1`, value: `${inputValue}-1`, key: `${inputValue}-1` },
      { label: `${inputValue} - 结果2`, value: `${inputValue}-2`, key: `${inputValue}-2` },
    ];
    loading.value = false;
  }, 1000);
};
</script>

<template>
  <TreeSelect
    v-model="value"
    :tree-data="treeData"
    remote
    filter-tree-node
    search-position="trigger"
    @search="onSearch"
    class="w-[260px]"
  />
</template>

尺寸

通过 size 设置尺寸大小。

<template>
  <TreeSelect :tree-data="treeData" size="small" class="w-[260px]" />
  <TreeSelect :tree-data="treeData" size="default" class="w-[260px]" />
  <TreeSelect :tree-data="treeData" size="large" class="w-[260px]" />
</template>

默认展开

<template>
  <!-- 默认展开所有 -->
  <TreeSelect :tree-data="treeData" default-expand-all class="w-[260px]" />

  <!-- 展开指定节点 -->
  <TreeSelect
    :tree-data="treeData"
    :default-expanded-keys="['0', '0-0']"
    class="w-[260px]"
  />
</template>

展开受控

<script setup lang="ts">
import { ref } from "vue";

const expandedKeys = ref(["0", "0-0"]);
</script>

<template>
  <TreeSelect
    v-model:expanded-keys="expandedKeys"
    :tree-data="treeData"
    class="w-[260px]"
  />
</template>

禁用

<script setup lang="ts">
const treeData = [
  {
    label: "亚洲",
    key: "0",
    children: [
      { label: "中国", key: "0-0", disabled: true },
      { label: "日本", key: "0-1" },
    ],
  },
];
</script>

<template>
  <!-- 整体禁用 -->
  <TreeSelect :tree-data="treeData" disabled class="w-[260px]" />

  <!-- 节点禁用 -->
  <TreeSelect :tree-data="treeData" class="w-[260px]" />
</template>

严格禁用

设置 disableStrictly 开启严格禁用，禁用节点不会被父级选中状态影响。

<template>
  <TreeSelect
    :tree-data="treeData"
    multiple
    disable-strictly
    class="w-[260px]"
  />
</template>

受控

<script setup lang="ts">
import { ref } from "vue";

const value = ref("Shanghai");
</script>

<template>
  <TreeSelect v-model="value" :tree-data="treeData" class="w-[260px]" />
</template>

节点选中关系

设置 checkRelation 为 unRelated，节点间选中互不影响。

<template>
  <TreeSelect
    v-model="value"
    :tree-data="treeData"
    multiple
    check-relation="unRelated"
    class="w-[260px]"
  />
</template>

无边框模式

<template>
  <TreeSelect :tree-data="treeData" borderless class="w-[260px]" />
</template>

目录树模式

<template>
  <TreeSelect :tree-data="treeData" directory class="w-[260px]" />
</template>

异步加载

通过 loadData 动态加载子节点，需在数据中传入 isLeaf。

<script setup lang="ts">
const treeData = [
  { label: "加载更多", value: "0", key: "0", isLeaf: false },
  { label: "叶子节点", value: "1", key: "1", isLeaf: true },
];

const loadData = async (node: any) => {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  node.children = [
    { label: "子节点1", value: `${node.key}-0`, key: `${node.key}-0`, isLeaf: true },
    { label: "子节点2", value: `${node.key}-1`, key: `${node.key}-1`, isLeaf: true },
  ];
};
</script>

<template>
  <TreeSelect :tree-data="treeData" :load-data="loadData" class="w-[260px]" />
</template>

选择后不关闭

<template>
  <TreeSelect :tree-data="treeData" :click-to-hide="false" class="w-[260px]" />
</template>

API

Props

属性	类型	默认值	说明
`treeData`	`TreeNodeData[]`	`[]`	树数据
`modelValue`	`string \| number \| (string \| number)[]`	-	当前选中值（v-model）
`defaultValue`	`string \| number \| (string \| number)[]`	-	默认选中值
`placeholder`	`string`	`请选择`	占位文字
`multiple`	`boolean`	`false`	是否多选
`disabled`	`boolean`	`false`	是否禁用
`allowClear`	`boolean`	`true`	是否允许清除
`size`	`small \| default \| large`	`default`	尺寸
`borderless`	`boolean`	`false`	无边框模式
`defaultExpandAll`	`boolean`	`false`	默认展开所有
`expandAll`	`boolean`	`false`	展开所有（数据更新时生效）
`defaultExpandedKeys`	`string[]`	-	默认展开的 key
`expandedKeys`	`string[]`	-	展开的 key（v-model）
`autoExpandParent`	`boolean`	`false`	自动展开父节点
`clickToHide`	`boolean`	`true`	选择后关闭（单选）
`defaultOpen`	`boolean`	`false`	默认展开下拉
`filterTreeNode`	`boolean \| ((input, node) => boolean)`	`false`	开启搜索
`searchPosition`	`dropdown \| trigger`	`dropdown`	搜索框位置
`searchPlaceholder`	`string`	`搜索`	搜索框占位
`showFilteredOnly`	`boolean`	`false`	仅展示匹配节点
`treeNodeFilterProp`	`string`	`label`	搜索匹配属性
`remote`	`boolean`	`false`	远程搜索
`checkRelation`	`related \| unRelated`	`related`	节点选中关系
`leafOnly`	`boolean`	`false`	仅返回叶子节点
`maxTagCount`	`number`	-	限制标签数量
`showRestTagsPopover`	`boolean`	`false`	hover +N 显示 Popover
`disableStrictly`	`boolean`	`false`	严格禁用
`directory`	`boolean`	`false`	目录树模式
`loadData`	`(node) => Promise<void>`	-	异步加载
`dropdownMaxHeight`	`number \| string`	`300`	弹层最大高度
`class`	`string`	-	附加类名

Events

事件	说明	回调参数
`change`	选中变化	`(value, node)`
`search`	搜索	`(value, filteredKeys)`
`expand`	展开/收起	`(keys, node)`
`clear`	清空	`()`

类型

TreeNodeData：

属性	类型	默认值	说明
`label`	`string`	-	标签
`value`	`string \| number`	-	值
`key`	`string`	用 value	唯一标识
`children`	`TreeNodeData[]`	-	子节点
`disabled`	`boolean`	`false`	是否禁用
`isLeaf`	`boolean`	-	是否叶子节点
`icon`	`VNode`	-	自定义图标
`defaultExpanded`	`boolean`	`false`	是否默认展开
`extra`	`string`	-	副文本

多选行为

checkRelation	说明
`related`	父子关联：选中父节点自动选中子节点，子节点全选时自动勾选父节点（含半选）
`unRelated`	父子不关联：各节点选中状态互不影响

国际化

placeholder、searchPlaceholder、空状态文案默认跟随全局语言（zh-CN / zh-TW / en-US），传 prop 可覆盖。

Transfer 穿梭框

双栏多选选择器，直观展示已选与未选，支持搜索、分组、拖拽。

Upload 上传

文件选择上传组件