【微信小程序实战教程】之微信小程序的配置文件详解_小程序全局配置

小程序的配置文件

对于有过服务端开发的程序员来说，肯定对“约定优于配置”并不陌生，这是一种按约定编程的软件设计范式，目的在于减少软件开发者做决定的数量。而微信小程序正好与这种软件设计范式的理念相反，小程序是一种“配置优于约定”的软件设计范式，处于对安全性的考虑，开发者必须在相应的配置文件中对小程序部分界面和功能进行配置，例如窗口的导航栏设计、底部tabBar设计等。本章主要对微信小程序的全局、页面等配置文件做详细的讲解，通过学习配置文件的配置项，可以掌握更多的小程序功能设计。

1 全局配置文件

小程序的全局配置文件控制着小程序的全局表现，所有的配置项都在项目根目录下的app.json文件中进行配置。全局配置文件的内容是一个JSON对象，涵盖了小程序的页面路径、窗口表现、底部tab栏、默认启动页、网络超时时间等几十项配置信息。

1.1 页面路径配置

pages属性用于配置小程序的所有页面路径，该配置项用于指定哪些页面可以被显示。pages属性的值为字符串类型的数组，数组元素是对应页面的访问路径。小程序的每个页面都是一个文件夹，页面的文件夹中都由.wxml、.wxss、.json、.js这四种文件组成，一般会将文件夹和四个文件的文件名设置为相同的名字，效果如例1所示。

【例1】小程序文件目录

├── app.js
├── app.json
├── app.wxss
├── pages
│   │── index
│   │   ├── index.wxml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.wxss
│   └── logs
│       ├── logs.wxml
│       └── logs.js
│       └── logs.json
│       └── logs.wxss
└── sitemap.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

在pages属性中定义页面路径时，要包含文件名称，但是不需要写文件的扩展名，小程序框架会自动找到对应的.wxml、.wxss、.json、.js四个文件进行处理。pages具体配置信息如例2所示。
【例2】pages页面路径配置

{
  "pages":[
    "pages/index/index",
    "pages/logs/logs"
  ]
}
1
2
3
4
5
6

pages中配置的路径都可以在小程序中被访问到，如果未在app.json文件中配置entryPagePath（默认启动页）属性的话，小程序会按照pages数组中的第一项作为默认首页。如果在项目中手动创建页面文件的话，pages数组的元素内容也会随之自动增加，但是如果手动删除了某个页面文件时，还需要手动删除pages数组中对应的元素。我们还可以在pages中添加一个页面路径元素，小程序开发者工具就会自动创建该页面的文件夹和四个文件，只要对小程序中的页面做了新增和删除操作，都需要对pages数组进行修改。

1.2 启动首页配置

entryPagePath属性用于配置小程序的默认启动路径，即小程序的默认首页。该属性的值为字符串类型的页面路径，配置的路径必须在pages属性中已经存在。默认启动路径配置的代码如例3所示。

【例3】配置默认启动路径

{
  "pages":[
    "pages/index/index",
    "pages/logs/logs"
  ],
  "entryPagePath": "pages/logs/logs"
}
1
2
3
4
5
6
7

如果没有配置entryPagePath属性的话，小程序会将pages数组中的第一项作为默认启动路径。entryPagePath属性的值如果不是pages数组中的元素的话，控制台会报错，效果如图1所示。

图1 控制台报错信息

1.3 窗口样式配置

window属性用于配置小程序的窗口表现，包含小程序的状态栏、导航条、标题、窗口背景颜色等。该属性的值是一个Object对象，具体配置信息如例4所示。

【例4】配置小程序的导航栏样式

{
  "pages":[
    "pages/index/index"
  ],
  "window":{
    "navigationBarBackgroundColor": "#000000",
    "navigationBarTextStyle":"white",
    "navigationBarTitleText": "首页"
  }
}
1
2
3
4
5
6
7
8
9
10

配置后的小程序页面效果如图2所示。

