小程序中界面相关的api总结

交互反馈

wx.showToast(OBJECT)

显示消息提示框

OBJECT参数说明：

参数	类型	必填	说明	最低版本
title	String	是	提示的内容
icon	String	否	图标，有效值 "success", "loading", "none"
image	String	否	自定义图标的本地路径，image 的优先级高于 icon	1.1.0
duration	Number	否	提示的延迟时间，单位毫秒，默认：1500
mask	Boolean	否	是否显示透明蒙层，防止触摸穿透，默认：false
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

icon有效值

有效值	说明	最低版本
success	显示成功图标，此时 title 文本最多显示 7 个汉字长度。默认值
loading	显示加载图标，此时 title 文本最多显示 7 个汉字长度
none	不显示图标，此时 title 文本最多可显示两行	1.9.0

wx.showToast({
  title: '成功',
  icon: 'success',
  duration: 2000
})

wx.showLoading(OBJECT)

显示 loading 提示框, 需主动调用 wx.hideLoading 才能关闭提示框。基础库 1.1.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明
title	String	是	提示的内容
mask	Boolean	否	是否显示透明蒙层，防止触摸穿透，默认：false
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.hideToast()

隐藏消息提示框

wx.hideLoading()

隐藏 loading 提示框。基础库 1.1.0 开始支持，低版本需做兼容处理

wx.showLoading({
  title: '加载中',
})
setTimeout(function(){
  wx.hideLoading()
},2000)

wx.showModal(OBJECT)

​显示模态弹窗

OBJECT参数说明：

参数	类型	必填	说明
title	String	是	提示的标题
content	String	是	提示的内容
showCancel	Boolean	否	是否显示取消按钮，默认为 true
cancelText	String	否	取消按钮的文字，默认为"取消"，最多 4 个字符
cancelColor	HexColor	否	取消按钮的文字颜色，默认为"#000000"
confirmText	String	否	确定按钮的文字，默认为"确定"，最多 4 个字符
confirmColor	HexColor	否	确定按钮的文字颜色，默认为"#3CC51F"
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

success返回参数说明：

参数	类型	说明	最低版本
confirm	Boolean	为 true 时，表示用户点击了确定按钮
cancel	Boolean	为 true 时，表示用户点击了取消（用于 Android 系统区分点击蒙层关闭还是点击取消按钮关闭）	1.1.0

wx.showModal({
  title: '提示',
  content: '这是一个模态弹窗',
  success: function(res) {
    if (res.confirm) {
      console.log('用户点击确定')
    } else if (res.cancel) {
      console.log('用户点击取消')
    }
  }
})

wx.showActionSheet(OBJECT)

​显示操作菜单

OBJECT参数说明：

参数	类型	必填	说明
itemList	String Array	是	按钮的文字数组，数组长度最大为6个
itemColor	HexColor	否	按钮的文字颜色，默认为"#000000"
success	Function	否	接口调用成功的回调函数，详见返回参数说明
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

success返回参数说明：

参数	类型	说明
tapIndex	Number	用户点击的按钮，从上到下的顺序，从0开始

wx.showActionSheet({
  itemList: ['A', 'B', 'C'],
  success: function(res) {
    console.log(res.tapIndex)
  },
  fail: function(res) {
    console.log(res.errMsg)
  }
})

Bug & Tip

1.wx.showLoading 和 wx.showToast 同时只能显示一个，但 wx.hideToast/wx.hideLoading 也应当配对使用；

2.Android 6.3.30，wx.showModal 的返回的 confirm 一直为 true；

3.wx.showActionSheet wx.showModal 点击取消或蒙层时，回调 fail, errMsg 为 "fail cancel"；

4.Android 6.7.2 及以上版本 和 iOS wx.showActionSheet wx.showModal 点击蒙层不会关闭模态弹窗，所以尽量避免使用“取消”分支中实现业务逻辑

设置导航条

wx.setNavigationBarTitle(OBJECT)

动态设置当前页面的标题

OBJECT参数说明：

参数	类型	必填	说明
title	String	是	页面标题
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.setNavigationBarTitle({
  title: '当前页面'
})

wx.showNavigationBarLoading()

在当前页面显示导航条加载动画

wx.hideNavigationBarLoading()

隐藏导航条加载动画

wx.setNavigationBarColor(OBJECT)

基础库 1.4.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明
frontColor	String	是	前景颜色值，包括按钮、标题、状态栏的颜色，仅支持 #ffffff 和 #000000
backgroundColor	String	是	背景颜色值，有效值为十六进制颜色
animation	Object	否	动画效果
animation.duration	Number	否	动画变化时间，默认0，单位：毫秒
animation.timingFunc	String	否	动画变化方式，默认 linear
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

animation.timingFunc 有效值：

值	说明
linear	动画从头到尾的速度是相同的
easeIn	动画以低速开始
easeOut	动画以低速结束
easeInOut	动画以低速开始和结束

success返回参数说明：

参数	类型	说明
errMsg	String	调用结果

wx.setNavigationBarColor({
    frontColor: '#ffffff',
    backgroundColor: '#ff0000',
    animation: {
        duration: 400,
        timingFunc: 'easeIn'
    }
})

设置tabBar

wx.setTabBarBadge(OBJECT)

为 tabBar 某一项的右上角添加文本。基础库 1.9.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明
index	Number	是	tabBar的哪一项，从左边算起
text	String	是	显示的文本，超过 3 个字符则显示成“…”
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.setTabBarBadge({
  index: 0,
  text: '1'
})

wx.removeTabBarBadge(OBJECT)

移除 tabBar 某一项右上角的文本。基础库 1.9.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明
index	Number	是	tabBar的哪一项，从左边算起
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.showTabBarRedDot(OBJECT)

显示 tabBar 某一项的右上角的红点。基础库 1.9.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明
index	Number	是	tabBar的哪一项，从左边算起
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.hideTabBarRedDot(OBJECT)

隐藏 tabBar 某一项的右上角的红点。基础库 1.9.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明
index	Number	是	tabBar的哪一项，从左边算起
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

onTabItemTap

点击 tab 时触发。基础库 1.9.0 开始支持，低版本需做兼容处理

Page({
  onTabItemTap(item) {
    console.log(item.index)
    console.log(item.pagePath)
    console.log(item.text)
  }
})

wx.setTabBarStyle(OBJECT)

动态设置 tabBar 的整体样式。

OBJECT参数说明：

参数	类型	说明
color	HexColor	tab 上的文字默认颜色
selectedColor	HexColor	tab 上的文字选中时的颜色
backgroundColor	HexColor	tab 的背景色
borderStyle	String	tabbar上边框的颜色， 仅支持 black/white
success	Function	接口调用成功的回调函数
fail	Function	接口调用失败的回调函数
complete	Function	接口调用结束的回调函数(调用成功,失败都会执行)

wx.setTabBarStyle({
    color: '#FF0000',
    selectedColor: '#00FF00',
    backgroundColor: '#0000FF',
    borderStyle: 'white'
})

wx.setTabBarItem(OBJECT)

动态设置 tabBar 某一项的内容。基础库 1.9.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明
index	Number	是	tabBar的哪一项，从左边算起
text	String	否	tab 上按钮文字
iconPath	String	否	图片路径，icon 大小限制为40kb，建议尺寸为 81px * 81px，当 postion 为 top 时，此参数无效，不支持网络图片
selectedIconPath	String	否	选中时的图片路径，icon 大小限制为40kb，建议尺寸为 81px * 81px ，当 postion 为 top 时，此参数无效
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.setTabBarItem({
    index: 0,
    text: 'text',
    iconPath: '/path/to/iconPath',
    selectedIconPath: '/path/to/selectedIconPath'
})

wx.showTabBar(OBJECT)

显示 tabBar。基础库 1.9.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明
animation	Boolean	否	是否需要动画效果，默认无
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.hideTabBar(OBJECT)

隐藏 tabBar。基础库 1.9.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明
animation	Boolean	否	是否需要动画效果，默认无
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

设置窗口背景

wx.setBackgroundColor(OBJECT)

动态设置窗口的背景色。基础库 2.1.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	说明
backgroundColor	HexColor	窗口的背景色
backgroundColorTop	HexColor	顶部窗口的背景色，仅 iOS 支持
backgroundColorBottom	HexColor	底部窗口的背景色，仅 iOS 支持

wx.setBackgroundColor({
    backgroundColor: '#ffffff', // 窗口的背景色为白色
})
wx.setBackgroundColor({
    backgroundColorTop: '#ffffff', // 顶部窗口的背景色为白色
    backgroundColorBottom: '#ffffff', // 底部窗口的背景色为白色
})

wx.setBackgroundTextStyle(OBJECT)

动态设置下拉背景字体、loading 图的样式。基础库 2.1.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	说明
textStyle	String	下拉背景字体、loading 图的样式，仅支持 'dark', 'light'

wx.setBackgroundTextStyle({
    textStyle: 'dark', // 下拉背景字体、loading 图的样式为dark
})

设置置顶信息

wx.setTopBarText(OBJECT)

动态设置置顶栏文字内容，只有当前小程序被置顶时能生效，如果当前小程序没有被置顶，也能调用成功，但是不会立即生效，只有在用户将这个小程序置顶后才换上设置的文字内容。注意：调用成功后，需间隔 5s 才能再次调用此接口，如果在 5s 内再次调用此接口，会回调 fail，errMsg："setTopBarText: fail invoke too frequently"

OBJECT参数说明：

参数	类型	必填	说明
text	String	是	置顶栏文字内容
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.setTopBarText({
  text: 'hello, world!'
})

导航

wx.navigateTo(OBJECT)

