Tree 树形控件

用清晰的层级结构展示信息。

基础用法

基础的树形结构。

一级 1

一级 2

一级 3

可选

用于节点选择。

该示例还展示了如何异步加载节点数据。

根节点1

根节点2

警告

当使用 show-checkbox 时，由于 `check-on-click-leaf` 默认为 true，可以通过点击最后的子节点来选中它们。

懒加载自定义叶子节点

由于节点数据不是一次性获取的，所以 Tree 组件无法判断当前节点是否为叶子节点，所以会为每个节点都渲染一个下拉按钮，你可以在点击节点后，动态告知 Tree 组件当前节点是否为叶子节点，从而让 Tree 组件移除当前节点的下拉按钮。

区域

多次懒加载 2.6.3

远程懒加载节点数据时，有时懒加载可能会失败。在这种情况下，你可以调用 reject 以保持节点状态不变并允许继续远程加载。

区域

禁用复选框

节点的复选框可以被设置为禁用。

在这个例子中，`disabled` 属性在 `defaultProps` 中声明，一些节点被设置为 `disabled:true`。相应的复选框被禁用并且不能被点击。

一级 1

默认展开和默认选中

树节点可以初始展开或选中

使用 default-expanded-keys 和 default-checked-keys 来分别设置默认展开和默认选中的节点。请注意，为使其生效，需要设置 node-key。它的值是数据对象中一个键的名称，该键的值在整个树中应该是唯一的。

树节点的可选择

本例展示了如何获取和设置选中节点。它们都可以通过两种方式完成：通过节点和通过键。如果你使用键的方式，则需要设置 node-key。

vue

<template>
  <el-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">
    <el-button class="!ml-0" @click="getCheckedNodes">get by node</el-button>
    <el-button class="!ml-0" @click="getCheckedKeys">get by key</el-button>
    <el-button class="!ml-0" @click="setCheckedNodes">set by node</el-button>
    <el-button class="!ml-0" @click="setCheckedKeys">set by key</el-button>
    <el-button class="!ml-0" @click="resetChecked">reset</el-button>
  </div>
</template>

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

import type { RenderContentContext, TreeInstance } from 'element-plus'

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 语法。在一个真实的项目中，如果正确配置了相关的依赖项，`render-content` 就会起作用。

vue

<template>
  <div class="custom-tree-container">
    <p>Using render-content</p>
    <el-tree
      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>
    <el-tree
      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>
            <el-button type="primary" link @click="append(data)">
              Append
            </el-button>
            <el-button
              style="margin-left: 4px"
              type="danger"
              link
              @click="remove(node, data)"
            >
              Delete
            </el-button>
          </div>
        </div>
      </template>
    </el-tree>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ElButton } from 'element-plus'

import type { RenderContentContext, RenderContentFunction } from 'element-plus'

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

let id = 1000

const append = (data: Data) => {
  const newChild = { id: id++, label: 'testtest', children: [] }
  if (!data.children) {
    data.children = []
  }
  data.children.push(newChild)
  dataSource.value = [...dataSource.value]
}

const remove = (node: Node, data: Data) => {
  const parent = node.parent
  const children: Tree[] = parent?.data.children || parent?.data
  const index = children.findIndex((d) => d.id === data.id)
  children.splice(index, 1)
  dataSource.value = [...dataSource.value]
}