图2 小程序导航栏配置效果

小程序的窗口配置还包括下拉刷新的开启与关闭、页面上拉触底距离、页面旋转设置等功能。在设置页面下拉刷新和上拉触底时，都需要配合相关的API来触发对应的事件函数，以设置下拉刷新为例，代码如例5所示。

【例5】触发下拉刷新事件

// 文件app.json
{
  "enablePullDownRefresh": true
}
1
2
3
4

// 文件pages/index/index.js
Page({
  data: {
    count:  10
  },
  onPullDownRefresh() {
    console.log('下拉刷新');
  }
})
1
2
3
4
5
6
7
8
9

<!-- 文件pages/index/index.wxml -->
<view>
  <view wx:for="{{count}}" wx:key="index">{{item}}</view>
</view>
1
2
3
4

在设置窗口颜色、导航栏颜色、文本颜色等颜色赋值时，如果没有特殊说明该配置项的固定颜色值，都可以使用十六进制的颜色值来进行设置。某些配置项需要考虑到移动终端的兼容性，例如backgroundColorTop（顶部窗口背景颜色）、backgroundColorBottom（底部窗口背景颜色）配置项仅支持iOS操作系统，navigationStyle（导航栏样式）配置项仅支持iOS和Android微信客户端6.6.0版本，不支持Windows微信客户端。

小程序的很多窗口样式都可以通过window属性来配置，还有些样式也可以自定义，但是考虑到小程序的安全性，不是所有的样式都可以自定义的，例如导航栏右上角的胶囊按钮，即使将navigationStyle属性的值设置为custom（自定义导航栏），也会保留胶囊按钮，因为该按钮统一管理了小程序的转发、分享、收藏和关闭等系统功能，所以是不允许开发者自定义的。

1.4 tab栏配置

tabBar属性用于配置小程序底部tab栏的样式与表现，该属性的值是一个Object对象。小程序的tab栏可以设置在窗口的底部和顶部，用户点击tab栏上不同的按钮来实现切换页面。

tabBar对象中有四个必填属性，分别是：

• list，用于配置tab的列表项；
• color，用于配置tab上的文字默认颜色，仅支持十六进制颜色值；
• selectedColor，用于配置tab上的文字选中时的颜色，仅支持十六进制的颜色值；
• backgroundColor，用于配置tab栏的背景颜色，仅支持十六进制颜色值。

其中list属性的值为数组类型，只能配置最少2个、最多5个tab列表项。tab项的顺序是按照数组的元素顺序排列的，数组的每个元素都是一个对象，在对象中配置tab项的路径、文字、默认与选中时的图片路径等信息。tab栏的具体代码如例6所示。

【例6】配置小程序底部的tab栏

{
  "pages":[
    "pages/index/index",
    "pages/logs/logs"
  ],
  "tabBar": {
    "color": "#7D6566",
    "selectedColor": "#5592FA",
    "backgroundColor": "#ffffff",
    "borderStyle": "black",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "images/icon-index.png",
        "selectedIconPath": "images/icon-index-sel.png"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "日志",
        "iconPath": "images/icon-logs.png",
        "selectedIconPath": "images/icon-logs-sel.png"
      }
    ],
    "position": "bottom"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

配置完成小程序窗口底部的tabBar之后，效果如图3所示。

图3 底部tabBar效果

在配置tab栏的页面路径时，页面的路径必须要先在pages中预先定义，否则会报错。tab栏上的图片必须是从项目本地引入的图片文件，不支持网络图片，图片的大小限制在40kb以内，建议尺寸为81(px)×81(px)。

1.5 网络超时配置

networkTimeout属性用于设置各类网络请求的超时时间，该属性的值为Object对象，设置的超时时间单位为毫秒，默认值均为60000毫秒（即1分钟）。networkTimeout对象的属性如表1所示。

配置网络请求超时的代码如例7所示。
【例7】配置HTTPS请求超时时间

// 文件app.json
{
  "networkTimeout": {
    "request": 60000
  }
}
1
2
3
4
5
6

