uni-appuni-app-x自定義導(dǎo)航欄組件 uni-nav-bar 完全指南安全區(qū)適配、三區(qū)布局與 slot 擴(kuò)展【免費(fèi)下載鏈接】uni-appA cross-platform framework using Vue.js項(xiàng)目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-nav-bar 是 uni-app / uni-app-x 官方提供的輕量級(jí)自定義導(dǎo)航欄組件用于在頁面關(guān)閉原生導(dǎo)航欄navigationStyle: custom后用純聲明式的方式重建頂部導(dǎo)航區(qū)域。本文將圍繞該組件在倉庫中的官方文檔readme.md與真實(shí)源碼uni-nav-bar.vue展開帶你掌握安全區(qū)適配原理、left/mid/right 三區(qū)布局、返回箭頭、標(biāo)題與前景色控制以及如何用 slot 和外部 class 完成任意自定義。一、組件定位接管被關(guān)閉的原生導(dǎo)航欄在 uni-app 中頁面默認(rèn)自帶原生導(dǎo)航欄。當(dāng)頁面需要沉浸式設(shè)計(jì)、自定義標(biāo)題欄樣式或與內(nèi)容區(qū)域一體化時(shí)通常會(huì)在pages.json中把該頁面的導(dǎo)航樣式改為自定義{ pages: [ { path: pages/index/index, style: { navigationStyle: custom } } ] }配置navigationStyle: custom之后原生導(dǎo)航欄不再渲染頁面頂部完全交由開發(fā)者自己控制。此時(shí)即可引入本組件替代原生導(dǎo)航欄。倉庫自身的演示工程在 src/pages.json 中即為navbar-lite/navbar-lite頁面配置了navigationStyle: custom并在 navbar-lite.uvue 中直接使用了組件uni-nav-bar :titletitle :is-leftisLeft :navigationBarTextStylenavigationBarTextColor/uni-nav-bar從 package.json 的uni_modules.platforms聲明可以看出該組件的 uni-app-x 版本支持 Android、iOS、HarmonyOS、Websafari/chrome以及微信小程序端屬于純跨端組件無需額外原生依賴。二、安全區(qū)適配與尺寸約定組件在模板根部對(duì)頂部安全區(qū)做了自動(dòng)適配見 uni-nav-bar.vueview styleflex-direction: row;padding-top: var(--status-bar-height);box-sizing: content-box;align-items: center;position: relative;核心要點(diǎn)通過padding-top: var(--status-bar-height)讓出頂部狀態(tài)欄劉海屏/挖孔屏的高度狀態(tài)欄區(qū)域不再遮擋內(nèi)容外層使用box-sizing: content-box確保內(nèi)層內(nèi)容高度不受 padding 影響除去狀態(tài)欄高度后組件主體高度固定為44px這也是 iOS 原生導(dǎo)航欄的標(biāo)準(zhǔn)高度視覺上與系統(tǒng)保持一致組件左右兩邊默認(rèn)各讓出 6px 邊距見樣式區(qū).uni-left-class-buildin { margin-left: 6px }與.uni-right-class-buildin { margin-right: 6px }讓按鈕不至于貼邊。需要自定義左右間距時(shí)通過left-class與right-class傳入自定義樣式類覆蓋即可同時(shí)組件底部也預(yù)留了--uni-safe-area-inset-bottom一類的安全區(qū)變量供頁面內(nèi)容使用參見 navbar-lite.uvue 的用法。三、left / mid / right 三區(qū)布局組件內(nèi)部結(jié)構(gòu)分為三個(gè)區(qū)域見 uni-nav-bar.vue區(qū)域默認(rèn)行為默認(rèn)寬度自定義方式left顯示返回箭頭44×44px 點(diǎn)擊區(qū)44px含 6px 左邊距slot nameleft替代left-class修飾樣式hideDefaultBack隱藏箭頭mid顯示title屬性設(shè)置的標(biāo)題屏幕寬度 ? 左右邊距 ? left 寬 ? right 寬樣式實(shí)現(xiàn)為left: 52px; right: 52px即 644slot namemid替代mid-class修飾樣式right默認(rèn)不顯示內(nèi)容44px含 6px 右邊距slot nameright填充內(nèi)容right-class修飾樣式從源碼可以確認(rèn)mid 區(qū)域的絕對(duì)定位區(qū)間為left: 52px; right: 52px注釋中明確 52 padding 6 44因此標(biāo)題默認(rèn)居中于「兩側(cè)各 52px」的安全區(qū)間內(nèi)。flatten屬性用于降低該節(jié)點(diǎn)的層級(jí)負(fù)擔(dān)保證絕對(duì)定位內(nèi)容正確覆蓋。3.1 left 區(qū)域返回箭頭與點(diǎn)擊區(qū)放大默認(rèn)返回箭頭并非使用圖片而是由兩個(gè) view 通過 CSS 旋轉(zhuǎn)拼出的箭頭uni-nav-bar.vueview v-if!hideDefaultBack slots[left]null stylewidth: 44px;height: 44px;justify-content: center;align-items: center; clickback view stylewidth: 12px;height: 12px;transform: rotate(45deg); border-left: 2px solid; border-bottom: 2px solid; :style{borderLeftColor:foreColor,borderBottomColor:foreColor}/view /view內(nèi)層箭頭大小為 12×12px、由左邊框與下邊框旋轉(zhuǎn) 45° 組成外層再套一層 44×44px 的透明容器以擴(kuò)大點(diǎn)擊區(qū)域符合移動(dòng)端最小觸控尺寸規(guī)范點(diǎn)擊調(diào)用back()其實(shí)現(xiàn)為uni.navigateBack({})uni-nav-bar.vue即返回上一頁傳入hideDefaultBack可隱藏該箭頭此時(shí)leftslot 若存在則會(huì)替換顯示。3.2 mid 區(qū)域標(biāo)題與居中/居左切換mid 區(qū)域在slots[mid]為空時(shí)渲染title文本顏色由foreColor控制傳入slot namemid后 title 屬性不再生效readme 明確「如果傳入 mid slot則不生效」。組件還額外提供了isLeft布爾屬性為true時(shí)標(biāo)題在 mid 區(qū)域內(nèi)左對(duì)齊justify-content: flex-start否則居中justify-content: center。倉庫示例頁面 navbar-lite.uvue 正是通過點(diǎn)擊切換isLeft來演示「標(biāo)題居中 / 居左」兩種形態(tài)。3.3 right 區(qū)域默認(rèn)空白slot 自由填充right 區(qū)域默認(rèn)不渲染任何內(nèi)容僅保留 44px 寬度占位通過slot nameright放入自定義按鈕、文字或圖標(biāo)。四、屬性詳解完整屬性定義見組件腳本區(qū)uni-nav-bar.vue屬性類型默認(rèn)值說明hideDefaultBackBooleanfalse是否隱藏默認(rèn)返回箭頭titleString標(biāo)題文本傳入midslot 后不生效navigationBarTextStyleString返回箭頭與標(biāo)題的前景色可選white/black也支持#fff/#ffffff/#000/#000000等十六進(jìn)制寫法不傳時(shí)在非 MP 平臺(tái)自動(dòng)讀取頁面pageStyle的navigationBarTextStyleleftClassStringleft 區(qū)域外部樣式類midClassStringmid 區(qū)域外部樣式類rightClassStringright 區(qū)域外部樣式類isLeftBooleanfalse標(biāo)題是否左對(duì)齊false 為居中4.1 navigationBarTextStyle 的前景色獲取邏輯源碼中foreColor是一個(gè)computed且存在平臺(tái)差異uni-nav-bar.vue非 MP 平臺(tái)當(dāng)外部未傳入navigationBarTextStyle為空字符串時(shí)通過getCurrentInstance()?.proxy?.$page?.getPageStyle()[navigationBarTextStyle]自動(dòng)獲取頁面pageStyle的默認(rèn)值只有顯式傳入時(shí)才以傳入值為準(zhǔn)。MP小程序平臺(tái)小程序端無法獲取pageStyle因此foreColor直接等于傳入的navigationBarTextStyle必須顯式傳入前景色否則返回箭頭與標(biāo)題會(huì)使用默認(rèn)色。這意味著在微信小程序等 MP 端使用本組件時(shí)請務(wù)必顯式傳入navigationBarTextStyle避免出現(xiàn)顏色與頁面風(fēng)格不一致的情況。4.2 動(dòng)態(tài)切換前景色示例倉庫演示頁 navbar-lite.uvue 展示了通過uni.setNavigationBarColor動(dòng)態(tài)修改導(dǎo)航欄背景、再同步組件前景色的完整寫法function setNavigationBarColor1() { uni.setNavigationBarColor({ frontColor: #ffffff, backgroundColor: #0000, success: () { navigationBarTextColor.value #fff }, fail: () { /* ... */ }, complete: () { /* ... */ } }) }頁面中的navigationBarTextColor為響應(yīng)式變量綁定到組件的:navigationBarTextStyle上前景色隨之聯(lián)動(dòng)更新。五、插槽與外部類三種自定義路徑組件支持兩種自定義機(jī)制對(duì)應(yīng) readme 中的描述Slot 替換內(nèi)容級(jí)自定義slot nameleft整體替換 left 區(qū)域內(nèi)容替換后默認(rèn)返回箭頭不再渲染slot namemid替換 mid 區(qū)域內(nèi)容title屬性失效slot nameright填充 right 區(qū)域自定義內(nèi)容。externalClasses樣式級(jí)自定義組件通過defineOptions聲明了externalClasses: [left-class,mid-class,right-class]uni-nav-bar.vue在頁面使用組件時(shí)給left-class/mid-class/right-class傳入自定義 class即可在不改組件源碼的情況下覆蓋三區(qū)樣式——例如修改左右邊距、調(diào)整標(biāo)題字號(hào)、給 right 區(qū)增加底色等。三區(qū)默認(rèn)樣式可在組件創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考