全局配置和页面配置

1. 前言

在开发uni-app 项目过程中,有许多配置项需要我们自己去操作配置,我们最常操作的就是项目的全局配置和页面配置,包括项目的标题栏、底部 Tab 栏、窗口背景色等。

主要通过操作项目根目录下面的 pages.json 文件,来进行项目的全局配置和页面配置。

接下来我们来学习怎样进行项目的配置。

2. 常用配置项属性

下面的这些属性都是用来进行项目配置的。一些常用的配置项,项目创建完成后,会自动帮我们生成,我们需要去了解每个配置项的含义,以及配置项对应的设置条件有哪些限制。

比如导航栏标题颜色样式 navigationBarTextStyle 这一个配置项,仅支持black/white 这两个颜色的设置,很多人会设置成十六进制颜色,比如 #0000FF,这样系统就会识别不了。

属性 默认值 说明 支持平台 全局配置 页面配置
navigationBarTextStyle white 导航栏标题颜色样式,仅支持 black/white 所有
navigationBarTitleText 导航栏标题文字内容 所有
navigationBarBackgroundColor #F7F7F7 导航栏背景颜色 所有,默认值小程序平台有差异,以各小程序文档为准
navigationBarShadow 导航栏阴影,详见3.2.2 所有
navigationStyle default 导航栏样式,仅支持 default/custom 微信小程序 7.0+、百度小程序、H5、App(2.0.3+)
disableScroll false 滚动条 微信小程序(iOS)、百度小程序(iOS)
backgroundColor #ffffff 下拉显示出来的窗口的背景色 微信小程序
backgroundTextStyle dark 下拉 loading 的样式,仅支持 dark / light 微信小程序
enablePullDownRefresh false 是否开启下拉刷新,详见3.1.1 所有
onReachBottomDistance 50 页面上拉触底事件触发时距页面底部距离,单位只支持px 所有
usingComponents 引用小程序组件 所有
pageOrientation portrait 横屏配置,屏幕旋转设置,仅支持 auto / portrait / landscape,详见3.1.2 App 2.4.7+、微信小程序

3. 配置项应用

接下来我们通过实例来了解一下各个配置项的应用。

3.1 全局配置

全局配置作用于整个项目,也就是对项目中所有的页面都起作用,在项目根目录下面的 pages.json 文件中,找到globalStyle配置项,在这个配置项中进行项目的全局配置。

实例:

"globalStyle": {
  "navigationBarTextStyle": "black", //导航栏标题颜色
  "navigationBarTitleText": "慕课网", //导航栏标题文字
  "navigationBarBackgroundColor": "#F8F8F8", //导航栏背景颜色
  "backgroundColor": "#F8F8F8", //下拉窗口背景颜色
  "backgroundTextStyle":light, //下拉 loading 的样式
  "enablePullDownRefresh":true, //开启下拉刷新
  "onReachBottomDistance":60,//页面上拉触发距页面底部距离为60
  "usingComponents":{
    "collapse-tree-item":"/components/collapse-tree-item"
  },//引用小程序组件
  "pageOrientation": "auto"//支持屏幕旋转
},

3.1.1 enablePullDownRefresh 下拉刷新

想要实现页面下拉刷新的效果,需要先在配置文件中将 enablePullDownRefresh 设置为 true,再在.vue页面文件中配合 onPullDownRefresh 函数进行页面下拉效果的实现。

这里很多人会忘记在配置文件中设置 enablePullDownRefresh 配置项,导致下拉效果失灵。
实例:

//pages.json 文件
"globalStyle": {
"enablePullDownRefresh":true
}
//页面.vue文件
onPullDownRefresh() {
  console.log('refresh');
  //用stopPullDownRefresh结束下拉
  uni.stopPullDownRefresh();
}

3.1.2 pageOrientation 屏幕旋转设置

这个属性可以设置为 auto、portrait、landscape。分别代表启用屏幕旋转、固定为竖屏显示、固定为横屏显示。默认值为 portrait 固定为竖屏显示。

这个属性,通常可以使用 js 作为辅助,用 js 读取页面的显示区域尺寸,来进行屏幕方向的监听,每次屏幕旋转时都会调用这个方法。需要注意的是,在模拟器上面不会触发这个方法,需要使用真机调试才能触发。
实例:

Page({
  onResize(res) {
    res.size.windowWidth // 新的显示区域宽度
    res.size.windowHeight // 新的显示区域高度
  }
})

3.2 页面配置

页面配置只作用于单个页面,与全局配置冲突的地方,页面配置会覆盖掉全局配置。在项目根目录下面的 pages.json 文件中,找到 pages 配置项里面的 style 来进行页面配置。

3.2.1 配置项属性

属性 描述
path 页面路径
style 页面窗口表现,配置项详见1

实例:

{
  "pages": [{
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页", //设置页面标题文字
        "disableScroll": true, //设置为true则页面整体不能上下滚动
        "enablePullDownRefresh":true, //开启下拉刷新
        "navigationBarShadow": {  
          "colorType": "green"
        },//导航栏阴影
      }
    },
    ...
  ]
}

导航栏阴影设置项不是所有的颜色都支持,需要注意哦。

属性 描述
colorType 阴影的颜色,支持:grey、blue、green、orange、red、yellow

4. 小结

uni-app 项目的配置主要就是这些内容,比较简单,但是很多细节需要我们去注意和掌握。如果掌握不熟练,会在实际开发的过程中埋下很多坑。
本小节主要介绍了 uni-app 项目的全局配置和页面配置,重点如下:

  • 了解几个常用配置项属性的作用;
  • 了解全局配置和页面配置的应用。