前端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 用于以樹形結構展示和交互層級化數(shù)據(jù)例如文件目錄、組織架構、分類菜單等。讀完本文你將掌握items數(shù)據(jù)模型、選中/展開的受控用法、扁平化渲染、圖標定制、復選框聯(lián)動、拖拽排序與虛擬化等完整實戰(zhàn)能力并能借助源碼與測試理解其底層實現(xiàn)。組件定位與底層架構Tree 是一個基于 Reka UI其中TreeRoot負責整棵樹的選中、展開狀態(tài)管理與鍵盤交互TreeItem負責單個節(jié)點的展開/選中行為并通過as-child透傳TreeVirtualizer在啟用虛擬化時按需渲染可見節(jié)點。組件對外暴露的類型TreeItem與TreeProps均在同一文件中定義TypeScript 泛型T extends TreeItem[]、M extends boolean讓多選與非多選場景擁有精確的類型推導見 test/components/Tree.spec.ts 底部的expectEmitPayloadType斷言?；A用法用 items 渲染一棵樹在 Nuxt 中直接使用UTreeVue 場景對應vue.UTree通過items屬性傳入層級數(shù)據(jù)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的節(jié)點自動渲染為可展開的父節(jié)點文件夾形態(tài)葉子節(jié)點渲染為普通條目defaultExpanded: true讓app/與components/默認展開。items 數(shù)據(jù)結構與 TreeItem 屬性items是TreeItem[]數(shù)組每個節(jié)點支持以下屬性屬性類型說明iconstring節(jié)點前導圖標Iconify 名稱通常用于葉子文件圖標labelstring節(jié)點顯示文本也是默認唯一標識來源trailingIconstring節(jié)點右側圖標用于覆蓋父節(jié)點的展開箭頭defaultExpandedboolean節(jié)點是否默認展開disabledboolean禁用單個節(jié)點slotstring為節(jié)點指定自定義插槽名稱實現(xiàn)逐節(jié)點定制childrenTreeItem[]子節(jié)點數(shù)組存在即視為父節(jié)點onToggle(e: TreeItemToggleEvent) void節(jié)點級展開/收起回調(diào)onSelect(e: TreeItemSelectEvent) void節(jié)點級選中回調(diào)classany作用于該節(jié)點鏈接的 classuiPartial...作用于該節(jié)點的插槽 class含item、itemWithChildren、link、linkLeadingIcon、linkLabel、linkTrailing、linkTrailingIcon、listWithChildren其中class與ui允許對單個節(jié)點進行局部樣式覆蓋[key: string]: any允許攜帶任意自定義字段如id供getKey或數(shù)據(jù)邏輯使用。關于唯一標識的重要約束每個節(jié)點都需要一個唯一標識符。默認情況下組件以label作為標識若label不唯一例如多個重名目錄必須通過get-key函數(shù)返回唯一標識或使用label-key指定參與標識的字段。源碼中getItemKey的邏輯為優(yōu)先使用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的值由單個節(jié)點變?yōu)楣?jié)點數(shù)組UTree :itemsitems multiple default-expanded classw-60 /defaultExpanded在這里也接受TreeItem[]以默認展開多個節(jié)點。多選與受控選中均可在 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時所有節(jié)點渲染在同一層級依靠縮進表現(xiàn)層級關系——這正是拖拽與虛擬化場景所依賴的形態(tài)。源碼中nested的計算是props.virtualize ? false : props.nested即開啟虛擬化時強制扁平化。扁平模式下的縮進通過內(nèi)聯(lián)padding-inline-start計算由flattenedPaddingFormula按size與節(jié)點level推算xs到xl各尺寸對應不同的基礎值與每級遞增量見 src/runtime/components/Tree.vue 第 185–195 行。因此即使傳入自定義主題尺寸也不會拋錯——測試does not throw when flattened with a custom theme size專門覆蓋了該場景。外觀定制Color 與 Sizecolor控制選中態(tài)高亮顏色默認primarysize控制緊湊程度支持xs/sm/md/lg/xl默認mdUTree :itemsitems colorneutral sizexl classw-60 /主題定義src/theme/tree.ts中color變體為選中態(tài)鏈接生成before:outline-{color}/25輪廓neutral使用before:outline-inverted/25size變體則調(diào)整內(nèi)邊距、字號與圖標尺寸。Trailing Icon父節(jié)點展開箭頭父節(jié)點右側默認渲染i-lucide-chevron-down可通過trailing-icon覆蓋UTree :itemsitems trailing-iconi-lucide-arrow-down classw-60 /若某個節(jié)點自身聲明了trailingIcon則節(jié)點級圖標始終優(yōu)先于組件級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文件夾圖標父節(jié)點未展開時默認顯示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。渲染優(yōu)先級在 src/runtime/components/Tree.vue 模板中體現(xiàn)節(jié)點自帶icon優(yōu)先否則有子節(jié)點時按展開狀態(tài)渲染expandedIcon或collapsedIcon。Disabled禁用組件級disabled會禁用整棵樹的全部交互也可以只對單個節(jié)點設置item.disabled。禁用態(tài)的鏈接樣式由主題disabled變體定義cursor-not-allowed opacity-75UTree :itemsitems disabled classw-60 /受控用法選中與展開控制選中項通過v-model或default-value受控管理選中項傳入v-model時建議同時用get-key指明取值函數(shù)確保值與數(shù)據(jù)一一對應script setup langts const selected refTreeItem() const getKey (item: TreeItem) item.label /script template UTree v-modelselected :itemsitems :get-keygetKey classw-60 / /template若希望點擊父節(jié)點時只展開/收起而不選中可通過節(jié)點屬性item.onSelect或組件級select事件阻止const onSelect (event: TreeItemSelectEventTreeItem) { if (event.originalEvent.type click event.node.children) { // 阻止選中僅切換展開狀態(tài) } }控制展開項同理展開狀態(tài)可通過v-model數(shù)組或default-expanded受控item.onToggle或組件級toggle事件可用于阻止展開/收起例如選中父節(jié)點但不展開其子項的場景。高級示例4.1節(jié)點內(nèi)嵌復選框在item-leading插槽中放置 Checkbox 組件配合multiple、propagate-select選中向父/子節(jié)點傳播與bubble-select屬性即可實現(xiàn)帶父子聯(lián)動關系的勾選樹再通過select、toggle事件同步選中與展開狀態(tài)。由于Checkbox本身渲染為button需要通過as屬性將樹節(jié)點由button改為div以規(guī)避嵌套按鈕的無障礙問題UTree :itemsitems multiple propagate-select bubble-select :as{ root: ul, link: div } classw-60 /拖拽排序使用vueuse/integrations提供的useSortable內(nèi)部封裝 Sortable.js可讓樹支持拖拽。前提是設置nested: false將樹渲染為扁平列表使每個節(jié)點成為可被 Sortable 識別/移動的同級元素import { useSortable } from vueuse/integrations/useSortable const treeRef refHTMLElement() const { } useSortable(treeRef, items, { animation: 150 })UTree reftreeRef :itemsitems :nestedfalse classw-60 /虛擬化大數(shù)據(jù)量渲染virtualize屬性可為大列表啟用虛擬化傳true或配置對象{ estimateSize, overscan }UTree :itemsitems :virtualize{ estimateSize: 32, overscan: 12 } classw-60 /estimateSize每項預估高度像素默認32也可以是(index) number函數(shù)overscan可視區(qū)外額外渲染的項數(shù)默認12。需要注意虛擬化開啟時樹結構會被扁平化效果等同nested: false且滾動容器由主題virtualize: true變體提供root: overflow-y-auto。源碼通過getEstimateSize(items, size)見 src/utils/virtualizer.ts依據(jù)當前size自動推算默認預估高度實際渲染由 Reka UI 的TreeVirtualizer完成。自定義插槽節(jié)點級slot屬性可指定個性化插槽每個具名插槽又衍生出五個子插槽#{item.slot}-wrapper包裹整個節(jié)點#{item.slot}節(jié)點主體內(nèi)容#{item.slot}-leading前導區(qū)域圖標#{item.slot}-label文本標簽區(qū)域#{item.slot}-trailing尾部區(qū)域展開箭頭未指定slot時對應基礎插槽item-wrapper/item/item-leading/item-label/item-trailing。所有插槽均暴露以下作用域屬性屬性說明item當前節(jié)點數(shù)據(jù)index節(jié)點在同級中的索引level節(jié)點所在層級從 1 開始expanded/selected/indeterminate展開、選中、半選狀態(tài)handleSelect/handleToggle手動觸發(fā)選中/展開的行為函數(shù)ui當前主題的ui對象含插槽 class示例為slot: app的節(jié)點定制內(nèi)容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文本截斷l(xiāng)inkTrailingms-auto inline-flex gap-1.5變體方面支持virtualize、color、size、selected、disabled默認變體為color: primary、size: mdselected與color的組合通過compoundVariants生成選中態(tài)文字顏色如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根節(jié)點與鏈接的渲染元素itemsTreeItem[]—樹數(shù)據(jù)colorprimary \| neutral \| ...primary選中態(tài)顏色sizexs \| sm \| md \| lg \| xlmd緊湊程度getKey(item) string—唯一標識函數(shù)labelKeystringlabel作為標識/文本的字段multiplebooleanfalse是否多選modelValue/defaultValueTreeItem \| TreeItem[]—受控/非受控選中值nestedbooleantrue嵌套 DOM 還是扁平列表virtualizeboolean \| { estimateSize?, overscan? }false虛擬化開關與參數(shù)trailingIconstringui.icons.chevronDown父節(jié)點展開箭頭expandedIcon/collapsedIconstringui.icons.folderOpen/ui.icons.folder展開/收起態(tài)文件夾圖標disabledbooleanfalse禁用整棵樹expanded/defaultExpandedTreeItem[]—展開狀態(tài)受控/默認值selectionBehavior/propagateSelect/bubbleSelect/loop繼承自 Reka UI—選擇與焦點行為onSelect/onToggle回調(diào)—組件級選中/展開回調(diào)Slotsitem-wrapper、item、item-leading、item-label、item-trailing以及由item.slot派生的動態(tài)插槽#{slot}-wrapper、#{slot}、#{slot}-leading、#{slot}-label、#{slot}-trailing。所有插槽共享上文列出的作用域屬性。Emits組件發(fā)出繼承自 Reka UITreeRoot的事件主要包括update:modelValuev-model選中值、select選中某節(jié)點、toggle展開/收起某節(jié)點等且攜帶對應節(jié)點數(shù)據(jù)供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與動態(tài)插槽的渲染。此外還包含兩項關鍵斷言通過axe無障礙審計passes accessibility tests驗證了基于 Reka UI 的 WAI-ARIA 語義、鍵盤導航與焦點管理通過expectEmitPayloadType驗證update:modelValue在普通與getKey場景下的載荷類型推導。結合文檔與測試可以確認 Tree 組件在交互語義與視覺表現(xiàn)上均具備生產(chǎn)可用性。建議在實際項目中優(yōu)先使用getKey保證數(shù)據(jù)唯一性并在數(shù)據(jù)量較大時開啟virtualize以獲得穩(wěn)定性能。提示本文對應的官方交互式示例選中控制、展開控制、復選框樹、拖拽、虛擬化、自定義插槽均可通過倉庫文檔目錄 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 開發(fā)框架是 Espressif 芯片的官方物聯(lián)網(wǎng)嵌入式手柄操作B站客戶端wiliwili 在Switch上從安裝到流暢播放的5步實戰(zhàn)指南手柄操作B站客戶端wiliwili 在Switch上從安裝到流暢播放的5步實戰(zhàn)指南 如果你想在電視或掌機上僅靠手柄就能刷視頻、發(fā)彈幕、追番劇而不必忍受傳統(tǒng)音視頻桌面應用rsuite 樹形表格Tree Table完全指南層級數(shù)據(jù)的展示、展開控制與虛擬化實戰(zhàn)rsuite 樹形表格Tree Table完全指南層級數(shù)據(jù)的展示、展開控制與虛擬化實戰(zhàn) 樹形表格是展示具有層級結構關系數(shù)據(jù)的表格形態(tài)它通過在普通表格中引前端UI組件上一篇Ente Locker 集合Collections使用指南用多標簽式組織管理你的加密文檔下一篇Prometheus Operator 官方 CLI 參考operator 二進制全部命令與參數(shù)詳解創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考