保留当前页面，跳转到应用内的某个页面，使用wx.navigateBack可以返回到原页面

OBJECT参数说明：

参数	类型	必填	说明
url	String	是	需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.navigateTo({
  url: 'test?id=1'
})
//test.js
Page({
  onLoad: function(option){
    console.log(option.query)
  }
})

注意：目前页面路径最多只能十层

wx.redirectTo(OBJECT)

关闭当前页面，跳转到应用内的某个页面

OBJECT参数说明：

参数	类型	必填	说明
url	String	是	需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.redirectTo({
  url: 'test?id=1'
})

wx.reLaunch(OBJECT)

关闭所有页面，打开到应用内的某个页面。基础库 1.1.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明
url	String	是	需要跳转的应用内页面的路径,路径后可以带参数,参数与路径之间使用?分隔,参数键与参数值用=相连,不同参数用&分隔,如'path?key=value&key2=value2',如果跳转的页面路径是tabBar页面则不能带参数
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

wx.reLaunch({
  url: 'test?id=1'
})
//test.js
Page({
  onLoad: function(option){
    console.log(option.query)
  }
})

wx.switchTab(OBJECT)

跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面

OBJECT参数说明：

参数	类型	必填	说明
url	String	是	需要跳转的 tabBar 页面的路径（需在 app.json 的 tabBar 字段定义的页面），路径后不能带参数
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数(调用成功,失败都会执行)

{
  "tabBar": {
    "list": [{
      "pagePath": "index",
      "text": "首页"
    },{
      "pagePath": "other",
      "text": "其他"
    }]
  }
}
wx.switchTab({
  url: '/index'
})

wx.navigateBack(OBJECT)

关闭当前页面，返回上一页面或多级页面。可通过 getCurrentPages() 获取当前的页面栈，决定需要返回几层

OBJECT参数说明：

参数	类型	默认值	说明
delta	Number	1	返回的页面数，如果 delta 大于现有页面数，则返回到首页

// 注意：调用 navigateTo 跳转时，调用该方法的页面会被加入堆栈，而 redirectTo 方法则不会。见下方示例代码
// 此处是A页面
wx.navigateTo({
  url: 'B?id=1'
})
// 此处是B页面
wx.navigateTo({
  url: 'C?id=1'
})
// 在C页面内 navigateBack，将返回A页面
wx.navigateBack({
  delta: 2
})

tip: wx.navigateTo 和 wx.redirectTo 不允许跳转到 tabbar 页面，只能用 wx.switchTab 跳转到 tabbar 页面

动画

wx.createAnimation(OBJECT)

创建一个动画实例animation。调用实例的方法来描述动画。最后通过动画实例的export方法导出动画数据传递给组件的animation属性。

注意: export 方法每次调用后会清掉之前的动画操作

OBJECT参数说明：

参数	类型	必填	说明
duration	Integer	否	动画持续时间，单位ms
timingFunction	String	否	定义动画的效果
delay	Integer	否	动画延迟时间，单位 ms
transformOrigin	String	否	设置transform-origin

timingFunction 有效值：

值	说明
linear	动画从头到尾的速度是相同的
ease	动画以低速开始，然后加快，在结束前变慢
ease-in	动画以低速开始
ease-in-out	动画以低速开始和结束
ease-out	动画以低速结束
step-start	动画第一帧就跳至结束状态直到结束
step-end	动画一直保持开始状态，最后一帧跳到结束状态

var animation = wx.createAnimation({
  transformOrigin: "50% 50%",
  duration: 1000,
  timingFunction: "ease",
  delay: 0
})

animation

动画实例可以调用以下方法来描述动画，调用结束后会返回自身，支持链式调用的写法

animation 对象的方法列表：

样式：

方法	参数	说明
opacity	value	透明度，参数范围 0~1
backgroundColor	color	颜色值
width	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值
height	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值
top	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值
left	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值
bottom	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值
right	length	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值

旋转：

方法	参数	说明
rotate	deg	deg的范围-180~180，从原点顺时针旋转一个deg角度
rotateX	deg	deg的范围-180~180，在X轴旋转一个deg角度
rotateY	deg	deg的范围-180~180，在Y轴旋转一个deg角度
rotateZ	deg	deg的范围-180~180，在Z轴旋转一个deg角度
rotate3d	(x,y,z,deg)	x/y/z分别表示旋转轴X/Y/Z坐标方向的矢量,deg表示旋转角度,正的角度值表示顺时针旋转,负值表示逆时针旋转

缩放：

方法	参数	说明
scale	sx,[sy]	一个参数时，表示在X轴、Y轴同时缩放sx倍数；两个参数时表示在X轴缩放sx倍数，在Y轴缩放sy倍数
scaleX	sx	在X轴缩放sx倍数
scaleY	sy	在Y轴缩放sy倍数
scaleZ	sz	在Z轴缩放sy倍数
scale3d	(sx,sy,sz)	在X轴缩放sx倍数，在Y轴缩放sy倍数，在Z轴缩放sz倍数

偏移：

方法	参数	说明
translate	tx,[ty]	一个参数时，表示在X轴偏移tx，单位px；两个参数时，表示在X轴偏移tx，在Y轴偏移ty，单位px
translateX	tx	在X轴偏移tx，单位px
translateY	ty	在Y轴偏移tx，单位px
translateZ	tz	在Z轴偏移tx，单位px
translate3d	(tx,ty,tz)	在X轴偏移tx，在Y轴偏移ty，在Z轴偏移tz，单位px

倾斜：

方法	参数	说明
skew	ax,[ay]	参数范围-180~180；一个参数时，Y轴坐标不变，X轴坐标延顺时针倾斜ax度；两个参数时，分别在X轴倾斜ax度，在Y轴倾斜ay度
skewX	ax	参数范围-180~180；Y轴坐标不变，X轴坐标延顺时针倾斜ax度
skewY	ay	参数范围-180~180；X轴坐标不变，Y轴坐标延顺时针倾斜ay度

矩阵变形：

方法	参数	说明
matrix	(a,b,c,d,tx,ty)
matrix3d

动画队列

调用动画操作方法后要调用 step() 来表示一组动画完成，可以在一组动画中调用任意多个动画方法，一组动画中的所有动画会同时开始，一组动画完成后才会进行下一组动画。step 可以传入一个跟 wx.createAnimation() 一样的配置参数用于指定当前组动画的配置

<view animation="{{animationData}}" style="background:red;height:100rpx;width:100rpx"></view>
<script>
Page({
  data: {
    animationData: {}
  },
  onShow: function(){
    var animation = wx.createAnimation({
      duration: 1000,
      timingFunction: 'ease',
    })
    this.animation = animation    
    animation.scale(2,2).rotate(45).step()    
    this.setData({
      animationData:animation.export()
    })    
    setTimeout(function() {
      animation.translate(30).step()
      this.setData({
        animationData:animation.export()
      })
    }.bind(this), 1000)
  },
  rotateAndScale: function () {// 旋转同时放大    
    this.animation.rotate(45).scale(2, 2).step()
    this.setData({
      animationData: this.animation.export()
    })
  },
  rotateThenScale: function () { // 先旋转后放大   
    this.animation.rotate(45).step()
    this.animation.scale(2, 2).step()
    this.setData({
      animationData: this.animation.export()
    })
  },
  rotateAndScaleThenTranslate: function () {// 先旋转同时放大，然后平移    
    this.animation.rotate(45).scale(2, 2).step()
    this.animation.translate(100, 100).step({ duration: 1000 })
    this.setData({
      animationData: this.animation.export()
    })
  }
})
</script>

bug: iOS/Android 6.3.30 通过 step() 分隔动画，只有第一步动画能生效

位置

wx.pageScrollTo(OBJECT)：将页面滚动到目标位置。基础库 1.4.0 开始支持，低版本需做兼容处理

参数名	类型	必填	说明
scrollTop	Number	是	滚动到页面的目标位置（单位px）
duration	Number	否	滚动动画的时长，默认300ms，单位 ms

wx.pageScrollTo({
  scrollTop: 0,
  duration: 300
})

绘图

在Canvas上画图

所有在 中的画图必须用 JavaScript 完成

WXML：（我们在接下来的例子中如无特殊声明都会用这个 WXML 为模板，不再重复）

<canvas canvas-id="myCanvas" style="border: 1px solid;"/>

JS：（我们在接下来的例子中会将 JS 放在 onLoad 中）

const ctx = wx.createCanvasContext('myCanvas')
ctx.setFillStyle('red')
ctx.fillRect(10, 10, 150, 75)
ctx.draw()

第一步：创建一个 Canvas 绘图上下文

首先，我们需要创建一个 Canvas 绘图上下文 CanvasContext。

CanvasContext 是小程序内建的一个对象，有一些绘图的方法：

const ctx = wx.createCanvasContext('myCanvas')

第二步：使用 Canvas 绘图上下文进行绘图描述

接着，我们来描述要在 Canvas 中绘制什么内容。设置绘图上下文的填充色为红色：

ctx.setFillStyle('red')

用 fillRect(x, y, width, height) 方法画一个矩形，填充为刚刚设置的红色：

ctx.fillRect(10, 10, 150, 75)

第三步：画图

告诉 组件你要将刚刚的描述绘制上去：

ctx.draw()

Canvas 坐标系

canvas 是在一个二维的网格当中。左上角的坐标为(0, 0)。

之前我们用了这个方法 fillRect(0, 0, 150, 75)，它的含义为：从左上角(0, 0)开始，画一个150 x 75px 的矩形

坐标系例子：

我们可以在 中加上一些事件，来观测它的坐标系

