官方文档:
https://uniapp.dcloud.io/collocation/pages?id=style

style

用于设置每个页面的状态栏、导航条、标题、窗口背景色等。
页面中配置项会覆盖 globalStyle 中相同的配置项

属性 类型 默认值 描述 平台差异说明
navigationBarBackgroundColor HexColor #000000 导航栏背景颜色(同状态栏背景色),如”#000000”
navigationBarTextStyle String white 导航栏标题颜色及状态栏前景颜色,仅支持 black/white
navigationBarTitleText String 导航栏标题文字内容
navigationBarShadow Object 导航栏阴影,配置参考下方 导航栏阴影
navigationStyle String default 导航栏样式,仅支持 default/custom。custom即取消默认的原生导航栏,需看使用注意 微信小程序 7.0+、百度小程序、H5、App(2.0.3+)
disableScroll Boolean false 设置为 true 则页面整体不能上下滚动(bounce效果),只在页面配置中有效,在globalStyle中设置无效 微信小程序(iOS)、百度小程序(iOS)
backgroundColor HexColor #ffffff 窗口的背景色 微信小程序、百度小程序、字节跳动小程序、飞书小程序
backgroundTextStyle String dark 下拉 loading 的样式,仅支持 dark/light
enablePullDownRefresh Boolean false 是否开启下拉刷新,详见页面生命周期
onReachBottomDistance Number 50 页面上拉触底事件触发时距页面底部距离,单位只支持px,详见页面生命周期
backgroundColorTop HexColor #ffffff 顶部窗口的背景色(bounce回弹区域) 仅 iOS 平台
backgroundColorBottom HexColor #ffffff 底部窗口的背景色(bounce回弹区域) 仅 iOS 平台
titleImage String 导航栏图片地址(替换当前文字标题),支付宝小程序内必须使用https的图片链接地址 支付宝小程序、H5
transparentTitle String none 导航栏透明设置。支持 always 一直透明 / auto 滑动自适应 / none 不透明 支付宝小程序、H5、APP
titlePenetrate String NO 导航栏点击穿透 支付宝小程序、H5
app-plus Object 设置编译到 App 平台的特定样式,配置项参考下方 app-plus App
h5 Object 设置编译到 H5 平台的特定样式,配置项参考下方 H5 H5
mp-alipay Object 设置编译到 mp-alipay 平台的特定样式,配置项参考下方 MP-ALIPAY 支付宝小程序
mp-weixin Object 设置编译到 mp-weixin 平台的特定样式 微信小程序
mp-baidu Object 设置编译到 mp-baidu 平台的特定样式 百度小程序
mp-toutiao Object 设置编译到 mp-toutiao 平台的特定样式 字节跳动小程序
mp-lark Object 设置编译到 mp-lark 平台的特定样式 飞书小程序
mp-qq Object 设置编译到 mp-qq 平台的特定样式 QQ小程序
mp-kuaishou Object 设置编译到 mp-kuaishou 平台的特定样式 快手小程序
usingComponents Object 引用小程序组件,参考 小程序组件 App、微信小程序、支付宝小程序、百度小程序
leftWindow Boolean true 当存在 leftWindow时,当前页面是否显示 leftWindow H5
topWindow Boolean true 当存在 topWindow 时,当前页面是否显示 topWindow H5
rightWindow Boolean true 当存在 rightWindow时,当前页面是否显示 rightWindow H5
maxWidth Number 单位px,当浏览器可见区域宽度大于maxWidth时,两侧留白,当小于等于maxWidth时,页面铺满;不同页面支持配置不同的maxWidth;maxWidth = leftWindow(可选)+page(页面主体)+rightWindow(可选) H5(2.9.9+)

自定义导航栏使用注意

当navigationStyle设为custom或titleNView设为false时,原生导航栏不显示,此时要注意几个问题:

  • 非H5端,手机顶部状态栏区域会被页面内容覆盖。这是因为窗体是沉浸式的原因,即全屏可写内容。uni-app提供了状态栏高度的css变量—status-bar-height,如果需要把状态栏的位置从前景部分让出来,可写一个占位div,高度设为css变量。

    1. <template>
    2. <view>
    3. <view class="status_bar">
    4. <!-- 这里是状态栏 -->
    5. </view>
    6. <view> 状态栏下的文字 </view>
    7. </view>
    8. </template>
    9. <style>
    10. .status_bar {
    11. height: var(--status-bar-height);
    12. width: 100%;
    13. }
    14. </style>
  • 如果原生导航栏不能满足需求,推荐使用uni ui的自定义导航栏NavBar。这个前端导航栏自动处理了状态栏高度占位问题。

  • 前端导航栏搭配原生下拉刷新时,会有问题,包括
    • 微信小程序下iOS需要拉更长才能看到下拉刷新的三个点,而Android是从屏幕顶部下拉,无法从导航栏下方下拉。如果一定要从前端导航栏下拉,小程序下只能放弃原生下拉刷新,纯前端模拟,参考mescroll插件,但这样很容易产生性能问题。目前小程序平台自身没有提供更好的方案
    • App和H5下,原生下拉刷新提供了circle样式,可以指定offset偏移量(pages.json的app-plus下配置),自定义下拉圈出现的位置。在hello uni-app的扩展组件中有示例。
  • 非H5端,前端导航盖不住原生组件。如果页面有video、map、textarea(仅小程序)等原生组件,滚动时会覆盖住导航栏
    • 如果是小程序下,可以使用cover-view来做导航栏,避免覆盖问题
    • 如果是App下,建议使用titleNViewsubNVue,体验更好
  • 前端组件在渲染速度上不如原生导航栏,原生导航可以在动画期间渲染,保证动画期间不白屏,但使用前端导航栏,在新窗体进入的动画期间可能会整页白屏,越低端的手机越明显。
  • 以上讨论的是前端自定义导航栏,但在App侧,原生导航栏也提供了比小程序导航更丰富的自定义性
    • titleNView:给原生导航栏提供更多配置,包括自定义按钮、滚动渐变效果、搜索框等,详见titleNView
    • subNVue:使用nvue原生渲染,所有布局自己开发,具备一切自定义灵活度。详见subNVue
  • 页面禁用原生导航栏后,想要改变状态栏的前景字体样式,仍可设置页面的 navigationBarTextStyle 属性(只能设置为 black或white)。如果想单独设置状态栏颜色,App端可使用plus.navigator.setStatusBarStyle设置。注意部分低端Android手机(4.4)自身不支持设置状态栏前景色。

鉴于以上问题,在原生导航能解决业务需求的情况下,尽量使用原生导航。甚至有时需要牺牲一些不是很重要的需求。在App和H5下,uni-app提供了灵活的处理方案:titleNViewsubNVue、或整页使用nvue。但在小程序下,因为其自身的限制,没有太好的方案。有必要的话,也可以用条件编译分端处理。

原生的导航栏:在pages.json中修改:

image.png