微信小程序学习

官方网站

https://mp.weixin.qq.com/debug/wxadoc/dev/index.html

项目结构介绍 —— MINA框架

https://mp.weixin.qq.com/debug/wxadoc/dev/framework/MINA.html

组件视图

#视图API文档
https://mp.weixin.qq.com/debug/wxadoc/dev/component/?t=20161122

#视图手机体验
https://mp.weixin.qq.com/debug/wxadoc/dev/demo.html?t=20161122

API文档

https://mp.weixin.qq.com/debug/wxadoc/dev/api/

开发工具下载

https://mp.weixin.qq.com/debug/wxadoc/dev/devtools/download.html

微信小程序（第三方）教程

//介绍
http://lib.csdn.net/article/wechat/46759
//环境搭建:QQ的小程序github
http://lib.csdn.net/article/wechat/46756
//初试微信小程序
http://lib.csdn.net/article/wechat/46757

注意点：

• 由于框架并非运行在浏览器中，所以 JavaScript 在 web 中一些能力都无法使用，如 document，window 等
• 每个页面有独立的作用域，并提供模块化能力
• 提供丰富的 API，如微信用户数据，扫一扫，支付等微信特有能力

---

 小程序全局配置

一个小程序主体部分由三个文件组成，必须放在项目的根目录，如下：

文件	必填	作用
app.js	是	小程序逻辑
app.json	是	小程序公共设置
app.wxss	否	小程序公共样式表

一个小程序页面由四个文件组成，分别是：

文件类型	必填	作用
js	是	页面逻辑
wxml	是	页面结构
wxss	否	页面样式表
json	否	页面配置

请注意（app.json）公共配置和（page.json）页面配置的区别

app.json有五个属性pages、window、tabBar、networkTimeout、debug

而page.json只需要配置window属性。

公共配置 app.json 之 pages：

接受一个数组，每一项都是字符串，来指定小程序由哪些页面组成,数组的第一项代表小程序的初始页面。小程序中新增/减少页面，都需要对 pages 数组进行修改。

如开发目录为：

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"
  ]
}

我们注意到了。index.wxml/index.js/index.wxss 这三个是同名的。也就是说，框架会自动去寻找.json,.js,.wxml,.wxss的四个文件进行整合

公共配置 app.json 之 window：

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

属性	类型	默认值	描述
navigationBarBackgroundColor	HexColor	#000000	导航栏背景颜色，如"#000000"
navigationBarTextStyle	String	white	导航栏标题颜色，仅支持 black/white
navigationBarTitleText	String		导航栏标题文字内容
backgroundColor	HexColor	#ffffff	窗口的背景色
backgroundTextStyle	String	dark	下拉背景字体、loading 图的样式，仅支持 dark/light
enablePullDownRefresh	Boolean	false	是否开启下拉刷新，详见页面相关事件处理函数。

公共配置 app.json 之 tabBar :

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

tabBar 是一个数组，只能配置最少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
selectedIconPath	String	是	选中时的图片路径，icon 大小限制为40kb

公共配置 app.json 之networkTimeout :

可以设置各种网络请求的超时时间。

属性说明：

属性	类型	必填	说明
request	Number	否	wx.request的超时时间，单位毫秒
connectSocket	Number	否	wx.connectSocket的超时时间，单位毫秒
uploadFile	Number	否	wx.uploadFile的超时时间，单位毫秒
downloadFile	Number	否	wx.downloadFile的超时时间，单位毫秒

---

逻辑层

注册程序 —— app.js

这里可以定义小程序全局函数和全局变量

App() 函数用来注册一个小程序。接受一个 object 参数，其指定小程序的生命周期函数等。

object参数说明：