<canvas canvas-id="myCanvas" style="margin: 5px; border:1px solid #d3d3d3;" bindtouchstart="start" bindtouchmove="move" bindtouchend="end"/>
<view hidden="{{hidden}}">
  Coordinates: ({{x}}, {{y}})
</view>
<script>
Page({
  data: {
    x: 0,
    y: 0,
    hidden: true
  },
  start: function(e) {
    this.setData({
      hidden: false,
      x: e.touches[0].x,
      y: e.touches[0].y
    })
  },
  move: function(e) {
    this.setData({
      x: e.touches[0].x,
      y: e.touches[0].y
    })
  },
  end: function(e) {
    this.setData({
      hidden: true
    })
  }
})  
</script>

当你把手指放到 canvas 中，就会在下边显示出触碰点的坐标

渐变

渐变能用于填充一个矩形，圆，线，文字等。填充色可以不固定为一种颜色。我们提供了两种颜色渐变的方式：

createLinearGradient(x, y, x1, y1) - 创建一个线性的渐变
createCircularGradient(x, y, r) - 创建一个从圆心开始的渐变

一旦我们创建了一个渐变对象，我们必须添加两个颜色渐变点。

addColorStop(position, color) 方法用于指定颜色渐变点的位置和颜色，位置必须位于0到1之间。

可以用setFillStyle() 和 setStrokeStyle() 方法设置渐变，然后进行画图描述

使用 createLinearGradient()

const ctx = wx.createCanvasContext('myCanvas')
// Create linear gradient
const grd = ctx.createLinearGradient(0, 0, 200, 0)
grd.addColorStop(0, 'red')
grd.addColorStop(1, 'white')
// Fill with gradient
ctx.setFillStyle(grd)
ctx.fillRect(10, 10, 150, 80)
ctx.draw()

使用 createCircularGradient()

const ctx = wx.createCanvasContext('myCanvas')
// Create circular gradient
const grd = ctx.createCircularGradient(75, 50, 50)
grd.addColorStop(0, 'red')
grd.addColorStop(1, 'white')
// Fill with gradient
ctx.setFillStyle(grd)
ctx.fillRect(10, 10, 150, 80)
ctx.draw()

api接口

方法	说明
createCanvasContext	创建 canvas 绘图上下文(指定 canvasId)
createContext(不推荐使用)	创建 canvas 绘图上下文
drawCanvas(不推荐使用)	进行绘图
canvasToTempFilePath	导出图片

context 对象的方法列表

颜色，样式，阴影

方法	说明
setFillStyle	设置填充样式
setStrokeStyle	设置线条样式
setShadow	设置阴影

渐变

方法	说明
createLinearGradient	创建一个线性渐变
createCircularGradient	创建一个圆形渐变
addColorStop	在渐变中的某一点添加一个颜色变化

线条样式

方法	说明
setLineWidth	设置线条宽度
setLineCap	设置线条端点的样式
setLineJoin	设置两线相交处的样式
setMiterLimit	设置最大倾斜

矩形

方法	说明
fill	对当前路径进行填充
stroke	对当前路径进行描边
beginPath	开始一个路径
closePath	关闭一个路径
moveTo	把路径移动到画布中的指定点，但不创建线条
lineTo	添加一个新点，然后在画布中创建从该点到最后指定点的线条
arc	添加一个弧形路径到当前路径，顺时针绘制
quadraticCurveTo	创建二次方贝塞尔曲线
quadraticCurveTo	bezierCurveTo

变形

方法	说明
scale	对横纵坐标进行缩放
rotate	对坐标轴进行顺时针旋转
translate	对坐标原点进行缩放

文字

方法	说明
fillText	在画布上绘制被填充的文本
setFontSize	设置字体大小
setTextBaseline	设置字体基准线
setTextAlign	设置字体对齐方式

图片

方法	说明
drawImage	在画布上绘制图像

混合

方法	说明
setGlobalAlpha	设置全局画笔透明度

其他

方法	说明
save	保存当前绘图上下文
restore	恢复之前保存过的绘图上下文
draw	进行绘图
getActions(不推荐使用)	获取当前context上存储的绘图动作
clearActions(不推荐使用)	清空当前的存储绘图动作

color

可以用以下几种方式来表示 canvas 中使用的颜色：

1.RGB 颜色： 如 'rgb(255, 0, 0)'

2.RGBA 颜色：如 'rgba(255, 0, 0, 0.3)'

3.16 进制颜色： 如 '#FF0000'

4.预定义的颜色： 如 'red'

其中预定义颜色有以下148个：

Note: Color Name 大小写不敏感

wx.createCanvasContext(canvasId, this)

定义：创建 canvas 绘图上下文（指定 canvasId）。在自定义组件下，第二个参数传入组件实例this，以操作组件内 组件

Tip: 需要指定 canvasId，该绘图上下文只作用于对应的

其他

参数	类型	说明
canvasId	String	画布标识，传入定义在 的 canvas-id
componentInstance	Object	自定义组件实例 this ，表示在这个自定义组件下查找拥有 canvas-id 的 ，如果省略，则不在任何自定义组件内查找

wx.createContext

创建并返回绘图上下文(不推荐使用)

drawCanvas

定义：用所提供的 actions 在所给的 canvas-id 对应的 canvas 上进行绘图(不推荐使用)

参数	类型	说明
canvasId	String	画布标识，传入定义在 的 canvas-id
actions	Array	绘图动作数组，由 wx.createContext 创建的 context，调用 getActions 方法导出绘图动作数组
reserve	Boolean	(可选)本次绘制是否接着上一次绘制，即reserve参数为false，则在本次调用drawCanvas绘制之前native层应先清空画布再继续绘制；若reserver参数为true，则保留当前画布上的内容，本次调用drawCanvas绘制的内容覆盖在上面，默认 false

wx.canvasToTempFilePath(OBJECT, this)

把当前画布指定区域的内容导出生成指定大小的图片，并返回文件路径。在自定义组件下，第二个参数传入组件实例this，以操作组件内 组件

OBJECT参数说明：

参数	类型	必填	说明	最低版本
x	Number	否	画布x轴起点（默认0）	1.2.0
y	Number	否	画布y轴起点（默认0）	1.2.0
width	Number	否	画布宽度（默认为canvas宽度-x）	1.2.0
height	Number	否	画布高度（默认为canvas高度-y）	1.2.0
destWidth	Number	否	输出图片宽度（默认为 width * 屏幕像素密度）	1.2.0
destHeight	Number	否	输出图片高度（默认为 height * 屏幕像素密度）	1.2.0
canvasId	String	是	画布标识，传入 的 canvas-id
fileType	String	否	目标文件的类型，只支持 'jpg' 或 'png'。默认为 'png'	1.7.0
quality	Number	否	图片的质量，目前仅对jpg有效。取值范围为 (0, 1]，不在范围内时当作1.0处理	1.7.0
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

tip: 在 draw 回调里调用该方法才能保证图片导出成功

wx.canvasToTempFilePath({
  x: 100,
  y: 200,
  width: 50,
  height: 50,
  destWidth: 100,
  destHeight: 100,
  canvasId: 'myCanvas',
  success: function(res) {
    console.log(res.tempFilePath)
  } 
})

wx.canvasGetImageData(OBJECT, this)

返回一个数组，用来描述 canvas 区域隐含的像素数据。在自定义组件下，第二个参数传入组件实例this，以操作组件内 组件。基础库 1.9.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明	最低版本
canvasId	String	是	画布标识，传入 的 canvas-id
x	Number	是	将要被提取的图像数据矩形区域的左上角 x 坐标
y	Number	是	将要被提取的图像数据矩形区域的左上角 y 坐标
width	Number	是	将要被提取的图像数据矩形区域的宽度
height	Number	是	将要被提取的图像数据矩形区域的高度
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success回调返回参数：

参数	类型	说明
errMsg	String
width	Number	图像数据矩形的宽度
height	Number	图像数据矩形的高度
data	Uint8ClampedArray	图像像素点数据，一维数组，每四项表示一个像素点的rgba

wx.canvasGetImageData({
  canvasId: 'myCanvas',
  x: 0,
  y: 0,
  width: 100,
  height: 100,
  success(res) {
    console.log(res.width) // 100
    console.log(res.height) // 100
    console.log(res.data instanceof Uint8ClampedArray) // true
    console.log(res.data.length) // 100 * 100 * 4
  }
})

wx.canvasPutImageData(OBJECT, this)

将像素数据绘制到画布的方法。在自定义组件下，第二个参数传入组件实例this，以操作组件内 组件。基础库 1.9.0 开始支持，低版本需做兼容处理

OBJECT参数说明：

参数	类型	必填	说明	最低版本
canvasId	String	是	画布标识，传入 的 canvas-id
data	Uint8ClampedArray	是	图像像素点数据，一维数组，每四项表示一个像素点的rgba
x	Number	是	源图像数据在目标画布中的位置偏移量（x 轴方向的偏移量）
y	Number	是	源图像数据在目标画布中的位置偏移量（y 轴方向的偏移量）
width	Number	是	源图像数据矩形区域的宽度
height	Number	是	源图像数据矩形区域的高度
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

const data = new Uint8ClampedArray([255, 0, 0, 1])
wx.canvasPutImageData({
  canvasId: 'myCanvas',
  x: 0,
  y: 0,
  width: 1,
  data: data,
  success(res) {}
})

canvasContext.setFillStyle

设置填充色。

Tip: 如果没有设置 fillStyle，默认颜色为 black

语法

canvasContext.setFillStyle(color)
canvasContext.fillStyle = color // 基础库 1.9.90 起支持