1.6 小程序接口权限配置

permission属性用于小程序接口权限相关设置，该属性的值为Object对象，对象中可以配置一个名为 scope.userLocation 的字段，字段的值为 PermissionObject结构，详细配置如例8所示。

【例8】配置小程序权限

{
  "pages": ["pages/index/index"],
  "permission": {
    "scope.userLocation": {
      "desc": "小程序将获取您的位置信息" 
    }
  }
}
1
2
3
4
5
6
7
8

在例8的配置示例中，scope.userLocation用于位置相关权限的声明，其值为对象类型，对象中的desc字段是用于说明小程序获取权限时展示的接口用途描述。

在使用小程序权限接口时，部分权限接口需要经过用户授权同意后才能够被调用。我们把这些接口按使用范围分成多个 scope ，用户选择对 scope 来进行授权，当授权给一个 scope 之后，其对应的所有接口都可以直接使用。scope可以设置的权限如表2所示。

在真正需要使用授权接口时，才向用户发起授权申请，并在授权申请中说明清楚要使用该功能的理由。一旦用户明确同意或拒绝过授权，其授权关系会记录在后台，直到用户主动删除小程序。

这些接口被调用时会出现以下情况：

• 如果用户未接受或拒绝过此权限，会弹窗询问用户，用户点击同意后方可调用接口；
• 如果用户已授权，可以直接调用接口；
• 如果用户已拒绝授权，则不会出现弹窗，而是直接进入接口 fail 回调。请开发者兼容用户拒绝授权的场景。

开发者可以使用 wx.getSetting 获取用户当前的授权状态，还可以使用 wx.authorize 在调用需授权 API 之前，提前向用户发起授权请求。

1.7 小程序样式版本配置

从微信客户端 7.0 开始，微信小程序 UI 界面做了很大的改版，同时也进行了基础组件的样式升级。在全局配置文件 app.json 中配置 style 属性的值为“v2”可表明启用新版的组件样式。详细的配置代码如例9所示。

【例9】配置小程序样式版本

{
  "style": "v2"
}
1
2
3

基础库2.8.0版本开始支持style的配置，如果使用了更低版本的基础库的话，不支持该功能，就需要做兼容处理。如果使用了小程序的第三方UI组件库，这些组件库与小程序新版基础组件之间存在不兼容的情况，需要在app.json全局配置文件中删除style的配置，不然就会造成部分组件样式混乱，例如Vant Weapp UI组件库。

1.8 全局自定义组件配置

usingComponents属性用于全局声明自定义组件，如果已经在app.json全局配置文件中声明了全局自定义组件，就不需要在小程序内的页面或自定义组件中再次声明，可以直接使用该组件。

从小程序基础库版本 1.6.3 开始，小程序支持简洁的组件化编程。所有自定义组件相关特性都需要基础库版本 1.6.3 或更高。开发者可以将页面内的功能模块抽象成自定义组件，以便在不同的页面中重复使用，也可以将复杂的页面拆分成多个低耦合的模块，有助于代码维护。自定义组件在使用时与基础组件非常相似。

自定义组件和创建页面一样，需要定义.json、.wxml、.wxss、.js四个文件。首先需要在 json 文件中进行自定义组件声明。在项目的根目录下的components文件夹中创建一个自定义组件“my-component”的文件夹，并在文件夹中创建四种类型的文件，都命名为index，效果如图4所示。

图4 自定义组件

自定义组件的配置代码如例10所示。

【例10】自定义组件的index.json配置文件

{
  "component": true
}
1
2
3

同时，还要在 index.wxml 文件中编写组件模板，在 index.wxss 文件中加入组件样式，它们的写法与页面的写法类似。示例代码如例11所示。

【例11】自定义组件模板和样式

<!-- 这是自定义组件的内部WXML结构 -->
<view class="inner">
  {{innerText}}
</view>
<slot></slot>
1
2
3
4
5