属性	类型	描述	触发时机
onLaunch	Function	生命周期函数--监听小程序初始化	当小程序初始化完成时，会触发 onLaunch（全局只触发一次）
onShow	Function	生命周期函数--监听小程序显示	当小程序启动，或从后台进入前台显示，会触发 onShow
onHide	Function	生命周期函数--监听小程序隐藏	当小程序从前台进入后台，会触发 onHide
其他	Any	开发者可以添加任意的函数或数据到 Object 参数中，用this 可以访问

前台、后台定义： 当用户点击左上角关闭，或者按了设备 Home 键离开微信，小程序并没有直接销毁，而是进入了后台；当再次进入微信或再次打开小程序，又会从后台进入前台。

只有当小程序进入后台一定时间，或者系统资源占用过高，才会被真正的销毁。

App({
  onLaunch: function() {
    // Do something initial when launch.
  },
  onShow: function() {
      // Do something when show.
  },
  onHide: function() {
      // Do something when hide.
  },
  globalData: 'I am global data'
})

两个相关的核心函数：

getCurrentPages()

getCurrentPages() 函数用于获取当前页面栈的实例，以数组形式按栈的顺序给出，第一个元素为首页，最后一个元素为当前页面。

注意：不要尝试修改页面栈，会导致路由以及页面状态错误。

页面栈

框架以栈的形式维护了当前的所有页面。 当发生路由切换的时候，页面栈的表现如下：

路由方式	页面栈表现
初始化	新页面入栈
打开新页面	新页面入栈
页面重定向	当前页面出栈，新页面入栈
页面返回	页面不断出栈，直到目标返回页，新页面入栈
Tab 切换	当前页面出栈，新页面入栈

getApp()

我们提供了全局的 getApp() 函数，可以获取到小程序实例。

// other.js
var appInstance = getApp()
console.log(appInstance.globalData) // I am global data

注意：

• App() 必须在 app.js 中注册，且不能注册多个。

• 不要在定义于 App() 内的函数中调用 getApp() ，使用 this 就可以拿到 app 实例。

• 不要在 onLaunch 的时候调用 getCurrentPage()，此时 page 还没有生成。

• 通过 getApp() 获取实例之后，不要私自调用生命周期函数。

---

注册页面 —— page()：

Page() 函数用来注册一个页面。接受一个 object 参数，其指定页面的初始数据、生命周期函数、事件处理函数等。

object 参数说明：

属性	类型	描述
data	Object	页面的初始数据
onLoad	Function	生命周期函数--监听页面加载
onReady	Function	生命周期函数--监听页面初次渲染完成
onShow	Function	生命周期函数--监听页面显示
onHide	Function	生命周期函数--监听页面隐藏
onUnload	Function	生命周期函数--监听页面卸载
onPullDownRefresh	Function	页面相关事件处理函数--监听用户下拉动作
onReachBottom	Function	页面上拉触底事件的处理函数
其他	Any	开发者可以添加任意的函数或数据到 object 参数中，在页面的函数中用 this 可以访问

示例代码：

//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.
  },
  // Event handler.
  viewTap: function() {
    this.setData({
      text: 'Set some data for updating view.'
    })
  },
  customData: {
    hi: 'MINA'
  }
})

初始化数据

初始化数据将作为页面的第一次渲染。data 将会以 JSON 的形式由逻辑层传至渲染层，所以其数据必须是可以转成 JSON 的格式：字符串，数字，布尔值，对象，数组。

渲染层可以通过 WXML 对数据进行绑定。

示例代码：

