README.md

Vue-Tree 3.x

一款高性能 vue 虚拟树控件，支持搜索，定位，拖拽等。该控件是在公司业务的基础上不断打磨出来的，提供了十分丰富强大的 API，几乎能够满足你对树控件的所有需求。该控件同时支持 vue2 以及 vue3。

这是原先ctree的升级版本，同时支持 vue2 和 vue3。 新版改变了包的名称和部分 export 模块名称。

案例

在线 demo

安装

yarn 安装方式

yarn add @wsfe/vue-tree

npm 安装方式

npm install @wsfe/vue-tree

样式引入

直接引入 css

@import '~@wsfe/vue-tree/style.css';

引入 less 以便于变量覆盖

@import '~@wsfe/vue-tree/src/styles/index.less';

使用方式

// 大家可以根据需要是否引入VTreeNode, VTreeSearch, VTreeDrop
import Vtree, { VTreeNode, VTreeSearch, VTreeDrop } from '@wsfe/vue-tree'
import '@wsfe/vue-tree/style.css'

接口文档

VTree API

VTree Props

属性	说明	类型	默认值
value	选中的值，可用 v-model ；单选为字符串或数字，多选为 separator 分隔的字符串或数组，优先多选	string | number | Array<string | number>	无
data	传入的树数据。数据量大时，不建议通过 props 传入数据，建议用 setData 方法代替	object[]	[]
unloadDataList	供未加载且选中节点查询 title 字段值用的列表，格式与 data 一致即可	object[]	[]
showUnloadCheckedNodes	过滤已选时是否在列表后面展示未加载的已选节点	boolean	true
emptyText	数据为空时显示的文本	string	'暂无数据'
titleField	节点标题字段	string	'title'
keyField	节点唯一标识字段	string	'id'
separator	多选模式下 value 分隔符	string	','
checkable	是否可多选	boolean	false
selectable	是否可单选	boolean	false
filteredNodeCheckable	是否可勾选被过滤节点	boolean	false
cascade	父子节点是否关联	boolean	true
enableLeafOnly	是否只启用子节点，当 多选且父子不关联 或 单选 时有效	boolean	false
disableAll	是否禁用所有节点	boolean	false
defaultExpandAll	是否默认展开所有节点	boolean	false
defaultExpandedKeys Deprecated	默认展开的节点 key	Array<string | number>	[]
expandedKeys 2.2.0	展开的节点 key ，组件内部将会响应此 Prop 的变化	Array<string | number>	[]
draggable	是否可拖拽	boolean	false
droppable	是否可放置	boolean	false
beforeDropMethod	在放置节点之前执行的方法，返回 true 允许放置， false 可阻止放置	(dragKey: string | number, dropKey: string | number, hoverPart: 'before' | 'body' | 'after') => boolean	() => true
ignoreMode	忽略模式，指定 getCheckedNodes, getCheckedKeys 与 v-model 默认要忽略的部分	'none' | 'parents' | 'children'	'none'
autoLoad	异步加载初始化时是否自动加载根节点	boolean	true
load	异步加载方法	(node: null | TreeNode, resolve: Function, reject: Function) => any	无
render	节点渲染 render 函数	(h: CreateElement, node: TreeNode) => VNode	无
filterMethod	节点过滤方法	(keyword: string, node: TreeNode) => boolean	无
expandOnFilter 2.1.0	过滤时是否展开所有可见节点	boolean	true
unselectOnClick 2.1.0	点击已选中节点是否取消选中	boolean	true
loading	是否显示 loading 图标	boolean	false
nodeClassName	节点根元素的 class ，传入函数以对每个节点定制 class	string | object | Array<string | object> | (node: TreeNode) => string | object | Array<string | object>	无
nodeMinHeight	根据节点最小高度计算数据总高度	number	30
nodeIndent	子节点缩进	number	20
renderNodeAmount	渲染节点数量，可见节点数大于此值且高度超过(容器可视高度能容纳节点数 + bufferNodeAmount)则不会渲染所有可见节点	number	100
bufferNodeAmount	当滚动到视野外的节点个数大于此值时刷新渲染节点	number	20

VTree Events

注：从 2.0.8 起，事件中返回的节点信息都是包括 _parent 与 children 的完整节点信息（拖拽事件的 dataTransfer 除外）。

