小程序开发框架的逻辑层由 Javascript 编写。逻辑层将数据进行处理后发送给视图层,同时接受视图层的事件反馈。
注册程序App
App()
函数用来注册一个小程序。接受一个 object 参数,其指定小程序的生命周期函数等。
object参数说明:
属性 | 类型 | 描述 | 触发时机 |
---|---|---|---|
onLaunch | Function | 生命周期函数--监听小程序初始化 | 当小程序初始化完成时,会触发 onLaunch(全局只触发一次) |
onShow | Function | 生命周期函数--监听小程序显示 | 当小程序启动,或从后台进入前台显示,会触发 onShow |
onHide | Function | 生命周期函数--监听小程序隐藏 | 当小程序从前台进入后台,会触发 onHide |
onError | Function | 错误监听函数 | 当小程序发生脚本错误,或 api 调用失败时,会触发 onError 并带上错误信息 |
其他 | Any | 开发者可以添加任意的函数或数据到 Object 参数中,用 this 可以访问 |
前台、后台定义: 当用户点击左上角关闭,或者按了设备 Home 键离开微信,小程序并没有直接销毁,而是进入了后台;当再次进入微信或再次打开小程序,又会从后台进入前台。需要注意的是:只有当小程序进入后台一定时间,或者系统资源占用过高,才会被真正的销毁。
关闭小程序(基础库版本1.1.0开始支持): 当用户从扫一扫、转发等入口(场景值为1007, 1008, 1011, 1025)进入小程序,且没有置顶小程序的情况下退出,小程序会被销毁。小程序运行机制在基础库版本 1.4.0 有所改变: 上一条关闭逻辑在新版本已不适用。
运行机制 小程序启动会有两种情况,一种是「冷启动」,一种是「热启动」。 假如用户已经打开过某小程序,然后在一定时间内再次打开该小程序,此时无需重新启动,只需将后台态的小程序切换到前台,这个过程就是热启动;冷启动指的是用户首次打开或小程序被微信主动销毁后再次打开的情况,此时小程序需要重新加载启动。 更新机制小程序冷启动时如果发现有新版本,将会异步下载新版本的代码包,并同时用客户端本地的包进行启动,即新版本的小程序需要等下一次冷启动才会应用上。 运行机制
再次打开逻辑
用户打开小程序的预期有以下两类场景: A. 打开首页: 场景值有 1001, 1019, 1022, 1023, 1038, 1056 B. 打开小程序指定的某个页面: 场景值为除 A 以外的其他 当再次打开一个小程序逻辑如下:
|
示例代码:
App({onLaunch: function(options) {// Do something initial when launch.},onShow: function(options) {// Do something when show.},onHide: function() {// Do something when hide.},onError: function(msg) {console.log(msg)},globalData: 'I am global data'
})
字段 | 类型 | 说明 |
---|---|---|
path | String | 打开小程序的路径 |
query | Object | 打开小程序的query |
scene | Number | 打开小程序的场景值 |
shareTicket | String | shareTicket |
referrerInfo | Object | 当场景为由从另一个小程序或公众号或App打开时,返回此字段 |
referrerInfo.appId | String | 来源小程序或公众号或App的 appId |
referrerInfo.extraData | Object | 来源小程序传过来的数据,scene=1037或1038时支持 |
shareTicket获取更多转发信息通常开发者希望转发出去的小程序被二次打开的时候能够获取到一些信息,例如群的标识。现在通过调 |
以下场景支持返回 referrerInfo.appId:
场景值 | 场景 | appId 信息含义 |
---|---|---|
1020 | 公众号 profile 页相关小程序列表 | 返回来源公众号 appId |
1035 | 公众号自定义菜单 | 返回来源公众号 appId |
1036 | App 分享消息卡片 | 返回来源应用 appId |
1037 | 小程序打开小程序 | 返回来源小程序 appId |
1038 | 从另一个小程序返回 | 返回来源小程序 appId |
1043 | 公众号模板消息 | 返回来源公众号 appId |
全局的 getApp()
函数可以用来获取到小程序实例。
// other.js
var appInstance = getApp()
console.log(appInstance.globalData) // I am global data
注意:
App()
必须在 app.js
中注册,且不能注册多个。App()
内的函数中调用 getApp()
,使用 this
就可以拿到 app 实例。getCurrentPages()
,此时 page 还没有生成。getApp()
获取实例之后,不要私自调用生命周期函数。基础库 1.1.0 开始支持,低版本需做兼容处理
当前支持的场景值有:
场景值ID | 说明 |
---|---|
1001 | 发现栏小程序主入口 |
1005 | 顶部搜索框的搜索结果页 |
1006 | 发现栏小程序主入口搜索框的搜索结果页 |
1007 | 单人聊天会话中的小程序消息卡片 |
1008 | 群聊会话中的小程序消息卡片 |
1011 | 扫描二维码 |
1012 | 长按图片识别二维码 |
1013 | 手机相册选取二维码 |
1014 | 小程序模版消息 |
1017 | 前往体验版的入口页 |
1019 | 微信钱包 |
1020 | 公众号 profile 页相关小程序列表 |
1022 | 聊天顶部置顶小程序入口 |
1023 | 安卓系统桌面图标 |
1024 | 小程序 profile 页 |
1025 | 扫描一维码 |
1026 | 附近小程序列表 |
1027 | 顶部搜索框搜索结果页“使用过的小程序”列表 |
1028 | 我的卡包 |
1029 | 卡券详情页 |
1030 | 自动化测试下打开小程序 |
1031 | 长按图片识别一维码 |
1032 | 手机相册选取一维码 |
1034 | 微信支付完成页 |
1035 | 公众号自定义菜单 |
1036 | App 分享消息卡片 |
1037 | 小程序打开小程序 |
1038 | 从另一个小程序返回 |
1039 | 摇电视 |
1042 | 添加好友搜索框的搜索结果页 |
1043 | 公众号模板消息 |
1044 | 带 shareTicket 的小程序消息卡片 |
1047 | 扫描小程序码 |
1048 | 长按图片识别小程序码 |
1049 | 手机相册选取小程序码 |
1052 | 卡券的适用门店列表 |
1053 | 搜一搜的结果页 |
1054 | 顶部搜索框小程序快捷入口 |
1056 | 音乐播放器菜单 |
1057 | 钱包中的银行卡详情页 |
1058 | 公众号文章 |
1059 | 体验版小程序绑定邀请页 |
1064 | 微信连Wi-Fi状态栏 |
1067 | 公众号文章广告 |
1068 | 附近小程序列表广告 |
1071 | 钱包中的银行卡列表页 |
1072 | 二维码收款页面 |
1073 | 客服消息列表下发的小程序消息卡片 |
1074 | 公众号会话下发的小程序消息卡片 |
1078 | 连Wi-Fi成功页 |
1089 | 微信聊天主界面下拉 |
1090 | 长按小程序右上角菜单唤出最近使用历史 |
1092 | 城市服务入口 |
可以在 App 的 onlaunch 和 onshow 中获取上述场景值,部分场景值下还可以获取来源应用、公众号或小程序的appId。详见
Tip: 由于Android系统限制,目前还无法获取到按 Home 键退出到桌面,然后从桌面再次进小程序的场景值,对于这种情况,会保留上一次的场景值。
注册页面PagePage()
函数用来注册一个页面。接受一个 object 参数,其指定页面的初始数据、生命周期函数、事件处理函数等。
object 参数说明:
属性 | 类型 | 描述 |
---|---|---|
data | Object | 页面的初始数据 |
onLoad | Function | 生命周期函数--监听页面加载 |
onReady | Function | 生命周期函数--监听页面初次渲染完成 |
onShow | Function | 生命周期函数--监听页面显示 |
onHide | Function | 生命周期函数--监听页面隐藏 |
onUnload | Function | 生命周期函数--监听页面卸载 |
onPullDownRefresh | Function | 页面相关事件处理函数--监听用户下拉动作 |
onReachBottom | Function | 页面上拉触底事件的处理函数 |
onShareAppMessage | Function | 用户点击右上角转发 |
onPageScroll | Function | 页面滚动触发事件的处理函数 |
onTabItemTap | Function | 当前是 tab 页时,点击 tab 时触发 |
其他 | Any | 开发者可以添加任意的函数或数据到 object 参数中,在页面的函数中用 this 可以访问 |
object 内容在页面加载时会进行一次深拷贝,需考虑数据大小对页面加载的开销
示例代码:
//index.js
Page({data: {text: "This is page data."},onLoad: function(options) {// Do some initialize when page load.},onReady: function() {// Do something when page ready.},onShow: function() {// Do something when page show.},onHide: function() {// Do something when page hide.},onUnload: function() {// Do something when page close.},onPullDownRefresh: function() {// Do something when pull down.},onReachBottom: function() {// Do something when page reach bottom.},onShareAppMessage: function () {// return custom share data when user share.},onPageScroll: function() {// Do something when page scroll},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'}
})
初始化数据将作为页面的第一次渲染。data 将会以 JSON 的形式由逻辑层传至渲染层,所以其数据必须是可以转成 JSON 的格式:字符串,数字,布尔值,对象,数组。
渲染层可以通过 WXML 对数据进行绑定。
示例代码:
<view>{{text}}view>
<view>{{array[0].msg}}view>
Page({data: {text: &#39;init data&#39;,array: [{msg: &#39;1&#39;}, {msg: &#39;2&#39;}]}
})
onLoad
: 页面加载
onShow
: 页面显示
onReady
: 页面初次渲染完成
wx.setNavigationBarTitle
请在onReady
之后设置。onHide
: 页面隐藏
navigateTo
或底部tab
切换时调用。onUnload
: 页面卸载
redirectTo
或navigateBack
的时候调用。onLoad参数
类型 | 说明 |
---|---|
Object | 其他页面打开当前页面所调用的 query 参数 |
onPullDownRefresh
: 下拉刷新
app.json
的window
选项中或页面配置中开启enablePullDownRefresh
。wx.stopPullDownRefresh
可以停止当前页面的下拉刷新。onReachBottom
: 上拉触底
app.json
的window
选项中或页面配置中设置触发距离onReachBottomDistance
。onPageScroll
: 页面滚动
字段 | 类型 | 说明 |
---|---|---|
scrollTop | Number | 页面在垂直方向已滚动的距离&#xff08;单位px&#xff09; |
onShareAppMessage
: 用户转发自定义转发字段
字段 | 说明 | 默认值 |
---|---|---|
title | 转发标题 | 当前小程序名称 |
path | 转发路径 | 当前页面 path &#xff0c;必须是以 / 开头的完整路径 |
示例代码
Page({onShareAppMessage: function () {return {title: &#39;自定义转发标题&#39;,path: &#39;/page/user?id&#61;123&#39;}}
})
除了初始化数据和生命周期函数&#xff0c;Page 中还可以定义一些特殊的函数&#xff1a;事件处理函数。在渲染层可以在组件中加入事件绑定&#xff0c;当达到触发事件时&#xff0c;就会执行 Page 中定义的事件处理函数。
示例代码&#xff1a;
<view bindtap&#61;"viewTap"> click me view>
Page({viewTap: function() {console.log(&#39;view tap&#39;)}
})
route
字段可以获取到当前页面的路径。
setData
函数用于将数据从逻辑层发送到视图层&#xff08;异步&#xff09;&#xff0c;同时改变对应的 this.data
的值&#xff08;同步&#xff09;。
字段 | 类型 | 必填 | 描述 | 最低版本 |
---|---|---|---|---|
data | Object | 是 | 这次要改变的数据 | |
callback | Function | 否 | 回调函数 | 1.5.0 |
object 以 key&#xff0c;value 的形式表示将 this.data 中的 key 对应的值改变成 value。 callback 是一个回调函数&#xff0c;在这次setData对界面渲染完毕后调用。
其中 key 可以非常灵活&#xff0c;以数据路径的形式给出&#xff0c;如 array[2].message
&#xff0c;a.b.c.d
&#xff0c;并且不需要在 this.data 中预先定义。
注意&#xff1a;
undefined
&#xff0c;否则这一项将不被设置并可能遗留一些潜在问题。示例代码&#xff1a;
//index.js
Page({data: {text: &#39;init data&#39;,num: 0,array: [{text: &#39;init data&#39;}],object: {text: &#39;init data&#39;}},changeText: function() {// this.data.text &#61; &#39;changed data&#39; // bad, it can not workthis.setData({text: &#39;changed data&#39;})},changeNum: function() {this.data.num &#61; 1this.setData({num: this.data.num})},changeItemInArray: function() {// you can use this way to modify a danamic data paththis.setData({&#39;array[0].text&#39;:&#39;changed data&#39;})},changeItemInObject: function(){this.setData({&#39;object.text&#39;: &#39;changed data&#39;});},addNewField: function() {this.setData({&#39;newField.text&#39;: &#39;new data&#39;})}
})
生命周期
下图说明了 Page 实例的生命周期。
页面路由框架以栈的形式维护了当前的所有页面。 当发生路由切换的时候&#xff0c;页面栈的表现如下&#xff1a;
路由方式 | 页面栈表现 |
---|---|
初始化 | 新页面入栈 |
打开新页面 | 新页面入栈 |
页面重定向 | 当前页面出栈&#xff0c;新页面入栈 |
页面返回 | 页面不断出栈&#xff0c;直到目标返回页&#xff0c;新页面入栈 |
Tab 切换 | 页面全部出栈&#xff0c;只留下新的 Tab 页面 |
重加载 | 页面全部出栈&#xff0c;只留下新的页面 |
getCurrentPages()
函数用于获取当前页面栈的实例&#xff0c;以数组形式按栈的顺序给出&#xff0c;第一个元素为首页&#xff0c;最后一个元素为当前页面。
Tip&#xff1a;不要尝试修改页面栈&#xff0c;会导致路由以及页面状态错误。
对于路由的触发方式以及页面生命周期函数如下&#xff1a;
路由方式 | 触发时机 | 路由前页面 | 路由后页面 |
---|---|---|---|
初始化 | 小程序打开的第一个页面 | onLoad, onShow | |
打开新页面 | 调用 API wx.navigateTo 或使用组件
| onHide | onLoad, onShow |
页面重定向 | 调用 API wx.redirectTo 或使用组件
| onUnload | onLoad, onShow |
页面返回 | 调用 API wx.navigateBack 或使用组件 或用户按左上角返回按钮 | onUnload | onShow |
Tab 切换 | 调用 API wx.switchTab 或使用组件 或用户切换 Tab | 各种情况请参考下表 | |
重启动 | 调用 API wx.reLaunch 或使用组件
| onUnload | onLoad, onShow |
Tab 切换对应的生命周期&#xff08;以 A、B 页面为 Tabbar 页面&#xff0c;C 是从 A 页面打开的页面&#xff0c;D 页面是从 C 页面打开的页面为例&#xff09;&#xff1a;
当前页面 | 路由后页面 | 触发的生命周期&#xff08;按顺序&#xff09; |
---|---|---|
A | A | Nothing happend |
A | B | A.onHide(), B.onLoad(), B.onShow() |
A | B&#xff08;再次打开&#xff09; | A.onHide(), B.onShow() |
C | A | C.onUnload(), A.onShow() |
C | B | C.onUnload(), B.onLoad(), B.onShow() |
D | B | D.onUnload(), C.onUnload(), B.onLoad(), B.onShow() |
D&#xff08;从转发进入&#xff09; | A | D.onUnload(), A.onLoad(), A.onShow() |
D&#xff08;从转发进入&#xff09; | B | D.onUnload(), B.onLoad(), B.onShow() |
Tips:
navigateTo
, redirectTo
只能打开非 tabBar 页面。switchTab
只能打开 tabBar 页面。reLaunch
可以打开任意页面。onLoad
中获取。在 Javascript 文件中声明的变量和函数只在该文件中有效&#xff1b;不同的文件中可以声明相同名字的变量和函数&#xff0c;不会互相影响。
通过全局函数 getApp()
可以获取全局的应用实例&#xff0c;如果需要全局的数据可以在 App()
中设置&#xff0c;如&#xff1a;
// app.js
App({globalData: 1
})
// a.js
// The localValue can only be used in file a.js.
var localValue &#61; &#39;a&#39;
// Get the app instance.
var app &#61; getApp()
// Get the global data and change it.
app.globalData&#43;&#43;
// b.js
// You can redefine localValue in file b.js, without interference with the localValue in a.js.
var localValue &#61; &#39;b&#39;
// If a.js it run before b.js, now the globalData shoule be 2.
console.log(getApp().globalData)
可以将一些公共的代码抽离成为一个单独的 js 文件&#xff0c;作为一个模块。模块只有通过 module.exports
或者 exports
才能对外暴露接口。
需要注意的是&#xff1a;
exports
是 module.exports
的一个引用&#xff0c;因此在模块里边随意更改 exports
的指向会造成未知的错误。所以更推荐开发者采用 module.exports
来暴露模块接口&#xff0c;除非你已经清晰知道这两者的关系。node_modules
, 开发者需要使用到 node_modules
时候建议拷贝出相关的代码到小程序的目录中。// common.js
function sayHello(name) {console.log(&#96;Hello ${name} !&#96;)
}
function sayGoodbye(name) {console.log(&#96;Goodbye ${name} !&#96;)
}module.exports.sayHello &#61; sayHello
exports.sayGoodbye &#61; sayGoodbye
在需要使用这些模块的文件中&#xff0c;使用 require(path)
将公共代码引入
var common &#61; require(&#39;common.js&#39;)
Page({helloMINA: function() {common.sayHello(&#39;MINA&#39;)},goodbyeMINA: function() {common.sayGoodbye(&#39;MINA&#39;)}
})
tip
: require 暂时不支持绝对路径