<view>{{text}}</view>
<view>{{array[].msg}}</view>
Page({
  data: {
    text: 'init data',
    array: [{msg: '}]
  }
})

生命周期函数

• onLoad: 页面加载

  • 一个页面只会调用一次。
  • 接收页面参数可以获取wx.navigateTo和wx.redirectTo及<navigator/>中的 query。

• onShow: 页面显示

  • 每次打开页面都会调用一次。

• onReady: 页面初次渲染完成

  • 一个页面只会调用一次，代表页面已经准备妥当，可以和视图层进行交互。
  • 对界面的设置如wx.setNavigationBarTitle请在onReady之后设置。详见生命周期

• onHide: 页面隐藏

  • 当navigateTo或底部tab切换时调用。

• onUnload: 页面卸载

  • 当redirectTo或navigateBack的时候调用。

页面相关事件处理函数

• onPullDownRefresh: 下拉刷新
  • 监听用户下拉刷新事件。
  • 需要在config的window选项中开启enablePullDownRefresh。
  • 当处理完数据刷新后，wx.stopPullDownRefresh可以停止当前页面的下拉刷新。

事件处理函数

除了初始化数据和生命周期函数，Page 中还可以定义一些特殊的函数：事件处理函数。在渲染层可以在组件中加入事件绑定，当达到触发事件时，就会执行 Page 中定义的事件处理函数。

示例代码：

<view bindtap="viewTap"> click me </view>
Page({
  viewTap: function() {
    console.log('view tap')
  }
})

setData()

setData 函数用于将数据从逻辑层发送到视图层，同时改变对应的 this.data 的值。

注意：

1. 直接修改 this.data 无效，无法改变页面的状态，还会造成数据不一致。
2. 单次设置的数据不能超过1024kB，请尽量避免一次设置过多的数据。

setData() 参数格式

接受一个对象，以 key，value 的形式表示将 this.data 中的 key 对应的值改变成 value。

其中 key 可以非常灵活，以数据路径的形式给出，如 array[2].message，a.b.c.d，并且不需要在 this.data 中预先定义。

示例代码：

//index.wxml
<view>{{text}}</view>
<button bindtap="changeText"> Change normal data </button>
<view>{{array[].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',
    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'
    })
  },
  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'
    })
  }
})

页面的路由

在小程序中所有页面的路由全部由框架进行管理，对于路由的触发方式以及页面生命周期函数如下：

路由方式	触发时机	路由后页面	路由前页面
初始化	小程序打开的第一个页面	onLoad，onShow
打开新页面	调用 API wx.navigateTo 或使用组件 <navigator />	onLoad，onShow	onHide
页面重定向	调用 API wx.redirectTo 或使用组件 <navigator />	onLoad，onShow	onUnload
页面返回	调用 API wx.navigateBack或用户按左上角返回按钮	onShow	onUnload（多层页面返回每个页面都会按顺序触发onUnload）
Tab 切换	多 Tab 模式下用户切换 Tab	第一次打开 onLoad，onshow；否则 onShow	onHide

---

模块化

我们可以将一些公共的代码抽离成为一个单独的 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')
  }
})

ES6 语法以及 API 支持

• 这种转换只会帮助开发处理语法上问题，新的 ES6 的 API 例如 Promise 等需要开发者自行引入 Polyfill 或者别的类库。
• 为了提高代码质量，在开启 ES6 转换功能的情况下，默认启用 javasctipt 严格模式，请参考 "use strict" 。

---

视图层

WXML 中的动态数据均来自对应 Page 的 data。

数据绑定使用 Mustache 语法（双大括号）将变量包起来

内容

<view> {{ message }} </view>
Page({
  data: {
    message: 'Hello MINA!'
  }
})

控制属性(需要在双引号之内)

<view wx:if="{{condition}}"> </view>
Page({
  data: {
    condition: true
  }
})

关键字(需要在双引号之内)

true：boolean 类型的 true，代表真值。

false： boolean 类型的 false，代表假值。

<checkbox checked="{{false}}"> </checkbox>

特别注意：不要直接写 checked="false"，其计算结果是一个字符串，转成 boolean 类型后代表真值(true)。

三元运算

<view hidden="{{flag ? true : false}}"> Hidden </view>

算数运算

<view> {{a + b}} + {{c}} + d </view>

逻辑判断

<view wx:if="{{length > 5}}"> </view>

字符串运算

<view>{{"hello" + name}}</view>