事件名	说明	返回值
input	选中节点改变时触发	选中的节点
expand	展开/折叠时触发	节点信息
check	勾选时触发（多选）	被勾选的节点信息
uncheck	取消勾选时触发（多选）	被取消勾选的节点信息
checked-change	勾选/取消勾选时触发（多选）	所有被勾选节点（数组）
select	选中时触发（单选）	被选中的节点信息
unselect	取消选中时触发（单选）	被取消选中的节点信息
selected-change	选中/取消选中时触发（单选）	被选中节点
click	点击节点时触发	节点信息, 鼠标事件
node-dblclick	双击节点时触发	节点信息, 鼠标事件
node-right-click	右击节点时触发	节点信息, 鼠标事件
node-dragstart	开始拖拽节点时触发	节点信息, 拖拽事件对象
node-dragenter	dragenter 时触发	节点信息 , 拖拽事件对象, 事件触发的节点部位 'before' | 'body' | 'after'
node-dragover	dragover 时触发	节点信息 , 拖拽事件对象, 事件触发的节点部位 'before' | 'body' | 'after'
node-dragleave	dragleave 时触发	节点信息 , 拖拽事件对象, 事件触发的节点部位 'before' | 'body' | 'after'
node-drop	放置节点时触发	节点信息 , 拖拽事件对象, 事件触发的节点部位 'before' | 'body' | 'after'

VTree Methods

方法	说明	参数	返回值
setData	使用此方法重置树数据，可避免大量数据被 vue 监听	data: object[]: 同 data Prop	void
setChecked	设置多选选中/取消选中	key: string | number: 节点 key value: boolean: 是否选中	void
setCheckedKeys	批量设置选中/取消选中	keys: Array<string | number>: 节点 key value: boolean: 是否选中	void
checkAll	设置所有数据全选	无	void
clearChecked	清空选中	无	void
setSelected	设置单选选中/取消选中	key: string | number: 节点 key value: boolean: 是否选中	void
setExpand	设置展开/折叠	key: string | number: 节点 key value: boolean: 是否展开 expandParent: boolean = true: 如果是展开是否同时展开父节点 2.0.6	void
setExpandKeys	批量展开/折叠	keys: Array<string | number>: 节点 key value: boolean: 是否展开	void
setExpandAll	设置全部展开/折叠	value: boolean: 是否展开	void
getCheckedNodes	获取多选选中节点	ignoreMode: 'none' | 'parents' | 'children': 需要忽略的部分，默认为 ignoreMode Prop	TreeNode[]
getCheckedKeys	获取多选选中节点 key	ignoreMode: 'none' | 'parents' | 'children': 需要忽略的部分，默认为 ignoreMode Prop	Array<string | number>
getIndeterminateNodes	获取半选状态的节点	无	TreeNode[]
getSelectedNode	获取单选选中节点	无	TreeNode | null
getSelectedKey	获取单选选中节点 key	无	TreeNode | null
getExpandNodes	获取展开的节点	无	TreeNode[]
getExpandKeys	获取展开的节点 key	无	TreeNode[]
getCurrentVisibleNodes	获取当前可见的节点	无	TreeNode[]
getNode	根据 key 获取节点	key: string | number: 节点 key	TreeNode | null
getTreeData	获取树形结构的节点数据	无	TreeNode[]
getFlatData	获取扁平化后的节点数据	无	TreeNode[]
getNodesCount	获取节点总数量	无	number
insertBefore	在参照节点前插入一个节点	insertedNode: 节点 key 或者单个节点数据 referenceKey: string | number: 参照节点 key	TreeNode | null 返回插入的节点
insertAfter	在参照节点后插入一个节点	insertedNode: 节点 key 或者单个节点数据 referenceKey: string | number: 参照节点 key	TreeNode | null 返回插入的节点
append	在父节点第一层子节点的末尾插入一个节点	insertedNode: 节点 key 或者单个节点数据 parentKey: string | number: 父节点 key	TreeNode | null 返回插入的节点
prepend	在父节点第一层子节点的开头插入一个节点	insertedNode: 节点 key 或者单个节点数据 parentKey: string | number: 父节点 key	TreeNode | null 返回插入的节点
remove	删除节点	removedKey: string | number: 要删除的节点 key	TreeNode | null 返回删除的节点
filter	过滤节点	keyword: string: 过滤关键词 filterMethod: (keyword: string, node: TreeNode) => boolean: 过滤方法，默认为 filterMethod Prop ，如果没有传 filterMethod Prop 则为搜索 title 字段的一个内置方法	void
showCheckedNodes	展示已选节点	showUnloadCheckedNodes: boolean: 是否显示未加载的选中节点，默认为 Prop 传入的值	void
loadRootNodes	从远程加载根节点	无	Promise<void>
scrollTo	滚动到指定节点位置	key: string | number: 节点 key verticalPosition: 'top' | 'center' | 'bottom' | number: 滚动的垂直位置	void

VTree Slots

名称	说明
empty	暂无数据
loading	加载中显示的图标

VTree Data Fields

注：以 '_' 开头的字段最好不要覆盖，以免影响内部处理逻辑

