Nuxt 內(nèi)置路由出口組件NuxtPage完全指南Props、頁(yè)面過(guò)渡與 Suspense 生命周期【免費(fèi)下載鏈接】nuxtthe full-stack Vue framework項(xiàng)目地址: https://gitcode.com/GitHub_Trending/nu/nuxtNuxtPage是 Nuxt 框架內(nèi)置的路由出口組件用于渲染位于app/pages/目錄下的頂層或嵌套頁(yè)面是文件路由系統(tǒng)的核心渲染節(jié)點(diǎn)。本文基于當(dāng)前倉(cāng)庫(kù)Nuxt 全棧 Vue 框架的官方 API 文檔與packages/nuxt/src/pages/runtime/page.ts源碼實(shí)現(xiàn)系統(tǒng)講解它的內(nèi)部結(jié)構(gòu)、全部 Props、頁(yè)面過(guò)渡與 keep-alive 配置方式、Suspense 下的生命周期差異、頁(yè)面實(shí)例引用獲取以及自定義 Props 透?jìng)骷记勺x完即可在應(yīng)用布局中正確地配置與調(diào)優(yōu)路由頁(yè)面渲染。為什么應(yīng)該使用NuxtPage而不是RouterView在 Nuxt 應(yīng)用中NuxtPage與 Vue Router 的RouterView組件職責(zé)相似——它們都是路由組件的出口決定當(dāng)前匹配的路由組件渲染在哪里。但官方文檔明確建議必須使用NuxtPage而不是直接使用RouterView。NuxtPage本質(zhì)上是RouterView的一層封裝它的額外價(jià)值在于負(fù)責(zé)維護(hù) Nuxt 內(nèi)部的頁(yè)面狀態(tài)例如頁(yè)面級(jí) route 的響應(yīng)式派生、page:start/page:finish等生命周期 Hook 的觸發(fā)如果繞過(guò)它直接使用RouterView內(nèi)部狀態(tài)得不到正確處理可能導(dǎo)致useRoute()返回錯(cuò)誤的路徑Nuxt 會(huì)自動(dòng)掃描并渲染app/pages/目錄下的所有 Vue 組件因此在使用NuxtPage時(shí)無(wú)需手動(dòng)傳入name與route它會(huì)由框架自動(dòng)解析見(jiàn)頁(yè)面目錄文檔。源碼中的組件定義印證了這一點(diǎn)在 page.ts 中組件通過(guò)h(RouterView, { name: props.name, route: props.route, ...attrs }, ...)將用戶傳入的name與route原樣交給RouterView并通過(guò)自定義的插槽渲染邏輯接管了頁(yè)面組件的掛載方式。這也解釋了它為什么在 Props 類(lèi)型上繼承了RouterViewProps。NuxtPage的內(nèi)部控制結(jié)構(gòu)從實(shí)現(xiàn)視角看NuxtPage在客戶端渲染的組件樹(shù)大致等效于下面這段模板僅示意實(shí)際經(jīng)組合式 API 與 VNode 構(gòu)建template RouterView v-slot{ Component } !-- 可選啟用頁(yè)面切換過(guò)渡時(shí) -- Transition !-- 可選啟用頁(yè)面狀態(tài)保持時(shí) -- KeepAlive Suspense component :isComponent / /Suspense /KeepAlive /Transition /RouterView /template這一嵌套層級(jí)對(duì)應(yīng)了源碼中的真實(shí)包裝順序在 page.ts 中可以看到最終渲染的 vnode 由_wrapInTransition(...)包裹wrapInKeepAlive(...)包裹Suspense組成而Suspense內(nèi)部再渲染RouteProvider來(lái)提供頁(yè)面級(jí)的響應(yīng)式 route。三個(gè)要點(diǎn)默認(rèn)不啟用Transition與KeepAlive。在 schema 的 app 配置 中app.pageTransition與app.keepalive的默認(rèn)值都是false。需要在三個(gè)層級(jí)中啟用它們nuxt.config全局配置、NuxtPage組件上的transition/keepaliveProps、頁(yè)面組件內(nèi)通過(guò)definePageMeta按頁(yè)配置。在頁(yè)面組件中啟用Transition時(shí)必須保證頁(yè)面模板只有一個(gè)根元素否則過(guò)渡動(dòng)畫(huà)無(wú)法正確執(zhí)行。啟用 Transition 與 KeepAlive 的三種方式方式一全局配置nuxt.configexport default defineNuxtConfig({ app: { pageTransition: { name: page, mode: out-in }, keepalive: true, }, })app.pageTransition默認(rèn)值為falseapp.keepalive同樣默認(rèn)關(guān)閉見(jiàn) packages/schema/src/config/app.ts。方式二在NuxtPage組件上按使用位置配置template NuxtPage transitionpage keepalive / /template方式三在頁(yè)面組件內(nèi)用definePageMeta單獨(dú)定義script setup langts definePageMeta({ key: route route.fullPath, transition: { name: page, mode: out-in }, keepalive: true, }) /script從源碼看這些來(lái)源之間存在明確的優(yōu)先級(jí)鏈。以 transition 為例在 page.ts 中const hasTransition !!(props.transition ?? routeProps.route.meta.pageTransition ?? defaultPageTransition)即NuxtPage的transitionProp 路由記錄的meta.pageTransition來(lái)自definePageMeta 全局默認(rèn)app.pageTransition。隨后這些配置通過(guò)_mergeTransitionProps合并定義于 packages/nuxt/src/app/components/utils.ts并在onAfterLeave回調(diào)里觸發(fā)page:transition:finishHook。keepalive 的解析邏輯類(lèi)似見(jiàn)源碼第 184 行const routeKeepaliveConfig props.keepalive ?? routeProps.route.meta.keepalive ?? defaultKeepaliveConfig另外源碼中還處理了一個(gè)重要細(xì)節(jié)如果某些頁(yè)面通過(guò)definePageMeta開(kāi)啟了 keep-alive當(dāng)導(dǎo)航到未開(kāi)啟 keep-alive 的頁(yè)面時(shí)Nuxt 會(huì)把已開(kāi)啟頁(yè)面組件的名稱累積到keepAliveInclude集合中并注入到有效的KeepAlive配置的include列表中從而保證切換路由時(shí)已緩存頁(yè)面不被清空對(duì)應(yīng) issue #33610 的修復(fù)。這一邏輯就實(shí)現(xiàn)在 page.ts 的shouldAugmentInclude分支中。Suspense 下的頁(yè)面生命周期差異NuxtPage在底層使用Suspense包裝頁(yè)面因此頁(yè)面切換時(shí)組件的生命周期行為與典型 Vue 應(yīng)用不同在典型 Vue 應(yīng)用中新頁(yè)面組件會(huì)在舊頁(yè)面完全卸載之后才被掛載在 Nuxt 中由于 VueSuspense的實(shí)現(xiàn)機(jī)制新頁(yè)面組件會(huì)在舊頁(yè)面卸載之前就被掛載。這一差異主要影響同時(shí)觀察舊頁(yè)面卸載與新頁(yè)面掛載兩個(gè)生命周期的代碼例如在onUnmounted/onMounted中執(zhí)行清理與初始化邏輯的場(chǎng)景編寫(xiě)跨頁(yè)面共享狀態(tài)或動(dòng)畫(huà)時(shí)需留意時(shí)序。源碼對(duì)該機(jī)制做了額外加固快速連續(xù)導(dǎo)航時(shí)組件會(huì)通過(guò)遞增suspenseKey重新掛載 Suspense 邊界僅在已成功 resolve 過(guò)一次之后避免未 resolve 的 Suspense 被提前拆除導(dǎo)致父級(jí)組件掛起對(duì)應(yīng) issue #28425 / #34683。同時(shí)客戶端在初次 hydration 期間如果組件在 Suspense resolve 前被卸載例如布局切換會(huì)通過(guò)onBeforeUnmount中的done()確保 hydration 流程正常收尾。此外客戶端渲染分支還做了陳舊 vnode 復(fù)用處理當(dāng)導(dǎo)航導(dǎo)致某個(gè)NuxtPage暫時(shí)沒(méi)有匹配的子頁(yè)面組件時(shí)會(huì)優(yōu)先渲染舊的 vnode 直到新路由解析完成對(duì)于已經(jīng)卸載的 Suspense 邊界上遺留的陳舊 vnode則通過(guò)isStaleVNode判斷并丟棄避免 hydration 階段讀取空el報(bào)錯(cuò)對(duì)應(yīng) issue #23232。Props 詳解NuxtPage的 Props 在源碼 page.ts 中有完整的類(lèi)型聲明與運(yùn)行時(shí)定義匯總?cè)缦翽rop類(lèi)型作用說(shuō)明namestring告訴RouterView渲染匹配路由記錄components選項(xiàng)中對(duì)應(yīng)名稱的組件。配合命名視圖使用對(duì)應(yīng)nameview.vue的命名文件約定見(jiàn)頁(yè)面目錄文檔的 Named Views 一節(jié)routeRouteLocationNormalized所有組件都已解析完畢的路由位置對(duì)象pageKeystring或(route) string控制NuxtPage何時(shí)被重新渲染transitionboolean或TransitionProps為通過(guò)該NuxtPage渲染的所有頁(yè)面定義全局過(guò)渡keepaliveboolean或KeepAliveProps控制通過(guò)該NuxtPage渲染的頁(yè)面狀態(tài)保持運(yùn)行時(shí)類(lèi)型校驗(yàn)與文檔一致transition接受Boolean/Objectkeepalive同樣接受Boolean/ObjectpageKey接受Function/String默認(rèn)null。除了顯式 PropsNuxt 會(huì)自動(dòng)解析name與route因?yàn)轫?yè)面系統(tǒng)會(huì)掃描并渲染app/pages/目錄下所有 Vue 組件文件并將每個(gè)組件與對(duì)應(yīng)的路由記錄自動(dòng)關(guān)聯(lián)起來(lái)。pageKey控制頁(yè)面組件的重新渲染pageKey用于控制NuxtPage何時(shí)重新渲染頁(yè)面組件。理解它最直接的方式是看示例。如果傳入一個(gè)恒定不變的 keyNuxtPage只會(huì)在首次掛載時(shí)渲染一次template NuxtPage page-keystatic / /template也可以基于當(dāng)前路由使用動(dòng)態(tài) keyNuxtPage :page-keyroute route.fullPath /?? 官方文檔特別警告不要在這里使用$route對(duì)象因?yàn)樗鼤?huì)干擾NuxtPage基于Suspense的頁(yè)面渲染機(jī)制可能引發(fā)渲染異常。除了組件上直接傳 ProppageKey也可以在頁(yè)面組件的script中通過(guò)definePageMeta以key字段傳入script setup langts definePageMeta({ key: route route.fullPath, }) /script關(guān)于pageKey的默認(rèn)行為可以從工具函數(shù) packages/nuxt/src/pages/runtime/utils.ts 的generateRouteKey中看出端倪當(dāng)沒(méi)有顯式傳入pageKey、路由也沒(méi)有meta.key時(shí)Nuxt 默認(rèn)基于路由匹配到的路徑將:param等動(dòng)態(tài)段替換為實(shí)際參數(shù)值生成 key——這意味著默認(rèn)情況下同一個(gè)頁(yè)面組件在不同參數(shù)如/users/1與/users/2之間切換會(huì)被判定為不同 key 而觸發(fā)重渲染。用key: route route.fullPath顯式定義則可以讓 key 精確跟隨完整路徑。另外在客戶端當(dāng)pageKey發(fā)生變化時(shí)源碼會(huì)通過(guò) watcher 觸發(fā)page:loading:startHook見(jiàn) page.ts 第 83-89 行并在頁(yè)面 resolve 后依次觸發(fā)page:finish與page:loading:end從而實(shí)現(xiàn)與useLoadingIndicator加載進(jìn)度條的聯(lián)動(dòng)。獲取頁(yè)面組件實(shí)例ref 與 pageRef由于NuxtPage內(nèi)部有多層包裝直接給NuxtPage綁ref拿到的并不是頁(yè)面組件本身而是NuxtPage組件實(shí)例。Nuxt 通過(guò)expose({ pageRef })將真正渲染的頁(yè)面組件實(shí)例暴露出來(lái)因此需要通過(guò)ref.value.pageRef訪問(wèn)。script setup langts const page ref() function logFoo () { page.value.pageRef.foo() } /script template NuxtPage refpage / /template對(duì)應(yīng)的頁(yè)面組件需要把方法暴露出去才能被外部調(diào)用script setup langts const foo () { console.log(foo method called) } defineExpose({ foo, }) /script源碼實(shí)現(xiàn)中pageRef定義于setup中并通過(guò)expose({ pageRef })暴露同時(shí)通過(guò)RouteProvider的vnodeRef傳入并作為頁(yè)面 vnode 的ref綁定見(jiàn) route-provider.ts 第 73 行h(props.vnode, { ref: props.vnodeRef })從而保證pageRef始終指向?qū)嶋H渲染的頁(yè)面組件實(shí)例。向頁(yè)面透?jìng)髯远x PropsNuxtPage除了上述內(nèi)置 Props 外還接受任何自定義 Props并會(huì)把它們繼續(xù)向下傳遞到頁(yè)面組件。例如在布局入口傳入一個(gè)自定義 Propfoobartemplate NuxtPage :foobar123 / /template在頁(yè)面組件中可以通過(guò)defineProps正常接收script setup langts const props defineProps{ foobar: number }() console.log(props.foobar) // 輸出: 123 /script如果頁(yè)面組件沒(méi)有用defineProps聲明該 Prop仍然可以通過(guò)attrsuseAttrs()拿到透?jìng)髦祍cript setup langts const attrs useAttrs() console.log(attrs.foobar) // 輸出: 123 /script這在實(shí)現(xiàn)布局統(tǒng)一注入頁(yè)面公共參數(shù)如頁(yè)面標(biāo)題 key、分區(qū)標(biāo)識(shí)等時(shí)非常實(shí)用。值得一提的是源碼中NuxtPage設(shè)置了inheritAttrs: false并在渲染時(shí)把除內(nèi)置 Props 外的attrs原樣展開(kāi)傳給RouterViewh(RouterView, { ..., ...attrs }, ...)再經(jīng)由插槽與RouteProvider傳遞到頁(yè)面 vnode這正是自定義 Props 能夠一路透?jìng)鞯巾?yè)面組件的底層原因。源碼中的配套實(shí)現(xiàn)與測(cè)試圍繞NuxtPage當(dāng)前倉(cāng)庫(kù)的源碼與測(cè)試形成了完整的印證鏈條組件主實(shí)現(xiàn)packages/nuxt/src/pages/runtime/page.ts —— 涵蓋 Props 聲明、Suspense包裝、transition/keepalive 合并與優(yōu)先級(jí)、suspenseKey重掛載策略、page:start/page:finish/page:loading:end等 Hook 觸發(fā)、hydration 期間錯(cuò)誤 Hook 的注冊(cè)等。路由 key 與 KeepAlive 工具packages/nuxt/src/pages/runtime/utils.ts ——generateRouteKey默認(rèn) key 推導(dǎo)與pageKey覆蓋、wrapInKeepAlive。頁(yè)面級(jí)響應(yīng)式 route 提供者packages/nuxt/src/app/components/route-provider.ts ——RouteProvider通過(guò)provide(PageRouteSymbol, ...)向頁(yè)面提供派生自當(dāng)前渲染分叉的 route并承擔(dān)pageRef綁定。過(guò)渡合并工具packages/nuxt/src/app/components/utils.ts ——_mergeTransitionProps與_wrapInTransition。全局默認(rèn)配置packages/schema/src/config/app.ts ——app.pageTransition: false與app.keepalive: false的默認(rèn)值。端到端測(cè)試test/nuxt/nuxt-page.test.ts —— 覆蓋不同嵌套深度路由下NuxtPage的掛載行為、setup/render 次數(shù)統(tǒng)計(jì)等可作為理解其生命周期語(yǔ)義的補(bǔ)充材料該測(cè)試文件超過(guò) 1100 行還包含多層級(jí)嵌套與異步 setup 場(chǎng)景的回歸用例。若需要進(jìn)一步了解頁(yè)面文件到路由的映射關(guān)系、命名視圖nameview.vue約定以及definePageMeta的全部可用字段可繼續(xù)閱讀 頁(yè)面目錄文檔 與 definePageMeta 工具文檔?！久赓M(fèi)下載鏈接】nuxtthe full-stack Vue framework項(xiàng)目地址: https://gitcode.com/GitHub_Trending/nu/nuxt創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考