数据路径运算

<view>{{]}}</view>
Page({
  data: {
    object: {
      key: 'Hello '
    },
    array: ['MINA']
  }
})

数组

<view wx:for="{{[zero, 1, 2, 3, 4]}}"> {{item}} </view>
Page({
  data: {
    zero:
  }
})

最终组合成数组[0, 1, 2, 3, 4]。

对象

<template is="objectCombine" data="{{for: a, bar: b}}"></template>
Page({
  data: {
    a: ,
    b:
  }
})

最终组合成的对象是 {for: 1, bar: 2}

扩展运算符 ... 来将一个对象展开

<template is="objectCombine" data="{{...obj1, ...obj2, e: 5}}"></template>

Page({
  data: {
    obj1: {
      a: ,
      b:
    },
    obj2: {
      c: ,
      d:
    }
  }
})

最终组合成的对象是 {a: 1, b: 2, c: 3, d: 4, e: 5}。

如果对象的 key 和 value 相同，也可以间接地表达。

<template is="objectCombine" data="{{foo, bar}}"></template>

Page({
  data: {
    foo: 'my-foo',
    bar: 'my-bar'
  }
})

最终组合成的对象是 {foo: 'my-foo', bar:'my-bar'}。

---

条件渲染

wx:if

在框架中，我们用 wx:if="{{condition}}" 来判断是否需要渲染该代码块：

<view wx:if="{{condition}}"> True </view>

也可以用 wx:elif 和 wx:else 来添加一个 else 块：

<view wx: </view>
<view wx:elif= </view>
<view wx: </view>

block wx:if

因为 wx:if 是一个控制属性，需要将它添加到一个标签上。但是如果我们想一次性判断多个组件标签，我们可以使用一个 <block/> 标签将多个组件包装起来，并在上边使用 wx:if 控制属性。

<block wx:if="{{true}}">
  <view> view1 </view>
  <view> view2 </view>
</block>

注意： <block/> 并不是一个组件，它仅仅是一个包装元素，不会在页面中做任何渲染，只接受控制属性。

wx:if vs hidden

因为 wx:if 之中的模板也可能包含数据绑定，所有当 wx:if 的条件值切换时，框架有一个局部渲染的过程，因为它会确保条件块在切换时销毁或重新渲染。

同时 wx:if 也是惰性的，如果在初始渲染条件为 false，框架什么也不做，在条件第一次变成真的时候才开始局部渲染。

相比之下，hidden 就简单的多，组件始终会被渲染，只是简单的控制显示与隐藏。

一般来说，wx:if 有更高的切换消耗而 hidden 有更高的初始渲染消耗。因此，如果需要频繁切换的情景下，用 hidden 更好，如果在运行时条件不大可能改变则 wx:if 较好。

---

列表渲染 —— 循环（重点）

wx:for

在组件上使用wx:for控制属性绑定一个数组，即可使用数组中各项的数据重复渲染该组件。

默认数组的当前项的下标变量名默认为index，数组当前项的变量名默认为item

<view wx:for="{{array}}">
  {{index}}: {{item.message}}
</view>

Page({
  data: {
    array: [{
      message: 'foo',
    }, {
      message: 'bar'
    }]
  }
})

使用 wx:for-item 可以指定数组当前元素的变量名，

使用 wx:for-index 可以指定数组当前下标的变量名

<view wx:for="{{array}}" wx:for-index="idx" wx:for-item="itemName">
  {{idx}}: {{itemName.message}}
</view>

wx:for也可以嵌套，下边是一个九九乘法表

<view wx:for="{{[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" wx:for-item="i">
  <view wx:for="{{[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" wx:for-item="j">
    <view wx:if="{{i <= j}}">
      {{i}} * {{j}} = {{i * j}}
    </view>
  </view>
</view>

block wx:for

类似block wx:if，也可以将wx:for用在<block/>标签上，以渲染一个包含多节点的结构块。例如：

