前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载ant-design-vue 的Tree是一个以树形结构展示层级数据的核心组件可用于文件目录、组织架构、分类体系等几乎所有能抽象为父子关系的业务场景。本文以官方英文文档components/tree/index.en-US.md为骨架结合组件源码与仓库内 13 个官方示例components/tree/demo系统讲解 Tree 的 API 全量参数、事件回调、节点插槽定制、异步加载、拖拽排序、虚拟滚动与 DirectoryTree 目录树等实战能力帮助你完整掌握在 Vue 3 项目中构建高性能树形交互的方案。何时使用 Tree任何可以用层级结构表达的信息都适合用树形组件呈现例如文件目录 / 资源管理器组织架构上下级汇报关系生物分类、地区行政划分、商品类目权限树、菜单树、多级评论Tree 组件在展示上述层级关系的同时天然支持节点的展开expand、折叠collapse与选中select并通过checkable提供勾选能力。从源码看ant-design-vue 的 Tree 是对底层vc-tree的封装components/tree/Tree.tsx统一注入 antd 主题样式、插槽协议与事件命名同时保留了TreeNode与DirectoryTree两个衍生组件并通过 components/tree/index.tsx 一次性注册ATree、ATreeNode、ADirectoryTree三个全局组件。Tree props 全量参数解析官方文档给出了完整的 Tree 属性表下面按功能分组逐项说明并结合 components/tree/Tree.tsx 中treeProps()的真实定义进行印证。数据与字段映射属性说明类型默认值版本treeData树的节点数据类型为TreeNode[]v1.1.4 之前请使用treeNodesTreeNode[]--fieldNames将 treeNode 中的title、key、children字段替换为 treeData 中对应的自定义字段object{ children: children, title: title, key: key }3.0.0treeData是最推荐的数据驱动写法。源码中组件还会对旧式插槽声明发出警告当treeData未传而使用了default插槽时会提示 childrenof Tree is deprecated. Please usetreeDatainstead.components/tree/Tree.tsx。fieldNames用于对接后端返回的非标准字段。例如后端数据使用name作为标题、child作为子节点数组时可以这样配置完整示例见 components/tree/demo/replaceFields.vuea-tree v-model:expandedKeysexpandedKeys v-model:selectedKeysselectedKeys v-model:checkedKeyscheckedKeys checkable :tree-datatreeData :field-namesfieldNames template #title{ name, key } span v-ifkey 0-0-1 stylecolor: #1890ff{{ name }}/span template v-else{{ name }}/template /template /a-treeconst fieldNames: TreeProps[fieldNames] { children: child, title: name, }; const treeData: TreeProps[treeData] [ { name: parent 1, key: 0-0, child: [ { name: leaf, key: 0-0-0, disabled: true }, ], }, ];需要说明的是更早版本中的replaceFields属性已被标记为 deprecated源码中通过watchEffect输出警告建议改用fieldNamescomponents/tree/Tree.tsx并在渲染时做了兼容回退fieldNames props.replaceFieldscomponents/tree/Tree.tsx。受控状态与 v-modelTree 的三组核心状态均支持v-model这是 Vue 3 语法的受控用法源码通过onUpdate:xxx事件实现双向绑定components/tree/Tree.tsx属性说明类型默认值expandedKeys(v-model)受控已展开节点的 keysstring[] | number[][]checkedKeys(v-model)受控已勾选节点的 keysstring[] | number[] |{ checked, halfChecked }[]selectedKeys(v-model)受控已选中节点的 keysstring[] | number[]-expandedKeys与selectedKeys均为简单的 key 数组。checkedKeys需要注意父子联动规则当指定的是父节点 key 时其所有子节点会被一并勾选当指定的是子节点 key 时其父节点也会被勾选。只有在checkable与checkStrictly同时为true时checkedKeys才接收{ checked: string[] | number[], halfChecked: string[] | number[] }对象且父子勾选互不影响。对应的非受控默认值版本defaultExpandedKeys、defaultCheckedKeys、defaultSelectedKeys均在源码的 props 中声明components/tree/Tree.tsx。基础示例components/tree/demo/basic.vue同时展示了勾选、选中、禁用与默认展开的组合用法a-tree v-model:expandedKeysexpandedKeys v-model:selectedKeysselectedKeys v-model:checkedKeyscheckedKeys checkable :tree-datatreeData template #title{ title, key } span v-ifkey 0-0-1-0 stylecolor: #1890ff{{ title }}/span template v-else{{ title }}/template /template /a-treeconst treeData: TreeProps[treeData] [ { title: parent 1, key: 0-0, children: [ { title: parent 1-0, key: 0-0-0, disabled: true, // 整个节点禁用 children: [ { title: leaf, key: 0-0-0-0, disableCheckbox: true }, // 仅禁用勾选框 { title: leaf, key: 0-0-0-1 }, ], }, { title: parent 1-1, key: 0-0-1, children: [{ key: 0-0-1-0, title: sss }] }, ], }, ];交互行为开关属性说明类型默认值selectable节点是否可被选中booleantruemultiple是否支持多选booleanfalsecheckable在节点前显示CheckboxbooleanfalsecheckStrictly精确勾选父节点与子节点勾选状态不再关联booleanfalsedisabled是否禁用整棵树boolfalseautoExpandParent展开父节点时是否自动联动展开其祖先booleanfalsedefaultExpandAll默认展开所有节点booleanfalseblockNode节点是否撑满剩余横向空间booleanfalseshowLine是否显示层级连接线3.0 可传{ showLeafIcon: boolean }boolean | objectfalseshowIcon是否在标题前展示图标开启后无默认样式需自行定制booleanfalsedraggable是否允许拖拽IE 8booleanfalseallowDrop是否允许节点被放置到目标位置({ dropNode, dropPosition }) boolean-源码中这些布尔属性的默认值通过initDefaultProps统一注入checkable: false、selectable: true、showIcon: false、blockNode: falsecomponents/tree/Tree.tsx。渲染时还会依据这些开关动态拼接类名例如关闭图标时添加-icon-hide、blockNode 时添加-block-node、关闭选中时添加-unselectablecomponents/tree/Tree.tsx。插槽与自定义渲染属性说明类型版本title自定义节点标题slot2.0.0switcherIcon自定义展开/折叠图标v-slot作用域参数见下表-height配置虚拟滚动高度开启后将不支持横向滚动number-virtual设置为 false 可关闭虚拟滚动boolean默认 true3.0loadData异步加载数据function(node)-loadedKeys受控已加载完成的节点需与loadData配合string[] | number[][]filterTreeNode过滤高亮节点返回true的节点将被高亮function(node)-switcherIcon插槽的作用域参数非常丰富官方文档列出的完整字段为{ active, checked, expanded, loading, selected, halfChecked, title, key, children, dataRef, data, defaultIcon, switcherCls }其中defaultIcon是内置默认图标组件、switcherCls是切换图标的样式类。源码 components/tree/utils/iconUtil.tsx 展示了默认图标的完整决策逻辑加载中显示LoadingOutlined叶子节点在showLine开启时显示FileOutlined或叶子连接线非叶子节点默认显示CaretDownFilled开启showLine后折叠态显示PlusSquareOutlined、展开态显示MinusSquareOutlined。若传入函数形式的switcherIcon会以{ ...props, defaultIcon, switcherCls }为参数调用components/tree/utils/iconUtil.tsx。Events 事件回调Tree 的全部事件与参数签名如下均可在官方文档 Events 表中查阅事件名说明回调参数select用户点击节点时触发function(selectedKeys, e: { selected: bool, selectedNodes, node, event })check勾选状态变化时触发function(checkedKeys, e: { checked: bool, checkedNodes, node, event })expand节点展开/折叠时触发function(expandedKeys, { expanded: bool, node })load节点异步加载完成时触发function(loadedKeys, { event, node })rightClick用户右键点击节点时触发function({ event, node })dragstart开始拖拽时触发function({ event, node })dragenter拖入节点范围时触发function({ event, node, expandedKeys })dragover在节点上方拖动时触发function({ event, node })dragleave拖离节点范围时触发function({ event, node })dragend拖拽结束时触发function({ event, node })drop放置到节点时触发function({ event, node, dragNode, dragNodesKeys })事件回调的类型定义集中在 components/tree/Tree.tsx包括AntTreeNodeCheckedEvent、AntTreeNodeSelectedEvent、AntTreeNodeExpandedEvent、AntTreeNodeDragEnterEvent、AntTreeNodeDropEvent等可从ant-design-vue/es/tree直接导入获得类型提示。select/check/expand三个事件在源码中会额外同步触发update:selectedKeys/update:checkedKeys/update:expandedKeys以支撑v-modelcomponents/tree/Tree.tsx。Tree 实例方法方法名说明scrollTo({ key, align?, offset? })在虚拟滚动模式下滚动到指定 key 的节点align可选top \| bottom \| autooffset为偏移量该方法在源码中通过expose暴露components/tree/Tree.tsx同时组件还向外暴露了treeRef以及selectedKeys、checkedKeys、halfCheckedKeys、loadedKeys、loadingKeys、expandedKeys等计算属性便于父组件以命令式方式获取当前状态。使用时先给a-tree加ref再调用ref.value.scrollTo({ key: 0-0-1, align: top })即可。TreeNode 节点配置Tree 同时支持以子节点嵌套方式声明树通过a-tree-node每个节点的可配置属性如下属性说明类型默认值key节点唯一标识用于与 (default)ExpandedKeys / (default)CheckedKeys / (default)SelectedKeys 对应必须保证整棵树内唯一string | number内部计算的位置值title节点标题string---disabled禁用该节点booleanfalseselectable该节点是否可选中booleantruecheckable当 Tree 开启 checkable 时控制该节点是否显示 Checkboxboolean-disableCheckbox禁用该节点的勾选框booleanfalseicon自定义节点图标传入组件时其渲染会收到完整 TreeNode propsslot | slot-scope-isLeaf是否为叶子节点在指定loadData时生效boolean-class节点类名string-style节点样式string | object-不过在treeData时代更推荐用数据驱动 #title、#icon插槽代替嵌套节点。源码中TreeNode直接复用vc-tree的VcTreeNode实现components/tree/index.tsx仅作再导出。DirectoryTree 目录树DirectoryTree是内置的目录风格树a-directory-tree自带文件/文件夹图标专为资源管理器式场景设计其实现位于 components/tree/DirectoryTree.tsx。属性属性说明类型默认值expandAction目录展开触发方式可选false、click、dblclickstringclick源码中对expandAction的解析components/tree/DirectoryTree.tsxclick单击文件夹节点即展开/折叠内部对展开操作做了 200ms 的 debounceonDebounceExpandcomponents/tree/DirectoryTree.tsx且按住Shift/Ctrl/Command时不触发展开dblclick或doubleclick双击展开/折叠false不自动展开仅靠点击切换箭头。文件/文件夹图标与多选DirectoryTree 默认showIcon: true、blockNode: true并根据节点状态自动切换图标叶子节点显示FileOutlined非叶子节点展开时显示FolderOpenOutlined、折叠时显示FolderOutlinedcomponents/tree/DirectoryTree.tsx。与普通 Tree 相比DirectoryTree 额外实现了类文件管理器的多选逻辑源码见 components/tree/DirectoryTree.tsxCtrl/Command 单击切换式多选multiple模式下Shift 单击以最近一次单选点为起点的连续范围多选通过calcRangeKeys计算范围 key 并合并去重普通单击单选始终以最新点击节点作为lastSelectedKey。完整示例见 components/tree/demo/directory.vuea-directory-tree v-model:expandedKeysexpandedKeys v-model:selectedKeysselectedKeys multiple :tree-datatreeData /a-directory-tree实战场景详解1. 异步加载数据loadData点击展开节点时动态请求子级数据是组织架构、区域级联等场景的标配。核心是利用loadData返回 Promise并在回调中直接修改节点的dataRef.children后重建 treeData 引用components/tree/demo/dynamic.vuea-tree v-model:expandedKeysexpandedKeys v-model:selectedKeysselectedKeys :load-dataonLoadData :tree-datatreeData /const treeData refTreeProps[treeData]([ { title: Expand to load, key: 0 }, { title: Expand to load, key: 1 }, { title: Tree Node, key: 2, isLeaf: true }, // isLeaf 阻止再次加载 ]); const onLoadData: TreeProps[loadData] treeNode { return new Promisevoid(resolve { if (treeNode.dataRef.children) { resolve(); return; } setTimeout(() { treeNode.dataRef.children [ { title: Child Node, key: ${treeNode.eventKey}-0 }, { title: Child Node, key: ${treeNode.eventKey}-1 }, ]; treeData.value [...treeData.value]; // 触发响应式更新 resolve(); }, 1000); }); };注意两个关键点叶子节点需显式声明isLeaf: true避免无效请求修改 children 后必须重建treeData的引用如展开新数组才能触发重新渲染。2. 可搜索树filterTreeNode title 插槽搜索场景需要三件事用#title插槽高亮命中文本、用expandedKeys展开命中节点的祖先链、用autoExpandParent保证展开时祖先联动。完整逻辑见 components/tree/demo/search.vuea-input-search v-model:valuesearchValue stylemargin-bottom: 8px placeholderSearch / a-tree :expanded-keysexpandedKeys :auto-expand-parentautoExpandParent :tree-datagData expandonExpand template #title{ title } span v-iftitle.indexOf(searchValue) -1 {{ title.substring(0, title.indexOf(searchValue)) }} span stylecolor: #f50{{ searchValue }}/span {{ title.substring(title.indexOf(searchValue) searchValue.length) }} /span span v-else{{ title }}/span /template /a-tree核心思路监听searchValue遍历全量dataList找到命中节点通过getParentKey递归反查祖先 key 集合作为新的expandedKeys并重置autoExpandParent true用户在树内手动展开时则关闭autoExpandParent避免展开状态被反复纠正。3. 拖拽排序draggable drop启用draggable后配合drop事件即可实现节点重排。官方示例components/tree/demo/draggable.vue展示了完整的拖入内部 / 拖到前后三种落点处理a-tree classdraggable-tree draggable block-node :tree-datagData dragenteronDragEnter droponDrop /const onDrop (info: AntTreeNodeDropEvent) { const dropKey info.node.key; const dragKey info.dragNode.key; const dropPos info.node.pos.split(-); const dropPosition info.dropPosition - Number(dropPos[dropPos.length - 1]); // 1) 从原位置移除拖拽节点 // 2) !info.dropToGap放置到节点内部 → item.children.unshift(dragObj) // 3) 展开节点底部空隙 → 同样插入 children 头部 // 4) 否则按 dropPosition 为 -1 / 1 插入到目标节点的前/后 };dropPosition的语义-1表示落在节点上方间隙、1表示落在下方间隙与dropToGap配合即可区分成为子节点还是成为兄弟节点。allowDrop属性可在此基础上进一步限制可放置位置。底层对拖拽落点指示线的渲染由 components/tree/utils/dropIndicator.tsx 提供。4. 连接线与自定义图标showLine / switcherIcon / icon文件目录类展示常开启showLine显示层级连接线并用switcherIcon替换默认的加减号图标components/tree/demo/line.vuea-tree :show-lineshowLine :show-iconshowIcon :default-expanded-keys[0-0-0] :tree-datatreeData selectonSelect template #iconcarry-out-outlined //template template #title{ dataRef } template v-ifdataRef.key 0-0-0-1 divmultiple line title/div /template template v-else{{ dataRef.title }}/template /template template #switcherIcon{ dataRef, defaultIcon } SmileTwoTone v-ifdataRef.key 0-0-2 / component :isdefaultIcon v-else / /template /a-tree#switcherIcon插槽可以拿到dataRef当前节点数据与defaultIcon内置默认图标从而做到大部分节点用默认图标、个别节点换图标。若只想针对不同节点定制标题前的图标使用#icon插槽并读取key、selected等参数即可components/tree/demo/customized-icon.vue。3.0 还可以用对象形式:show-line{ showLeafIcon: true }控制叶子节点是否显示文件图标。5. 虚拟滚动height / virtual / scrollTo当节点数量庞大如数千个时传入height属性即可启用虚拟滚动配合default-expand-all一次性渲染海量节点components/tree/demo/virtual-scroll.vuea-tree v-model:selectedKeysselectedKeys v-model:checkedKeyscheckedKeys default-expand-all checkable :height233 :tree-datadig() /启用虚拟滚动后virtual默认为true可显式传:virtualfalse关闭通过实例方法scrollTo({ key, align })可以编程式定位到任意节点。需要注意文档中的限制开启height后将不支持横向滚动。6. 右键菜单rightClick 或 title 插槽 Dropdown官方推荐用#title插槽包裹a-dropdown实现节点级右键菜单比rightClick事件更灵活components/tree/demo/context-menu.vuea-tree v-model:expandedKeysexpandedKeys :tree-datatreeData template #title{ key: treeKey, title } a-dropdown :trigger[contextmenu] span{{ title }}/span template #overlay a-menu click({ key: menuKey }) onContextMenuClick(treeKey, menuKey) a-menu-item key11st menu item/a-menu-item a-menu-item key22nd menu item/a-menu-item a-menu-item key33rd menu item/a-menu-item /a-menu /template /a-dropdown /template /a-tree若需要在树级统一处理右键拿到节点信息也可以直接用right-click({ event, node }) ...事件。FAQ如何隐藏 showLine 模式下的文件图标当开启showLine后叶子节点会通过switcherIcon渲染出文件图标FileOutlined见 components/tree/utils/iconUtil.tsx。官方 FAQ 给出的方案是覆盖样式将其隐藏/* 隐藏叶子节点的文件图标 */ .ant-tree-switcher-leaf-line { visibility: hidden; }或者从根上处理3.0 使用:show-line{ showLeafIcon: false }此时iconUtil会为叶子节点渲染纯连接线-switcher-leaf-line而非文件图标无需再写覆盖样式。小结Tree 组件在 ant-design-vue 中承担着全部层级数据展示职责其能力可以总结为一句话*数据驱动treeData fieldNames 三组受控状态v-model:expandedKeys / selectedKeys / checkedKeys 完备事件体系select / check / expand / drag/ drop / rightClick 插槽定制title / icon / switcherIcon 进阶能力异步加载、虚拟滚动、目录树**。本文所有结论均可在 components/tree/index.en-US.md 官方文档、components/tree/Tree.tsx 与 components/tree/DirectoryTree.tsx 源码、以及 components/tree/demo 目录下 13 个可运行示例中逐条验证适合作为接入 Tree 组件时的速查与排障参考。赞分享前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载相关推荐Radix Vuereka-uiTree 树形控件完全指南从基础用法到虚拟滚动与拖拽实现Radix Vuereka uiTree 树形控件完全指南从基础用法到虚拟滚动与拖拽实现 Badge Alpha/Badge Tree树形视图是前端UI组件设计系统Ant Design List 组件完全指南从基础列表到虚拟滚动与网格布局Ant Design List 组件完全指南从基础列表到虚拟滚动与网格布局 本指南围绕 antd 仓库 List 组件文档 https://link.gitc前端UI组件设计系统Ant Design List 组件完全指南从基础列表到虚拟滚动的高性能数据展示方案Ant Design List 组件完全指南从基础列表到虚拟滚动的高性能数据展示方案 List列表是 Ant Design 中最基础、应用最广泛的数据展示前端UI组件设计系统上一篇otter.nvim常见问题解决诊断与修复嵌入式代码LSP连接问题下一篇React Hooks完全指南TOP课程中的最新特性创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考