前端UI组件【免费下载链接】uiThe Intuitive Vue UI Library powered by Reka UI Tailwind CSS.项目地址https://gitcode.com/gh_mirrors/ui4/ui点击查看免费下载本篇技术指南围绕 Nuxt UI即当前仓库gh_mirrors/ui4/ui对应的开源组件库中的Tree组件展开。Tree 用于以树形结构展示和交互层级化数据例如文件目录、组织架构、分类菜单等。读完本文你将掌握items数据模型、选中/展开的受控用法、扁平化渲染、图标定制、复选框联动、拖拽排序与虚拟化等完整实战能力并能借助源码与测试理解其底层实现。组件定位与底层架构Tree 是一个基于 Reka UI其中TreeRoot负责整棵树的选中、展开状态管理与键盘交互TreeItem负责单个节点的展开/选中行为并通过as-child透传TreeVirtualizer在启用虚拟化时按需渲染可见节点。组件对外暴露的类型TreeItem与TreeProps均在同一文件中定义TypeScript 泛型T extends TreeItem[]、M extends boolean让多选与非多选场景拥有精确的类型推导见 test/components/Tree.spec.ts 底部的expectEmitPayloadType断言。基础用法用 items 渲染一棵树在 Nuxt 中直接使用UTreeVue 场景对应vue.UTree通过items属性传入层级数据script setup langts import type { TreeItem } from #ui/components/Tree const items: TreeItem[] [ { label: app/, defaultExpanded: true, children: [ { label: composables/, children: [ { label: useAuth.ts, icon: i-vscode-icons-file-type-typescript }, { label: useUser.ts, icon: i-vscode-icons-file-type-typescript } ] }, { label: components/, defaultExpanded: true, children: [ { label: Card.vue, icon: i-vscode-icons-file-type-vue }, { label: Button.vue, icon: i-vscode-icons-file-type-vue } ] } ] }, { label: app.vue, icon: i-vscode-icons-file-type-vue }, { label: nuxt.config.ts, icon: i-vscode-icons-file-type-nuxt } ] /script template UTree :itemsitems classw-60 / /template上例中带children的节点自动渲染为可展开的父节点文件夹形态叶子节点渲染为普通条目defaultExpanded: true让app/与components/默认展开。items 数据结构与 TreeItem 属性items是TreeItem[]数组每个节点支持以下属性属性类型说明iconstring节点前导图标Iconify 名称通常用于叶子文件图标labelstring节点显示文本也是默认唯一标识来源trailingIconstring节点右侧图标用于覆盖父节点的展开箭头defaultExpandedboolean节点是否默认展开disabledboolean禁用单个节点slotstring为节点指定自定义插槽名称实现逐节点定制childrenTreeItem[]子节点数组存在即视为父节点onToggle(e: TreeItemToggleEvent) void节点级展开/收起回调onSelect(e: TreeItemSelectEvent) void节点级选中回调classany作用于该节点链接的 classuiPartial...作用于该节点的插槽 class含item、itemWithChildren、link、linkLeadingIcon、linkLabel、linkTrailing、linkTrailingIcon、listWithChildren其中class与ui允许对单个节点进行局部样式覆盖[key: string]: any允许携带任意自定义字段如id供getKey或数据逻辑使用。关于唯一标识的重要约束每个节点都需要一个唯一标识符。默认情况下组件以label作为标识若label不唯一例如多个重名目录必须通过get-key函数返回唯一标识或使用label-key指定参与标识的字段。源码中getItemKey的逻辑为优先使用props.getKey(item)否则回退到getItemLabel(item)即labelKey字段默认label// src/runtime/components/Tree.vue function getItemKey(item: TreeItem): string { return props.getKey ? props.getKey(item) || getItemLabel(item) : getItemLabel(item) }多选multiple 与选中值设置multiple后v-model或default-value的值由单个节点变为节点数组UTree :itemsitems multiple default-expanded classw-60 /defaultExpanded在这里也接受TreeItem[]以默认展开多个节点。多选与受控选中均可在 test/components/Tree.spec.ts 中找到对应渲染用例with multiple、with multiple and modelValue、with multiple and defaultValue。渲染模式nested 与扁平列表nested属性控制树以嵌套 DOM 结构渲染还是以扁平列表渲染默认trueUTree :itemsitems :nestedfalse classw-60 /当nested为false时所有节点渲染在同一层级依靠缩进表现层级关系——这正是拖拽与虚拟化场景所依赖的形态。源码中nested的计算是props.virtualize ? false : props.nested即开启虚拟化时强制扁平化。扁平模式下的缩进通过内联padding-inline-start计算由flattenedPaddingFormula按size与节点level推算xs到xl各尺寸对应不同的基础值与每级递增量见 src/runtime/components/Tree.vue 第 185–195 行。因此即使传入自定义主题尺寸也不会抛错——测试does not throw when flattened with a custom theme size专门覆盖了该场景。外观定制Color 与 Sizecolor控制选中态高亮颜色默认primarysize控制紧凑程度支持xs/sm/md/lg/xl默认mdUTree :itemsitems colorneutral sizexl classw-60 /主题定义src/theme/tree.ts中color变体为选中态链接生成before:outline-{color}/25轮廓neutral使用before:outline-inverted/25size变体则调整内边距、字号与图标尺寸。Trailing Icon父节点展开箭头父节点右侧默认渲染i-lucide-chevron-down可通过trailing-icon覆盖UTree :itemsitems trailing-iconi-lucide-arrow-down classw-60 /若某个节点自身声明了trailingIcon则节点级图标始终优先于组件级trailing-icon。该默认图标定义在appConfig.ui.icons.chevronDown默认值见 src/theme/icons.ts 的i-lucide-chevron-down可在 Nuxt 的app.config.ts或 Vue 的vite.config.ts中全局替换。Expanded / Collapsed Icon文件夹图标父节点未展开时默认显示i-lucide-folder展开后显示i-lucide-folder-open分别对应collapsed-icon与expanded-iconUTree :itemsitems expanded-iconi-lucide-book-open collapsed-iconi-lucide-book classw-60 /全局默认值位于appConfig.ui.icons.folder/appConfig.ui.icons.folderOpensrc/theme/icons.ts。渲染优先级在 src/runtime/components/Tree.vue 模板中体现节点自带icon优先否则有子节点时按展开状态渲染expandedIcon或collapsedIcon。Disabled禁用组件级disabled会禁用整棵树的全部交互也可以只对单个节点设置item.disabled。禁用态的链接样式由主题disabled变体定义cursor-not-allowed opacity-75UTree :itemsitems disabled classw-60 /受控用法选中与展开控制选中项通过v-model或default-value受控管理选中项传入v-model时建议同时用get-key指明取值函数确保值与数据一一对应script setup langts const selected refTreeItem() const getKey (item: TreeItem) item.label /script template UTree v-modelselected :itemsitems :get-keygetKey classw-60 / /template若希望点击父节点时只展开/收起而不选中可通过节点属性item.onSelect或组件级select事件阻止const onSelect (event: TreeItemSelectEventTreeItem) { if (event.originalEvent.type click event.node.children) { // 阻止选中仅切换展开状态 } }控制展开项同理展开状态可通过v-model数组或default-expanded受控item.onToggle或组件级toggle事件可用于阻止展开/收起例如选中父节点但不展开其子项的场景。高级示例4.1节点内嵌复选框在item-leading插槽中放置 Checkbox 组件配合multiple、propagate-select选中向父/子节点传播与bubble-select属性即可实现带父子联动关系的勾选树再通过select、toggle事件同步选中与展开状态。由于Checkbox本身渲染为button需要通过as属性将树节点由button改为div以规避嵌套按钮的无障碍问题UTree :itemsitems multiple propagate-select bubble-select :as{ root: ul, link: div } classw-60 /拖拽排序使用vueuse/integrations提供的useSortable内部封装 Sortable.js可让树支持拖拽。前提是设置nested: false将树渲染为扁平列表使每个节点成为可被 Sortable 识别/移动的同级元素import { useSortable } from vueuse/integrations/useSortable const treeRef refHTMLElement() const { } useSortable(treeRef, items, { animation: 150 })UTree reftreeRef :itemsitems :nestedfalse classw-60 /虚拟化大数据量渲染virtualize属性可为大列表启用虚拟化传true或配置对象{ estimateSize, overscan }UTree :itemsitems :virtualize{ estimateSize: 32, overscan: 12 } classw-60 /estimateSize每项预估高度像素默认32也可以是(index) number函数overscan可视区外额外渲染的项数默认12。需要注意虚拟化开启时树结构会被扁平化效果等同nested: false且滚动容器由主题virtualize: true变体提供root: overflow-y-auto。源码通过getEstimateSize(items, size)见 src/utils/virtualizer.ts依据当前size自动推算默认预估高度实际渲染由 Reka UI 的TreeVirtualizer完成。自定义插槽节点级slot属性可指定个性化插槽每个具名插槽又衍生出五个子插槽#{item.slot}-wrapper包裹整个节点#{item.slot}节点主体内容#{item.slot}-leading前导区域图标#{item.slot}-label文本标签区域#{item.slot}-trailing尾部区域展开箭头未指定slot时对应基础插槽item-wrapper/item/item-leading/item-label/item-trailing。所有插槽均暴露以下作用域属性属性说明item当前节点数据index节点在同级中的索引level节点所在层级从 1 开始expanded/selected/indeterminate展开、选中、半选状态handleSelect/handleToggle手动触发选中/展开的行为函数ui当前主题的ui对象含插槽 class示例为slot: app的节点定制内容template #app-label{ item } span classfont-bold{{ item.label }}/span /template主题定制Tree 的主题结构定义在 src/theme/tree.ts包含插槽样式与变体插槽默认样式要点rootrelative isolate虚拟化时追加overflow-y-autoitemw-fulllistWithChildrenborder-s border-default左侧层级线itemWithChildrenps-1.5 -ms-px对齐层级线link弹性布局、text-sm、before伪元素圆角高亮底linkLeadingIcon/linkTrailingIconshrink-0展开箭头带group-data-expanded:rotate-180旋转动画linkLabeltruncate文本截断linkTrailingms-auto inline-flex gap-1.5变体方面支持virtualize、color、size、selected、disabled默认变体为color: primary、size: mdselected与color的组合通过compoundVariants生成选中态文字颜色如text-primary未选中且未禁用时提供hover:text-highlighted悬停反馈。通过app.config.tsNuxt或vite.config.tsVue中的ui.tree键即可覆盖上述任意插槽 class也可利用ui.icons.chevronDown、ui.icons.folder、ui.icons.folderOpen全局更换默认图标。API 汇总Props核心属性类型默认值说明asany \| { root, link }ul/button根节点与链接的渲染元素itemsTreeItem[]—树数据colorprimary \| neutral \| ...primary选中态颜色sizexs \| sm \| md \| lg \| xlmd紧凑程度getKey(item) string—唯一标识函数labelKeystringlabel作为标识/文本的字段multiplebooleanfalse是否多选modelValue/defaultValueTreeItem \| TreeItem[]—受控/非受控选中值nestedbooleantrue嵌套 DOM 还是扁平列表virtualizeboolean \| { estimateSize?, overscan? }false虚拟化开关与参数trailingIconstringui.icons.chevronDown父节点展开箭头expandedIcon/collapsedIconstringui.icons.folderOpen/ui.icons.folder展开/收起态文件夹图标disabledbooleanfalse禁用整棵树expanded/defaultExpandedTreeItem[]—展开状态受控/默认值selectionBehavior/propagateSelect/bubbleSelect/loop继承自 Reka UI—选择与焦点行为onSelect/onToggle回调—组件级选中/展开回调Slotsitem-wrapper、item、item-leading、item-label、item-trailing以及由item.slot派生的动态插槽#{slot}-wrapper、#{slot}、#{slot}-leading、#{slot}-label、#{slot}-trailing。所有插槽共享上文列出的作用域属性。Emits组件发出继承自 Reka UITreeRoot的事件主要包括update:modelValuev-model选中值、select选中某节点、toggle展开/收起某节点等且携带对应节点数据供item.onSelect/item.onToggle之外的全局拦截使用。测试与可访问性保障test/components/Tree.spec.ts 以快照渲染方式覆盖了本文提及的绝大部分能力items、modelValue、defaultValue、expanded、defaultExpanded、labelKey、getKey、multiple、disabled、nested、virtualize、三类图标、全部size变体、neutral颜色、as、class、ui覆盖以及item-wrapper/item/item-leading/item-trailing与动态插槽的渲染。此外还包含两项关键断言通过axe无障碍审计passes accessibility tests验证了基于 Reka UI 的 WAI-ARIA 语义、键盘导航与焦点管理通过expectEmitPayloadType验证update:modelValue在普通与getKey场景下的载荷类型推导。结合文档与测试可以确认 Tree 组件在交互语义与视觉表现上均具备生产可用性。建议在实际项目中优先使用getKey保证数据唯一性并在数据量较大时开启virtualize以获得稳定性能。提示本文对应的官方交互式示例选中控制、展开控制、复选框树、拖拽、虚拟化、自定义插槽均可通过仓库文档目录 docs/content/docs/2.components/tree.md 中嵌入的 component-example 宏查看源码与实时效果。赞分享前端UI组件【免费下载链接】uiThe Intuitive Vue UI Library powered by Reka UI Tailwind CSS.项目地址https://gitcode.com/gh_mirrors/ui4/ui点击查看免费下载相关推荐如何快速安装 ESP-IDF用 EIM 一条命令装好工具链完整覆盖 4 大场景如何快速安装 ESP IDF用 EIM 一条命令装好工具链完整覆盖 4 大场景 ESP IDF乐鑫 IoT 开发框架是 Espressif 芯片的官方物联网嵌入式手柄操作B站客户端wiliwili 在Switch上从安装到流畅播放的5步实战指南手柄操作B站客户端wiliwili 在Switch上从安装到流畅播放的5步实战指南 如果你想在电视或掌机上仅靠手柄就能刷视频、发弹幕、追番剧而不必忍受传统音视频桌面应用rsuite 树形表格Tree Table完全指南层级数据的展示、展开控制与虚拟化实战rsuite 树形表格Tree Table完全指南层级数据的展示、展开控制与虚拟化实战 树形表格是展示具有层级结构关系数据的表格形态它通过在普通表格中引前端UI组件上一篇Ente Locker 集合Collections使用指南用多标签式组织管理你的加密文档下一篇Prometheus Operator 官方 CLI 参考operator 二进制全部命令与参数详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考