Tree 树形控件

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

基础用法

基础的树形结构。

一级 1

一级 2

一级 3

可选

用于节点选择。

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

根节点1

根节点2

警告

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

懒加载自定义叶子节点

在点击节点之前，节点的数据不会被提取，因此 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
      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>
    <el-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>
            <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,
  TreeInstance,
} from 'element-plus'

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(
          ElButton,
          {
            type: 'primary',
            link: true,
            onClick: () => append(data),
          },
          {
            default: () => 'Append',
          }
        ),
        h(
          ElButton,
          {
            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 来构建节点的类名。

节点过滤

树节点可以被过滤

调用 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>
import type {
  AllowDropType,
  NodeDropType,
  RenderContentContext,
} from 'element-plus'

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>

Tree API

属性

名称	描述	类型	默认值
data	树数据	`array`	—
empty-text	数据为空时显示的文本	`string`	—
每个树节点用来作为唯一标识的属性，在整棵树中应该是唯一的	节点的唯一标识键名，其值在整个树中应唯一	`string`	—
props	配置选项，请参见下表	`object`	—
是否在第一次展开父节点后才渲染子节点	是否在第一次展开父节点后才渲染子节点	`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
展开子节点时是否自动展开父节点	展开子节点时是否自动展开父节点	`boolean`	true
default-expanded-keys	初始展开节点的键数组	`array`	—
show-checkbox	节点是否可选	`boolean`	false
check-strictly	当 `show-checkbox` 为 `true` 时，节点的选中状态是否不影响其父节点和子节点	`boolean`	false
default-checked-keys	初始选中节点的键数组	`array`	—
current-node-key	初始选中节点的键	`string` / `number`	—
对树节点进行筛选时执行的方法	使用过滤方法时，此函数将在每个节点上执行。如果返回 `false`，树节点将被隐藏。	`Function`	—
accordion	是否每次只打开一个同级树节点展开	`boolean`	false
indent	相邻层级节点之间的水平缩进（以像素为单位）	`number`	18
icon	自定义树节点图标组件	`string` / `Component`	—
lazy	是否懒加载叶子节点，需与 `load` 属性结合使用	`boolean`	false
draggable	是否开启拖拽节点功能	`boolean`	false
判断节点能否被拖拽	该函数在拖拽节点前执行。如果返回 `false`，则该节点无法被拖拽	`Function`	—
拖拽时判定目标节点能否被放置	该函数在拖拽节点放置前执行。如果返回 `false`，则拖拽节点无法放置在目标节点。`type` 有三个可能的值：'prev'（将拖拽节点插入到目标节点前）、'inner'（将拖拽节点插入到目标节点内）和 'next'（将拖拽节点插入到目标节点后）	`Function`	—

props

属性	描述	类型	默认值
label	指定节点对象的哪个键用作节点的标签	`string` / `Function`	—
children	指定哪个节点对象用作节点的子树	`string`	—
disabled	指定节点对象的哪个键表示节点的复选框是否被禁用	`string` / `Function`	—
指定节点是否为叶子节点	指定节点是否为叶子节点，仅在开启懒加载时生效	`string` / `Function`	—
class	自定义节点类名	`string` / `Function`	—

暴露

`Tree` 有以下方法，它返回当前选中的节点数组。

方法	描述	参数
filter	过滤所有树节点，被过滤的节点将被隐藏	接收一个参数，该参数将作为 filter-node-method 的第一个参数
更新节点的子节点	为节点设置新数据，仅在指定了 `node-key` 时生效	(key, data) 接收两个参数：1. 节点的 key 2. 新数据
getCheckedNodes	如果节点可选（`show-checkbox` 为 `true`），则返回当前选中的节点数组	(leafOnly, includeHalfChecked) 接收两个布尔类型参数：1. 默认值为 `false`。如果参数为 `true`，它只返回当前选中的子节点数组。2. 默认值为 `false`。如果参数为 `true`，返回值将包含半选节点
设置选中节点	设置某些节点为选中状态，仅在指定了 `node-key` 时生效	(nodes, leafOnly) 接收两个参数：1. 要选中的节点对象数组 2. 布尔类型参数。如果设置为 `true`，则仅设置叶子节点的选中状态。默认值为 `false`。
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 或数据 2. 一个布尔参数，指示是否选中。3. 一个布尔参数，指示是否递归地选中/取消选中子节点（自 2.14.0 起，无论 `check-strictly` 设置如何，此参数都有效）。
getHalfCheckedNodes	如果节点可选（`show-checkbox` 为 `true`），则返回当前半选中的节点数组	—
getHalfCheckedKeys	如果节点可选（`show-checkbox` 为 `true`），则返回当前半选中的节点键数组	—
getCurrentKey	返回当前高亮节点的 key（如果没有高亮节点则返回 null）	—
getCurrentNode	返回当前高亮节点的数据（如果没有高亮节点则返回 null）	—
setCurrentKey	通过 key 设置高亮节点，仅在指定了 `node-key` 时生效	(key, shouldAutoExpandParent=true) 1. 要高亮的节点 key。如果为 `null`，则取消当前高亮节点 2. 是否自动展开父节点
设置当前节点	设置高亮节点，仅在指定了 `node-key` 时生效	(node, shouldAutoExpandParent=true) 1. 要高亮的节点 2. 是否自动展开父节点
getNode	通过数据或 key 获取节点	(data) 节点的数据或 key
删除	删除一个节点，仅在指定了 node-key 时生效	(data) 要删除的节点数据或节点对象
append	为树中的给定节点追加一个子节点	(data, parentNode) 1. 要追加的子节点数据 2. 父节点的数据、key 或节点对象
向前插入	在树中给定节点前插入一个节点	(data, refNode) 1. 要插入的节点数据 2. 参考节点的数据、key 或节点对象
向后插入	在树中给定节点后插入一个节点	(data, refNode) 1. 要插入的节点数据 2. 参考节点的数据、key 或节点对象

事件

名称	描述	参数
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 实例本身
节点拖拽开始	在节点开始拖拽时触发	两个参数：对应拖拽节点的节点对象、事件对象。
节点拖拽进入	在拖拽节点进入其他节点时触发	三个参数：对应拖拽节点的节点对象、对应进入节点的节点对象、事件对象。
节点拖拽离开	在拖拽节点离开某个节点时触发	三个参数：对应拖拽节点的节点对象、对应离开节点的节点对象、事件对象。
节点拖拽经过	在节点上拖拽时触发（类似于 mouseover 事件）	三个参数：对应拖拽节点的节点对象、对应拖拽经过节点的节点对象、事件对象。
节点拖拽结束	在拖拽结束时触发	四个参数：对应拖拽节点的节点对象、对应拖拽结束节点的节点对象（可能为 `undefined`）、节点放置类型（before / after / inner）、事件对象。
节点放置	在拖拽节点成功放置后触发	四个参数：对应拖拽节点的节点对象、对应放置节点的节点对象、节点放置类型（before / after / inner）、事件对象。

插槽

名称	描述	类型
default	自定义树节点的内容	`object`
空数据 2.3.4	数据为空时的自定义内容	—

类型声明

显示声明

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 }
}