参数	类型	定义
color	color	Gradient Object

const ctx = wx.createCanvasContext('myCanvas')
ctx.setFillStyle('red')
ctx.fillRect(10, 10, 150, 75)
ctx.draw()

canvasContext.setStrokeStyle

设置边框颜色

Tip: 如果没有设置 fillStyle，默认颜色为 black

canvasContext.setStrokeStyle(color)
canvasContext.strokeStyle = color // 基础库 1.9.90 起支持

参数	类型	定义
color	color	Gradient Object

const ctx = wx.createCanvasContext('myCanvas')
ctx.setStrokeStyle('red')
ctx.strokeRect(10, 10, 150, 75)
ctx.draw()

canvasContext.setShadow

设置阴影样式。

Tip: 如果没有设置，offsetX 默认值为0， offsetY 默认值为0， blur 默认值为0，color 默认值为 black

参数	类型	范围	定义
offset	Number		阴影相对于形状在水平方向的偏移
offset	Number		阴影相对于形状在竖直方向的偏移
blur	Number	0~100	阴影的模糊级别，数值越大越模糊
color	color		阴影的颜色

const ctx = wx.createCanvasContext('myCanvas')
ctx.setFillStyle('red')
ctx.setShadow(10, 50, 50, 'blue')
ctx.fillRect(10, 10, 150, 75)
ctx.draw()

canvasContext.shadowBlur

设置阴影的模糊级别。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.shadowBlur = value

canvasContext.shadowColor

设置阴影的颜色。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.shadowColor = value

canvasContext.shadowOffsetX

设置阴影相对于形状在水平方向的偏移。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.shadowOffsetX = value

canvasContext.shadowOffsetY

设置阴影相对于形状在竖直方向的偏移。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.shadowOffsetY = value

canvasContext.createLinearGradient

创建一个线性的渐变颜色

Tip: 需要使用 addColorStop() 来指定渐变点，至少要两个

参数	类型	定义
X0	Number	起点的x坐标
Y0	Number	起点的y坐标
X1	Number	终点的x坐标
Y1	Number	终点的y坐标

const ctx = wx.createCanvasContext('myCanvas')
// Create linear gradient
const grd = ctx.createLinearGradient(0, 0, 200, 0)
grd.addColorStop(0, 'red')
grd.addColorStop(1, 'white')
// Fill with gradient
ctx.setFillStyle(grd)
ctx.fillRect(10, 10, 150, 80)
ctx.draw()

canvasContext.createCircularGradient

创建一个圆形的渐变颜色。

Tip:

1.起点在圆心，终点在圆环。

2.需要使用 addColorStop() 来指定渐变点，至少要两个

参数	类型	定义
X	Number	圆心的x坐标
Y	Number	圆心的y坐标
r	Number	圆的半径

const ctx = wx.createCanvasContext('myCanvas')
// Create circular gradient
const grd = ctx.createCircularGradient(75, 50, 50)
grd.addColorStop(0, 'red')
grd.addColorStop(1, 'white')
// Fill with gradient
ctx.setFillStyle(grd)
ctx.fillRect(10, 10, 150, 80)
ctx.draw()

canvasContext.addColorStop

创建一个颜色的渐变点。

Tip:

1.小于最小 stop 的部分会按最小 stop 的 color 来渲染，大于最大 stop 的部分会按最大 stop 的 color 来渲染。

2.需要使用 addColorStop() 来指定渐变点，至少要两个

参数	类型	定义
stop	Number(0-1)	表示渐变点在起点和终点中的位置
color	color	渐变点的颜色

const ctx = wx.createCanvasContext('myCanvas')
// Create circular gradient
const grd = ctx.createLinearGradient(30, 10, 120, 10)
grd.addColorStop(0, 'red')
grd.addColorStop(0.16, 'orange')
grd.addColorStop(0.33, 'yellow')
grd.addColorStop(0.5, 'green')
grd.addColorStop(0.66, 'cyan')
grd.addColorStop(0.83, 'blue')
grd.addColorStop(1, 'purple')
// Fill with gradient
ctx.setFillStyle(grd)
ctx.fillRect(10, 10, 150, 80)
ctx.draw()

canvasContext.setLineWidth

设置线条的宽度

语法

canvasContext.setLineWidth(lineWidth)
canvasContext.lineWidth = lineWidth // 基础库 1.9.90 起支持

参数	类型	定义
lineWidth	Number	线条的宽度(单位是px)

const ctx = wx.createCanvasContext('myCanvas')
ctx.beginPath()
ctx.moveTo(10, 10)
ctx.lineTo(150, 10)
ctx.stroke()
ctx.beginPath()
ctx.setLineWidth(5)
ctx.moveTo(10, 30)
ctx.lineTo(150, 30)
ctx.stroke()
ctx.beginPath()
ctx.setLineWidth(10)
ctx.moveTo(10, 50)
ctx.lineTo(150, 50)
ctx.stroke()
ctx.beginPath()
ctx.setLineWidth(15)
ctx.moveTo(10, 70)
ctx.lineTo(150, 70)
ctx.stroke()
ctx.draw()

canvasContext.setLineCap

设置线条的端点样式

语法

canvasContext.setLineCap(lineCap)
canvasContext.lineCap = lineCap // 基础库 1.9.90 起支持

参数	类型	范围	说明
lineCap	String	'butt'、'round'、'square'	线条的结束端点样式

const ctx = wx.createCanvasContext('myCanvas')
ctx.beginPath()
ctx.moveTo(10, 10)
ctx.lineTo(150, 10)
ctx.stroke()

ctx.beginPath()
ctx.setLineCap('butt')
ctx.setLineWidth(10)
ctx.moveTo(10, 30)
ctx.lineTo(150, 30)
ctx.stroke()

ctx.beginPath()
ctx.setLineCap('round')
ctx.setLineWidth(10)
ctx.moveTo(10, 50)
ctx.lineTo(150, 50)
ctx.stroke()

ctx.beginPath()
ctx.setLineCap('square')
ctx.setLineWidth(10)
ctx.moveTo(10, 70)
ctx.lineTo(150, 70)
ctx.stroke()

ctx.draw()

canvasContext.setLineJoin

设置线条的交点样式

语法

canvasContext.setLineJoin(lineJoin)
canvasContext.lineJoin = lineJoin // 基础库 1.9.90 起支持

参数	类型	范围	说明
lineJoin	String	'bevel'、'round'、'miter'	线条的结束交点样式

const ctx = wx.createCanvasContext('myCanvas')
ctx.beginPath()
ctx.moveTo(10, 10)
ctx.lineTo(100, 50)
ctx.lineTo(10, 90)
ctx.stroke()

ctx.beginPath()
ctx.setLineJoin('bevel')
ctx.setLineWidth(10)
ctx.moveTo(50, 10)
ctx.lineTo(140, 50)
ctx.lineTo(50, 90)
ctx.stroke()

ctx.beginPath()
ctx.setLineJoin('round')
ctx.setLineWidth(10)
ctx.moveTo(90, 10)
ctx.lineTo(180, 50)
ctx.lineTo(90, 90)
ctx.stroke()

ctx.beginPath()
ctx.setLineJoin('miter')
ctx.setLineWidth(10)
ctx.moveTo(130, 10)
ctx.lineTo(220, 50)
ctx.lineTo(130, 90)
ctx.stroke()

ctx.draw()

canvasContext.setLineDash

设置虚线样式的方法。基础库 1.6.0 开始支持，低版本需做兼容处理

参数	类型	说明
pattern	Array	一组描述交替绘制线段和间距（坐标空间单位）长度的数字
offset	Number	虚线偏移量

const ctx = wx.createCanvasContext('myCanvas')
ctx.setLineDash([10, 20], 5);
ctx.beginPath();
ctx.moveTo(0,100);
ctx.lineTo(400, 100);
ctx.stroke();
ctx.draw()

canvasContext.setMiterLimit

设置最大斜接长度，斜接长度指的是在两条线交汇处内角和外角之间的距离。 当 setLineJoin() 为 miter 时才有效。超过最大倾斜长度的，连接处将以 lineJoin 为 bevel 来显示

语法

canvasContext.setMiterLimit(miterLimit)
canvasContext.miterLimit = miterLimit // 基础库 1.9.90 起支持

参数	类型	说明
miterLimit	Number	最大斜接长度

const ctx = wx.createCanvasContext('myCanvas')
ctx.beginPath()
ctx.setLineWidth(10)
ctx.setLineJoin('miter')
ctx.setMiterLimit(1)
ctx.moveTo(10, 10)
ctx.lineTo(100, 50)
ctx.lineTo(10, 90)
ctx.stroke()

ctx.beginPath()
ctx.setLineWidth(10)
ctx.setLineJoin('miter')
ctx.setMiterLimit(2)
ctx.moveTo(50, 10)
ctx.lineTo(140, 50)
ctx.lineTo(50, 90)
ctx.stroke()

ctx.beginPath()
ctx.setLineWidth(10)
ctx.setLineJoin('miter')
ctx.setMiterLimit(3)
ctx.moveTo(90, 10)
ctx.lineTo(180, 50)
ctx.lineTo(90, 90)
ctx.stroke()

ctx.beginPath()
ctx.setLineWidth(10)
ctx.setLineJoin('miter')
ctx.setMiterLimit(4)
ctx.moveTo(130, 10)
ctx.lineTo(220, 50)
ctx.lineTo(130, 90)
ctx.stroke()

ctx.draw()

canvasContext.rect

创建一个矩形

Tip: 用 fill() 或者 stroke() 方法将矩形真正的画到 canvas 中

