Tree 树形控件

以层级结构展示一组数据。

基础用法

基础树结构。

Level one 1

Level one 2

Level one 3

可选择

用于节点选择。

本示例同时演示如何异步加载节点数据。

Root1

Root2

WARNING

使用 show-checkbox 时，由于 check-on-click-leaf 默认为 true，点击末级子节点可选中对应复选框。

懒加载下的叶子节点

节点数据在点击前不会加载，因此树无法预知是否为叶子节点，故每个节点会显示下拉按钮；点击后若为叶子节点则下拉按钮消失。你也可以预先告知树该节点是否为叶子节点，从而在叶子节点渲染前避免显示下拉按钮。

region

多次懒加载

远程懒加载可能失败，此时可调用 reject 保持节点状态并允许继续远程加载。

region

禁用复选框

可将节点复选框设为禁用。

示例在 defaultProps 中声明 disabled 属性，部分节点设置 disabled: true，对应复选框禁用且不可点击。

Level one 1

默认展开与默认选中

节点可设置初始展开或选中。

使用 default-expanded-keys 与 default-checked-keys 分别设置初始展开与初始选中节点。二者生效需要 node-key，其值为数据对象中的字段名，且该字段在整棵树中唯一。

勾选树节点

演示如何获取与设置勾选节点，支持按节点对象或 key 两种方式；若使用 key 方式，需要配置 node-key。

vue

<template>
  <u-tree
    ref="treeRef"
    style="max-width: 600px"
    :data="data"
    show-checkbox
    default-expand-all
    node-key="id"
    highlight-current
    :props="defaultProps"
  />

  <div class="flex flex-wrap gap-1 mt-2">
    <u-button class="!ml-0" @click="getCheckedNodes">get by node</u-button>
    <u-button class="!ml-0" @click="getCheckedKeys">get by key</u-button>
    <u-button class="!ml-0" @click="setCheckedNodes">set by node</u-button>
    <u-button class="!ml-0" @click="setCheckedKeys">set by key</u-button>
    <u-button class="!ml-0" @click="resetChecked">reset</u-button>
  </div>
</template>

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

import type { RenderContentContext, TreeInstance } from 'uniboot-ui'

interface Tree {
  id: number
  label: string
  children?: Tree[]
}
type Node = RenderContentContext['node']

const treeRef = ref<TreeInstance>()

const getCheckedNodes = () => {
  console.log(treeRef.value!.getCheckedNodes(false, false))
}
const getCheckedKeys = () => {
  console.log(treeRef.value!.getCheckedKeys(false))
}
const setCheckedNodes = () => {
  treeRef.value!.setCheckedNodes(
    [
      {
        id: 5,
        label: 'Level two 2-1',
      },
      {
        id: 9,
        label: 'Level three 1-1-1',
      },
    ] as Node[],
    false
  )
}
const setCheckedKeys = () => {
  treeRef.value!.setCheckedKeys([3], false)
}
const resetChecked = () => {
  treeRef.value!.setCheckedKeys([], false)
}

const defaultProps = {
  children: 'children',
  label: 'label',
}

const data: Tree[] = [
  {
    id: 1,
    label: 'Level one 1',
    children: [
      {
        id: 4,
        label: 'Level two 1-1',
        children: [
          {
            id: 9,
            label: 'Level three 1-1-1',
          },
          {
            id: 10,
            label: 'Level three 1-1-2',
          },
        ],
      },
    ],
  },
  {
    id: 2,
    label: 'Level one 2',
    children: [
      {
        id: 5,
        label: 'Level two 2-1',
      },
      {
        id: 6,
        label: 'Level two 2-2',
      },
    ],
  },
  {
    id: 3,
    label: 'Level one 3',
    children: [
      {
        id: 7,
        label: 'Level two 3-1',
      },
      {
        id: 8,
        label: 'Level two 3-2',
      },
    ],
  },
]
</script>

自定义节点内容

可自定义节点内容，例如添加图标或按钮。

两种方式：render-content 与作用域插槽。render-content 接收渲染函数并返回节点内容，详见 Vue 文档。作用域插槽可访问 node 与 data，分别表示当前 TreeNode 与节点数据。注意：render-content 示例无法在 JSFiddle 运行（不支持 JSX）；真实项目配置依赖后可正常使用。

