微信小程序开发文档 第40页

组件生命周期 组件的生命周期，指的是组件自身的一些函数，这些函数在特殊的时间点或遇到一些特殊的框架事件时被自动触发。 其中，最重要的生命周期是 created attached detached ，包含一个组件实例生命流程的最主要时间点。 组件实例刚刚被创建好时， created 生命周期被触发。此时，组件数据 this.data 就是在 Component 构造器中定义的数据 data 。 此时还不能调用 setData 。 通常情况下，这个生命周期只应该用于给组件 this 添加一些自定义属性字段。 在组件完全初始化完毕、进入页面节点树后， attached 生命周期被触发。此时， this.data 已被初始化为组件的当前值。这个生命周期很有用，绝大多数初始化工作可以在这个时机进行。 在组件离开页面节点树后， detached 生命周期被触发。退出一个页面时，如果组件还在页面节点树中，则 detached 会被触发。 定义生命周期方法 生命周期方法可以直接定义在 Component 构造器的第一级参数中。 自小程序基础库版本 2.2.3 起，组件的的生命周期也可以在 lifetimes 字段内进行声明（这是推荐的方式，其优先级最高）。 代码示例： Component({ lifetimes: { attached: function() { // 在组件实例进入页面节点树时执行 }, detached: function() { // 在组件实例被从页面节点树移除时执行 }, }, // 以下是旧式的定义方式，可以保持对 <2.2.3 版本基础库的兼容 attached: function() { // 在组件实例进入页面节点树时执行 }, detached: function() { // 在组件实例被从页面节点树移除时执行 }, // ... }) 在 behaviors 中也可以编写生命周期方法，同时不会与其他 behaviors 中的同名生命周期相互覆盖。但要注意，如果一个组件多次直接或间接引用同一个 behavior ，这个 behavior 中的生命周期函数在一个执行时机内只会执行一次。 可用的全部生命周期如下表所示。 生命周期 参数 描述 最低版本 created 无 在组件实例刚刚被创建时执行 1.6.3 attached 无 在组件实例进入页面节点树时执行 1.6.3 ready 无 在组件在视图层布局完成后执行 1.6.3 moved 无 在组件实例被移动到节点树另一个位置时执行 1.6.3 detached 无 在组件实例被从页面节点树移除时执行 1.6.3 error Object Error 每当组件方法抛出错误时执行 2.4.1 组件所在页面的生命周期 还有一些特殊的生命周期，它们并非与组件有很强的关联，但有时组件需要获知，以便组件内部处理。这样的生命周期称为“组件所在页面的生命周期”，在 pageLifetimes 定义段中定义。其中可用的生命周期包括： 生命周期 参数 描述 最低版本 show 无 组件所在的页面被展示时执行 2.2.3 hide 无 组件所在的页面被隐藏时执行 2.2.3 resize Object Size 组件所在的页面尺寸变化时执行 2.4.0 代码示例： Component({ pageLifetimes: { show: function() { // 页面被展示 }, hide: function() { // 页面被隐藏 }, resize:...

组件间通信与事件 组件间通信 组件间的基本通信方式有以下几种。 WXML 数据绑定：用于父组件向子组件的指定属性设置数据，仅能设置 JSON 兼容数据（自基础库版本 2.0.9 开始，还可以在数据中包含函数）。具体在 组件模板和样式 章节中介绍。 事件：用于子组件向父组件传递数据，可以传递任意数据。 如果以上两种方式不足以满足需要，父组件还可以通过 this.selectComponent 方法获取子组件实例对象，这样就可以直接访问组件的任意数据和方法。 监听事件 事件系统是组件间通信的主要方式之一。自定义组件可以触发任意的事件，引用组件的页面可以监听这些事件。关于事件的基本概念和用法，参见 事件 。 监听自定义组件事件的方法与监听基础组件事件的方法完全一致： 代码示例： <!-- 当自定义组件触发“myevent”事件时，调用“onMyEvent”方法 --> <component-tag-name bindmyevent="onMyEvent" /> <!-- 或者可以写成 --> <component-tag-name bind:myevent="onMyEvent" /> Page({ onMyEvent: function(e){ e.detail // 自定义组件触发事件时提供的detail对象 } }) 触发事件 自定义组件触发事件时，需要使用 triggerEvent 方法，指定事件名、detail对象和事件选项： 代码示例： <!-- 在自定义组件中 --> <button bindtap="onTap">点击这个按钮将触发“myevent”事件</button> Component({ properties: {}, methods: { onTap: function(){ var myEventDetail = {} // detail对象，提供给事件监听函数 var myEventOption = {} // 触发事件的选项 this.triggerEvent('myevent', myEventDetail, myEventOption) } } }) 触发事件的选项包括： 选项名 类型 是否必填 默认值 描述 bubbles Boolean 否 false 事件是否冒泡 composed Boolean 否 false 事件是否可以穿越组件边界，为false时，事件将只能在引用组件的节点树上触发，不进入其他任何组件内部 capturePhase Boolean 否 false 事件是否拥有捕获阶段 关于冒泡和捕获阶段的概念，请阅读 事件 章节中的相关说明。 代码示例： 在开发者工具中预览效果 // 页面 page.wxml <another-component bindcustomevent="pageEventListener1"> <my-component bindcustomevent="pageEventListener2"></my-component> </another-component> // 组件 another-component.wxml <view bindcustomevent="anotherEventListener"> <slot /> </view> // 组件 my-component.wxml <view bindcustomevent="myEventListener"> <slot /> </view> // 组件 my-component.js Component({ methods: {...

小程序运行机制 前台/后台状态 小程序启动后，界面被展示给用户，此时小程序处于前台状态。 当用户点击右上角胶囊按钮关闭小程序，或者按了设备 Home 键离开微信时，小程序并没有完全终止运行，而是进入了后台状态，小程序还可以运行一小段时间。 当用户再次进入微信或再次打开小程序，小程序又会从后台进入前台。但如果用户很久没有再进入小程序，或者系统资源紧张，小程序可能被销毁，即完全终止运行。 小程序启动 这样，小程序启动可以分为两种情况，一种是冷启动，一种是热启动。 冷启动：如果用户首次打开，或小程序销毁后被用户再次打开，此时小程序需要重新加载启动，即冷启动。 热启动：如果用户已经打开过某小程序，然后在一定时间内再次打开该小程序，此时小程序并未被销毁，只是从后台状态进入前台状态，这个过程就是热启动。 小程序销毁时机 通常，只有当小程序进入后台一定时间，或者系统资源占用过高，才会被销毁。具体而言包括以下几种情形： 当小程序进入后台，可以维持一小段时间的运行状态，如果这段时间内都未进入前台，小程序会被销毁。 当小程序占用系统资源过高，可能会被系统销毁或被微信客户端主动回收。在 iOS 上，当微信客户端在一定时间间隔内连续收到系统内存告警时，会根据一定的策略，主动销毁小程序，并提示用户 「运行内存不足，请重新打开该小程序」。具体策略会持续进行调整优化。建议小程序在必要时使用 wx.onMemoryWarning 监听内存告警事件，进行必要的内存清理。 基础库 1.1.0 及以上，1.4.0 以下版本： 当用户从扫一扫、转发等入口（场景值为1007, 1008, 1011, 1025）进入小程序，且没有置顶小程序的情况下退出，小程序会被销毁。 启动场景分类 用户打开小程序时，场景可分为以下 A、B 两类： A. 保留上次的浏览状态。场景值有以下几项： 场景值ID 说明 1001 发现栏小程序主入口，「最近使用」列表（基础库2.2.4版本起包含「我的小程序」列表） 1003 星标小程序列表 1023 系统桌面小图标打开小程序 1038 从其他小程序返回小程序 1056 聊天顶部音乐播放器右上角菜单，打开小程序 1080 客服会话菜单小程序入口，打开小程序 1083 公众号会话菜单小程序入口 ，打开小程序（只有腾讯客服小程序有） 1089 聊天主界面下拉，打开小程序/微信聊天主界面下拉，「最近使用」栏（基础库2.2.4版本起包含「我的小程序」栏） 1090 长按小程序右上角菜单，打开小程序 1103 发现-小程序主入口我的小程序，打开小程序 1104 聊天主界面下拉，从我的小程序，打开小程序 1113 安卓手机负一屏，打开小程序 1114 安卓手机侧边栏，打开小程序 1117 后台运行小程序的管理页中，打开小程序 若进入的场景中带有 path，则每次打开小程序时都进入对应的 path 页面 若进入的场景中不带 path：若小程序是热启动，则保留原来状态若小程序是冷启动，则遵循下一节的重启策略，可能是首页或上次退出的页面 B. relaunch 到指定页或首页 包括除 A 类外的其他场景 若进入的场景中带有 path，则每次点击时都进入对应的 path 页面 若进入的场景中不带 path，则每次进入都打开首页 A 类场景的重新启动策略 基础库 2.8.0 开始支持，低版本需做兼容处理。 小程序被销毁后，下次冷启动如果属于 B 类场景，将会进入特定的页面。 下次冷启动如果属于 A 类场景，默认情况下将会进入小程序的首页。在页面对应的 json 文件中（也可以全局配置在 app.json 的 window 段中），指定 restartStrategy 配置项可以改变这个默认的行为，使得从某个页面退出后，下次 A 类场景的冷启动可以回到这个页面。 代码示例： { "restartStrategy": "homePage" } restartStrategy 可选值： 可选值 含义 homePage （默认值）如果从这个页面退出小程序，下次将从首页冷启动 homePageAndLatestPage 如果从这个页面退出小程序，下次冷启动后立刻加载这个页面，页面的参数保持不变（不可用于 tab 页） 注意：即使不配置为 homePage ，小程序如果退出过久（当前默认一天时间，可以使用退出状态来调整），下次冷启动时也将不再遵循 restartStrategy 的配置，而是直接从首页冷启动。 无论如何，页面中的状态并不会被保留，如输入框中的文本内容、 checkbox 的勾选状态等都不会还原。如果需要还原或部分还原，需要利用退出状态。 退出状态 每当小程序可能被销毁之前，页面回调函数 onSaveExitState 会被调用。如果想保留页面中的状态，可以在这个回调函数中“保存”一些数据，下次启动时可以通过 exitState 获得这些已保存数据。...

JavaScript 支持情况 运行限制 基于安全考虑，小程序中不支持动态执行 JS 代码，即： 不支持使用 eval 执行 JS 代码 不支持使用 new Function 创建函数 客户端 ES6 API 支持情况 微信小程序已经支持了绝大部分的 ES6 API，已支持的 API 如下（部分API依赖系统版本）： String iOS8 iOS9 iOS10+ Android codePointAt normalize includes startsWith endsWith repeat String.fromCodePoint Array iOS8 iOS9 iOS10+ Android copyWithin find findIndex fill entries keys values includes Array.from Array.of Number iOS8 iOS9 iOS10+ Android isFinite isNaN parseInt parseFloat isInteger EPSILON isSafeInteger Math iOS8 iOS9 iOS10+ Android trunc sign cbrt clz32 imul fround hypot expm1 log1p log10 log2 sinh cosh tanh asinh acosh atanh Object iOS8 iOS9 iOS10+ Android is assign getOwnPropertyDescriptor keys getOwnPropertyNames getOwnPropertySymbols Other iOS8 iOS9 iOS10+ Android Symbol Set Map Proxy Reflect Promise

动画 界面动画的常见方式 在小程序中，通常可以使用 CSS 渐变 和 CSS 动画 来创建简易的界面动画。 动画过程中，可以使用 bindtransitionend bindanimationstart bindanimationiteration bindanimationend 来监听动画事件。 事件名 含义 transitionend CSS 渐变结束或 wx.createAnimation 结束一个阶段 animationstart CSS 动画开始 animationiteration CSS 动画结束一个阶段 animationend CSS 动画结束 注意：这几个事件都不是冒泡事件，需要绑定在真正发生了动画的节点上才会生效。 同时，还可以使用 wx.createAnimation 接口来动态创建简易的动画效果。（新版小程序基础库中推荐使用下述的关键帧动画接口代替。） 关键帧动画 基础库 2.9.0 开始支持，低版本需做兼容处理。 从小程序基础库 2.9.0 开始支持一种更友好的动画创建方式，用于代替旧的 wx.createAnimation 。它具有更好的性能和更可控的接口。 在页面或自定义组件中，当需要进行关键帧动画时，可以使用 this.animate 接口： this.animate(selector, keyframes, duration, callback) 参数说明 属性 类型 默认值 必填 说明 selector String 是 选择器（同 SelectorQuery.select 的选择器格式） keyframes Array 是 关键帧信息 duration Number 是 动画持续时长（毫秒为单位） callback function 否 动画完成后的回调函数 keyframes 中对象的结构 属性 类型 默认值 必填 说明 offset Number 否 关键帧的偏移，范围[0-1] ease String linear 否 动画缓动函数 transformOrigin String 否 基点位置，即 CSS transform-origin backgroundColor String 否 背景颜色，即 CSS background-color bottom Number/String 否 底边位置，即 CSS bottom height Number/String 否 高度，即 CSS height left Number/String 否 左边位置，即 CSS left width Number/String 否 宽度，即 CSS width opacity Number 否 不透明度，即 CSS opacity right Number 否 右边位置，即 CSS right top Number/String...

基础组件 框架为开发者提供了一系列基础组件，开发者可以通过组合这些基础组件进行快速开发。详细介绍请参考组件文档。 什么是组件： 组件是视图层的基本组成单元。 组件自带一些功能与微信风格一致的样式。 一个组件通常包括 开始标签 和 结束标签，属性 用来修饰这个组件，内容 在两个标签之内。 <tagname property="value"> Content goes here ... </tagname> 注意：所有组件与属性都是小写，以连字符-连接 属性类型 类型 描述 注解 Boolean 布尔值 组件写上该属性，不管是什么值都被当作 true；只有组件上没有该属性时，属性值才为false。 如果属性值为变量，变量的值会被转换为Boolean类型 Number 数字 1, 2.5 String 字符串 "string" Array 数组 [ 1, "string" ] Object 对象 { key: value } EventHandler 事件处理函数名 "handlerName" 是 Page 中定义的事件处理函数名 Any 任意属性 公共属性 所有组件都有以下属性： 属性名 类型 描述 注解 id String 组件的唯一标示 保持整个页面唯一 class String 组件的样式类 在对应的 WXSS 中定义的样式类 style String 组件的内联样式 可以动态设置的内联样式 hidden Boolean 组件是否显示 所有组件默认显示 data-* Any 自定义属性 组件上触发的事件时，会发送给事件处理函数 bind* / catch* EventHandler 组件的事件 详见事件 特殊属性 几乎所有组件都有各自定义的属性，可以对该组件的功能或样式进行修饰，请参考各个组件的定义。

事件 什么是事件 事件是视图层到逻辑层的通讯方式。 事件可以将用户的行为反馈到逻辑层进行处理。 事件可以绑定在组件上，当达到触发事件，就会执行逻辑层中对应的事件处理函数。 事件对象可以携带额外信息，如 id, dataset, touches。 事件的使用方式 在组件中绑定一个事件处理函数。 如bindtap，当用户点击该组件的时候会在该页面对应的Page中找到相应的事件处理函数。 <button id="tapTest" data-hi="WeChat" bindtap="tapName"> Click me! </button> 在相应的Page定义中写上相应的事件处理函数，参数是event。 Page({ tapName: function(event) { console.log(event) } }) 可以看到log出来的信息大致如下： { "type":"tap", "timeStamp":895, "target": { "id": "tapTest", "dataset": { "hi":"WeChat" } }, "currentTarget": { "id": "tapTest", "dataset": { "hi":"WeChat" } }, "detail": { "x":53, "y":14 }, "touches":[{ "identifier":0, "pageX":53, "pageY":14, "clientX":53, "clientY":14 }], "changedTouches":[{ "identifier":0, "pageX":53, "pageY":14, "clientX":53, "clientY":14 }] } 使用WXS函数响应事件 基础库 2.4.4 开始支持，低版本需做兼容处理。 从基础库版本2.4.4开始，支持使用WXS函数绑定事件，WXS函数接受2个参数，第一个是event，在原有的event的基础上加了event.instance对象，第二个参数是ownerInstance，和event.instance一样是一个ComponentDescriptor对象。具体使用如下： 在组件中绑定和注册事件处理的WXS函数。 <wxs module="wxs" src="./test.wxs"></wxs> <view id="tapTest" data-hi="WeChat" bindtap="{{wxs.tapName}}"> Click me! </view> **注：绑定的WXS函数必须用{{}}括起来** test.wxs文件实现tapName函数 function tapName(event, ownerInstance) { console.log('tap wechat', JSON.stringify(event)) } module.exports = { tapName: tapName } ownerInstance包含了一些方法，可以设置组件的样式和class，具体包含的方法以及为什么要用WXS函数响应事件。 事件详解 事件分类 事件分为冒泡事件和非冒泡事件： 冒泡事件：当一个组件上的事件被触发后，该事件会向父节点传递。 非冒泡事件：当一个组件上的事件被触发后，该事件不会向父节点传递。 WXML的冒泡事件列表： 类型 触发条件 最低版本 touchstart 手指触摸动作开始 touchmove 手指触摸后移动 touchcancel 手指触摸动作被打断，如来电提醒，弹窗 touchend 手指触摸动作结束 tap...

WXSS WXSS (WeiXin Style Sheets)是一套样式语言，用于描述 WXML 的组件样式。 WXSS 用来决定 WXML 的组件应该怎么显示。 为了适应广大的前端开发者，WXSS 具有 CSS 大部分特性。同时为了更适合开发微信小程序，WXSS 对 CSS 进行了扩充以及修改。 与 CSS 相比，WXSS 扩展的特性有： 尺寸单位 样式导入 尺寸单位 rpx（responsive pixel）: 可以根据屏幕宽度进行自适应。规定屏幕宽为750rpx。如在 iPhone6 上，屏幕宽度为375px，共有750个物理像素，则750rpx = 375px = 750物理像素，1rpx = 0.5px = 1物理像素。 设备 rpx换算px (屏幕宽度/750) px换算rpx (750/屏幕宽度) iPhone5 1rpx = 0.42px 1px = 2.34rpx iPhone6 1rpx = 0.5px 1px = 2rpx iPhone6 Plus 1rpx = 0.552px 1px = 1.81rpx 建议： 开发微信小程序时设计师可以用 iPhone6 作为视觉稿的标准。 注意： 在较小的屏幕上不可避免的会有一些毛刺，请在开发时尽量避免这种情况。 样式导入 使用@import语句可以导入外联样式表，@import后跟需要导入的外联样式表的相对路径，用;表示语句结束。 示例代码： /** common.wxss **/ .small-p { padding:5px; } /** app.wxss **/ @import "common.wxss"; .middle-p { padding:15px; } 内联样式 框架组件上支持使用 style、class 属性来控制组件的样式。 style：静态的样式统一写到 class 中。style 接收动态的样式，在运行时会进行解析，请尽量避免将静态的样式写进 style 中，以免影响渲染速度。 <view style="color:{{color}};" /> class：用于指定样式规则，其属性值是样式规则中类选择器名(样式类名)的集合，样式类名不需要带上.，样式类名之间用空格分隔。 <view class="normal_view" /> 选择器 目前支持的选择器有： 选择器 样例 样例描述 .class .intro 选择所有拥有 class=”intro” 的组件 #id #firstname 选择拥有 id=”firstname” 的组件...

API 小程序开发框架提供丰富的微信原生 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 文档中的说明。 同步 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) } }) 异步 API 返回 Promise 基础库 2.10.2 版本起，异步 API 支持 callback & promise 两种调用方式。当接口参数 Object 对象中不包含 success/fail/complete 时将默认返回...

页面路由 在小程序中所有页面的路由全部由框架进行管理。 页面栈 框架以栈的形式维护了当前的所有页面。 当发生路由切换的时候，页面栈的表现如下： 路由方式 页面栈表现 初始化 新页面入栈 打开新页面 新页面入栈 页面重定向 当前页面出栈，新页面入栈 页面返回 页面不断出栈，直到目标返回页 Tab 切换 页面全部出栈，只留下新的 Tab 页面 重加载 页面全部出栈，只留下新的页面 开发者可以使用 getCurrentPages() 函数获取当前页面栈。 getCurrentPages() 函数用于获取当前页面栈的实例，以数组形式按栈的顺序给出，第一个元素为首页，最后一个元素为当前页面。 页面栈示例：页面栈遵循先进后出的规则，当前也在最上面。 路由方式 对于路由的触发方式以及页面生命周期函数如下： 路由方式 触发时机 路由前页面 路由后页面 初始化 小程序打开的第一个页面 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（从转发进入）...