官方文档:
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变量。
<template>
<view>
<view class="status_bar">
<!-- 这里是状态栏 -->
</view>
<view> 状态栏下的文字 </view>
</view>
</template>
<style>
.status_bar {
height: var(--status-bar-height);
width: 100%;
}
</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下,建议使用titleNView或subNVue,体验更好
- 前端组件在渲染速度上不如原生导航栏,原生导航可以在动画期间渲染,保证动画期间不白屏,但使用前端导航栏,在新窗体进入的动画期间可能会整页白屏,越低端的手机越明显。
- 以上讨论的是前端自定义导航栏,但在App侧,原生导航栏也提供了比小程序导航更丰富的自定义性
- titleNView:给原生导航栏提供更多配置,包括自定义按钮、滚动渐变效果、搜索框等,详见titleNView
- subNVue:使用nvue原生渲染,所有布局自己开发,具备一切自定义灵活度。详见subNVue
- 页面禁用原生导航栏后,想要改变状态栏的前景字体样式,仍可设置页面的 navigationBarTextStyle 属性(只能设置为 black或white)。如果想单独设置状态栏颜色,App端可使用plus.navigator.setStatusBarStyle设置。注意部分低端Android手机(4.4)自身不支持设置状态栏前景色。
鉴于以上问题,在原生导航能解决业务需求的情况下,尽量使用原生导航。甚至有时需要牺牲一些不是很重要的需求。在App和H5下,uni-app提供了灵活的处理方案:titleNView、subNVue、或整页使用nvue。但在小程序下,因为其自身的限制,没有太好的方案。有必要的话,也可以用条件编译分端处理。