vue

<template>
  <div class="custom-tree-container">
    <p>Using render-content</p>
    <u-tree
      ref="treeRef1"
      style="max-width: 600px"
      :data="dataSource"
      show-checkbox
      node-key="id"
      default-expand-all
      :expand-on-click-node="false"
      :render-content="renderContent"
    />
    <p>Using scoped slot</p>
    <u-tree
      ref="treeRef2"
      style="max-width: 600px"
      :data="dataSource"
      show-checkbox
      node-key="id"
      default-expand-all
      :expand-on-click-node="false"
    >
      <template #default="{ node, data }">
        <div class="custom-tree-node">
          <span>{{ node.label }}</span>
          <div>
            <u-button type="primary" link @click="append(data)">
              Append
            </u-button>
            <u-button
              style="margin-left: 4px"
              type="danger"
              link
              @click="remove(node, data)"
            >
              Delete
            </u-button>
          </div>
        </div>
      </template>
    </u-tree>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { UButton } from 'uniboot-ui'

import type {
  RenderContentContext,
  RenderContentFunction,
  TreeInstance,
} from 'uniboot-ui'

interface Tree {
  id: number
  label: string
  children?: Tree[]
}
type Node = RenderContentContext['node']
type Data = RenderContentContext['data']

let id = 1000
const treeRef1 = ref<TreeInstance>()
const treeRef2 = ref<TreeInstance>()

const append = (data: Data) => {
  const newChild = { id: id++, label: 'testtest', children: [] }
  treeRef1.value?.append(newChild, data)
  treeRef2.value?.append(newChild, data)
}

const remove = (node: Node, data: Data) => {
  treeRef1.value?.remove(data)
  treeRef2.value?.remove(data)
}

const renderContent: RenderContentFunction = (h, { node, data }) => {
  return h(
    'div',
    {
      class: 'custom-tree-node',
    },
    [
      h('span', null, node.label),
      h('div', null, [
        h(
          UButton,
          {
            type: 'primary',
            link: true,
            onClick: () => append(data),
          },
          {
            default: () => 'Append',
          }
        ),
        h(
          UButton,
          {
            type: 'danger',
            link: true,
            style: 'margin-left: 4px',
            onClick: () => remove(node, data),
          },
          {
            default: () => 'Delete',
          }
        ),
      ]),
    ]
  )
}

const dataSource = ref<Tree[]>([
  {
    id: 1,
    label: 'Level one 1',
    children: [
      {
        id: 4,
        label: 'Level two 1-1',
        children: [
          {
            id: 9,
            label: 'Level three 1-1-1',
          },
          {
            id: 10,
            label: 'Level three 1-1-2',
          },
        ],
      },
    ],
  },
  {
    id: 2,
    label: 'Level one 2',
    children: [
      {
        id: 5,
        label: 'Level two 2-1',
      },
      {
        id: 6,
        label: 'Level two 2-2',
      },
    ],
  },
  {
    id: 3,
    label: 'Level one 3',
    children: [
      {
        id: 7,
        label: 'Level two 3-1',
      },
      {
        id: 8,
        label: 'Level two 3-2',
      },
    ],
  },
])
</script>

<style>
.custom-tree-node {
  flex: 1;
  display: flex;
  align-items: center;
  justify-content: space-between;
  font-size: 14px;
  padding-right: 8px;
}
</style>

自定义节点类名

可自定义节点类名。

使用 props.class 构建节点类名。

树节点过滤

可对树节点进行过滤。

调用树实例的 filter 方法并传入关键字；需要同时配置 filter-node-method 作为过滤函数。

Level one 1

Level two 1-1

Level three 1-1-1

Level three 1-1-2

Level one 2

Level two 2-1

Level two 2-2

Level one 3

Level two 3-1

Level two 3-2

手风琴模式

同级仅允许展开一个节点。

Level one 1

Level one 2

Level one 3

可拖拽

添加 draggable 属性可拖拽节点。

Level one 1

Level two 1-1

Level three 1-1-1

Level one 2

Level two 2-1

Level three 2-1-1

Level two 2-2

Level three 2-2-1

Level one 3

Level two 3-1

Level three 3-1-1

Level two 3-2

Level three 3-2-1

vue