参数	类型	定义
X	Number	矩形路径左上角的x坐标
Y	Number	矩形路径左上角的y坐标
width	Number	矩形路径的宽度
height	Number	矩形路径的高度

const ctx = wx.createCanvasContext('myCanvas')
ctx.rect(10, 10, 150, 75)
ctx.setFillStyle('red')
ctx.fill()
ctx.draw()

canvasContext.fillRect

填充一个矩形

Tip: 用 setFillStyle() 设置矩形的填充色，如果没设置默认是黑色

参数	类型	定义
X	Number	矩形路径左上角的x坐标
Y	Number	矩形路径左上角的y坐标
width	Number	矩形路径的宽度
height	Number	矩形路径的高度

const ctx = wx.createCanvasContext('myCanvas')
ctx.setFillStyle('red')
ctx.fillRect(10, 10, 150, 75)
ctx.draw()

canvasContext.strokeRect

画一个矩形(非填充)

Tip: 用 setFillStroke() 设置矩形线条的颜色，如果没设置默认是黑色

参数	类型	定义
X	Number	矩形路径左上角的x坐标
Y	Number	矩形路径左上角的y坐标
width	Number	矩形路径的宽度
height	Number	矩形路径的高度

const ctx = wx.createCanvasContext('myCanvas')
ctx.setStrokeStyle('red')
ctx.strokeRect(10, 10, 150, 75)
ctx.draw()

canvasContext.clearRect

清除画布上在该矩形区域内的内容

Tip: clearRect 并非画一个白色的矩形在地址区域，而是清空，为了有直观感受，对 canvas 加了一层背景色

<canvas canvas-id="myCanvas" style="border: 1px solid; background: #123456;"/>

参数	类型	定义
X	Number	矩形区域左上角的x坐标
Y	Number	矩形区域左上角的y坐标
width	Number	矩形区域的宽度
height	Number	矩形区域的高度

const ctx = wx.createCanvasContext('myCanvas')
ctx.setFillStyle('red')
ctx.fillRect(0, 0, 150, 200)
ctx.setFillStyle('blue')
ctx.fillRect(150, 0, 150, 200)
ctx.clearRect(10, 10, 150, 75)
ctx.draw()

canvasContext.fill

对当前路径中的内容进行填充。默认的填充色为黑色。

Tip:

1.如果当前路径没有闭合，fill() 方法会将起点和终点进行连接，然后填充

2.fill() 填充的的路径是从 beginPath() 开始计算，但是不会将 fillRect() 包含进去

const ctx = wx.createCanvasContext('myCanvas')
ctx.moveTo(10, 10)
ctx.lineTo(100, 10)
ctx.lineTo(100, 100)
ctx.fill()
ctx.draw()

const ctx = wx.createCanvasContext('myCanvas')
// begin path
ctx.rect(10, 10, 100, 30)
ctx.setFillStyle('yellow')
ctx.fill()
// begin another path
ctx.beginPath()
ctx.rect(10, 40, 100, 30)
// only fill this rect, not in current path
ctx.setFillStyle('blue')
ctx.fillRect(10, 70, 100, 30)
ctx.rect(10, 100, 100, 30)
// it will fill current path
ctx.setFillStyle('red')
ctx.fill()
ctx.draw()

canvasContext.stroke

画出当前路径的边框。默认颜色色为黑色。

Tip: stroke() 描绘的的路径是从 beginPath() 开始计算，但是不会将 strokeRect() 包含进去

const ctx = wx.createCanvasContext('myCanvas')
ctx.moveTo(10, 10)
ctx.lineTo(100, 10)
ctx.lineTo(100, 100)
ctx.stroke()
ctx.draw()

const ctx = wx.createCanvasContext('myCanvas')
// begin path
ctx.rect(10, 10, 100, 30)
ctx.setStrokeStyle('yellow')
ctx.stroke()
// begin another path
ctx.beginPath()
ctx.rect(10, 40, 100, 30)
// only stoke this rect, not in current path
ctx.setStrokeStyle('blue')
ctx.strokeRect(10, 70, 100, 30)
ctx.rect(10, 100, 100, 30)
// it will stroke current path
ctx.setStrokeStyle('red')
ctx.stroke()
ctx.draw()

canvasContext.beginPath

开始创建一个路径，需要调用fill或者stroke才会使用路径进行填充或描边。

Tip:

1.在最开始的时候相当于调用了一次 beginPath()。

2.同一个路径内的多次setFillStyle()、setStrokeStyle()、setLineWidth()等设置，以最后一次设置为准

const ctx = wx.createCanvasContext('myCanvas')
// begin path
ctx.rect(10, 10, 100, 30)
ctx.setFillStyle('yellow')
ctx.fill()
// begin another path
ctx.beginPath()
ctx.rect(10, 40, 100, 30)
// only fill this rect, not in current path
ctx.setFillStyle('blue')
ctx.fillRect(10, 70, 100, 30)
ctx.rect(10, 100, 100, 30)
// it will fill current path
ctx.setFillStyle('red')
ctx.fill()
ctx.draw()

canvasContext.closePath

关闭一个路径

Tip:

1.关闭路径会连接起点和终点。

2.如果关闭路径后没有调用 fill() 或者 stroke() 并开启了新的路径，那之前的路径将不会被渲染

const ctx = wx.createCanvasContext('myCanvas')
ctx.moveTo(10, 10)
ctx.lineTo(100, 10)
ctx.lineTo(100, 100)
ctx.closePath()
ctx.stroke()
ctx.draw()

const ctx = wx.createCanvasContext('myCanvas')
// begin path
ctx.rect(10, 10, 100, 30)
ctx.closePath()
// begin another path
ctx.beginPath()
ctx.rect(10, 40, 100, 30)
// only fill this rect, not in current path
ctx.setFillStyle('blue')
ctx.fillRect(10, 70, 100, 30)
ctx.rect(10, 100, 100, 30)
// it will fill current path
ctx.setFillStyle('red')
ctx.fill()
ctx.draw()

canvasContext.moveTo

把路径移动到画布中的指定点，不创建线条。

Tip: 用 stroke() 方法来画线条

参数	类型	定义
X	Number	目标位置的x坐标
Y	Number	目标位置的y坐标

const ctx = wx.createCanvasContext('myCanvas')
ctx.moveTo(10, 10)
ctx.lineTo(100, 10)
ctx.moveTo(10, 50)
ctx.lineTo(100, 50)
ctx.stroke()
ctx.draw()

canvasContext.lineTo

lineTo 方法增加一个新点，然后创建一条从上次指定点到目标点的线。

Tip: 用 stroke() 方法来画线条

参数	类型	定义
X	Number	目标位置的x坐标
Y	Number	目标位置的y坐标

const ctx = wx.createCanvasContext('myCanvas')
ctx.moveTo(10, 10)
ctx.rect(10, 10, 100, 50)
ctx.lineTo(110, 60)
ctx.stroke()
ctx.draw()

canvasContext.arc

画一条弧线。

Tip:

1.创建一个圆可以用 arc() 方法指定起始弧度为0，终止弧度为 2 * Math.PI。

2.用 stroke() 或者 fill() 方法来在 canvas 中画弧线

参数	类型	定义
X	Number	圆的x坐标
Y	Number	圆的y坐标
r	Number	圆的半径
sAngle	Number	起始弧度，单位弧度（在3点钟方向）
eAngle	Number	终止弧度
counterclockwise	Boolean	可选。指定弧度的方向是逆时针还是顺时针。默认是false，即顺时针

const ctx = wx.createCanvasContext('myCanvas')
// Draw coordinates
ctx.arc(100, 75, 50, 0, 2 * Math.PI)
ctx.setFillStyle('#EEEEEE')
ctx.fill()
ctx.beginPath()
ctx.moveTo(40, 75)
ctx.lineTo(160, 75)
ctx.moveTo(100, 15)
ctx.lineTo(100, 135)
ctx.setStrokeStyle('#AAAAAA')
ctx.stroke()
ctx.setFontSize(12)
ctx.setFillStyle('black')
ctx.fillText('0', 165, 78)
ctx.fillText('0.5*PI', 83, 145)
ctx.fillText('1*PI', 15, 78)
ctx.fillText('1.5*PI', 83, 10)
// Draw points
ctx.beginPath()
ctx.arc(100, 75, 2, 0, 2 * Math.PI)
ctx.setFillStyle('lightgreen')
ctx.fill()
ctx.beginPath()
ctx.arc(100, 25, 2, 0, 2 * Math.PI)
ctx.setFillStyle('blue')
ctx.fill()
ctx.beginPath()
ctx.arc(150, 75, 2, 0, 2 * Math.PI)
ctx.setFillStyle('red')
ctx.fill()
// Draw arc
ctx.beginPath()
ctx.arc(100, 75, 50, 0, 1.5 * Math.PI)
ctx.setStrokeStyle('#333333')
ctx.stroke()
ctx.draw()

针对 arc(100, 75, 50, 0, 1.5 * Math.PI)的三个关键坐标如下：

圆心 (100, 75) 起始弧度 (0) 终止弧度 (1.5 * Math.PI)

canvasContext.bezierCurveTo

创建三次方贝塞尔曲线路径

Tip: 曲线的起始点为路径中前一个点

参数	类型	定义
cp1x	Number	第一个贝塞尔控制点的 x 坐标
cp1y	Number	第一个贝塞尔控制点的 y 坐标
cp2x	Number	第二个贝塞尔控制点的 x 坐标
cp2y	Number	第二个贝塞尔控制点的 y 坐标
X	Number	结束点的 x 坐标
Y	Number	结束点的 y 坐标

