支付宝小程序代码结构及组成 （二）

本章内容出自《小程序开发不求人》电子书， 点击下载完整版

支付宝小程序代码结构及组成

小程序全局结构

概述

App() 代表顶层应用，管理所有页面和全局数据，以及提供生命周期回调等。它也是一个构造方法，生成 App 实例。

一个小程序就是一个 App 实例。

每个小程序顶层一般包含三个文件。

• app.json：应用配置
• app.js：应用逻辑
• app.acss：应用样式（可选）

简单示例

一个简单的 app.json 代码如下：

{
 "pages": [
 "pages/index/index",
 "pages/logs/logs"
 ],
 "window": {
 "defaultTitle": "Demo"
 }
}           

这段代码配置指定小程序包含两个页面（index 和 logs），以及应用窗口的默认标题设置为 “Demo”。

一个简单的 app.js 代码如下：

App({
 onLaunch(options) {
 // 第一次打开
 },
 onShow(options) {
 // 小程序启动，或从后台被重新打开
 },
 onHide() {
 // 小程序从前台进入后台
 },
 onError(msg) {
 // 小程序发生脚本错误或 API 调用出现报错
 console.log(msg);
 },
 globalData: {
 // 全局数据
 name: 'alipay',
 },
});           

app.json 全局配置

app.json 用于对小程序进行全局配置，设置页面文件的路径、窗口表现、多 tab等。

以下是一个基本配置示例：

{
 "pages": [
 "pages/index/index",
 "pages/logs/index"
 ],
 "window": {
 "defaultTitle": "Demo"
 }
}           

完整配置项如下：

pages

app.json 中的 pages 为数组属性，数组中每一项都是字符串，用于指定小程序的页面。在小程序中新增或删除页面，都需要对 pages 数组进行修改。

pages 数组的每一项代表对应页面的路径信息，其中，第一项代表小程序的首页。

页面路径不需要写任何后缀，框架会自动去加载同名的 .json、.js、.axml、.acss文件。举例来说，如果开发目录为：

├── pages
│ ├──index
│ │ ├── index.json
│ │ ├── index.js
│ │ ├── index.axml
│ │ └── index.acss
│ ├──logs
│ │ ├── logs.json
│ │ ├── logs.js
│ │ └── logs.axml
├── app.json
├── app.js
└── app.acss           

app.json 中应当如下配置：

{
 "pages":[
 "pages/index/index",
 "pages/logs/logs"
 ]
}           

window

window 用于设置小程序的状态栏、导航条、标题、窗口背景色等。

示例代码：

{
 "window":{
 "defaultTitle": "支付宝接口功能演示"
 }
}           

属性	类型	是否必填	描述	最低版本
defaultTitle	String	否	页面默认标题	-
pullRefresh			是否允许下拉刷新。默认NO, 备注：下拉刷新生效的前提是allowsBounceVertical 值为 YES
allowsBounceVertical			是否允许向下拉拽。默认YES, 支持 YES / NO
transparentTitle			导航栏透明设置。默认none，支持 always 一直透明 / auto 滑动自适应 /none 不透明
titlePenetrate			是否允许导航栏点击穿透。默认 NO，支持 YES / NO
showTitleLoading			是否进入时显示导航栏的loading。默认 NO，支持YES / NO
titleImage			导航栏图片地址
titleBarColor	HexColor		导航栏背景色，十六进制颜色值（0-255）
backgroundColor			页面的背景色，十六进制颜色值（0-255）
backgroundImageColor			下拉露出显示的背景图底色，十六进制颜色值（0-255）
backgroundImageUrl			下拉露出显示的背景图链接
gestureBack			iOS 用，是否支持手势返回。默认 NO，支持 YES /NO
enableScrollBar	Boolean		Android 用，是否显示WebView 滚动条。默认YES，支持 YES / NO
onReachBottomDistance	Number		页面上拉触底时触发时距离页面底部的距离，单位为px。相关文档 页面事件处理函数	1.19.0 ，目前iOS 在page.json 下设置无效，只能全局设置。

tabBar

如果你的小程序是一个多 tab 应用（客户端窗口的底部栏可以切换页面），那么可以通过 tabBar 配置项指定 tab 栏的表现，以及 tab 切换时显示的对应页面。

注意：

• 通过页面跳转（ my.navigateTo ）或者页面重定向（ my.redirectTo ）所到达的页面，即使它是定义在 tabBar 配置中的页面，也不会显示底部的 tab 栏。
• tabBar 的第一个页面必须是首页。

tabBar 配置项有以下：

每个 item 配置：

icon 图标推荐大小为 60×60 px 大小，系统会对传入的非推荐尺寸的图片进行非等比拉伸或缩放。

{
 "tabBar": {
 "textColor": "#dddddd",
 "selectedColor": "#49a9ee",
 "backgroundColor": "#ffffff",
 "items": [
 {
 "pagePath": "pages/index/index",
 "name": "首页"
 },
 {
 "pagePath": "pages/logs/logs",
 "name": "日志"
 }
 ]
 }
}           

app.acss 全局样式

app.acss 作为全局样式，作用于当前小程序的所有页面。

ACSS 是一套样式语言，用于描述 AXML 的组件样式，决定 AXML 的组件的显示效果。

为适应广大前端开发者，ACSS 和 CSS 规则完全一致，100% 可以用。同时为更适合开发小程序，对 CSS 进行了扩充。

ACSS 支持 px，rpx，vh，vw 等单位。

rpx