<template>
  <u-tree
    style="max-width: 600px"
    :allow-drop="allowDrop"
    :allow-drag="allowDrag"
    :data="data"
    draggable
    default-expand-all
    node-key="id"
    @node-drag-start="handleDragStart"
    @node-drag-enter="handleDragEnter"
    @node-drag-leave="handleDragLeave"
    @node-drag-over="handleDragOver"
    @node-drag-end="handleDragEnd"
    @node-drop="handleDrop"
  />
</template>

<script lang="ts" setup>
import type {
  AllowDropType,
  NodeDropType,
  RenderContentContext,
} from 'uniboot-ui'

type Node = RenderContentContext['node']

const handleDragStart = (node: Node, ev: DragEvent) => {
  console.log('drag start', node)
}
const handleDragEnter = (draggingNode: Node, dropNode: Node, ev: DragEvent) => {
  console.log('tree drag enter:', dropNode.label)
}
const handleDragLeave = (draggingNode: Node, dropNode: Node, ev: DragEvent) => {
  console.log('tree drag leave:', dropNode.label)
}
const handleDragOver = (draggingNode: Node, dropNode: Node, ev: DragEvent) => {
  console.log('tree drag over:', dropNode.label)
}
const handleDragEnd = (
  draggingNode: Node,
  dropNode: Node | null,
  dropType: NodeDropType,
  ev: DragEvent
) => {
  console.log('tree drag end:', dropNode && dropNode.label, dropType)
}
const handleDrop = (
  draggingNode: Node,
  dropNode: Node,
  dropType: Exclude<NodeDropType, 'none'>,
  ev: DragEvent
) => {
  console.log('tree drop:', dropNode.label, dropType)
}
const allowDrop = (draggingNode: Node, dropNode: Node, type: AllowDropType) => {
  if (dropNode.data.label === 'Level two 3-1') {
    return type !== 'inner'
  } else {
    return true
  }
}
const allowDrag = (draggingNode: Node) => {
  return !draggingNode.data.label.includes('Level three 3-1-1')
}