/* 这里的样式只应用于这个自定义组件 */
.inner {
  color: red;
}
1
2
3
4

为自定义组件设置样式时不能使用ID选择器、属性选择器和标签选择器，只能使用类选择器。在自定义组件的 index.js 文件中，需要使用 Component() 来注册组件，并提供组件的属性定义、内部数据和自定义方法。组件的属性值和内部数据将被用于组件 wxml 的渲染，其中，属性值是可由组件外部传入的。示例代码如例12所示。

【例12】自定义组件的逻辑

Component({
  properties: {
    // 这里定义了innerText属性，属性值可以在组件使用时指定
    innerText: {
      type: String,
      value: 'default value',
    }
  },
  data: {
    // 这里是一些组件内部数据
    someData: {}
  },
  methods: {
    // 这里是一个自定义方法
    customMethod: function(){}
  }
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

使用已注册的自定义组件之前，需要在app.json全局配置文件中进行引用声明，也可以在页面的 page.json 文件中引用声明。引用自定义组件的示例代码如例13所示。

【例13】在app.json中引用自定义组件

{
  "usingComponents": {
    "my-component": "/components/my-component/index"
  }
}
1
2
3
4
5

这样，在 index.wxml 页面中就可以像使用基础组件一样使用自定义组件。节点名即自定义组件的标签名，节点属性即传递给组件的属性值，示例代码如例14所示。

【例14】在页面中使用自定义组件

<view>
  <!-- 以下是对一个自定义组件的引用 -->
  <my-component inner-text="Some text"></my-component>
</view>
1
2
3
4

自定义组件的 wxml 节点结构在与数据结合之后，将被插入到引用位置内。

2 页面配置文件

小程序应用的每个页面都是由四个文件组成的，分别为 page.wxml、page.wxss、page.js 和 page.json 。其中， page.json 就是当前页面的配置文件，用于对当前页面的窗口表现进行配置。页面的配置在当前页面会覆盖 app.json 的 window 属性中的相同配置项。page.json 可以对当前页面的导航栏、窗口背景、下拉刷新、上拉触底、页面自定义组件等表现能力进行配置。

2.1 导航栏配置

开发者可以对微信小程序的导航栏进行自定义样式设置，但是在设置导航栏时必须保留右上角的胶囊按钮。通过 page.json 配置文件可以设置小程序导航栏的背景颜色、标题颜色、标题文字内容等，具体的配置项如下所示：

• navigationBarBackgroundColor，值为十六进制的颜色，用于设置导航栏的背景颜色，默认值为 “#000000”；
• navigationBarTextStyle，值为字符串类型，用于设置导航栏的标题颜色，值必须为指定的字符串，仅支持“black”和“white”两个值；
• navigationBarTitleText，值为字符串类型，用于设置导航栏标题文字内容；
• navigationStyle，值为字符串类型，用于设置导航栏的样式，仅支持“default”和“custom”两个字符串值；如果值为“custom”时，可以自定义导航栏样式，但是必须要保留右上角的胶囊按钮；自定义导航栏仅在IOS、Android操作系统的微信客户端可用。

小程序页面中的导航栏配置代码如例15所示。

【例15】配置页面导航栏样式

// index.json
{
  "navigationBarBackgroundColor": "#ffffff",
  "navigationBarTextStyle": "black",
  "navigationBarTitleText": "商城首页"
}
1
2
3
4
5
6

运行上面代码，小程序的导航效果如图5所示。

图5 小程序首页导航样式

如果在小程序页面的配置文件中设置了导航样式，那么全局配置文件 app.json 中关于导航的配置在当前页面将会被覆盖。

2.2 窗口配置

页面配置文件中的窗口样式配置项和app.json文件中相关的配置项用法是相同的，常见的配置有：

• backgroundColor，值为十六进制颜色，用于设置窗口的背景颜色，默认值为“#ffffff”；
• backgroundColorTop，值为十六进制颜色，用于设置顶部窗口的背景颜色，仅支持IOS操作系统的微信客户端，并且微信客户端要高于6.5.16版本；
• backgroundColorBottom，值为十六进制颜色，用于设置底部窗口的背景颜色，仅支持IOS操作系统的微信客户端，并且微信客户端要高于6.5.16版本；
• pageOrientation，值为字符串类型，用于设置屏幕的旋转方向，支持“auto”、“portrait”、“landscape”等固定值；
• disableScroll，值为boolean类型，用于设置页面整体上下滚动的能力，默认值为false；当值设置为true时页面不能整体上下滚动，并且只在页面配置中有效，无法在app.json中设置；

显示区域指小程序界面中可以自由布局展示的区域。在默认情况下，小程序显示区域的尺寸自页面初始化起就不会发生变化。从小程序基础库版本 2.0 开始，小程序在手机上支持屏幕旋转。使小程序中的页面支持屏幕旋转的方法是：在 app.json 的 window 段中设置 “pageOrientation”: “auto” ，或在页面 json 文件中配置 “pageOrientation”: “auto” 。

在单个页面 json 文件中启用屏幕旋转的代码如例16所示。

【例16】设置屏幕旋转

// index.json
{
  "pageOrientation": "auto"
}
1
2
3
4

如果页面添加了例16的配置项，则在屏幕旋转时，这个页面将随之旋转，显示区域尺寸也会随着屏幕旋转而变化。还可以将 pageOrientation 的值设置为 landscape ，表示固定为横屏显示。

有时，对于不同尺寸的显示区域，页面的布局会有所差异。此时可以使用 media query 来解决大多数问题。仅仅使用 media query 无法控制一些精细的布局变化。此时可以使用 js 作为辅助。在 js 中读取页面的显示区域尺寸，可以使用 selectorQuery.selectViewport 。

页面尺寸发生改变的事件，可以使用页面的 onResize 来监听。对于自定义组件，可以使用 resize 生命周期来监听。回调函数中将返回显示区域的尺寸信息。示例代码如例17所示。

【例17】监听页面尺寸变化

// 在页面中监听
Page({
  onResize(res) {
    res.size.windowWidth // 新的显示区域宽度
    res.size.windowHeight // 新的显示区域高度
  }
})

// 在自定义组件中监听
Component({
  pageLifetimes: {
    resize(res) {
      res.size.windowWidth // 新的显示区域宽度
      res.size.windowHeight // 新的显示区域高度
    }
  }
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

2.3 页面加载配置

小程序页面加载配置包括：

• enablePullDownRefresh，值为boolean类型，用于设置当前页面下拉刷新功能的开启与关闭，Page.onPullDownRefresh()方法可以监听页面的下拉刷新；
• onReachBottomDistance，值为number类型，用于设置页面上拉触底事件触发时，页面底部的触发距离，默认值为50px，Page.onReachBottom方法可以监听页面的上拉触底；
• initialRenderingCache，值为字符串类型，用于设置页面初始渲染缓存，支持“static”和“dynamic”两个固定值；
• restartStrategy，值为字符串类型，用于设置小程序的重启策略。

小程序页面的初始化分为两个部分，分别为逻辑层初始化和视图层初始化。在启动页面时，尤其是小程序冷启动、进入第一个页面时，逻辑层初始化的时间较长。在页面初始化过程中，用户将看到小程序的标准载入画面（冷启动时）或可能看到轻微的白屏现象（页面跳转过程中）。

启用初始渲染缓存，可以使视图层不需要等待逻辑层初始化完毕，而直接提前将页面初始 data 的渲染结果展示给用户，这可以使得页面对用户可见的时间大大提前。

利用初始渲染缓存，可以：

• 快速展示出页面中永远不会变的部分，如导航栏；
• 预先展示一个骨架页，提升用户体验；
• 展示自定义的加载提示；
• 提前展示广告。

3 sitemap 配置文件

3.1 sitemap 介绍

微信客户端提供了搜索小程序的能力，开发者可以通过 sitemap.json 配置文件来配置小程序页面是否允许被微信索引。当开发者允许微信索引时，微信会通过爬虫的形式，为小程序的页面内容建立索引。当用户的搜索词条触发该索引时，小程序的页面将可能展示在搜索结果中。

sitemap.json配置文件被放置在小程序的根目录下，文件内容是一个JSON对象，如果小程序中没有创建 sitemap.json 配置文件，则默认为所有页面都允许被索引。JSON对象中的 rules 字段用于设置索引规则，配置代码如例18所示。

【例18】配置小程序的索引规则

// sitemap.json
{
  "desc": "当前配置文件的描述信息",
  "rules": [{
    "action": "allow",
    "page": "*"
  }]
}
1
2
3
4
5
6
7
8

rules 配置项指定了索引规则，每项规则为一个JSON对象，属性如表3所示。

3.2 小程序的索引规则

在rules配置项中，使用matching字段来说明params的匹配方式。matching字段的值包括：

• exact，当小程序页面的参数列表等于 params 时，规则命中；
• inclusive，当小程序页面的参数列表包含 params 时，规则命中；
• exclusive，当小程序页面的参数列表与 params 交集为空时，规则命中；
• partial，当小程序页面的参数列表与 params 交集不为空时，规则命中。

我们以exact的命中规则为例，具体的配置代码如例19所示。

【19】配置小程序的索引规则

// sitemap.json
{
  "rules":[{
    "action": "allow",
    "page": "path/to/page",
    "params": ["a", "b"],
    "matching": "exact"
  }, {
    "action": "disallow",
    "page": "path/to/page"
  }]
}
1
2
3
4
5
6
7
8
9
10
11
12

在上面的配置中，命中规则matching的值为exact，表示当小程序页面的参数必须包含“a”和“b”时才会被索引。例如：“path/to/page?a=1&b=2”则优先被索引；如果参数中仅包含“a”、“b”中的一个参数，或者是“a”和“b”都包含，当前页面都不会被索引；如果参数中除了包含“a”、“b”之外，还包含了其他额外的参数，那么当前页面也不会被索引；除此“path/to/page”页面之外，其他页面都会被索引，但是优先级都低于此页面。

4 项目配置文件

小程序项目根目录下还有一个project.config.js配置文件，该文件用于对项目进行配置。如果开发者在一台电脑上的微信开发者工具中做很多项目相关的配置，当把项目拷贝到其他电脑中，用微信开发者工具打开时还想继续保留之前的配置，那就需要使用 project.config.js 保留项目的配置信息。

project.config.js 的配置项如表4所示。

在上列的配置项中，setting 字段是用于对项目的编译设置，我们可以手动在 project.config.js 配置文件中对项目进行设置，具体代码如例20所示。

【例20】项目编译设置

// project.config.js
{
    "setting": {
        "urlCheck": false, // 是否检查安全域名和 TLS 版本
        "es6": true, // 是否开启es6转es5
        "enhance": true, // 是否打开增强编译
        "postcss": true, // 上传代码时样式是否自动补全
        "preloadBackgroundData": false,
        "minified": true, // 上传代码时是否自动压缩
        "uglifyFileName": false, // 是否进行代码保护
    }
}
1
2
3
4
5
6
7
8
9
10
11
12

除此之外，我们还可以使用微信开发者工具进行图形化设置，如图6所示。

图6 小程序项目的本地设置

点击工具栏右侧的【详情】按钮，选择【本地设置】，通过复选框勾选的本地设置最终会在 project.config.js 配置文件中以JSON对象的形式保存。

5 本章小结

本章通过对小程序配置文件的学习，了解到小程序一共有四种配置文件，分别是全局配置文件、页面配置文件、索引配置文件、项目配置文件。配置文件在小程序项目开发中起着至关重要的作用，一些核心的样式和属性都需要通过配置文件来实现修改，这也体现了小程序“配置优越约定”的架构思想。