const ctx = wx.createCanvasContext('myCanvas')
// Draw points
ctx.beginPath()
ctx.arc(20, 20, 2, 0, 2 * Math.PI)
ctx.setFillStyle('red')
ctx.fill()
ctx.beginPath()
ctx.arc(200, 20, 2, 0, 2 * Math.PI)
ctx.setFillStyle('lightgreen')
ctx.fill()
ctx.beginPath()
ctx.arc(20, 100, 2, 0, 2 * Math.PI)
ctx.arc(200, 100, 2, 0, 2 * Math.PI)
ctx.setFillStyle('blue')
ctx.fill()
ctx.setFillStyle('black')
ctx.setFontSize(12)
// Draw guides
ctx.beginPath()
ctx.moveTo(20, 20)
ctx.lineTo(20, 100)
ctx.lineTo(150, 75)
ctx.moveTo(200, 20)
ctx.lineTo(200, 100)
ctx.lineTo(70, 75)
ctx.setStrokeStyle('#AAAAAA')
ctx.stroke()
// Draw quadratic curve
ctx.beginPath()
ctx.moveTo(20, 20)
ctx.bezierCurveTo(20, 100, 200, 100, 200, 20)
ctx.setStrokeStyle('black')
ctx.stroke()
ctx.draw()

针对 moveTo(20, 20) bezierCurveTo(20, 100, 200, 100, 200, 20) 的三个关键坐标如下：

起始点(20, 20) 两个控制点(20, 100) (200, 100) 终止点(200, 20)

canvasContext.quadraticCurveTo

创建二次贝塞尔曲线路径。

Tip: 曲线的起始点为路径中前一个点

参数	类型	定义
cpx	Number	贝塞尔控制点的 x 坐标
cpy	Number	贝塞尔控制点的 y 坐标
X	Number	结束点的 x 坐标
Y	Number	结束点的 y 坐标

const ctx = wx.createCanvasContext('myCanvas')
// Draw points
ctx.beginPath()
ctx.arc(20, 20, 2, 0, 2 * Math.PI)
ctx.setFillStyle('red')
ctx.fill()
ctx.beginPath()
ctx.arc(200, 20, 2, 0, 2 * Math.PI)
ctx.setFillStyle('lightgreen')
ctx.fill()
ctx.beginPath()
ctx.arc(20, 100, 2, 0, 2 * Math.PI)
ctx.setFillStyle('blue')
ctx.fill()
ctx.setFillStyle('black')
ctx.setFontSize(12)
// Draw guides
ctx.beginPath()
ctx.moveTo(20, 20)
ctx.lineTo(20, 100)
ctx.lineTo(200, 20)
ctx.setStrokeStyle('#AAAAAA')
ctx.stroke()
// Draw quadratic curve
ctx.beginPath()
ctx.moveTo(20, 20)
ctx.quadraticCurveTo(20, 100, 200, 20)
ctx.setStrokeStyle('black')
ctx.stroke()
ctx.draw()

针对 moveTo(20, 20) quadraticCurveTo(20, 100, 200, 20) 的三个关键坐标如下：

起始点(20, 20) 控制点(20, 100) 终止点(200, 20)

canvasContext.scale

在调用scale方法后，之后创建的路径其横纵坐标会被缩放。多次调用scale，倍数会相乘

参数	类型	定义
scaleWidth	Number	横坐标缩放的倍数 (1 = 100%，0.5 = 50%，2 = 200%)
scaleHeight	Number	纵坐标轴缩放的倍数 (1 = 100%，0.5 = 50%，2 = 200%)

const ctx = wx.createCanvasContext('myCanvas')
ctx.strokeRect(10, 10, 25, 15)
ctx.scale(2, 2)
ctx.strokeRect(10, 10, 25, 15)
ctx.scale(2, 2)
ctx.strokeRect(10, 10, 25, 15)
ctx.draw()

canvasContext.rotate

以原点为中心，原点可以用 translate方法修改。顺时针旋转当前坐标轴。多次调用rotate，旋转的角度会叠加

参数	类型	定义
rotate	Number	旋转角度，以弧度计(degrees * Math.PI/180；degrees范围为0~360)

const ctx = wx.createCanvasContext('myCanvas')
ctx.strokeRect(100, 10, 150, 100)
ctx.rotate(20 * Math.PI / 180)
ctx.strokeRect(100, 10, 150, 100)
ctx.rotate(20 * Math.PI / 180)
ctx.strokeRect(100, 10, 150, 100)
ctx.draw()

canvasContext.translate

对当前坐标系的原点(0, 0)进行变换，默认的坐标系原点为页面左上角

参数	类型	定义
x	Number	水平坐标平移量
y	Number	竖直坐标平移量

const ctx = wx.createCanvasContext('myCanvas')
ctx.strokeRect(10, 10, 150, 100)
ctx.translate(20, 20)
ctx.strokeRect(10, 10, 150, 100)
ctx.translate(20, 20)
ctx.strokeRect(10, 10, 150, 100)
ctx.draw()

canvasContext.clip

clip() 方法从原始画布中剪切任意形状和尺寸。一旦剪切了某个区域，则所有之后的绘图都会被限制在被剪切的区域内（不能访问画布上的其他区域）。可以在使用 clip() 方法前通过使用 save() 方法对当前画布区域进行保存，并在以后的任意时间对其进行恢复（通过 restore() 方法）。

基础库 1.6.0 开始支持，低版本需做兼容处理

const ctx = wx.createCanvasContext('myCanvas')
wx.downloadFile({
  url: 'http://is5.mzstatic.com/image/thumb/Purple128/v4/75/3b/90/753b907c-b7fb-5877-215a-759bd73691a4/source/50x50bb.jpg',
  success: function(res) {
    ctx.save()
    ctx.beginPath()
    ctx.arc(50, 50, 25, 0, 2*Math.PI)
    ctx.clip()
    ctx.drawImage(res.tempFilePath, 25, 25)
    ctx.restore()
    ctx.draw()
  }
})

canvasContext.setFontSize

设置字体的字号

参数	类型	定义
fontSize	Number	字体的字号

const ctx = wx.createCanvasContext('myCanvas')
ctx.setFontSize(20)
ctx.fillText('20', 20, 20)
ctx.setFontSize(30)
ctx.fillText('30', 40, 40)
ctx.setFontSize(40)
ctx.fillText('40', 60, 60)
ctx.setFontSize(50)
ctx.fillText('50', 90, 90)
ctx.draw()

canvasContext.fillText

在画布上绘制被填充的文本

参数	类型	定义
text	String	在画布上输出的文本
x	Number	绘制文本的左上角x坐标位置
y	Number	绘制文本的左上角y坐标位置
maxWidth	Number	需要绘制的最大宽度，可选

const ctx = wx.createCanvasContext('myCanvas')
ctx.setFontSize(20)
ctx.fillText('Hello', 20, 20)
ctx.fillText('MINA', 100, 100)
ctx.draw()

canvasContext.setTextAlign

用于设置文字的对齐

基础库 1.1.0 开始支持，低版本需做兼容处理

语法

canvasContext.setTextAlign(align)
canvasContext.textAlign = align // 基础库 1.9.90 起支持

参数	类型	定义
align	String	可选值 'left'、'center'、'right'

const ctx = wx.createCanvasContext('myCanvas')
ctx.setStrokeStyle('red')
ctx.moveTo(150, 20)
ctx.lineTo(150, 170)
ctx.stroke()
ctx.setFontSize(15)
ctx.setTextAlign('left')
ctx.fillText('textAlign=left', 150, 60)
ctx.setTextAlign('center')
ctx.fillText('textAlign=center', 150, 80)
ctx.setTextAlign('right')
ctx.fillText('textAlign=right', 150, 100)
ctx.draw()

canvasContext.setTextBaseline

用于设置文字的水平对齐

基础库 1.4.0 开始支持，低版本需做兼容处理

语法

canvasContext.setTextBaseline(textBaseline)
canvasContext.textBaseline = textBaseline // 基础库 1.9.90 起支持

参数	类型	定义
textBaseline	String	可选值 'top'、'bottom'、'middle'、'normal'

const ctx = wx.createCanvasContext('myCanvas')
ctx.setStrokeStyle('red')
ctx.moveTo(5, 75)
ctx.lineTo(295, 75)
ctx.stroke()
ctx.setFontSize(20)
ctx.setTextBaseline('top')
ctx.fillText('top', 5, 75)
ctx.setTextBaseline('middle')
ctx.fillText('middle', 50, 75)
ctx.setTextBaseline('bottom')
ctx.fillText('bottom', 120, 75)
ctx.setTextBaseline('normal')
ctx.fillText('normal', 200, 75)
ctx.draw()

canvasContext.drawImage

绘制图像到画布

参数	类型	定义
imageResource	String	所要绘制的图片资源
dx	Number	图像的左上角在目标canvas上 X 轴的位置
dy	Number	图像的左上角在目标canvas上 Y 轴的位置
dWidth	Number	在目标画布上绘制图像的宽度，允许对绘制的图像进行缩放
dHeight	Number	在目标画布上绘制图像的高度，允许对绘制的图像进行缩放
sx	Number	源图像的矩形选择框的左上角 X 坐标
sy	Number	源图像的矩形选择框的左上角 Y 坐标
sWidth	Number	源图像的矩形选择框的宽度
sHeight	Number	源图像的矩形选择框的高度

有三个版本的写法：

drawImage(dx, dy)
drawImage(dx, dy, dWidth, dHeight)
drawImage(sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight) 从 1.9.0 起支持

例子