const data = [
  {
    label: 'Level one 1',
    children: [
      {
        label: 'Level two 1-1',
        children: [
          {
            label: 'Level three 1-1-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Level one 2',
    children: [
      {
        label: 'Level two 2-1',
        children: [
          {
            label: 'Level three 2-1-1',
          },
        ],
      },
      {
        label: 'Level two 2-2',
        children: [
          {
            label: 'Level three 2-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Level one 3',
    children: [
      {
        label: 'Level two 3-1',
        children: [
          {
            label: 'Level three 3-1-1',
          },
        ],
      },
      {
        label: 'Level two 3-2',
        children: [
          {
            label: 'Level three 3-2-1',
          },
        ],
      },
    ],
  },
]
</script>

树形控件 API

属性

名称	说明	类型	默认值
data	展示数据	`array`	—
empty-text	内容为空时展示的文本	`string`	—
node-key	每个树节点用来作为唯一标识的属性，整棵树中应唯一	`string`	—
props	配置选项，见下表	`object`	—
render-after-expand	是否在第一次展开父节点后才渲染子节点	`boolean`	true
load	加载子树数据的方法，仅当 `lazy` 为 true 时生效	`Function`	—
render-content	树节点的渲染函数	`Function`	—
highlight-current	是否高亮当前选中节点	`boolean`	false
default-expand-all	是否默认展开所有节点	`boolean`	false
expand-on-click-node	是否在点击节点时展开/收起；为 false 时仅点击箭头图标才会展开/收起	`boolean`	true
check-on-click-node	是否在点击节点时选中/取消；为 false 时仅点击复选框才会切换选中状态	`boolean`	false
check-on-click-leaf	是否在点击叶子节点（末级）时切换选中状态	`boolean`	true
auto-expand-parent	展开子节点时是否自动展开父节点	`boolean`	true
default-expanded-keys	默认展开的节点 key 数组	`array`	—
show-checkbox	节点是否可被选择（显示复选框）	`boolean`	false
check-strictly	在显示复选框时，是否严格的遵循父子不互相关联	`boolean`	false
default-checked-keys	默认勾选的节点 key 数组	`array`	—
current-node-key	当前选中节点的 key	`string` / `number`	—
filter-node-method	对树节点进行筛选时执行的方法，返回 `false` 表示隐藏该节点	`Function`	—
accordion	是否每次只打开一个同级树节点展开	`boolean`	false
indent	相邻级节点间的水平缩进，单位为像素	`number`	18
icon	自定义树节点图标组件	`string` / `Component`	—
lazy	是否懒加载子节点，需与 `load` 方法结合使用	`boolean`	false
draggable	是否开启拖拽节点功能	`boolean`	false
allow-drag	判断节点能否被拖拽；若返回 `false`，节点不能被拖拽	`Function`	—
allow-drop	拖拽时判定目标节点能否被放置。若返回 `false`，拖拽节点不能被放置到目标节点。`type` 有三种取值：`prev`（插入目标节点前）、`inner`（插入至目标节点内）、`next`（插入目标节点后）	`Function`	—

props

属性	说明	类型	默认值
label	指定节点标签为节点对象的某个属性值，或返回字符串的函数	`string` / `Function`	—
children	指定子树为节点对象的某个属性值	`string`	—
disabled	指定节点选择框是否禁用为节点对象的某个属性值或返回布尔值的函数	`string` / `Function`	—
isLeaf	指定节点是否为叶子节点，仅在懒加载时有效	`string` / `Function`	—
class	自定义节点类名	`string` / `Function`	—

暴露

Tree 提供以下方法（与当前选中节点数组等相关）。

方法	说明	参数
filter	过滤所有树节点；被过滤的节点将被隐藏	一个参数，会作为 `filter-node-method` 的第一个入参
updateKeyChildren	为节点设置新数据，仅在设置了 `node-key` 时生效	`(key, data)` 两个参数：1. 节点 key 2. 新数据
getCheckedNodes	若节点可被选择（`show-checkbox` 为 `true`），返回目前被选中的节点所组成的数组	`(leafOnly, includeHalfChecked)` 两个布尔参数：1. 默认 `false`；为 `true` 时仅返回叶子节点中被选中的节点 2. 默认 `false`；为 `true` 时返回值包含半选节点
setCheckedNodes	设置目前勾选的节点，仅在使用 `node-key` 时生效	`(nodes, leafOnly)` 两个参数：1. 待勾选节点的对象数组 2. 布尔值，为 `true` 时仅设置叶子节点的选中状态，默认 `false`
getCheckedKeys	若节点可被选择（`show-checkbox` 为 `true`），返回目前选中节点的 key 所组成的数组	`(leafOnly)` 布尔参数，默认 `false`；为 `true` 时仅返回叶子节点的选中 key
setCheckedKeys	通过 key 设置目前勾选的节点，仅在使用 `node-key` 时生效	`(keys, leafOnly)` 两个参数：1. 待勾选节点的 key 数组 2. 布尔值，为 `true` 时仅设置叶子节点选中状态，默认 `false`
setChecked	通过 key 或 data 设置节点勾选状态，仅在使用 `node-key` 时生效	`(key/data, checked, deep)` 三个参数：1. 待勾选节点的 key 或 data 2. 是否选中 3. 是否深度选中（要求 `check-strictly` 为 `false`）
getHalfCheckedNodes	若节点可被选择（`show-checkbox` 为 `true`），返回半选节点组成的数组	—
getHalfCheckedKeys	若节点可被选择（`show-checkbox` 为 `true`），返回目前半选节点的 key 所组成的数组	—
getCurrentKey	获取当前被选中节点的 key，若没有则返回 `null`	—
getCurrentNode	获取当前被选中节点的 data，若没有则返回 `null`	—
setCurrentKey	通过 key 设置当前高亮节点，仅在使用 `node-key` 时生效	`(key, shouldAutoExpandParent=true)` 1. 待高亮节点的 key，`null` 表示取消高亮 2. 是否自动展开父节点
setCurrentNode	通过 node 设置当前高亮节点，仅在使用 `node-key` 时生效	`(node, shouldAutoExpandParent=true)` 1. 待高亮节点 2. 是否自动展开父节点
getNode	根据 data 或 key 获取 Tree 中的 node	`(data)` 节点的 data 或 key
remove	删除节点，仅在使用 `node-key` 时生效	`(data)` 要删除节点的 data 或 node
append	为指定节点追加子节点	`(data, parentNode)` 1. 要追加的子节点 data 2. 父节点的 data、key 或 node
insertBefore	在指定节点前插入节点	`(data, refNode)` 1. 要插入的节点 data 2. 参考节点的 data、key 或 node
insertAfter	在指定节点后插入节点	`(data, refNode)` 1. 要插入的节点 data 2. 参考节点的 data、key 或 node

事件

名称	说明	参数
node-click	节点被点击时触发	四个参数：对应节点的节点对象、TreeNode 的 `node` 属性、TreeNode 自身、原生事件对象
node-contextmenu	节点上点击鼠标右键时触发	四个参数：事件对象、对应节点的节点对象、TreeNode 的 `node` 属性、TreeNode 自身
check-change	节点选中状态发生变化时触发	三个参数：状态发生变化的节点对象、是否选中、子树是否有选中节点
check	点击节点复选框后触发	两个参数：勾选/取消勾选的节点对象、树目前的勾选状态对象（含 `checkedNodes`、`checkedKeys`、`halfCheckedNodes`、`halfCheckedKeys`）
current-change	当前选中节点变化时触发	两个参数：当前选中节点的节点对象、TreeNode 的 `node` 属性
node-expand	节点展开时触发	三个参数：被展开节点的节点对象、TreeNode 的 `node` 属性、TreeNode 自身
node-collapse	节点收起时触发	三个参数：被收起节点的节点对象、TreeNode 的 `node` 属性、TreeNode 自身
node-drag-start	节点开始拖拽时触发	两个参数：被拖拽节点对应的对象、事件对象
node-drag-enter	拖拽进入其他节点时触发	三个参数：被拖拽节点对象、进入的节点对象、事件对象
node-drag-leave	拖拽离开节点时触发	三个参数：被拖拽节点对象、离开的节点对象、事件对象
node-drag-over	在节点上拖拽经过时触发（类似 mouseover）	三个参数：被拖拽节点对象、经过的节点对象、事件对象
node-drag-end	拖拽结束时触发	四个参数：被拖拽节点对象、拖拽结束位置节点对象（可能为 `undefined`）、放置类型（before / after / inner）、事件对象
node-drop	拖拽成功放置后触发	四个参数：被拖拽节点对象、目标节点对象、放置类型（before / after / inner）、事件对象

插槽

名称	说明	类型
default	自定义树节点内容	`object`
empty	数据为空时的展示内容	—

类型声明

显示类型声明

interface RootTreeType {
  root: Ref<Node>
  // ...
}

// UnwrapRef<RootTreeType['root']> => Node
type Node = {
  canFocus: boolean
  checked: boolean
  childNodes: Node[]
  data: TreeNodeData
  expanded: boolean
  id: number
  indeterminate: boolean
  isCurrent: boolean
  isEffectivelyChecked: boolean
  isLeaf?: boolean
  isLeafByUser?: boolean
  level: number
  loaded: boolean
  loading: boolean
  parent: Node | null
  store: TreeStore
  text: string | null
  visible: boolean
}

// TreeNodeData => Tree / TreeOptionProps
// Tree type is your prop type.
// TreeOptionProps is default prop type
interface TreeOptionProps {
  children?: string
  label?: string | ((data: TreeNodeData, node: Node) => string)
  disabled?: string | ((data: TreeNodeData, node: Node) => boolean)
  isLeaf?: string | ((data: TreeNodeData, node: Node) => boolean)
  class?: (
    data: TreeNodeData,
    node: Node
  ) => string | { [key: string]: boolean }
}

Tour 漫游式引导

Virtualized Tree 虚拟化树形控件

Tree 树形控件 ​

基础用法 ​

可选择 ​

懒加载下的叶子节点 ​

多次懒加载 ​

禁用复选框 ​

默认展开与默认选中 ​

勾选树节点 ​

自定义节点内容 ​

自定义节点类名 ​

树节点过滤 ​

手风琴模式 ​

可拖拽 ​

树形控件 API ​

属性 ​

props ​

暴露 ​

事件 ​

插槽 ​

类型声明 ​

Tree 树形控件

基础用法

可选择

懒加载下的叶子节点

多次懒加载

禁用复选框

默认展开与默认选中

勾选树节点

自定义节点内容

自定义节点类名

树节点过滤

手风琴模式

可拖拽

树形控件 API

属性

props

暴露

事件

插槽

类型声明