小程序宿主环境
我们称微信客户端给小程序所提供的环境为宿主环境。小程序借助宿主环境提供的能力,可以完成许多普通网页无法完成的功能。
上一章中我们把小程序涉及到的文件类型阐述了一遍,接下来结合项目来看一下这些文件是怎么配合工作的。
(1)渲染层和逻辑层
首先,我们来简单了解下小程序的运行环境。小程序的运行环境分成渲染层和逻辑层,其中 WXML 模板和 WXSS 样式工作在渲染层,JS 脚本工作在逻辑层。
小程序的渲染层和逻辑层分别由2个线程管理:渲染层的界面使用了WebView 进行渲染;逻辑层采用JsCore线程运行JS脚本。一个小程序存在多个界面,所以渲染层存在多个WebView线程,这两个线程的通信会经由微信客户端(下文中也会采用Native<本地>来代指微信客户端)做中转,逻辑层发送网络请求也经由Native转发,小程序的通信模型下图所示。
(2)框架
①小程序开发框架的目标是通过尽可能简单、高效的方式让开发者可以在微信中开发具有原生 APP 体验的服务。整个小程序框架系统分为两部分:逻辑层(App Service)和 视图层(View)。小程序提供了自己的视图层描述语言 WXML 和 WXSS,以及基于 JavaScript 的逻辑层框架,并在视图层与逻辑层间提供了数据传输和事件系统,让开发者能够专注于数据与逻辑。有关渲染层和逻辑层的详细文档参考 小程序框架 。
②响应的数据绑定
框架的核心是一个响应的数据绑定系统,可以让数据与视图非常简单地保持同步。当做数据修改的时候,只需要在逻辑层修改数据,视图层就会做相应的更新。
③页面管理
框架 管理了整个小程序的页面路由,可以做到页面间的无缝切换,并给以页面完整的生命周期。开发者需要做的只是将页面的数据、方法、生命周期函数注册到 框架 中,其他的一切复杂的操作都交由 框架 处理。
④基础组件
框架 提供了一套基础的组件,这些组件自带微信风格的样式以及特殊的逻辑,开发者可以通过组合基础组件,创建出强大的微信小程序 。
⑤丰富的 API
框架 提供丰富的微信原生 API,可以方便的调起微信提供的能力,如获取用户信息,本地存储,支付功能等。
(3)程序与页面
微信客户端在打开小程序之前,会把整个小程序的代码包下载到本地。紧接着通过 app.json 的 pages 字段就可以知道你当前小程序的所有页面路径:
{ "pages":[ "pages/index/index", "pages/logs/logs" ] }
这个配置说明在 项目定义了两个页面,分别位于 pages/index/index 和 pages/logs/logs。而写在 pages 字段的第一个页面就是这个小程序的首页(打开小程序看到的第一个页面)。于是微信客户端就把首页的代码装载进来,通过小程序底层的一些机制,就可以渲染出这个首页。
小程序启动之后,在 app.js 定义的 App 实例的 onLaunch 回调会被执行:
App({
/*function,非必填,生命周期回调——监听小程序初始化*/ onLaunch: function () { // 小程序启动之后 触发 } })
整个小程序只有一个 App 实例,是全部页面共享的,更多的事件回调参考文档 注册程序 App 。
(4)事件回调->注册小程序
每个小程序都需要在 app.js 中调用 App 方法注册小程序示例,绑定生命周期回调函数、错误监听和页面不存在监听函数等。
// app.js App({ onLaunch (options) { // Do something initial when launch. }, onShow (options) { // Do something when show. }, onHide () { // Do something when hide. }, onError (msg) { console.log(msg) }, globalData: 'I am global data' })
整个小程序只有一个 App 实例,是全部页面共享的。开发者可以通过 getApp 方法获取到全局唯一的 App 示例,获取App上的数据或调用开发者注册在 App 上的函数。
// xxx.js const appInstance = getApp() console.log(appInstance.globalData) // I am global data
(5)小程序注册-->参数
App(Object object)注册小程序,接受一个 Object 参数,其指定小程序的生命周期回调等。
App() 必须在 app.js 中调用,必须调用且只能调用一次。不然会出现无法预期的后果。参数如下
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
onLaunch | function | 否 | 生命周期回调——监听小程序初始化。 | |
onShow | function | 否 | 生命周期回调——监听小程序启动或切前台。 | |
onHide | function | 否 | 生命周期回调——监听小程序切后台。 | |
onError | function | 否 | 错误监听函数。 | |
onPageNotFound | function | 否 | 页面不存在监听函数。 | |
其他 | any | 否 | 开发者可以添加任意的函数或数据变量到 Object 参数中,用 this 可以访问 |
onLaunch(Object object)
小程序初始化完成时触发,全局只触发一次。参数也可以使用 wx.getLaunchOptionsSync 获取。
参数:与 wx.getLaunchOptionsSync 一致
onShow(Object object)
小程序启动,或从后台进入前台显示时触发。也可以使用 wx.onAppShow 绑定监听。
参数:与 wx.onAppShow 一致
onHide()
小程序从前台进入后台时触发。也可以使用 wx.onAppHide 绑定监听。
onError(String error)
小程序发生脚本错误或 API 调用报错时触发。也可以使用 wx.onError 绑定监听。
参数:与 wx.onError 一致
onPageNotFound(Object object)
基础库 1.9.90 开始支持,低版本需做兼容处理。
小程序要打开的页面不存在时触发。也可以使用 wx.onPageNotFound 绑定监听。注意事项请参考 wx.onPageNotFound。
参数:与 wx.onPageNotFound 一致
示例代码:
App({
onPageNotFound(res) {
wx.redirectTo({
url: 'pages/...'
}) // 如果是 tabbar 页面,请使用 wx.switchTab
}
})
(6)小程序页面构成
接下来我们简单看看小程序的一个页面是怎么写的。
你可以观察到 pages/logs/logs
下其实是包括了4种文件的,微信客户端会先根据 logs.json
配置生成一个界面,顶部的颜色和文字你都可以在这个 json
文件里边定义好。紧接着客户端就会装载这个页面的 WXML
结构和 WXSS
样式。最后客户端会装载 logs.js
顺序:【.json配置页面基本样式】==>【.wxml装载结构】==>【.wxss装载样式】==>【.js渲染绑定数据】
你可以看到 logs.js
的大体内容就是:
Page({ data: { // 参与页面渲染的数据 logs: [] }, onLoad: function () { // 页面渲染后 执行 } })
Page
是一个页面构造器,这个构造器就生成了一个页面。在生成页面的时候,小程序框架会把 data
数据和 index.wxml
一起渲染出最终的结构,于是就得到了你看到的小程序的样子。在渲染完界面之后,页面实例就会收到一个 onLoad
的回调,你可以在这个回调处理你的逻辑。有关于 Page
构造器更多详细的文档参考 注册页面 Page 。
(7)注册页面
对于小程序中的每个页面,都需要在页面对应的 js 文件中调用 Page 方法注册页面示例,指定页面的初始数据、生命周期回调、事件处理函数等。详细的参数含义和使用请参考 Page 参考文档 。
Page(Object object)参考文档:
注册小程序中的一个页面。接受一个 Object 类型参数,其指定页面的初始数据、生命周期回调、事件处理函数等。
参数:Object object
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
data | Object | 页面的初始数据 | ||
onLoad | function | 生命周期回调—监听页面加载 | ||
onShow | function | 生命周期回调—监听页面显示 | ||
onReady | function | 生命周期回调—监听页面初次渲染完成 | ||
onHide | function | 生命周期回调—监听页面隐藏 | ||
onUnload | function | 生命周期回调—监听页面卸载 | ||
onPullDownRefresh | function | 监听用户下拉动作 | ||
onReachBottom | function | 页面上拉触底事件的处理函数 | ||
onShareAppMessage | function | 用户点击右上角转发 | ||
onPageScroll | function | 页面滚动触发事件的处理函数 | ||
onResize | function | 页面尺寸改变时触发,详见 响应显示区域变化 | ||
onTabItemTap | function | 当前是 tab 页时,点击 tab 时触发 | ||
其他 | any | 开发者可以添加任意的函数或数据到 Object 参数中,在页面的函数中用 this 可以访问 |
实例代码:
//index.js Page({
/*页面第一次渲染使用的初始数据*/ data: { text: "This is page data." },
/*页面加载时触发。一个页面只会调用一次,可以在 onLoad 的参数中获取打开当前页面路径中的参数。*/ onLoad: function(options) { // Do some initialize when page load. },
/*页面初次渲染完成时触发。一个页面只会调用一次,代表页面已经准备妥当,可以和视图层进行交互。*/ onReady: function() { // Do something when page ready. },
/*页面显示/切入前台时触发*/ onShow: function() { // Do something when page show. },
/*页面隐藏/切入后台时触发。 如 wx.navigateTo 或底部tab
切换到其他页面,小程序切入后台等*/ onHide: function() { // Do something when page hide. },
/*页面卸载时触发。如wx.redirectTo或wx.navigateBack到其他页面时*/ onUnload: function() { // Do something when page close. },
/*监听用户下拉刷新事件*/ onPullDownRefresh: function() { // Do something when pull down. },
/*监听用户上拉触底事件*/ onReachBottom: function() { // Do something when page reach bottom. },
/*监听用户点击页面内转发按钮(button 组件open-type="share"
)或右上角菜单“转发”按钮的行为,并自定义转发内容*/ onShareAppMessage: function () { // return custom share data when user share. },
/*监听用户滑动页面事件*/ onPageScroll: function() { // Do something when page scroll },
/*小程序屏幕旋转时触发*/ onResize: function() { // Do something when page resize },
/*点击 tab 时触发*/ onTabItemTap(item) { console.log(item.index) console.log(item.pagePath) console.log(item.text) },
/*事件处理程序*/ // Event handler. viewTap: function() { this.setData({ text: 'Set some data for updating view.' }, function() { // this is setData callback }) },
/*自定义数据*/ customData: { hi: 'MINA' } })
(8)参数即回调函数详解
data 是页面第一次渲染使用的初始数据。页面加载时,data 将会以JSON字符串的形式由逻辑层传至渲染层,因此data中的数据必须是可以转成JSON的类型:字符串,数字,布尔值,对象,数组。渲染层可以通过 WXML 对数据进行绑定。
<view>{{text}}</view> <view>{{array[0].msg}}</view> Page({ data: { text: 'init data', array: [{msg: '1'}, {msg: '2'}] } })
(9)组件
小程序提供了丰富的基础组件给开发者,开发者可以像搭积木一样,组合各种组件拼合成自己的小程序。就像 HTML 的 div, p 等标签一样,在小程序里边,你只需要在 WXML 写上对应的组件标签名字就可以把该组件显示在界面上,例如,你需要在界面上显示地图,你只需要这样写即可:
<map></map>
使用组件的时候,还可以通过属性传递值给组件,让组件可以以不同的状态去展现,例如,我们希望地图一开始的中心的经纬度是广州,那么你需要声明地图的 longitude(中心经度) 和 latitude(中心纬度)两个属性:
<map longitude="广州经度" latitude="广州纬度"></map>
组件的内部行为也会通过事件的形式让开发者可以感知,例如用户点击了地图上的某个标记,你可以在 js 编写 markertap 函数来处理:
<map bindmarkertap="markertap" longitude="广州经度" latitude="广州纬度"></map>
当然你也可以通过 style
或者 class
来控制组件的外层样式,以便适应你的界面宽度高度等等。更多的组件可以参考 小程序的组件。
(10)API
为了让开发者可以很方便的调起微信提供的能力,例如获取用户信息、微信支付等等,小程序提供了很多 API 给开发者去使用。
①要获取用户的地理位置时,只需要:
onReady:function(){ wx.getLocation({ type: 'wgs84', success: (res) => { var latitude = res.latitude // 纬度 var longitude = res.longitude // 经度 console.log('经度' + longitude + ',纬度' + latitude) } }) }
此时会提示需要设置permission字段
②调用微信扫一扫能力,只需要:
<button bindtap="getewm">扫一扫</button> getewm:function(){ wx.scanCode({ success: (res) => { console.log(res) } }) }
扫描后返回的对象中便包含“复仇者联盟”。
需要注意的是:多数 API 的回调都是异步,你需要处理好代码逻辑的异步问题。更多的 API 能力见 小程序的API。通过这个章节已经大概了解了小程序运行的一些基本概念,当你开发完一个小程序之后,你需要发布你的小程序。之后章节,你会知道发布前需要做什么准备。
(11)API
小程序开发框架提供丰富的微信原生 API,可以方便的调起微信提供的能力,如获取用户信息,本地存储,支付功能等。通常,在小程序 API 有以下几种类型:
①事件监听 API
小程序规定:以 on 开头的 API 用于监听某个事件是否触发,如:wx.onSocketOpen,wx.onCompassChange 等。这类 API 接受一个回调函数作为参数,当事件触发时会调用这个回调函数,并将相关数据以参数形式传入。
wx.onCompassChange(function (res) {
console.log(res.direction)
})
②同步 API
以 Sync 结尾的 API 都是同步 API, 如 wx.setStorageSync,wx.getSystemInfoSync 等。此外,也有一些其他的同步 API,如 wx.createWorker,wx.getBackgroundAudioManager 等。同步 API 的执行结果可以通过函数返回值直接获取,如果执行出错会抛出异常。
try { wx.setStorageSync('key', 'value') } catch (e) { console.error(e) }
③异步 API
大多数 API 都是异步 API,如 wx.request,wx.login 等。这类 API 接口通常都接受一个 Object 类型的参数,这个参数都支持按需指定以下字段来接收接口调用结果:
Object参数说明:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
success | function | 否 | 接口调用成功的回调函数 |
fail | function | 否 | 接口调用失败的回调函数 |
complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
其他 | Any | - | 接口定义的其他参数 |
回调函数的参数
success
,fail
,complete
函数调用时会传入一个 Object
类型参数,包含以下字段:
属性 | 类型 | 说明 |
---|---|---|
errMsg | string | 错误信息,如果调用成功返回 ${apiName}:ok |
errCode | number | 错误码,仅部分 API 支持,具体含义请参考对应 API 文档,成功时为 0 。 |
其他 | Any | 接口返回的其他数据 |
异步 API 的执行结果需要通过 Object
类型的参数中传入的对应回调函数获取。部分异步 API 也会有返回值,可以用来实现更丰富的功能,如 wx.request,wx.connectSocket 等。
wx.login({
success(res) {
console.log(res.code)
}
})
..