uni-appuni-app-x自定义导航栏组件 uni-nav-bar 完全指南安全区适配、三区布局与 slot 扩展【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-nav-bar 是 uni-app / uni-app-x 官方提供的轻量级自定义导航栏组件用于在页面关闭原生导航栏navigationStyle: custom后用纯声明式的方式重建顶部导航区域。本文将围绕该组件在仓库中的官方文档readme.md与真实源码uni-nav-bar.vue展开带你掌握安全区适配原理、left/mid/right 三区布局、返回箭头、标题与前景色控制以及如何用 slot 和外部 class 完成任意自定义。一、组件定位接管被关闭的原生导航栏在 uni-app 中页面默认自带原生导航栏。当页面需要沉浸式设计、自定义标题栏样式或与内容区域一体化时通常会在pages.json中把该页面的导航样式改为自定义{ pages: [ { path: pages/index/index, style: { navigationStyle: custom } } ] }配置navigationStyle: custom之后原生导航栏不再渲染页面顶部完全交由开发者自己控制。此时即可引入本组件替代原生导航栏。仓库自身的演示工程在 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以及微信小程序端属于纯跨端组件无需额外原生依赖。二、安全区适配与尺寸约定组件在模板根部对顶部安全区做了自动适配见 uni-nav-bar.vueview styleflex-direction: row;padding-top: var(--status-bar-height);box-sizing: content-box;align-items: center;position: relative;核心要点通过padding-top: var(--status-bar-height)让出顶部状态栏刘海屏/挖孔屏的高度状态栏区域不再遮挡内容外层使用box-sizing: content-box确保内层内容高度不受 padding 影响除去状态栏高度后组件主体高度固定为44px这也是 iOS 原生导航栏的标准高度视觉上与系统保持一致组件左右两边默认各让出 6px 边距见样式区.uni-left-class-buildin { margin-left: 6px }与.uni-right-class-buildin { margin-right: 6px }让按钮不至于贴边。需要自定义左右间距时通过left-class与right-class传入自定义样式类覆盖即可同时组件底部也预留了--uni-safe-area-inset-bottom一类的安全区变量供页面内容使用参见 navbar-lite.uvue 的用法。三、left / mid / right 三区布局组件内部结构分为三个区域见 uni-nav-bar.vue区域默认行为默认宽度自定义方式left显示返回箭头44×44px 点击区44px含 6px 左边距slot nameleft替代left-class修饰样式hideDefaultBack隐藏箭头mid显示title属性设置的标题屏幕宽度 − 左右边距 − left 宽 − right 宽样式实现为left: 52px; right: 52px即 644slot namemid替代mid-class修饰样式right默认不显示内容44px含 6px 右边距slot nameright填充内容right-class修饰样式从源码可以确认mid 区域的绝对定位区间为left: 52px; right: 52px注释中明确 52 padding 6 44因此标题默认居中于「两侧各 52px」的安全区间内。flatten属性用于降低该节点的层级负担保证绝对定位内容正确覆盖。3.1 left 区域返回箭头与点击区放大默认返回箭头并非使用图片而是由两个 view 通过 CSS 旋转拼出的箭头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内层箭头大小为 12×12px、由左边框与下边框旋转 45° 组成外层再套一层 44×44px 的透明容器以扩大点击区域符合移动端最小触控尺寸规范点击调用back()其实现为uni.navigateBack({})uni-nav-bar.vue即返回上一页传入hideDefaultBack可隐藏该箭头此时leftslot 若存在则会替换显示。3.2 mid 区域标题与居中/居左切换mid 区域在slots[mid]为空时渲染title文本颜色由foreColor控制传入slot namemid后 title 属性不再生效readme 明确「如果传入 mid slot则不生效」。组件还额外提供了isLeft布尔属性为true时标题在 mid 区域内左对齐justify-content: flex-start否则居中justify-content: center。仓库示例页面 navbar-lite.uvue 正是通过点击切换isLeft来演示「标题居中 / 居左」两种形态。3.3 right 区域默认空白slot 自由填充right 区域默认不渲染任何内容仅保留 44px 宽度占位通过slot nameright放入自定义按钮、文字或图标。四、属性详解完整属性定义见组件脚本区uni-nav-bar.vue属性类型默认值说明hideDefaultBackBooleanfalse是否隐藏默认返回箭头titleString标题文本传入midslot 后不生效navigationBarTextStyleString返回箭头与标题的前景色可选white/black也支持#fff/#ffffff/#000/#000000等十六进制写法不传时在非 MP 平台自动读取页面pageStyle的navigationBarTextStyleleftClassStringleft 区域外部样式类midClassStringmid 区域外部样式类rightClassStringright 区域外部样式类isLeftBooleanfalse标题是否左对齐false 为居中4.1 navigationBarTextStyle 的前景色获取逻辑源码中foreColor是一个computed且存在平台差异uni-nav-bar.vue非 MP 平台当外部未传入navigationBarTextStyle为空字符串时通过getCurrentInstance()?.proxy?.$page?.getPageStyle()[navigationBarTextStyle]自动获取页面pageStyle的默认值只有显式传入时才以传入值为准。MP小程序平台小程序端无法获取pageStyle因此foreColor直接等于传入的navigationBarTextStyle必须显式传入前景色否则返回箭头与标题会使用默认色。这意味着在微信小程序等 MP 端使用本组件时请务必显式传入navigationBarTextStyle避免出现颜色与页面风格不一致的情况。4.2 动态切换前景色示例仓库演示页 navbar-lite.uvue 展示了通过uni.setNavigationBarColor动态修改导航栏背景、再同步组件前景色的完整写法function setNavigationBarColor1() { uni.setNavigationBarColor({ frontColor: #ffffff, backgroundColor: #0000, success: () { navigationBarTextColor.value #fff }, fail: () { /* ... */ }, complete: () { /* ... */ } }) }页面中的navigationBarTextColor为响应式变量绑定到组件的:navigationBarTextStyle上前景色随之联动更新。五、插槽与外部类三种自定义路径组件支持两种自定义机制对应 readme 中的描述Slot 替换内容级自定义slot nameleft整体替换 left 区域内容替换后默认返回箭头不再渲染slot namemid替换 mid 区域内容title属性失效slot nameright填充 right 区域自定义内容。externalClasses样式级自定义组件通过defineOptions声明了externalClasses: [left-class,mid-class,right-class]uni-nav-bar.vue在页面使用组件时给left-class/mid-class/right-class传入自定义 class即可在不改组件源码的情况下覆盖三区样式——例如修改左右边距、调整标题字号、给 right 区增加底色等。三区默认样式可在组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