const renderContent: RenderContentFunction = (h, { node, data }) => {
  return h(
    'div',
    {
      class: 'custom-tree-node',
    },
    [
      h('span', null, node.label),
      h('div', null, [
        h(
          ElButton,
          {
            type: 'primary',
            link: true,
            onClick: () => append(data),
          },
          'Append '
        ),
        h(
          ElButton,
          {
            type: 'danger',
            link: true,
            style: 'margin-left: 4px',
            onClick: () => remove(node, data),
          },
          '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 构建节点的类名。

树节点的过滤

可以对树节点进行筛选操作

调用 Tree 实例的 `filter` 方法来筛选树节点。它的参数是筛选关键字。请注意，为了使其生效，需要设置 `filter-node-method`，它的值是筛选方法。

一级 1

二级 1-1

三级 1-1-1

三级 1-1-2

一级 2

二级 2-1

二级 2-2

一级 3

二级 3-1

二级 3-2

手风琴

同一时间，只可以展开一个同级节点。

一级 1

一级 2

一级 3

可拖拽

你可以通过添加一个 `draggable` 属性来拖放树节点。

一级 1

二级 1-1

三级 1-1-1

一级 2

二级 2-1

三级 2-1-1

二级 2-2

三级 2-2-1

一级 3

二级 3-1

三级 3-1-1

二级 3-2

三级 3-2-1

vue

<template>
  <el-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>
// eslint-disable-next-line no-restricted-imports
import type { DragEvents } from 'element-plus/es/components/tree/src/model/useDragNode'
import type {
  AllowDropType,
  NodeDropType,
  RenderContentContext,
} from 'element-plus'

type Node = RenderContentContext['node']

const handleDragStart = (node: Node, ev: DragEvents) => {
  console.log('drag start', node)
}
const handleDragEnter = (
  draggingNode: Node,
  dropNode: Node,
  ev: DragEvents
) => {
  console.log('tree drag enter:', dropNode.label)
}
const handleDragLeave = (
  draggingNode: Node,
  dropNode: Node,
  ev: DragEvents
) => {
  console.log('tree drag leave:', dropNode.label)
}
const handleDragOver = (draggingNode: Node, dropNode: Node, ev: DragEvents) => {
  console.log('tree drag over:', dropNode.label)
}
const handleDragEnd = (
  draggingNode: Node,
  dropNode: Node,
  dropType: NodeDropType,
  ev: DragEvents
) => {
  console.log('tree drag end:', dropNode && dropNode.label, dropType)
}
const handleDrop = (
  draggingNode: Node,
  dropNode: Node,
  dropType: NodeDropType,
  ev: DragEvents
) => {
  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>

属性

名称	描述	类型	默认值
data	树数据	`object`	—
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 2.9.6	是否在点击叶子节点（最后的子节点）时选中或取消选中节点。	`boolean`	true
auto-expand-parent	展开子节点的时候是否自动展开父节点	`boolean`	true
default-expanded-keys	初始展开节点的键数组	`object`	—
show-checkbox	节点是否可选	`boolean`	false
check-strictly	当 `show-checkbox` 为 `true` 时，节点的选中状态是否不影响其父节点和子节点	`boolean`	false
default-checked-keys	初始选中节点的键数组	`object`	—
current-node-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` 时有效	一个要被选中的节点数组
getCheckedKeys	如果节点可选（`show-checkbox` 为 `true`），则返回当前选中的节点键数组	(leafOnly) 接受一个布尔类型的参数，其默认值为 `false`。如果参数为 `true`，它只返回当前选中的子节点数组。
setCheckedKeys	设置某些节点为选中状态，仅在指定 `node-key` 时有效	(keys, leafOnly) 接受两个参数：1. 一个要被选中的节点 key 的数组 2. 一个布尔参数。如果设置为 `true`，则只设置叶子节点的选中状态。默认值为 `false`。
setChecked	设置节点是否被选中，仅在指定了 `node-key` 时有效	(key/data, checked, deep) 接受三个参数：1. 要选中的节点的 key 或 data 2. 一个布尔类型的参数，表示选中或不选中。 3. 一个布尔类型的参数，表示是否深度选中。
getHalfCheckedNodes	如果节点可选（`show-checkbox` 为 `true`），则返回当前半选中的节点数组	—
getHalfCheckedKeys	如果节点可选（`show-checkbox` 为 `true`），则返回当前半选中的节点键数组	—
getCurrentKey	返回高亮节点的 key (如果没有节点被高亮，则为 null)	—
getCurrentNode	返回高亮节点的数据 (如果没有节点被高亮，则为 null)	—
setCurrentKey	通过 key 设置高亮节点，仅在指定了 `node-key` 时有效	(key, shouldAutoExpandParent=true) 1. 要高亮的节点的 key。如果为 `null`，则取消当前高亮的节点 2. 是否自动展开父节点
setCurrentNode	设置高亮节点，仅在指定 `node-key` 时有效	(node, shouldAutoExpandParent=true) 1. 要高亮的节点 2. 是否自动展开父节点
getNode	通过 data 或 key 获取节点	(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)，事件。