rpx（responsive pixel）可以根据屏幕宽度进行自适应，规定屏幕宽为750rpx。以 Apple iPhone6 为例，屏幕宽度为 375px，共有 750 个物理像素，则 750rpx = 375px = 750 物理像素，1rpx = 0.5px = 1 物理像素。

样式导入

使用 @import 语句可以导入外联样式表，@import 后需要加上外联样式表相对路径，用;表示结束。

/** button.acss **/
.sm-button {
 padding: 5px;
}           

/** app.acss **/
@import "./button.acss";
.md-button {
 padding: 15px;
}           

导入路径支持从 node_modules 目录载入第三方模块，例如 page.acss:

@import "./button.acss"; /*相对路径*/
@import "/button.acss"; /*项目绝对路径*/
@import "third-party/page.acss"; /*第三方 npm 包路径*/           

内联样式

组件上支持使用 style、class 属性来控制样式。

style 属性

用于接收动态样式，样式在运行时会进行解析。行内样式不支持!important 优先级规则。

<view style="color:{{color}};" />           

class 属性

用于接收静态样式，属性值是样式规则中类选择器名（样式类名）的集合，样式类名不需要带上.，多个类名间以空格分隔。请静态样式写进 class 中，避免将静态样式写进 style 中，以免影响渲染速度。

<view class="my-awesome-view" />           

选择器

同 CSS3 保持一致。

• .a-, .am- 开头的类选择器为系统组件占用，不可使用。
• 不支持属性选择器。

全局样式与局部样式

• app.acss 中的样式为全局样式，作用于每一个页面。
• 页面文件夹内的 .acss 文件中定义的样式为局部样式，只作用在对应的页面，并会覆盖app.acss 中相同的选择器。

本地资源引用

ACSS 文件里的本地资源引用请使用绝对路径的方式，不支持相对路径引用。例如：

/* 支持 */
background-image: url('/images/ant.png');
/* 不支持 */
background-image: url('./images/ant.png');           

app.js 注册小程序

App(object: Object)

App() 用于注册小程序，接受一个 Object 作为属性，用来配置小程序的生命周期等。

App() 必须在 app.js 中调用，必须调用且只能调用一次。

object 属性说明

前台/后台定义：

• 小程序用户点击右上角关闭，或者按下设备 Home 键离开支付宝时，小程序并不会直接销毁，而是进入后台。
• 当用户再次进入支付宝或再次打开小程序时，小程序会从后台进入前台。
• 只有当小程序进入后台 5 分钟后，或占用系统资源过高，才会被真正销毁。

onLaunch(object: Object) 及 onShow(object: Object)

object 属性说明：

query	Object	当前小程序的 query，从启动参数的 query字段解析而来
scene	number	启动小程序的 场景值
path	string	当前小程序的页面地址，从启动参数 page字段解析而来，page 忽略时默认为首页
referrerInfo		来源信息

比如，启动小程序的 schema url 如下:

alipays://platformapi/startapp?appId=1999&query=number%3D1&page=x%2Fy%2
Fz           

• 小程序首次启动时，onLaunch 方法可获取 query、path 属性值。
• 小程序在后台被用 schema 打开，也可从 onShow 方法中获取 query、path 属性值。

App({
 onLaunch(options) {
 // 第一次打开
 console.log(options.query);
 // {number:1}
 console.log(options.path);
 // x/y/z
 },
 onShow(options) {
 // 从后台被 schema 重新打开
 console.log(options.query);
 // {number:1}
 console.log(options.path);
 // x/y/z
 },
});           

referrerInfo 子属性说明：

appId		来源小程序
sourceServiceId		来源插件，当处于插件运行模式时可见	1.11.0
extraData		来源小程序传过来的数据。

• 不要在 onShow 中进行 redirectTo 或 navigateTo 等操作页面栈的行为。
• 不要在 onLaunch 里调用 getCurrentPages() ，因为此时 page 还未生成。

onHide()

小程序从前台进入后台时触发 onHide() 。

App({
 onHide() {
 // 进入后台时
 console.log('app hide');
 },
});           

onError(error: String)

小程序发生脚本错误时触发。

App({
 onError(error) {
 // 小程序执行出错时
 console.log(error);
 },
});           

onShareAppMessage(object: Object)

全局分享配置。当页面未设置 page.onShareAppMessage 时，调用分享会执行全局的分享设置，具体见

分享

。

globalData 全局数据

App() 中可以设置全局数据 globalData。

// app.js
App({
 globalData: 1
});           

getApp 方法

小程序提供了全局的 getApp() 方法，可获取当前小程序实例，一般用于在子页面中获取顶层应用。

var app = getApp();
console.log(app.globalData); // 获取 globalData           

使用过程中，请注意以下几点：

• App() 函数中不可以调用 getApp()，可使用 this 可以获取当前小程序实例。
• 通过 getApp() 获取实例后，请勿私自调用生命周期回调函数。
• 请区分全局变量及页面局部变量，比如：

// app.js
App({
 //定义全局变量 globalData，在整个 App 中有效
 globalData: 1
});           

// a.js
// 定义页面局部变量 localValue，只在 a.js 有效
var localValue = 'a';
// 获取 app 实例
var app = getApp();
// 拿到全局数据，并改变它
app.globalData++;           

// b.js
// 定义页面局部变量 localValue，只在 b.js 有效
var localValue = 'b';
// 如果 a.js 先运行，globalData 会返回 2
console.log(getApp().globalData);           

a.js 和 b.js 两个文件中都声明了变量 localValue，但并不会互相影响，因为各个文件声明的局部变量和函数只在当前文件下有效。