字段	说明
id	默认以 'id' 作为 key 字段，也可以通过 keyField Prop 指定其他字段作为 key 字段
title	默认显示的名称，可通过 titleField Prop 指定其他字段作为 title 字段
checked	多选模式下是否勾选
selected	单选模式下是否选中
indeterminate	多选模式下是否半选状态
disabled	是否禁用
expand	父节点有效，节点展开状态
visible	是否可见
_filterVisible	过滤后是否可见，如果为 false 则在其他可见情况下也是不可见的
_parent	父节点
children	子节点数组
isLeaf	标记节点是否为叶子节点
_level	节点层级，默认从 0 开始
_loading	节点是否正在加载
_loaded	节点是否已经加载过，异步加载下有效

VTreeSearch API

VTreeSearch Props

注：可在 VTreeSearch 上直接使用 VTree 的所有 Props

属性	说明	类型	默认值
searchPlaceholder	搜索输入框的 placeholder	string	'搜索关键字'
showCheckAll	是否显示全选复选框	boolean	true
showCheckedButton	是否显示已选按钮	boolean	true
checkedButtonText	已选按钮文字	string	'已选'
showFooter	是否显示底部信息	boolean	true
searchMethod 2.0.2	如果传入此 Prop ，触发 search 事件后将会执行此方法，否则会执行组件内置的搜索方法	(keyword: string) => void | Promise<void>	无
searchLength	触发搜索的字符长度	number	1
searchDisabled	禁用搜索功能	boolean	false
searchRemote	是否远程搜索，传入 searchMethod 时无效	boolean	false
searchDebounceTime	搜索防抖时间，单位为毫秒	number	300

VTreeSearch Events

注：可在 VTreeSearch 上直接监听 VTree 的所有 Events

事件名	说明	返回值
search	执行搜索操作时触发	搜索的关键字

VTreeSearch Methods

注：可在 VTreeSearch 上直接调用 VTree 的所有 Methods

方法	说明	参数	返回值
clearKeyword	清空关键字	无	void
getKeyword	获取搜索关键字	无	string
search	执行搜索	keyword: string: 搜索的关键字，默认为内部 this.keyword	Promise<void>

VTreeSearch Slots

注：可在 VTreeSearch 上直接传入 VTree 的所有 Slots

名称	说明
search-input	搜索输入框，可通过此 slot 自行封装树搜索组件的行为
actions	操作按钮，可在搜索输入框后加入更多操作按钮
footer	底部信息

VTreeDrop API

VTreeDrop Props

注：可在 VTreeDrop 上直接使用 VTree 和 VTreeSearch 的所有 Props

属性	说明	类型	默认值
dropHeight	下拉内容高度	number	300
dropPlaceholder	展示输入框 placeholder	string	无
dropDisabled	是否禁用	boolean	false
clearable	允许清空	boolean	false
placement	下拉弹出框位置，注意！！不支持自动识别方向	'bottom-start' | 'bottom-end' | 'bottom' | 'top-start' | 'top-end' | 'top'	'bottom-start'
transfer	将下拉 DOM 转移到 body 中	boolean	false
dropdownClassName	在下拉框容器上额外添加的 class	string | string[]	无
dropdownMinWidth 2.0.1	下拉框容器最小宽度，未指定则默认为展示输入框宽度。 适合 transfer 为 false 时使用	number	无
dropdownWidthFixed 2.0.5	固定下拉框容器宽度，当内容超出最小宽度不会伸长，而是出现横向滚动条	boolean	false

VTreeDrop Events

注：可在 VTreeDrop 上直接监听 VTree 和 VTreeSearch 的所有 Events

事件名	说明	返回值
dropdown-visible-change	下拉框出现或消失时触发	下拉框是否可见
clear	点击清空按钮时触发	无

VTreeDrop Methods

注：可在 VTreeDrop 上直接调用 VTree 和 VTreeSearch 的所有 Methods

VTreeDrop Slots

注：可在 VTreeDrop 上直接传入 VTree 和 VTreeSearch 的所有 Slots

名称	说明
默认	展示输入框
display	展示输入框的展示文字，如果有默认 slot 则此 slot 无效
clear	替换清空图标，如果有默认 slot 则此 slot 无效

默认 slot 与 display slot 的 Slot Props 2.3.0 ：

/** 展示 slot 的 props */
slotProps: {
  /** 多选选中的节点 */
  checkedNodes: [] as TreeNode[],

  /** 多选选中的节点 key */
  checkedKeys: [] as Array<string | number>,

  /** 单选选中的节点 */
  selectedNode: null as TreeNode | null,

  /** 单选选中的节点 key */
  selectedKey: null as string | number | null,
},

注意： checkedNodes 与 selectedNode 只包含已加载的节点，如果设置了选中的值（比如设置了 value Prop），但没有设置树的数据，则这两个字段内容将为空；而 checkedKeys 与 selectedKey 则会包含未加载的选中节点 key 。