<block wx:for="{{[1, 2, 3]}}">
  <view> {{index}}: </view>
  <view> {{item}} </view>
</block>

---

模板

模板的作用域

模板拥有自己的作用域，只能使用data传入的数据。

定义模板

使用name属性，作为模板的名字。然后在<template/>内定义代码片段，如：

<template name="msgItem">
  <view>
    <text> {{index}}: {{msg}} </text>
    <text> Time: {{time}} </text>
  </view>
</template>

使用模板

使用 is 属性，声明需要的使用的模板，然后将模板所需要的 data 传入，如：

<template is="msgItem" data="{{...item}}"/>

Page({
  data: {
    item: {
      index: 0,
      msg: 'this is a template',
      time: '2016-09-15'
    }
  }
})

---

事件

WXML的冒泡事件列表：

类型	触发条件
touchstart	手指触摸动作开始
touchmove	手指触摸后移动
touchcancel	手指触摸动作被打断，如来电提醒，弹窗
touchend	手指触摸动作结束
tap	手指触摸后马上离开
longtap	手指触摸后，超过350ms再离开

注：除上表之外的其他组件自定义事件如无特殊申明都是非冒泡事件，如<form/>的submit事件，<input/>的input事件，<scroll-view/>的scroll事件，(详见各个组件)

<view id="tapTest" data-hi="WeChat" bindtap="tapName"> Click me! </view>

Page({
  tapName: function(event) {
    console.log(event)
  }
})

事件绑定

事件绑定的写法同组件的属性，以 key、value 的形式。

• key 以bind或catch开头，然后跟上事件的类型，如bindtap, catchtouchstart
• value 是一个字符串，需要在对应的 Page 中定义同名的函数。不然当触发事件的时候会报错。

重点：bind事件绑定不会阻止冒泡事件向上冒泡，catch事件绑定可以阻止冒泡事件向上冒泡。

如在下边这个例子中，点击 inner view 会先后触发handleTap3和handleTap2(因为tap事件会冒泡到 middle view，而 middle view 阻止了 tap 事件冒泡，不再向父节点传递)，点击 middle view 会触发handleTap2，点击 outter view 会触发handleTap1。

<view id="outter" bindtap="handleTap1">
  outer view
  <view id="middle" catchtap="handleTap2">
    middle view
    <view id="inner" bindtap="handleTap3">
      inner view
    </view>
  </view>
</view>

引用

WXML 提供两种文件引用方式import和include。

import可以在该文件中使用目标文件定义的template，如：

#在 item.wxml 中定义了一个叫item的template：

<template name="item">
  <text>{{text}}</text>
</template>

在 index.wxml 中引用了 item.wxml，就可以使用item模板：

<import src="item.wxml"/>
<template is="item" data="{{text: 'forbar'}}"/>

import 的作用域

import 有作用域的概念，即只会 import 目标文件中定义的 template，而不会 import 目标文件 import 的 template。

如：C import B，B import A，在C中可以使用B定义的template，在B中可以使用A定义的template，但是C不能使用A定义的template。

include

include可以将目标文件除了<template/>的整个代码引入，相当于是拷贝到include位置，如：

<!-- index.wxml -->
<include src="header.wxml"/>
<view> body </view>
<include src="footer.wxml"/>

<!-- header.wxml -->
<view> header </view>

<!-- footer.wxml -->
<view> footer </view>

---

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

• rem（root em）: 规定屏幕宽度为20rem；1rem = (750/20)rpx 。

建议： 开发微信小程序时设计师可以用 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" />

---

 API快速学习

微信小程序中的localstorage（缓存） 

// API地址
https://mp.weixin.qq.com/debug/wxadoc/dev/api/data.html?t=20161122

// 设置缓存
wx.setStorageSync('logs', logs)

// 获取缓存
var logs = wx.getStorageSync('logs') || []