const ctx = wx.createCanvasContext('myCanvas')
wx.chooseImage({
  success: function(res){
    ctx.drawImage(res.tempFilePaths[0], 0, 0, 150, 100)
    ctx.draw()
  }
})

canvasContext.setGlobalAlpha

设置全局画笔透明度。

语法

canvasContext.setGlobalAlpha(alpha)
canvasContext.globalAlpha = alpha // 基础库 1.9.90 起支持

参数	类型	范围	定义
alpha	Number	0~1	透明度，0 表示完全透明，1 表示完全不透明

const ctx = wx.createCanvasContext('myCanvas')
ctx.setFillStyle('red')
ctx.fillRect(10, 10, 150, 100)
ctx.setGlobalAlpha(0.2)
ctx.setFillStyle('blue')
ctx.fillRect(50, 50, 150, 100)
ctx.setFillStyle('yellow')
ctx.fillRect(100, 100, 150, 100)
ctx.draw()

canvasContext.save

保存当前的绘图上下文

restore

恢复之前保存的绘图上下文

const ctx = wx.createCanvasContext('myCanvas')
// save the default fill style
ctx.save() 
ctx.setFillStyle('red')
ctx.fillRect(10, 10, 150, 100)
// restore to the previous saved state
ctx.restore()
ctx.fillRect(50, 50, 150, 100)
ctx.draw()

canvasContext.draw

将之前在绘图上下文中的描述（路径、变形、样式）画到 canvas 中

Tip: 绘图上下文需要由 wx.createCanvasContext(canvasId) 来创建

参数	类型	说明	最低版本
reserve	Boolean	非必填。本次绘制是否接着上一次绘制，即reserve参数为false，则在本次调用drawCanvas绘制之前native层应先清空画布再继续绘制；若reserver参数为true，则保留当前画布上的内容，本次调用drawCanvas绘制的内容覆盖在上面，默认 false
callback	Function	绘制完成后回调	1.7.0

const ctx = wx.createCanvasContext('myCanvas')
ctx.setFillStyle('red')
ctx.fillRect(10, 10, 150, 100)
ctx.draw()
ctx.fillRect(50, 50, 150, 100)
ctx.draw()

const ctx = wx.createCanvasContext('myCanvas')
ctx.setFillStyle('red')
ctx.fillRect(10, 10, 150, 100)
ctx.draw()
ctx.fillRect(50, 50, 150, 100)
ctx.draw(true)

getActions

返回绘图上下文的绘图动作。不推荐使用

canvasContext.clearActions

清空绘图上下文的绘图动作。不推荐使用

canvasContext.measureText

测量文本尺寸信息，目前仅返回文本宽度。同步接口。基础库 1.9.90 开始支持，低版本需做兼容处理

参数	类型	说明
text	String	要测量的文本

返回 TextMetrics 对象，结构如下：

参数	类型	说明
width	Numbe	文本的宽度

const ctx = wx.createCanvasContext('myCanvas')
ctx.font = 'italic bold 20px cursive'
const metrics = ctx.measureText('Hello World')
console.log(metrics.width)

canvasContext.globalCompositeOperation

该属性是设置要在绘制新形状时应用的合成操作的类型。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.globalCompositeOperation = type

参数	类型	说明
type	String	标识要使用哪种合成或混合模式操作

type 支持的操作有：

平台	操作
安卓	xor, source-over, source-atop, destination-out, lighter, overlay, darken, lighten, hard-light
iOS	xor, source-over, source-atop, destination-over, destination-out, lighter, multiply, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, exclusion, saturation, luminosity

Bug: 目前安卓版本只适用于 fill 填充块的合成，用于 stroke 线段的合成效果都是 source-over

canvasContext.arcTo

根据控制点和半径绘制圆弧路径。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.arcTo(x1, y1, x2, y2, radius)

参数	类型	定义
x1	Number	第一个控制点的 x 轴坐标
y1	Number	第一个控制点的 y 轴坐标
x2	Number	第二个控制点的 x 轴坐标
y2	Number	第二个控制点的 y 轴坐标
radius	Number	圆弧的半径

canvasContext.strokeText

给定的 (x, y) 位置绘制文本描边的方法。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.strokeText(text, x, y, maxWidth)

参数	类型	说明
text	String	要绘制的文本
x	Number	文本起始点的 x 轴坐标
y	Number	文本起始点的 y 轴坐标
maxWidth	Number	需要绘制的最大宽度，可选

canvasContext.lineDashOffset

设置虚线偏移量的属性。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.lineDashOffset = value

参数	类型	说明
value	Number	偏移量，初始值为 0

canvasContext.createPattern

对指定的图像创建模式的方法，可在指定的方向上重复元图像。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.createPattern(image, repetition)

参数	类型	说明
image	String	重复的图像源，仅支持包内路径和临时路径
repetition	String	指定如何重复图像，有效值有: repeat, repeat-x, repeat-y, no-repeat

const ctx = wx.createCanvasContext('myCanvas')
const pattern = ctx.createPattern('/path/to/image', 'repeat-x')
ctx.fillStyle = pattern
ctx.fillRect(0, 0, 300, 150)
ctx.draw()

canvasContext.font

设置当前字体样式的属性。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.font = value

属性值	类型	说明
value	String	符合 CSS font 语法的 DOMString 字符串，至少需要提供字体大小和字体族名。默认值为 10px sans-serif

value 支持的属性有：

属性	说明
style	字体样式。仅支持 italic, oblique, normal
weight	字体粗细。仅支持 normal, bold
size	字体大小
family	字体族名。注意确认各平台所支持的字体

canvasContext.transform

使用矩阵多次叠加当前变换的方法。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.transform(scaleX, skewX, skewY, scaleY, translateX, translateY)

属性值	类型	说明
scaleX	Number	水平缩放
scaleY	Number	垂直缩放
skewX	Number	水平倾斜
skewY	Number	垂直倾斜
translateX	Number	水平移动
translateY	Number	垂直移动

canvasContext.setTransform

使用矩阵重新设置（覆盖）当前变换的方法。基础库 1.9.90 开始支持，低版本需做兼容处理

语法

canvasContext.setTransform(scaleX, skewX, skewY, scaleY, translateX, translateY)

属性值	类型	说明
scaleX	Number	水平缩放
scaleY	Number	垂直缩放
skewX	Number	水平倾斜
skewY	Number	垂直倾斜
translateX	Number	水平移动
translateY	Number	垂直移动

下拉刷新

Page.onPullDownRefresh()

在 Page 中定义 onPullDownRefresh 处理函数，监听该页面用户下拉刷新事件

wx.startPullDownRefresh(OBJECT)

开始下拉刷新，调用后触发下拉刷新动画，效果与用户手动下拉刷新一致。基础库 1.5.0 开始支持，低版本需做兼容处理

Object参数说明：

参数	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数说明：

参数名	类型	说明
errMsg	String	接口调用结果

wx.startPullDownRefresh()

wx.stopPullDownRefresh()

停止当前页面下拉刷新

Page({
  onPullDownRefresh: function(){
    wx.stopPullDownRefresh()
  }
})

WXML节点信息API

wx.createSelectorQuery()

返回一个SelectorQuery对象实例。可以在这个实例上使用select等方法选择节点，并使用boundingClientRect等方法选择需要查询的信息。

Page({
  queryMultipleNodes: function(){
    var query = wx.createSelectorQuery()
    query.select('#the-id').boundingClientRect()
    query.selectViewport().scrollOffset()
    query.exec(function(res){
      res[0].top       // #the-id节点的上边界坐标
      res[1].scrollTop // 显示区域的竖直滚动位置
    })
  }
})

selectorQuery

selectorQuery 对象的方法列表：

方法	参数	说明
in	object Component	参考下面详细介绍
select	selector	参考下面详细介绍
selectAll	selector	参考下面详细介绍
selectViewport		参考下面详细介绍
exec	[callback]	参考下面详细介绍

selectorQuery.in(component)

将选择器的选取范围更改为自定义组件component内。（初始时，选择器仅选取页面范围的节点，不会选取任何自定义组件中的节点。）

基础库 1.6.0 开始支持，低版本需做兼容处理

Component({
  queryMultipleNodes: function(){
    var query = wx.createSelectorQuery().in(this)
    query.select('#the-id').boundingClientRect(function(res){
      res.top // 这个组件内 #the-id 节点的上边界坐标
    }).exec()
  }
})

selectorQuery.select(selector)

在当前页面下选择第一个匹配选择器selector的节点，返回一个NodesRef对象实例，可以用于获取节点信息。

selector类似于CSS的选择器，但仅支持下列语法。

1.ID选择器：#the-id

2.class选择器（可以连续指定多个）：.a-class.another-class

3.子元素选择器：.the-parent > .the-child

4.后代选择器：.the-ancestor .the-descendant

5.跨自定义组件的后代选择器：.the-ancestor >>> .the-descendant

6.多选择器的并集：#a-node, .some-other-nodes

selectorQuery.selectAll(selector)

在当前页面下选择匹配选择器selector的节点，返回一个NodesRef对象实例

与selectorQuery.select(selector)不同的是，它选择所有匹配选择器的节点

selectorQuery.selectViewport()

选择显示区域，可用于获取显示区域的尺寸、滚动位置等信息，返回一个NodesRef对象实例

nodesRef.boundingClientRect([callback])

添加节点的布局位置的查询请求，相对于显示区域，以像素为单位。其功能类似于DOM的getBoundingClientRect。返回值是nodesRef对应的selectorQuery。

返回的节点信息中，每个节点的位置用left、right、top、bottom、width、height字段描述。如果提供了callback回调函数，在执行selectQuery的exec方法后，节点信息会在callback中返回

