上一章节,简单学习了一下文档里的 简易教程
从这一章节开始,分4步,来学习官方文档中剩余的4个部分:
框架
组件
API
工具
首先,学习一下官方文档 中的框架介绍
框架
小程序开发框架的目标是通过尽可能简单、高效的方式让开发者可以在微信中开发具有原生 APP 体验的服务。
框架提供了自己的视图层描述语言 WXML 和 WXSS,以及基于 JavaScript 的逻辑层框架,并在视图层与逻辑层间提供了数据传输和事件系统,可以让开发者可以方便的聚焦于数据与逻辑上。
响应的数据绑定
框架的核心是一个响应的数据绑定系统。
整个系统分为两块视图层(View)和逻辑层(App Service)
框架可以让数据与视图非常简单地保持同步。当做数据修改的时候,只需要在逻辑层修改数据,视图层就会做相应的更新。
通过这个简单的例子来看:
在开发者工具中预览效果
<!-- This is our View -->
<view> Hello {{name}}! </view>
<button bindtap="changeName"> Click me! </button>
// This is our App Service.
// This is our data.
var helloData = {
name: 'WeChat'
}
// Register a Page.
Page({
data: helloData,
changeName: function(e) {
// sent data change to view
this.setData({
name: 'MINA'
})
}
})
- 开发者通过框架将逻辑层数据中的
name
与视图层的name
进行了绑定,所以在页面一打开的时候会显示Hello WeChat!
- 当点击按钮的时候,视图层会发送
changeName
的事件给逻辑层,逻辑层找到对应的事件处理函数 - 逻辑层执行了
setData
的操作,将 name 从WeChat
变为MINA
,因为该数据和视图层已经绑定了,从而视图层会自动改变为Hello MINA!
。
页面管理
框架 管理了整个小程序的页面路由,可以做到页面间的无缝切换,并给以页面完整的生命周期。开发者需要做的只是将页面的数据,方法,生命周期函数注册进 框架 中,其他的一切复杂的操作都交由 框架 处理。
基础组件
框架 提供了一套基础的组件,这些组件自带微信风格的样式以及特殊的逻辑,开发者可以通过组合基础组件,创建出强大的微信小程序 。
丰富的 API
框架 提供丰富的微信原生 API,可以方便的调起微信提供的能力,如获取用户信息,本地存储,支付功能等。
文件结构
小程序包含一个描述整体程序的 app 和多个描述各自页面的 page。
一个小程序主体部分由三个文件组成,必须放在项目的根目录,如下:
文件 | 必填 | 作用 |
---|---|---|
app.js | 是 | 小程序逻辑 |
app.json | 是 | 小程序公共设置 |
app.wxss | 否 | 小程序公共样式表 |
一个小程序页面由四个文件组成,分别是:
文件类型 | 必填 | 作用 |
---|---|---|
js | 是 | 页面逻辑 |
wxml | 是 | 页面结构 |
wxss | 否 | 页面样式表 |
json | 否 | 页面配置 |
注意:为了方便开发者减少配置项,描述页面的四个文件必须具有相同的路径与文件名。
配置
app.json
文件用来对微信小程序进行全局配置,决定页面文件的路径、窗口表现、设置网络超时时间、设置多 tab 等。
以下是一个包含了所有配置选项的 app.json
:
{
"pages": [
"pages/index/index",
"pages/logs/index"
],
"window": {
"navigationBarTitleText": "Demo"
},
"tabBar": {
"list": [{
"pagePath": "pages/index/index",
"text": "首页"
}, {
"pagePath": "pages/logs/logs",
"text": "日志"
}]
},
"networkTimeout": {
"request": 10000,
"downloadFile": 10000
},
"debug": true
}
app.json 配置项列表
属性 | 类型 | 必填 | 描述 |
---|---|---|---|
pages | String Array | 是 | 设置页面路径 |
window | Object | 否 | 设置默认页面的窗口表现 |
tabBar | Object | 否 | 设置底部 tab 的表现 |
networkTimeout | Object | 否 | 设置网络超时时间 |
debug | Boolean | 否 | 设置是否开启 debug 模式 |
pages
接受一个数组,每一项都是字符串,来指定小程序由哪些页面组成。每一项代表对应页面的【路径+文件名】信息,数组的第一项代表小程序的初始页面。小程序中新增/减少页面,都需要对 pages 数组进行修改。
文件名不需要写文件后缀,因为框架会自动去寻找路径下 .json
, .js
, .wxml
, .wxss
四个文件进行整合。
如开发目录为:
pages/
pages/index/index.wxml
pages/index/index.js
pages/index/index.wxss
pages/logs/logs.wxml
pages/logs/logs.js
app.js
app.json
app.wxss
则需要在 app.json 中写
{
"pages":[
"pages/index/index",
"pages/logs/logs"
]
}
window
用于设置小程序的状态栏、导航条、标题、窗口背景色。
属性 | 类型 | 默认值 | 描述 | 最低版本 |
---|---|---|---|---|
navigationBarBackgroundColor | HexColor | #000000 | 导航栏背景颜色,如"#000000" | |
navigationBarTextStyle | String | white | 导航栏标题颜色,仅支持 black/white | |
navigationBarTitleText | String | 导航栏标题文字内容 | ||
navigationStyle | String | default | 导航栏样式,仅支持 default/custom。custom 模式可自定义导航栏,只保留右上角胶囊状的按钮 | 微信版本 6.6.0 |
backgroundColor | HexColor | #ffffff | 窗口的背景色 | |
backgroundTextStyle | String | dark | 下拉 loading 的样式,仅支持 dark/light | |
backgroundColorTop | String | #ffffff | 顶部窗口的背景色,仅 iOS 支持 | 微信版本 6.5.16 |
backgroundColorBottom | String | #ffffff | 底部窗口的背景色,仅 iOS 支持 | 微信版本 6.5.16 |
enablePullDownRefresh | Boolean | false | 是否开启下拉刷新,详见页面相关事件处理函数 | |
onReachBottomDistance | Number | 50 | 页面上拉触底事件触发时距页面底部距离,单位为px |
注:HexColor(十六进制颜色值),如"#ff00ff"
注:navigationStyle 只在 app.json 中生效。开启 custom 后,低版本客户端需要做好兼容。开发者工具基础库版本切到 1.7.0(不代表最低版本,只供调试用) 可方便切到旧视觉
如 app.json :
{
"window":{
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black",
"navigationBarTitleText": "微信接口功能演示",
"backgroundColor": "#eeeeee",
"backgroundTextStyle": "light"
}
}
tabBar
如果小程序是一个多 tab 应用(客户端窗口的底部或顶部有 tab 栏可以切换页面),可以通过 tabBar 配置项指定 tab 栏的表现,以及 tab 切换时显示的对应页面。
Tip:
- 当设置 position 为 top 时,将不会显示 icon
- tabBar 中的 list 是一个数组,只能配置最少2个、最多5个 tab,tab 按数组的顺序排序。
属性说明:
属性 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
color | HexColor | 是 | tab 上的文字默认颜色 | |
selectedColor | HexColor | 是 | tab 上的文字选中时的颜色 | |
backgroundColor | HexColor | 是 | tab 的背景色 | |
borderStyle | String | 否 | black | tabbar上边框的颜色, 仅支持 black/white |
list | Array | 是 | tab 的列表,详见 list 属性说明,最少2个、最多5个 tab | |
position | String | 否 | bottom | 可选值 bottom、top |
其中 list 接受一个数组,数组中的每个项都是一个对象,其属性值如下:
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
pagePath | String | 是 | 页面路径,必须在 pages 中先定义 |
text | String | 是 | tab 上按钮文字 |
iconPath | String | 否 | 图片路径,icon 大小限制为40kb,建议尺寸为 81px * 81px,当 postion 为 top 时,此参数无效,不支持网络图片 |
selectedIconPath | String | 否 | 选中时的图片路径,icon 大小限制为40kb,建议尺寸为 81px * 81px ,当 postion 为 top 时,此参数无效 |
networkTimeout
可以设置各种网络请求的超时时间。
属性说明:
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
request | Number | 否 | wx.request的超时时间,单位毫秒,默认为:60000 |
connectSocket | Number | 否 | wx.connectSocket的超时时间,单位毫秒,默认为:60000 |
uploadFile | Number | 否 | wx.uploadFile的超时时间,单位毫秒,默认为:60000 |
downloadFile | Number | 否 | wx.downloadFile的超时时间,单位毫秒,默认为:60000 |
debug
可以在开发者工具中开启 debug 模式,在开发者工具的控制台面板,调试信息以 info 的形式给出,其信息有Page的注册
,页面路由
,数据更新
,事件触发
。 可以帮助开发者快速定位一些常见的问题。
page.json
每一个小程序页面也可以使用.json
文件来对本页面的窗口表现进行配置。 页面的配置比app.json
全局配置简单得多,只是设置 app.json 中的 window 配置项的内容,页面中配置项会覆盖 app.json 的 window 中相同的配置项。
页面的.json
只能设置 window
相关的配置项,以决定本页面的窗口表现,所以无需写 window
这个键,如:
属性 | 类型 | 默认值 | 描述 | |
---|---|---|---|---|
navigationBarBackgroundColor | HexColor | #000000 | 导航栏背景颜色,如"#000000" | |
navigationBarTextStyle | String | white | 导航栏标题颜色,仅支持 black/white | |
navigationBarTitleText | String | 导航栏标题文字内容 | ||
backgroundColor | HexColor | #ffffff | 窗口的背景色 | |
backgroundTextStyle | String | dark | 下拉 loading 的样式,仅支持 dark/light | |
enablePullDownRefresh | Boolean | false | 是否开启下拉刷新,详见页面相关事件处理函数。 | |
disableScroll | Boolean | false | 设置为 true 则页面整体不能上下滚动;只在 page.json 中有效,无法在 app.json 中设置该项 | |
onReachBottomDistance | Number | 50 | 页面上拉触底事件触发时距页面底部距离,单位为px |
{
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black",
"navigationBarTitleText": "微信接口功能演示",
"backgroundColor": "#eeeeee",
"backgroundTextStyle": "light"
}
逻辑层(App Service)
小程序开发框架的逻辑层由 JavaScript 编写。
逻辑层将数据进行处理后发送给视图层,同时接受视图层的事件反馈。
在 JavaScript 的基础上,我们做了一些修改,以方便地开发小程序。
- 增加 App 和 Page 方法,进行程序和页面的注册。
- 增加
getApp
和getCurrentPages
方法,分别用来获取 App 实例和当前页面栈。 - 提供丰富的 API,如微信用户数据,扫一扫,支付等微信特有能力。
- 每个页面有独立的作用域,并提供模块化能力。
- 由于框架并非运行在浏览器中,所以
JavaScript
在 web 中一些能力都无法使用,如document
,window
等。 - 开发者写的所有代码最终将会打包成一份
JavaScript
,并在小程序启动的时候运行,直到小程序销毁。类似 ServiceWorker,所以逻辑层也称之为 App Service。
App
App()
App()
函数用来注册一个小程序。接受一个 object 参数,其指定小程序的生命周期函数等。
object参数说明:
属性 | 类型 | 描述 | 触发时机 |
---|---|---|---|
onLaunch | Function | 生命周期函数--监听小程序初始化 | 当小程序初始化完成时,会触发 onLaunch(全局只触发一次) |
onShow | Function | 生命周期函数--监听小程序显示 | 当小程序启动,或从后台进入前台显示,会触发 onShow |
onHide | Function | 生命周期函数--监听小程序隐藏 | 当小程序从前台进入后台,会触发 onHide |
onError | Function | 错误监听函数 | 当小程序发生脚本错误,或者 api 调用失败时,会触发 onError 并带上错误信息 |
onPageNotFound | Function | 页面不存在监听函数 | 当小程序出现要打开的页面不存在的情况,会带上页面信息回调该函数,详见下文 |
其他 | Any | 开发者可以添加任意的函数或数据到 Object 参数中,用 this 可以访问 |
前台、后台定义: 当用户点击左上角关闭,或者按了设备 Home 键离开微信,小程序并没有直接销毁,而是进入了后台;当再次进入微信或再次打开小程序,又会从后台进入前台。需要注意的是:只有当小程序进入后台一定时间,或者系统资源占用过高,才会被真正的销毁。
关闭小程序(基础库版本1.1.0开始支持): 当用户从扫一扫、转发等入口(场景值为1007, 1008, 1011, 1025)进入小程序,且没有置顶小程序的情况下退出,小程序会被销毁。
小程序运行机制在基础库版本 1.4.0 有所改变: 上一条关闭逻辑在新版本已不适用。详情
示例代码:
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'
})
onLaunch, onShow 参数
字段 | 类型 | 说明 |
---|---|---|
path | String | 打开小程序的路径 |
query | Object | 打开小程序的query |
scene | Number | 打开小程序的场景值 |
shareTicket | String | shareTicket,详见 获取更多转发信息 |
referrerInfo | Object | 当场景为由从另一个小程序或公众号或App打开时,返回此字段 |
referrerInfo.appId | String | 来源小程序或公众号或App的 appId,详见下方说明 |
referrerInfo.extraData | Object | 来源小程序传过来的数据,scene=1037或1038时支持 |
场景值 详见。
以下场景支持返回 referrerInfo.appId:
场景值 | 场景 | appId 信息含义 |
---|---|---|
1020 | 公众号 profile 页相关小程序列表 | 返回来源公众号 appId |
1035 | 公众号自定义菜单 | 返回来源公众号 appId |
1036 | App 分享消息卡片 | 返回来源应用 appId |
1037 | 小程序打开小程序 | 返回来源小程序 appId |
1038 | 从另一个小程序返回 | 返回来源小程序 appId |
1043 | 公众号模板消息 | 返回来源公众号 appId |
onPageNotFound
基础库 1.9.90 开始支持,低版本需做兼容处理
当要打开的页面并不存在时,会回调这个监听器,并带上以下信息:
字段 | 类型 | 说明 |
---|---|---|
path | String | 不存在页面的路径 |
query | Object | 打开不存在页面的 query |
isEntryPage | Boolean | 是否本次启动的首个页面(例如从分享等入口进来,首个页面是开发者配置的分享页面) |
开发者可以在 onPageNotFound
回调中进行重定向处理,但必须在回调中同步处理,异步处理(例如 setTimeout 异步执行)无效。
示例代码:
App({
onPageNotFound(res) {
wx.redirectTo({
url: 'pages/...'
}) // 如果是 tabbar 页面,请使用 wx.switchTab
}
})
注意:
- 如果开发者没有添加
onPageNotFound
监听,当跳转页面不存在时,将推入微信客户端原生的页面不存在提示页面 - 如果
onPageNotFound
回调中又重定向到另一个不存在的页面,将推入微信客户端原生的页面不存在提示页面,并且不在回调onPageNotFound
getApp()
全局的 getApp()
函数可以用来获取到小程序实例。
// other.js
var appInstance = getApp()
console.log(appInstance.globalData) // I am global data
注意:
App()
必须在app.js
中注册,且不能注册多个。- 不要在定义于
App()
内的函数中调用getApp()
,使用this
就可以拿到 app 实例。 - 不要在 onLaunch 的时候调用
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 的小程序消息卡片(详情) |
1045 | 朋友圈广告 |
1047 | 扫描小程序码 |
1048 | 长按图片识别小程序码 |
1049 | 手机相册选取小程序码 |
1052 | 卡券的适用门店列表 |
1053 | 搜一搜的结果页 |
1054 | 顶部搜索框小程序快捷入口 |
1056 | 音乐播放器菜单 |
1057 | 钱包中的银行卡详情页 |
1058 | 公众号文章 |
1059 | 体验版小程序绑定邀请页 |
1064 | 微信连Wi-Fi状态栏 |
1067 | 公众号文章广告 |
1068 | 附近小程序列表广告 |
1069 | 移动应用 |
1071 | 钱包中的银行卡列表页 |
1072 | 二维码收款页面 |
1073 | 客服消息列表下发的小程序消息卡片 |
1074 | 公众号会话下发的小程序消息卡片 |
1077 | 摇周边 |
1078 | 连Wi-Fi成功页 |
1079 | 微信游戏中心 |
1081 | 客服消息下发的文字链 |
1082 | 公众号会话下发的文字链 |
1089 | 微信聊天主界面下拉 |
1090 | 长按小程序右上角菜单唤出最近使用历史 |
1091 | 公众号文章商品卡片 |
1092 | 城市服务入口 |
1095 | 小程序广告组件 |
1096 | 聊天记录 |
1097 | 微信支付签约页 |
可以在 App 的 onlaunch 和 onshow 中获取上述场景值,部分场景值下还可以获取来源应用、公众号或小程序的appId。详见
Tip: 由于Android系统限制,目前还无法获取到按 Home 键退出到桌面,然后从桌面再次进小程序的场景值,对于这种情况,会保留上一次的场景值。
Page
Page()
函数用来注册一个页面。接受一个 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: 'init data',
array: [{msg: '1'}, {msg: '2'}]
}
})
生命周期函数
onLoad
: 页面加载- 一个页面只会调用一次,可以在 onLoad 中获取打开当前页面所调用的 query 参数。
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
: 页面滚动- 监听用户滑动页面事件。
- 参数为 Object,包含以下字段:
字段 | 类型 | 说明 |
---|---|---|
scrollTop | Number | 页面在垂直方向已滚动的距离(单位px) |
onShareAppMessage
: 用户转发- 只有定义了此事件处理函数,右上角菜单才会显示“转发”按钮
- 用户点击转发按钮的时候会调用
- 此事件需要 return 一个 Object,用于自定义转发内容
自定义转发字段
字段 | 说明 | 默认值 |
---|---|---|
title | 转发标题 | 当前小程序名称 |
path | 转发路径 | 当前页面 path ,必须是以 / 开头的完整路径 |
示例代码
在开发者工具中预览效果
Page({
onShareAppMessage: function () {
return {
title: '自定义转发标题',
path: '/page/user?id=123'
}
}
})
事件处理函数
除了初始化数据和生命周期函数,Page 中还可以定义一些特殊的函数:事件处理函数。在渲染层可以在组件中加入事件绑定,当达到触发事件时,就会执行 Page 中定义的事件处理函数。
示例代码:
在开发者工具中预览效果
<view bindtap="viewTap"> click me </view>
Page({
viewTap: function() {
console.log('view tap')
}
})
Page.prototype.route
基础库 1.2.0 开始支持,低版本需做兼容处理
route
字段可以获取到当前页面的路径。
Page.prototype.setData()
setData
函数用于将数据从逻辑层发送到视图层(异步),同时改变对应的 this.data
的值(同步)。
setData() 参数格式
字段 | 类型 | 必填 | 描述 | 最低版本 |
---|---|---|---|---|
data | Object | 是 | 这次要改变的数据 | |
callback | Function | 否 | 回调函数 | 1.5.0 |
object 以 key,value 的形式表示将 this.data 中的 key 对应的值改变成 value。 callback 是一个回调函数,在这次setData对界面渲染完毕后调用。
其中 key 可以非常灵活,以数据路径的形式给出,如 array[2].message
,a.b.c.d
,并且不需要在 this.data 中预先定义。
注意:
- 直接修改 this.data 而不调用 this.setData 是无法改变页面的状态的,还会造成数据不一致。
- 单次设置的数据不能超过1024kB,请尽量避免一次设置过多的数据。
- 请不要把 data 中任何一项的 value 设为
undefined
,否则这一项将不被设置并可能遗留一些潜在问题。
示例代码:
在开发者工具中预览效果
<!--index.wxml-->
<view>{{text}}</view>
<button bindtap="changeText"> Change normal data </button>
<view>{{num}}</view>
<button bindtap="changeNum"> Change normal num </button>
<view>{{array[0].text}}</view>
<button bindtap="changeItemInArray"> Change Array data </button>
<view>{{object.text}}</view>
<button bindtap="changeItemInObject"> Change Object data </button>
<view>{{newField.text}}</view>
<button bindtap="addNewField"> Add new data </button>
//index.js
Page({
data: {
text: 'init data',
num: 0,
array: [{text: 'init data'}],
object: {
text: 'init data'
}
},
changeText: function() {
// this.data.text = 'changed data' // bad, it can not work
this.setData({
text: 'changed data'
})
},
changeNum: function() {
this.data.num = 1
this.setData({
num: this.data.num
})
},
changeItemInArray: function() {
// you can use this way to modify a danamic data path
this.setData({
'array[0].text':'changed data'
})
},
changeItemInObject: function(){
this.setData({
'object.text': 'changed data'
});
},
addNewField: function() {
this.setData({
'newField.text': 'new data'
})
}
})
以下内容你不需要立马完全弄明白,不过以后它会有帮助。
生命周期
下图说明了 Page 实例的生命周期。
页面路由
在小程序中所有页面的路由全部由框架进行管理。
页面栈
框架以栈的形式维护了当前的所有页面。 当发生路由切换的时候,页面栈的表现如下:
路由方式 | 页面栈表现 |
---|---|
初始化 | 新页面入栈 |
打开新页面 | 新页面入栈 |
页面重定向 | 当前页面出栈,新页面入栈 |
页面返回 | 页面不断出栈,直到目标返回页 |
Tab 切换 | 页面全部出栈,只留下新的 Tab 页面 |
重加载 | 页面全部出栈,只留下新的页面 |
getCurrentPages()
getCurrentPages()
函数用于获取当前页面栈的实例,以数组形式按栈的顺序给出,第一个元素为首页,最后一个元素为当前页面。
Tip:不要尝试修改页面栈,会导致路由以及页面状态错误。
路由方式
对于路由的触发方式以及页面生命周期函数如下:
路由方式 | 触发时机 | 路由前页面 | 路由后页面 |
---|---|---|---|
初始化 | 小程序打开的第一个页面 | onLoad, onShow | |
打开新页面 | 调用 API wx.navigateTo 或使用组件 <navigator open-type="navigateTo"/> |
onHide | onLoad, onShow |
页面重定向 | 调用 API wx.redirectTo 或使用组件 <navigator open-type="redirectTo"/> |
onUnload | onLoad, onShow |
页面返回 | 调用 API wx.navigateBack 或使用组件<navigator open-type="navigateBack"> 或用户按左上角返回按钮 |
onUnload | onShow |
Tab 切换 | 调用 API wx.switchTab 或使用组件 <navigator open-type="switchTab"/> 或用户切换 Tab |
各种情况请参考下表 | |
重启动 | 调用 API wx.reLaunch 或使用组件 <navigator open-type="reLaunch"/> |
onUnload | onLoad, onShow |
Tab 切换对应的生命周期(以 A、B 页面为 Tabbar 页面,C 是从 A 页面打开的页面,D 页面是从 C 页面打开的页面为例):
当前页面 | 路由后页面 | 触发的生命周期(按顺序) |
---|---|---|
A | A | Nothing happend |
A | B | A.onHide(), B.onLoad(), B.onShow() |
A | B(再次打开) | 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(从转发进入) | A | D.onUnload(), A.onLoad(), A.onShow() |
D(从转发进入) | B | D.onUnload(), B.onLoad(), B.onShow() |
Tips:
navigateTo
,redirectTo
只能打开非 tabBar 页面。switchTab
只能打开 tabBar 页面。reLaunch
可以打开任意页面。- 页面底部的 tabBar 由页面决定,即只要是定义为 tabBar 的页面,底部都有 tabBar。
- 调用页面路由带的参数可以在目标页面的
onLoad
中获取。
文件作用域
在 JavaScript 文件中声明的变量和函数只在该文件中有效;不同的文件中可以声明相同名字的变量和函数,不会互相影响。
通过全局函数 getApp()
可以获取全局的应用实例,如果需要全局的数据可以在 App()
中设置,如:
// app.js
App({
globalData: 1
})
// a.js
// The localValue can only be used in file a.js.
var localValue = 'a'
// Get the app instance.
var app = getApp()
// Get the global data and change it.
app.globalData++
// b.js
// You can redefine localValue in file b.js, without interference with the localValue in a.js.
var localValue = 'b'
// If a.js it run before b.js, now the globalData shoule be 2.
console.log(getApp().globalData)
模块化
可以将一些公共的代码抽离成为一个单独的 js 文件,作为一个模块。模块只有通过 module.exports
或者 exports
才能对外暴露接口。
需要注意的是:
exports
是module.exports
的一个引用,因此在模块里边随意更改exports
的指向会造成未知的错误。所以更推荐开发者采用module.exports
来暴露模块接口,除非你已经清晰知道这两者的关系。- 小程序目前不支持直接引入
node_modules
, 开发者需要使用到node_modules
时候建议拷贝出相关的代码到小程序的目录中。
// common.js
function sayHello(name) {
console.log(`Hello ${name} !`)
}
function sayGoodbye(name) {
console.log(`Goodbye ${name} !`)
}
module.exports.sayHello = sayHello
exports.sayGoodbye = sayGoodbye
在需要使用这些模块的文件中,使用 require(path)
将公共代码引入
var common = require('common.js')
Page({
helloMINA: function() {
common.sayHello('MINA')
},
goodbyeMINA: function() {
common.sayGoodbye('MINA')
}
})
Tips
tip
: require 暂时不支持绝对路径
API
小程序开发框架提供丰富的微信原生 API,可以方便的调起微信提供的能力,如获取用户信息,本地存储,支付功能等。
详细介绍请参考 API 文档