Tui

Tree 树形控件

TsTree 提供常见树节点交互能力：单选、父子勾选联动、节点禁用，以及同层/自由拖拽。

支持 childCheckMode（同级多选/单选）与标准三态（checked/unchecked/indeterminate）父节点状态计算。

支持 parentKeysInChecked 配置 checkedKeys 返回是否包含父节点（全选/半选）。

支持 disabledKeys 默认禁用节点配置。

支持通过 nodePaddingLeft 自定义节点 padding-left（并兼容 indent）。

支持 showOverflowTooltip + tooltipEffect 的内置超长文案提示，并保留 slot 自定义覆盖。

拖拽场景推荐配合 update:data 持久化最新结构。

基础用法（单选 + 勾选模式 + 禁用 keys）

支持节点单选、childCheckMode 子节点勾选模式与 disabledKeys 默认禁用节点配置。

示例代码

vue

同层拖拽（dragMode = sibling）

同一父节点下允许拖拽排序，不允许跨层级移动。

示例代码

vue

自由拖拽（dragMode = free）

支持跨层级拖拽，可放置到目标节点前、后或内部。

示例代码

vue

自定义箭头 + 独立勾选

通过 #arrow 插槽替换展开箭头；通过 independentCheck 开启父子节点互不影响的勾选模式。

使用 `showArrow` 可关闭 arrow（含 arrow 插槽渲染）。

使用 `independentCheck` 后，父子节点勾选互不影响。

当前勾选：service-api

示例代码

vue

文件夹目录（FolderOpen/FolderClose）

通过 showCheckbox=false 隐藏复选框，结合 label-prefix/label-suffix 插槽实现文件夹目录样式。

docs2

guides2

getting-started.md

tree-component.md

examples2

tree-basic.vue

tree-folder.vue

src1

components2

Tree.vue

TreeNode.vue

该示例使用 FolderCloseIcon / FolderOpenIcon 构建文件夹目录，并隐藏了复选框。

示例代码

vue

右键菜单（node-contextmenu）

通过 node-contextmenu 获取当前节点与原生鼠标事件，可用于自定义右键菜单。

最近右键节点：-

示例中在 `handleRightClick` 里调用了 `event.preventDefault()` 来接管浏览器右键菜单。

示例代码

vue

属性 Props

data

树节点数据

TreeNodeData[]

[]

v-model

当前单选节点 key

string | number | null

null

value

非受控模式下的单选节点 key

string | number | null

null

checkedKeys

勾选节点 key 列表

Array<string | number>

[]

expandedKeys

展开节点 key 列表

Array<string | number>

[]

checkable

是否显示勾选框

boolean

true

showCheckbox

是否显示复选框（隐藏后不影响 v-model 与展开逻辑）

boolean

true

selectable

是否允许节点单选

boolean

true

independentCheck

勾选是否父子不关联（父子互不影响）

boolean

false

childCheckMode

子节点勾选模式：`multiple` 为同级多选；`single` 为同级单选（两者在关联模式下都会计算父节点全选/半选状态）

'multiple' | 'single'

multiple / single

multiple

parentKeysInChecked

`checkedKeys` 返回是否包含父节点：`all` 仅全选父节点；`all-or-indeterminate` 包含全选与半选父节点；`none` 不包含父节点

'all' | 'all-or-indeterminate' | 'none'

all / all-or-indeterminate / none

all-or-indeterminate

defaultExpandAll

是否默认展开全部节点

boolean

false

showArrow

是否显示展开箭头（关闭后也会关闭 arrow 插槽渲染）

boolean

true

showOverflowTooltip

节点文案超出省略时是否显示内置 tooltip（default slot 可自定义覆盖）

boolean

false

tooltipEffect

内置 tooltip 主题风格

'light' | 'dark'

light / dark

light

disabled

是否禁用整个树

boolean

false

dragMode

拖拽模式

'none' | 'sibling' | 'free'

none / sibling / free

none

indent

层级缩进像素（兼容参数）

number

nodePaddingLeft

节点行内 `padding-left` 缩进像素（优先级高于 `indent`）

number

nodeKey

节点唯一键字段名

string

key

labelKey

节点显示文本字段名

string

label

childrenKey

子节点字段名

string

children

disabledKey

禁用字段名

string

disabled

disabledKeys

默认禁用节点 key 列表（支持父/子节点）

Array<string | number>

[]

事件 Events

update:modelValue

单选节点变化

(value: TreeKey | null) => void

change

单选节点变化（附带节点）

(value: TreeKey | null, node: TreeNodeData | null) => void

update:checkedKeys

勾选节点变化

(keys: TreeKey[]) => void

check

勾选动作触发

(keys: TreeKey[], node: TreeNodeData, checked: boolean) => void

update:expandedKeys

展开节点变化

(keys: TreeKey[]) => void

expand

展开动作触发

(keys: TreeKey[], node: TreeNodeData, expanded: boolean) => void

update:data

拖拽后最新树数据

(treeData: TreeNodeData[]) => void

node-drop

拖拽落点事件

(payload: TreeDropPayload) => void

node-contextmenu

节点右键事件

(node: TreeNodeData, event: MouseEvent) => void

插槽 Slots

default

自定义节点内容，参数：{ node, level }

label-prefix

label 前缀插槽，参数：{ node, level, expanded, hasChildren, disabled }

label-suffix

label 后缀插槽，参数：{ node, level, expanded, hasChildren, disabled }

arrow

自定义展开箭头，参数：{ node, level, expanded, hasChildren, disabled }

TreeNodeData Type

key

节点唯一 key

string | number

label

节点显示文本

string

children

子节点

TreeNodeData[]

[]

disabled

节点是否禁用

boolean

false

checkable

节点是否可勾选

boolean

true

selectable

节点是否可单选

boolean

true

draggable

节点是否可拖拽

boolean

true

基础用法（单选 + 勾选模式 + 禁用 keys）

同层拖拽（dragMode = sibling）

自由拖拽（dragMode = free）

自定义箭头 + 独立勾选

文件夹目录（FolderOpen/FolderClose）

右键菜单（node-contextmenu）

属性 Props

事件 Events

插槽 Slots

TreeNodeData Type