Page({
  getRect: function(){
    wx.createSelectorQuery().select('#the-id').boundingClientRect(function(rect){
      rect.id      // 节点的ID
      rect.dataset // 节点的dataset
      rect.left    // 节点的左边界坐标
      rect.right   // 节点的右边界坐标
      rect.top     // 节点的上边界坐标
      rect.bottom  // 节点的下边界坐标
      rect.width   // 节点的宽度
      rect.height  // 节点的高度
    }).exec()
  },
  getAllRects: function(){
    wx.createSelectorQuery().selectAll('.a-class').boundingClientRect(function(rects){
      rects.forEach(function(rect){
        rect.id      // 节点的ID
        rect.dataset // 节点的dataset
        rect.left    // 节点的左边界坐标
        rect.right   // 节点的右边界坐标
        rect.top     // 节点的上边界坐标
        rect.bottom  // 节点的下边界坐标
        rect.width   // 节点的宽度
        rect.height  // 节点的高度
      })
    }).exec()
  }
})

nodesRef.scrollOffset([callback])

添加节点的滚动位置查询请求，以像素为单位。节点必须是scroll-view或者viewport。返回值是nodesRef对应的selectorQuery。

返回的节点信息中，每个节点的滚动位置用scrollLeft、scrollTop字段描述。如果提供了callback回调函数，在执行selectQuery的exec方法后，节点信息会在callback中返回

Page({
  getScrollOffset: function(){
    wx.createSelectorQuery().selectViewport().scrollOffset(function(res){
      res.id      // 节点的ID
      res.dataset // 节点的dataset
      res.scrollLeft // 节点的水平滚动位置
      res.scrollTop  // 节点的竖直滚动位置
    }).exec()
  }
})

nodesRef.fields(fields, [callback])

获取节点的相关信息，需要获取的字段在fields中指定。返回值是nodesRef对应的selectorQuery。可指定获取的字段包括：

字段名	默认值	说明	最低版本
id	否	是否返回节点id
dataset	否	是否返回节点dataset
rect	否	是否返回节点布局位置（left right top bottom）
size	否	是否返回节点尺寸（width height）
scrollOffset	否	是否返回节点的 scrollLeft scrollTop ，节点必须是scroll-view或者viewport
properties	[]	指定属性名列表，返回节点对应属性名的当前属性值（只能获得组件文档中标注的常规属性值， id class style 和事件绑定的属性值不可获取）
computedStyle	[]	指定样式名列表，返回节点对应样式名的当前值	2.1.0

注意： computedStyle 的优先级高于 size，当同时在 computedStyle 里指定了 width/height 和传入了 size: true，则优先返回 computedStyle 获取到的 width/height

Page({
  getFields: function(){
    wx.createSelectorQuery().select('#the-id').fields({
      dataset: true,
      size: true,
      scrollOffset: true,
      properties: ['scrollX', 'scrollY'],
      computedStyle: ['margin', 'backgroundColor']
    }, function(res){
      res.dataset    // 节点的dataset
      res.width      // 节点的宽度
      res.height     // 节点的高度
      res.scrollLeft // 节点的水平滚动位置
      res.scrollTop  // 节点的竖直滚动位置
      res.scrollX    // 节点 scroll-x 属性的当前值
      res.scrollY    // 节点 scroll-y 属性的当前值
      // 此处返回指定要返回的样式名
      res.margin
      res.backgroundColor
    }).exec()
  }
})

selectorQuery.exec([callback])

执行所有的请求，请求结果按请求次序构成数组，在callback的第一个参数中返回

WXML节点布局相交状态

节点布局交叉状态API可用于监听两个或多个组件节点在布局位置上的相交状态。这一组API常常可以用于推断某些节点是否可以被用户看见、有多大比例可以被用户看见。

这一组API涉及的主要概念如下。

1.参照节点：监听的参照节点，取它的布局区域作为参照区域。如果有多个参照节点，则会取它们布局区域的 交集 作为参照区域。页面显示区域也可作为参照区域之一。

2.目标节点：监听的目标，默认只能是一个节点（使用 selectAll 选项时，可以同时监听多个节点）。

3.相交区域：目标节点的布局区域与参照区域的相交区域。

4.相交比例：相交区域占参照区域的比例。

5.阈值：相交比例如果达到阈值，则会触发监听器的回调函数。阈值可以有多个

以下示例代码可以在目标节点（用选择器 .target-class 指定）每次进入或离开页面显示区域时，触发回调函数

Page({
  onLoad: function(){
    wx.createIntersectionObserver().relativeToViewport().observe('.target-class', (res) => {
      res.id // 目标节点 id
      res.dataset // 目标节点 dataset
      res.intersectionRatio // 相交区域占目标节点的布局区域的比例
      res.intersectionRect // 相交区域
      res.intersectionRect.left // 相交区域的左边界坐标
      res.intersectionRect.top // 相交区域的上边界坐标
      res.intersectionRect.width // 相交区域的宽度
      res.intersectionRect.height // 相交区域的高度
    })
  }
})

以下示例代码可以在目标节点（用选择器 .target-class 指定）与参照节点（用选择器 .relative-class 指定）在页面显示区域内相交或相离，且相交或相离程度达到目标节点布局区域的20%和50%时，触发回调函数

Page({
  onLoad: function(){
    wx.createIntersectionObserver(this, {
      thresholds: [0.2, 0.5]
    }).relativeTo('.relative-class').relativeToViewport().observe('.target-class', (res) => {
      res.intersectionRatio // 相交区域占目标节点的布局区域的比例
      res.intersectionRect // 相交区域
      res.intersectionRect.left // 相交区域的左边界坐标
      res.intersectionRect.top // 相交区域的上边界坐标
      res.intersectionRect.width // 相交区域的宽度
      res.intersectionRect.height // 相交区域的高度
    })
  }
})

wx.createIntersectionObserver([this], [options])

创建并返回一个 IntersectionObserver 对象实例。在自定义组件中，可以使用 this.createIntersectionObserver([options]) 来代替。基础库 1.9.3 开始支持，低版本需做兼容处理

可选的 options ：

字段名	类型	说明	最低版本
thresholds	Array	一个数值数组，包含所有阈值。默认为 [0]
initialRatio	Number	初始的相交比例，如果调用时检测到的相交比例与这个值不相等且达到阈值，则会触发一次监听器的回调函数。默认为 0
selectAll	Boolean	是否同时观测多个目标节点（而非一个），如果设为 true ， observe 的 targetSelector 将选中多个节点（注意：同时选中过多节点将影响渲染性能）	2.0.0

intersectionObserver.relativeTo(selector, [margins])

使用选择器指定一个节点，作为参照区域之一。 margins 可以用来扩展（或收缩）参照节点布局区域的边界，可包含 left 、 right 、 top 、 bottom 四项

intersectionObserver.relativeToViewport([margins])

指定页面显示区域作为参照区域之一。 margins 可以用来扩展（或收缩）参照节点布局区域的边界，可包含 left 、 right 、 top 、 bottom 四项

下面的示例代码中，如果目标节点（用选择器 .target-class 指定）进入显示区域以下 100px 时，就会触发回调函数

Page({
  onLoad: function(){
    wx.createIntersectionObserver().relativeToViewport({bottom: 100}).observe('.target-class', (res) => {
      res.intersectionRatio // 相交区域占目标节点的布局区域的比例
      res.intersectionRect // 相交区域
      res.intersectionRect.left // 相交区域的左边界坐标
      res.intersectionRect.top // 相交区域的上边界坐标
      res.intersectionRect.width // 相交区域的宽度
      res.intersectionRect.height // 相交区域的高度
    })
  }
})

intersectionObserver.observe(targetSelector, callback)

指定目标节点并开始监听相交状态变化情况。回调函数 callback 包含一个参数 result

回调函数 result 包含的字段：

字段名	类型	说明
intersectionRatio	Number	相交比例
intersectionRect	Object	相交区域的边界，包含 left 、 right 、 top 、 bottom 四项
boundingClientRect	Object	目标节点布局区域的边界，包含 left 、 right 、 top 、 bottom 四项
relativeRect	Object	参照区域的边界，包含 left 、 right 、 top 、 bottom 四项
time	Number	相交检测时的时间戳

intersectionObserver.disconnect()

停止监听。回调函数将不再触发。

Tips:与页面显示区域的相交区域并不准确代表用户可见的区域，因为参与计算的区域是“布局区域”，布局区域可能会在绘制时被其他节点裁剪隐藏（如遇祖先节点中 overflow 样式为 hidden 的节点）或遮盖（如遇 fixed 定位的节点）

自定义组件

wx.nextTick(FUNCTION)

用于延迟一部分操作到下一个时间片再执行（类似于 setTimeout）。基础库 2.2.3 开始支持，低版本需做兼容处理

PS：因为自定义组件中的 setData 和 triggerEvent 等接口本身是同步的操作，当这几个接口被连续调用时，都是在一个同步流程中执行完的，因此若逻辑不当可能会导致出错。

一个极端的案例：当父组件的 setData 引发了子组件的 triggerEvent，进而使得父组件又进行了一次 setData，期间有通过 wx:if 语句对子组件进行卸载，就有可能引发奇怪的错误，所以对于不需要在一个同步流程内完成的逻辑，可以使用此接口延迟到下一个时间片再执行

Component({
  doSth() {
    this.setData({ number: 1 }) // 直接在当前同步流程中执行

    wx.nextTick(() => {
      this.setData({ number: 3 }) // 在当前同步流程结束后，下一个时间片执行
    })

    this.setData({ number: 2 }) // 直接在当前同步流程中执行
  }
})