开发者可使用微信客户端(6.7.2 及以上版本)扫码下方小程序码,体验小程序。

源码查看:

微信小程序demo

小程序演示


开始学习本教程之前,请先确保您已经有了一定的编程基础,您可以提前通过编程实战训练进行学习。

本教程将带你一步步创建完成一个微信小程序,并可以在手机上体验该小程序的实际效果。这个小程序的首页将会显示欢迎语以及当前用户的微信头像,点击头像,可以在新开的页面中查看当前小程序的启动日志。查看小程序示例源码

如果你需要开发微信小游戏,你可以查看:微信小游戏开发手册文档

1. 获取微信小程序的 AppID

登录 https://mp.weixin.qq.com ,就可以在网站的“设置”-“开发者设置”中,查看到微信小程序的 AppID 了,注意不可直接使用服务号或订阅号的 AppID 。

微信小程序设置

注意:如果我们不是用注册时绑定的管理员微信号,在手机上体验该小程序,那么我们还需要操作“绑定开发者”。即在“用户身份”-“开发者”模块,绑定上需要体验该小程序的微信号。本教程默认注册帐号、体验都是使用管理员微信号。

2. 创建项目

我们需要通过开发者工具,来完成小程序创建和代码编辑。

开发者工具安装完成后,打开并使用微信扫码登录。选择创建“项目”,填入上文获取到的 AppID ,设置一个本地项目的名称(非小程序名称),比如“我的第一个项目”,并选择一个本地的文件夹作为代码存储的目录,点击“新建项目”就可以了。

为方便初学者了解微信小程序的基本代码结构,在创建过程中,如果选择的本地文件夹是个空文件夹,开发者工具会提示,是否需要创建一个 quick start 项目。选择“是”,开发者工具会帮助我们在开发目录里生成一个简单的 demo。

小程序组件

项目创建成功后,我们就可以点击该项目,进入并看到完整的开发者工具界面,点击左侧导航,在“编辑”里可以查看和编辑我们的代码,在“调试”里可以测试代码并模拟小程序在微信客户端效果,在“项目”里可以发送到手机里预览实际效果。

3. 编写代码

创建小程序实例

点击开发者工具左侧导航的“编辑”,我们可以看到这个项目,已经初始化并包含了一些简单的代码文件。最关键也是必不可少的,是 app.js、app.json、app.wxss 这三个。其中,.js后缀的是脚本文件,.json后缀的文件是配置文件,.wxss后缀的是样式表文件。微信小程序会读取这些文件,并生成小程序实例

下面我们简单了解这三个文件的功能,方便修改以及从头开发自己的微信小程序。

app.js是小程序的脚本代码。我们可以在这个文件中监听并处理小程序的生命周期函数、声明全局变量。调用框架提供的丰富的 API,如本例的同步存储及同步读取本地数据。想了解更多可用 API,可参考 API 文档

//app.jsApp({  onLaunch: function () {    //调用API从本地缓存中获取数据    var logs = wx.getStorageSync('logs') || []    logs.unshift(Date.now())    wx.setStorageSync('logs', logs)  },  getUserInfo:function(cb){    var that = this;    if(this.globalData.userInfo){      typeof cb == "function" && cb(this.globalData.userInfo)    }else{      //调用登录接口      wx.login({        success: function () {          wx.getUserInfo({            success: function (res) {              that.globalData.userInfo = res.userInfo;              typeof cb == "function" && cb(that.globalData.userInfo)            }          })        }      });    }  },  globalData:{    userInfo:null  }})

app.json 是对整个小程序的全局配置。我们可以在这个文件中配置小程序是由哪些页面组成,配置小程序的窗口背景色,配置导航条样式,配置默认标题。注意该文件不可添加任何注释。更多可配置项可参考配置详解

{  "pages":[    "pages/index/index",    "pages/logs/logs"  ],  "window":{    "backgroundTextStyle":"light",    "navigationBarBackgroundColor": "#fff",    "navigationBarTitleText": "WeChat",    "navigationBarTextStyle":"black"  }}

app.wxss 是整个小程序的公共样式表。我们可以在页面组件的 class 属性上直接使用 app.wxss 中声明的样式规则。

/**app.wxss**/.container {  height: 100%;  display: flex;  flex-direction: column;  align-items: center;  justify-content: space-between;  padding: 200rpx 0;  box-sizing: border-box;}

创建页面

在这个教程里,我们有两个页面,index 页面和 logs 页面,即欢迎页和小程序启动日志的展示页,他们都在 pages 目录下。微信小程序中的每一个页面的【路径+页面名】都需要写在 app.json 的 pages 中,且 pages 中的第一个页面是小程序的首页。

每一个小程序页面是由同路径下同名的四个不同后缀文件的组成,如:index.js、index.wxml、index.wxss、index.json。.js后缀的文件是脚本文件,.json后缀的文件是配置文件,.wxss后缀的是样式表文件,.wxml后缀的文件是页面结构文件。

index.wxml 是页面的结构文件:

<!--index.wxml--><view class="container">  <view  bindtap="bindViewTap" class="userinfo">    <image class="userinfo-avatar" src="{{userInfo.avatarUrl}}" background-size="cover"></image>    <text class

开发者可使用微信客户端(6.7.2 及以上版本)扫码下方小程序码,体验小程序。

源码查看:

微信小程序demo

小程序演示


小程序简介

小程序是一种全新的连接用户与服务的方式,它可以在微信内被便捷地获取和传播,同时具有出色的使用体验。

小程序技术发展史

​小程序并非凭空冒出来的一个概念。当微信中的 ​WebView ​逐渐成为移动 Web 的一个重要入口时,微信就有相关的 ​JS API​ 了。

代码清单1-1 使用 ​WeixinJSBridge​ 预览图片

WeixinJSBridge.invoke('imagePreview', {    current: 'http://inews.gtimg.com/newsapp_bt/0/1693121381/641',    urls: [ // 所有图片的URL列表,数组格式        'https://img1.gtimg.com/10/1048/104857/10485731_980x1200_0.jpg',        'https://img1.gtimg.com/10/1048/104857/10485726_980x1200_0.jpg',        'https://img1.gtimg.com/10/1048/104857/10485729_980x1200_0.jpg'    ]}, function(res) {    console.log(res.err_msg)})

​代码1-1是一个调用微信原生组件浏览图片的​JS API​,相比于额外引入一个​JS​图片预览组件库,这种调用方式显得非常简洁和高效。

​实际上,微信官方是没有对外暴露过如此调用的,此类 ​API​ 最初是提供给腾讯内部一些业务使用,很多外部开发者发现了之后,依葫芦画瓢地使用了,逐渐成为微信中网页的事实标准。2015年初,微信发布了一整套网页开发工具包,称之为 ​JS-SDK​,开放了拍摄、录音、语音识别、二维码、地图、支付、分享、卡券等几十个​API​。给所有的 Web 开发者打开了一扇全新的窗户,让所有开发者都可以使用到微信的原生能力,去完成一些之前做不到或者难以做到的事情。

同样是调用原生的浏览图片,调用方式如代码清单1-2所示。

代码清单1-2 使用 ​JS-SDK​ 调用图片预览组件

wx.previewImage({  current: 'https://img1.gtimg.com/10/1048/104857/10485726_980x1200_0.jpg',  urls: [ // 所有图片的URL列表,数组格式    'https://img1.gtimg.com/10/1048/104857/10485731_980x1200_0.jpg',    'https://img1.gtimg.com/10/1048/104857/10485726_980x1200_0.jpg',    'https://img1.gtimg.com/10/1048/104857/10485729_980x1200_0.jpg'  ],  success: function(res) {    console.log(res)  }})

​JS-SDK​是对之前的 ​WeixinJSBridge​ 的一个包装,以及新能力的释放,并且由对内开放转为了对所有开发者开放,在很短的时间内获得了极大的关注。从数据监控来看,绝大部分在微信内传播的移动网页都使用到了相关的接口。

​JS-SDK​ 解决了移动网页能力不足的问题,通过暴露微信的接口使得 Web 开发者能够拥有更多的能力,然而在更多的能力之外,JS-SDK 的模式并没有解决使用移动网页遇到的体验不良的问题。用户在访问网页的时候,在浏览器开始显示之前都会有一个的白屏过程,在移动端,受限于设备性能和网络速度,白屏会更加明显。我们团队把很多技术精力放置在如何帮助平台上的 Web 开发者解决这个问题。因此我们设计了一个 ​JS-SDK​ 的增强版本,其中有一个重要的功能,称之为“微信 Web 资源离线存储”。

​以下文字引用自内部的文档(没有最终对外开放):

微信 Web 资源离线存储是面向 Web 开发者提供的基于微信内的 Web 加速方案。通过使用微信离线存储,Web 开发者可借助微信提供的资源存储能力,直接从微信本地加载 Web 资源而不需要再从服务端拉取,从而减少网页加载时间,为微信用户提供更优质的网页浏览体验。每个公众号下所有 Web App 累计最多可缓存 5M 的资源。

​这个设计有点类似 HTML5 的 ​Application Cache​,但在设计上规避了一些 ​Application Cache​的不足。

​在内部测试中,我们发现 离线存储 能够解决一些问题,但对于一些复杂的页面依然会有白屏问题,例如页面加载了大量的 CSS 或者是 JavaScript 文件。​除了白屏,影响 Web 体验的问题还有缺少操作的反馈,主要表现在两个方面:页面切换的生硬和点击的迟滞感。

​微信面临的问题是如何设计一个比较好的系统,使得所有开发者在微信中都能获得比较好的体验。这个问题是之前的​ JS-SDK​ 所处理不了的,需要一个全新的系统来完成,它需要使得所有的开发者都能做到:

- 快速的加载

- 更强大的能力

- 原生的体验

- 易用且安全的微信数据开放

- 高效和简单的开发

这就是小程序的由来。

小程序与普通网页开发的区别

​小程序的主要开发语言是 JavaScript ,小程序的开发同普通的网页开发相比有很大的相似性。对于前端开发者而言,从网页开发迁移到小程序的开发成本并不高,但是二者还是有些许区别的。

​网页开发渲染线程和脚本线程是互斥的,这也是为什么长时间的脚本运行可能会导致页面失去响应,而在小程序中,二者是分开的,分别运行在不同的线程中。网页开发者可以使用到各种浏览器暴露出来的 DOM API,进行 DOM 选中和操作。而如上文所述,小程序的逻辑层和渲染层是分开的,逻辑层运行在 JSCore 中,并没有一个完整浏览器对象,因而缺少相关的 DOM API 和 BOM API。这一区别导致了前端开发非常熟悉的一些库,例如 jQuery、 Zepto 等,在小程序中是无法运行的。同时 JSCore 的环境同 NodeJS 环境也是不尽相同,所以一些 NPM 的包在小程序中也是无法运行的。

​网页开发者需要面对的环境是各式各样的浏览器,PC 端需要面对 IE、Chrome、QQ 浏览器等,在移动端需要面​对​ Safari ​​​​、Chrome 以及 iOS、Android 系统中的各式 WebView 。而小程序开发过程中需要面对的是两大操作系统 iOS 和 Android 的微信客户端,以及用于辅助开发的小程序开发者工具,小程序中三大运行环境也是有所区别的,如表1-1所示。

表1-1 小程序的运行环境

运行环境逻辑层渲染层
iOSJavaScriptCoreWKWebView
安卓V8chromium定制内核
小程序开发者工具NWJSChrome WebView

​网页开发者在开发网页的时候,只需要使用到浏览器,并且搭配上一些辅助工具或者编辑器即可。小程序的开发则有所不同,需要经过申请小程序帐号、安装小程序开发者工具、配置项目等等过程方可完成。

体验小程序

开发者可使用微信客户端(6.7.2 及以上版本)扫码下方小程序码,体验小程序。

查看小程序示例源码


开始

开发小程序的第一步,你需要拥有一个小程序帐号,通过这个帐号你就可以管理你的小程序。

跟随这个教程,开始你的小程序之旅吧!

申请帐号

进入小程序注册页 根据指引填写信息和提交相应的资料,就可以拥有自己的小程序帐号。

在这个小程序管理平台,你可以管理你的小程序的权限,查看数据报表,发布小程序等操作。

登录 小程序后台 ,我们可以在菜单 “开发”-“开发设置” 看到小程序的 AppID 了 。

小程序的 AppID 相当于小程序平台的一个身份证,后续你会在很多地方要用到 AppID (注意这里要区别于服务号或订阅号的 AppID)。

有了小程序帐号之后,我们需要一个工具来开发小程序。

安装开发工具

前往 开发者工具下载页面 ,根据自己的操作系统下载对应的安装包进行安装,有关开发者工具更详细的介绍可以查看 《开发者工具介绍》 。

打开小程序开发者工具,用微信扫码登录开发者工具,准备开发你的第一个小程序吧!

你的第一个小程序

新建项目选择小程序项目,选择代码存放的硬盘路径,填入刚刚申请到的小程序的 AppID,给你的项目起一个好听的名字,勾选 "不使用云服务" (注意: 你要选择一个空的目录才可以创建项目),点击新建,你就得到了你的第一个小程序了,点击顶部菜单编译就可以在微信开发者工具中预览你的第一个小程序。

接下来我们来预览一下这个小程序的效果。

编译预览

点击工具上的编译按钮,可以在工具的左侧模拟器界面看到这个小程序的表现,也可以点击预览按钮,通过微信的扫一扫在手机上体验你的第一个小程序。

通过这个章节,你已经成功创建了你的第一个小程序,并且在微信客户端上体验到它流畅的表现。

下个章节,我们一起来看看这个小程序的代码构成。


小程序代码构成

​在上一章中,我们通过开发者工具快速创建了一个 QuickStart 项目。你可以留意到这个项目里边生成了不同类型的文件:

  1. .json 后缀的 JSON 配置文件
  2. .wxml 后缀的 WXML 模板文件
  3. .wxss 后缀的 WXSS 样式文件
  4. .js 后缀的 JS 脚本逻辑文件

接下来我们分别看看这4种文件的作用。

JSON 配置

JSON 是一种数据格式,并不是编程语言,在小程序中,JSON扮演的静态配置的角色。

我们可以看到在项目的根目录有一个 app.json 和 project.config.json,此外在 pages/logs 目录下还有一个 logs.json,我们依次来说明一下它们的用途。

小程序配置 app.json

app.json 是当前小程序的全局配置,包括了小程序的所有页面路径、界面表现、网络超时时间、底部 tab 等。QuickStart 项目里边的 app.json 配置内容如下:

{  "pages":[    "pages/index/index",    "pages/logs/logs"  ],  "window":{    "backgroundTextStyle":"light",    "navigationBarBackgroundColor": "#fff",    "navigationBarTitleText": "WeChat",    "navigationBarTextStyle":"black"  }}

我们简单说一下这个配置各个项的含义:

  1. pages字段 —— 用于描述当前小程序所有页面路径,这是为了让微信客户端知道当前你的小程序页面定义在哪个目录。
  2. window字段 —— 定义小程序所有页面的顶部背景颜色,文字颜色定义等。

其他配置项细节可以参考文档 小程序的配置 app.json 。

工具配置 project.config.json

通常大家在使用一个工具的时候,都会针对各自喜好做一些个性化配置,例如界面颜色、编译配置等等,当你换了另外一台电脑重新安装工具的时候,你还要重新配置。

考虑到这点,小程序开发者工具在每个项目的根目录都会生成一个 project.config.json,你在工具上做的任何配置都会写入到这个文件,当你重新安装工具或者换电脑工作时,你只要载入同一个项目的代码包,开发者工具就自动会帮你恢复到当时你开发项目时的个性化配置,其中会包括编辑器的颜色、代码上传时自动压缩等等一系列选项。

其他配置项细节可以参考文档 开发者工具的配置 。

页面配置 page.json

这里的 page.json 其实用来表示 pages/logs 目录下的 logs.json 这类和小程序页面相关的配置。

如果你整个小程序的风格是蓝色调,那么你可以在 app.json 里边声明顶部颜色是蓝色即可。实际情况可能不是这样,可能你小程序里边的每个页面都有不一样的色调来区分不同功能模块,因此我们提供了 page.json,让开发者可以独立定义每个页面的一些属性,例如刚刚说的顶部颜色、是否允许下拉刷新等等。

其他配置项细节可以参考文档 页面配置 。

JSON 语法

这里说一下小程序里JSON配置的一些注意事项。

JSON文件都是被包裹在一个大括号中 {},通过key-value的方式来表达数据。JSON的Key必须包裹在一个双引号中,在实践中,编写 JSON 的时候,忘了给 Key 值加双引号或者是把双引号写成单引号是常见错误。

JSON的值只能是以下几种数据格式,其他任何格式都会触发报错,例如 JavaScript 中的 undefined。

  1. 数字,包含浮点数和整数
  2. 字符串,需要包裹在双引号中
  3. Bool值,true 或者 false
  4. 数组,需要包裹在方括号中 []
  5. 对象,需要包裹在大括号中 {}
  6. Null

还需要注意的是 JSON 文件中无法使用注释,试图添加注释将会引发报错。

WXML 模板

从事过网页编程的人知道,网页编程采用的是 HTML + CSS + JS 这样的组合,其中 HTML 是用来描述当前这个页面的结构,CSS 用来描述页面的样子,JS 通常是用来处理这个页面和用户的交互。

同样道理,在小程序中也有同样的角色,其中 WXML 充当的就是类似 HTML 的角色。打开 pages/index/index.wxml,你会看到以下的内容:

<view class="container">  <view class="userinfo">    <button wx:if="{{!hasUserInfo && canIUse}}"> 获取头像昵称 </button>    <block wx:else>      <image src="{{userInfo.avatarUrl}}" background-size="cover"></image>      <text class="userinfo-nickname">{{userInfo.nickName}}</text>    </block>  </view>  <view class="usermotto">    <text class="user-motto">{{motto}}</text>  </view></view>

和 HTML 非常相似,WXML 由标签、属性等等构成。但是也有很多不一样的地方,我们来一一阐述一下:

  1. 标签名字有点不一样往往写 HTML 的时候,经常会用到的标签是 div, p, span,开发者在写一个页面的时候可以根据这些基础的标签组合出不一样的组件,例如日历、弹窗等等。换个思路,既然大家都需要这些组件,为什么我们不能把这些常用的组件包装起来,大大提高我们的开发效率。从上边的例子可以看到,小程序的 WXML 用的标签是 view, button, text 等等,这些标签就是小程序给开发者包装好的基本能力,我们还提供了地图、视频、音频等等组件能力。更多详细的组件讲述参考下个章节 小程序的能力
  2. 多了一些 wx:if 这样的属性以及 {{ }} 这样的表达式在网页的一般开发流程中,我们通常会通过 JS 操作 DOM (对应 HTML 的描述产生的树),以引起界面的一些变化响应用户的行为。例如,用户点击某个按钮的时候,JS 会记录一些状态到 JS 变量里边,同时通过 DOM API 操控 DOM 的属性或者行为,进而引起界面一些变化。当项目越来越大的时候,你的代码会充斥着非常多的界面交互逻辑和程序的各种状态变量,显然这不是一个很好的开发模式,因此就有了 MVVM 的开发模式(例如 React, Vue),提倡把渲染和逻辑分离。简单来说就是不要再让 JS 直接操控 DOM,JS 只需要管理状态即可,然后再通过一种模板语法来描述状态和界面结构的关系即可。小程序的框架也是用到了这个思路,如果你需要把一个 Hello World 的字符串显示在界面上。WXML 是这么写 :<text>{{msg}}</text>JS 只需要管理状态即可:this.setData({ msg: "Hello World" })通过 {{ }} 的语法把一个变量绑定到界面上,我们称为数据绑定。仅仅通过数据绑定还不够完整的描述状态和界面的关系,还需要 if/else, for等控制能力,在小程序里边,这些控制能力都用 wx: 开头的属性来表达。

更详细的文档可以参考 WXML

WXSS 样式

WXSS 具有 CSS 大部分的特性,小程序在 WXSS 也做了一些扩充和修改。

  1. 新增了尺寸单位。在写 CSS 样式时,开发者需要考虑到手机设备的屏幕会有不同的宽度和设备像素比,采用一些技巧来换算一些像素单位。WXSS 在底层支持新的尺寸单位 rpx ,开发者可以免去换算的烦恼,只要交给小程序底层来换算即可,由于换算采用的浮点数运算,所以运算结果会和预期结果有一点点偏差。
  2. 提供了全局的样式和局部样式。和前边 app.json, page.json 的概念相同,你可以写一个 app.wxss 作为全局样式,会作用于当前小程序的所有页面,局部页面样式 page.wxss 仅对当前页面生效。
  3. 此外 WXSS 仅支持部分 CSS 选择器

更详细的文档可以参考 WXSS 。

JS 逻辑交互

一个服务仅仅只有界面展示是不够的,还需要和用户做交互:响应用户的点击、获取用户的位置等等。在小程序里边,我们就通过编写 JS 脚本文件来处理用户的操作。

<view>{{ msg }}</view><button bindtap="clickMe">点击我</button>

点击 button 按钮的时候,我们希望把界面上 msg 显示成 "Hello World",于是我们在 button 上声明一个属性: bindtap ,在 JS 文件里边声明了 clickMe 方法来响应这次点击操作:

Page({  clickMe: function() {    this.setData({ msg: "Hello World" })  }})

响应用户的操作就是这么简单,更详细的事件可以参考文档 WXML - 事件 。

此外你还可以在 JS 中调用小程序提供的丰富的 API,利用这些 API 可以很方便的调起微信提供的能力,例如获取用户信息、本地存储、微信支付等。在前边的 QuickStart 例子中,在 pages/index/index.js 就调用了 wx.getUserInfo 获取微信用户的头像和昵称,最后通过 setData 把获取到的信息显示到界面上。更多 API 可以参考文档 小程序的API 。

通过这个章节,你了解了小程序涉及到的文件类型以及对应的角色,在下个章节中,我们把这一章所涉及到的文件通过 “小程序的框架” 给 “串” 起来,让他们都工作起来。


小程序宿主环境

我们称微信客户端给小程序所提供的环境为宿主环境。小程序借助宿主环境提供的能力,可以完成许多普通网页无法完成的功能。

上一章中我们把小程序涉及到的文件类型阐述了一遍,我们结合 QuickStart 这个项目来讲一下这些文件是怎么配合工作的。

渲染层和逻辑层

首先,我们来简单了解下小程序的运行环境。小程序的运行环境分成渲染层和逻辑层,其中 WXML 模板和 WXSS 样式工作在渲染层,JS 脚本工作在逻辑层。

小程序的渲染层和逻辑层分别由2个线程管理:渲染层的界面使用了WebView 进行渲染;逻辑层采用JsCore线程运行JS脚本。一个小程序存在多个界面,所以渲染层存在多个WebView线程,这两个线程的通信会经由微信客户端(下文中也会采用Native来代指微信客户端)做中转,逻辑层发送网络请求也经由Native转发,小程序的通信模型下图所示。

有关渲染层和逻辑层的详细文档参考 小程序框架 。

程序与页面

微信客户端在打开小程序之前,会把整个小程序的代码包下载到本地。

紧接着通过 app.json 的 pages 字段就可以知道你当前小程序的所有页面路径:

{  "pages":[    "pages/index/index",    "pages/logs/logs"  ]}

这个配置说明在 QuickStart 项目定义了两个页面,分别位于 pages/index/index 和 pages/logs/logs。而写在 pages 字段的第一个页面就是这个小程序的首页(打开小程序看到的第一个页面)。

于是微信客户端就把首页的代码装载进来,通过小程序底层的一些机制,就可以渲染出这个首页。

小程序启动之后,在 app.js 定义的 App 实例的 onLaunch 回调会被执行:

App({  onLaunch: function () {    // 小程序启动之后 触发  }})

整个小程序只有一个 App 实例,是全部页面共享的,更多的事件回调参考文档 注册程序 App 。

接下来我们简单看看小程序的一个页面是怎么写的。

你可以观察到 pages/logs/logs 下其实是包括了4种文件的,微信客户端会先根据 logs.json 配置生成一个界面,顶部的颜色和文字你都可以在这个 json 文件里边定义好。紧接着客户端就会装载这个页面的 WXML 结构和 WXSS 样式。最后客户端会装载 logs.js,你可以看到 logs.js 的大体内容就是:

Page({  data: { // 参与页面渲染的数据    logs: []  },  onLoad: function () {    // 页面渲染后 执行  }})

Page 是一个页面构造器,这个构造器就生成了一个页面。在生成页面的时候,小程序框架会把 data 数据和 index.wxml 一起渲染出最终的结构,于是就得到了你看到的小程序的样子。

在渲染完界面之后,页面实例就会收到一个 onLoad 的回调,你可以在这个回调处理你的逻辑。

有关于 Page 构造器更多详细的文档参考 注册页面 Page 。

组件

小程序提供了丰富的基础组件给开发者,开发者可以像搭积木一样,组合各种组件拼合成自己的小程序。

就像 HTML 的 div, p 等标签一样,在小程序里边,你只需要在 WXML 写上对应的组件标签名字就可以把该组件显示在界面上,例如,你需要在界面上显示地图,你只需要这样写即可:

<map></map>

使用组件的时候,还可以通过属性传递值给组件,让组件可以以不同的状态去展现,例如,我们希望地图一开始的中心的经纬度是广州,那么你需要声明地图的 longitude(中心经度) 和 latitude(中心纬度)两个属性:

<map longitude="广州经度" latitude="广州纬度"></map>

组件的内部行为也会通过事件的形式让开发者可以感知,例如用户点击了地图上的某个标记,你可以在 js 编写 markertap 函数来处理:

<map bindmarkertap="markertap" longitude="广州经度" latitude="广州纬度"></map>

当然你也可以通过 style 或者 class 来控制组件的外层样式,以便适应你的界面宽度高度等等。

API

为了让开发者可以很方便的调起微信提供的能力,例如获取用户信息、微信支付等等,小程序提供了很多 API 给开发者去使用。

要获取用户的地理位置时,只需要:

wx.getLocation({  type: 'wgs84',  success: (res) => {    var latitude = res.latitude // 纬度    var longitude = res.longitude // 经度  }})

调用微信扫一扫能力,只需要:

wx.scanCode({  success: (res) => {    console.log(res)  }})

需要注意的是:多数 API 的回调都是异步,你需要处理好代码逻辑的异步问题。

更多的 API 能力见 小程序的API

通过这个章节你已经大概了解了小程序运行的一些基本概念,当你开发完一个小程序之后,你就需要发布你的小程序。在下个章节,你会知道发布前需要做什么准备。


小程序协同工作和发布

在中大型的公司里,人员的分工非常仔细,一般会有不同岗位角色的员工同时参与同一个小程序项目。为此,小程序平台设计了不同的权限管理使得项目管理者可以更加高效管理整个团队的协同工作。

以往我们在开发完网页之后,需要把网页的代码和资源放在服务器上,让用户通过互联网来访问。在小程序的平台里,开发者完成开发之后,需要在开发者工具提交小程序的代码包,然后在小程序后台发布小程序,用户可以通过搜索或者其它入口来进入该小程序。

在这一章我们会把团队的协同工作的注意事项和小程序发布前后涉及的概念和流程做一些介绍。

协同工作

如果你只是一个人开发小程序,可以暂时先跳过这部分,如果是一个团队需要先了解一些概念。

多数情况下,一个团队多人同时参与同一个小程序项目,每个角色所承担的工作或者权限不一样,中大公司的分工更为仔细。为了更形象的表达团队不同角色的关系以及权限的管理,我们通过虚拟一个项目成员组织结构来描述日常如何协同合作完成一个小程序的发布,组织关系如图5-1所示。

img​ 图5-1 虚拟小程序项目组

项目管理成员负责统筹整个项目的进展和风险、把控小程序对外发布的节奏,产品组提出需求,设计组与产品讨论并对需求进行抽象,设计出可视化流程与图形,输出设计方案。开发组依据设计方案,进行程序代码的编写,代码编写完成后,产品组与设计组体验小程序的整体流程,测试组编写测试用例并对小程序进行各种边界测试。项目一般的成员构成与工作流程如图5-2所示。

img​ 图5-2 提需求到发布小程序的流程

小程序成员管理

小程序成员管理包括对小程序项目成员及体验成员的管理。

  • 项目成员:表示参与小程序开发、运营的成员,可登录小程序管理后台,包括运营者、开发者及数据分析者。管理员可在“成员管理”中添加、删除项目成员,并设置项目成员的角色。
  • 体验成员:表示参与小程序内测体验的成员,可使用体验版小程序,但不属于项目成员。管理员及项目成员均可添加、删除体验成员。

不同项目成员拥有不同的权限,从而保证小程序开发安全有序。

权限运营者开发者数据分析者
开发者权限
体验者权限
登录
数据分析
微信支付
推广
开发管理
开发设置
暂停服务
解除关联公众号
腾讯云管理
小程序插件
游戏运营管理

各权限功能说明

  • 开发者权限:可使用小程序开发者工具及开发版小程序进行开发
  • 体验者权限:可使用体验版小程序
  • 登录:可登录小程序管理后台,无需管理员确认
  • 数据分析:使用小程序统计模块功能查看小程序数据
  • 微信支付:使用小程序微信支付(虚拟支付)模块
  • 推广:使用小程序流量主、广告主模块
  • 开发管理:小程序提交审核、发布、回退
  • 开发设置:设置小程序服务器域名、消息推送及扫描普通链接二维码打开小程序
  • 暂停服务设置:暂停小程序线上服务
  • 解除关联公众号:可解绑小程序已关联的公众号
  • 小程序插件:可进行小程序插件开发管理和设置
  • 游戏运营管理:可使用小游戏管理后台的素材管理、游戏圈管理等功能

需要留意,项目管理者控制整个小程序的发布、回退、下架等敏感操作,不应把敏感操作的权限分配给不相关人员

小程序的版本

一般的软件开发流程,开发者编写代码自测开发版程序,直到程序达到一个稳定可体验的状态时,开发者会把这个体验版本给到产品经理和测试人员进行体验测试,最后修复完程序的Bug后发布供外部用户正式使用。小程序的版本根据这个流程设计了小程序版本的概念,如表5-3所示。

表5-3 小程序的版本

权限说明
开发版本使用开发者工具,可将代码上传到开发版本中。 开发版本只保留每人最新的一份上传的代码。
点击提交审核,可将代码提交审核。开发版本可删除,不影响线上版本和审核中版本的代码。
体验版本可以选择某个开发版本作为体验版,并且选取一份体验版。
审核中版本只能有一份代码处于审核中。有审核结果后可以发布到线上,也可直接重新提交审核,覆盖原审核版本。
线上版本线上所有用户使用的代码版本,该版本代码在新版本代码发布后被覆盖更新。

考虑到项目是协同开发的模式,一个小程序可能同时由多个开发者进行开发,往往开发者在小程序开发者工具上编写完代码后需要到手机进行真机体验,所以每个开发者拥有自己对应的一个开发版本。因为处于开发中的版本是不稳定的,开发者随时会修改代码覆盖开发版,为了让测试和产品经理有一个完整稳定的版本可以体验测试,小程序平台允许把其中一个开发版本设置成体验版,因此建议在项目开发阶段特殊分配一个开发角色,用于上传稳定可供体验测试的代码,并把他上传的开发版本设置成体验版。

发布上线

一个小程序从开发完到上线一般要经过 预览-> 上传代码 -> 提交审核 -> 发布等步骤。

预览

使用开发者工具可以预览小程序,帮助开发者检查小程序在移动客户端上的真实表现。

点击开发者工具顶部操作栏的预览按钮,开发者工具会自动打包当前项目,并上传小程序代码至微信的服务器,成功之后会在界面上显示一个二维码。使用当前小程序开发者的微信扫码即可看到小程序在手机客户端上的真实表现。

上传代码

同预览不同,上传代码是用于提交体验或者审核使用的。

点击开发者工具顶部操作栏的上传按钮,填写版本号以及项目备注,需要注意的是,这里版本号以及项目备注是为了方便管理员检查版本使用的,开发者可以根据自己的实际要求来填写这两个字段。

上传成功之后,登录小程序管理后台 - 开发管理 - 开发版本 就可以找到刚提交上传的版本了。

可以将这个版本设置 体验版 或者是 提交审核

提交审核

为了保证小程序的质量,以及符合相关的规范,小程序的发布是需要经过审核的。

在开发者工具中上传了小程序代码之后,登录 小程序管理后台 - 开发管理 - 开发版本 找到提交上传的版本。

在开发版本的列表中,点击 提交审核 按照页面提示,填写相关的信息,即可以将小程序提交审核。

需要注意的是,请开发者严格测试了版本之后,再提交审核, 过多的审核不通过,可能会影响后续的时间。

发布

审核通过之后,管理员的微信中会收到小程序通过审核的通知,此时登录 小程序管理后台 - 开发管理 - 审核版本中可以看到通过审核的版本。

点击发布后,即可发布小程序。小程序提供了两种发布模式:全量发布和分阶段发布。全量发布是指当点击发布之后,所有用户访问小程序时都会使用当前最新的发布版本。分阶段发布是指分不同时间段来控制部分用户使用最新的发布版本,分阶段发布我们也称为灰度发布。一般来说,普通小程序发布时采用全量发布即可,当小程序承载的功能越来越多,使用的用户数越来越多时,采用分阶段发布是一个非常好的控制风险的办法。

小程序码

很多场景下用户会通过扫码快速进入一个小程序,在小程序设计的初期,小程序平台提供的二维码的形式。我们发现用户在扫一个二维码时,他并不知道当前这次扫码会出现什么样的服务,因为二维码的背后有可能是公众号、小程序、网页服务、支付页面、添加好友等不同的服务。为了让用户在扫码之前就有一个明确的预期,因此微信设计了小程序码,如图5-3所示。

img

​ 图5-3 “小程序数据助手”的小程序码

小程序码在样式上更具辨识度和视觉冲击力,相对于二维码来说,小程序主题的品牌形象更加清晰明显,可以帮助开发者更好地推广小程序。在发布小程序之后,小程序管理平台会提供对应的小程序码的预览和下载,开发者可以自行下载用于线上和线下的小程序服务推广。

运营数据

有两种方式可以方便的看到小程序的运营数据

方法一:

登录 小程序管理后台 - 数据分析

点击相应的 tab 可以看到相关的数据。

方法二:

使用小程序数据助手,在微信中方便的查看运营数据


目录结构

小程序包含一个描述整体程序的 app 和多个描述各自页面的 page。

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

文件必需作用
app.js小程序逻辑
app.json小程序公共配置
app.wxss小程序公共样式表

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

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

注意:为了方便开发者减少配置项,描述页面的四个文件必须具有相同的路径与文件名。

允许上传的文件

在项目目录中,以下文件会经过编译,因此上传之后无法直接访问到:.js、app.json、.wxml、*.wxss(其中 wxml 和 wxss 文件仅针对在 app.json 中配置了的页面)。除此之外,只有后缀名在白名单内的文件可以被上传,不在白名单列表内文件在开发工具能被访问到,但无法被上传。具体白名单列表如下:

  1. wxs
  2. png
  3. jpg
  4. jpeg
  5. gif
  6. svg
  7. json
  8. cer
  9. mp3
  10. aac
  11. m4a
  12. mp4
  13. wav
  14. ogg
  15. silk


全局配置

小程序根目录下的 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/index",      "text": "日志"    }]  },  "networkTimeout": {    "request": 10000,    "downloadFile": 10000  },  "debug": true,  "navigateToMiniProgramAppIdList": [    "wxe5f52902cf4de896"  ]}

完整配置项说明请参考小程序全局配置

页面配置

每一个小程序页面也可以使用同名 .json 文件来对本页面的窗口表现进行配置,页面中配置项会覆盖 app.json 的 window 中相同的配置项。

完整配置项说明请参考小程序页面配置

例如:

{  "navigationBarBackgroundColor": "#ffffff",  "navigationBarTextStyle": "black",  "navigationBarTitleText": "微信接口功能演示",  "backgroundColor": "#eeeeee",  "backgroundTextStyle": "light"}


全局配置

小程序根目录下的 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/index",      "text": "日志"    }]  },  "networkTimeout": {    "request": 10000,    "downloadFile": 10000  },  "debug": true,  "navigateToMiniProgramAppIdList": [    "wxe5f52902cf4de896"  ]}

完整配置项说明请参考小程序全局配置

页面配置

每一个小程序页面也可以使用同名 .json 文件来对本页面的窗口表现进行配置,页面中配置项会覆盖 app.json 的 window 中相同的配置项。

完整配置项说明请参考小程序页面配置

例如:

{  "navigationBarBackgroundColor": "#ffffff",  "navigationBarTextStyle": "black",  "navigationBarTitleText": "微信接口功能演示",  "backgroundColor": "#eeeeee",  "backgroundTextStyle": "light"}


微信现已开放小程序内搜索,开发者可以通过 sitemap.json 配置,或者管理后台页面收录开关来配置其小程序页面是否允许微信索引。当开发者允许微信索引时,微信会通过爬虫的形式,为小程序的页面内容建立索引。当用户的搜索词条触发该索引时,小程序的页面将可能展示在搜索结果中。 爬虫访问小程序内页面时,会携带特定的 user-agent:mpcrawler 及场景值:1129。需要注意的是,若小程序爬虫发现的页面数据和真实用户的呈现不一致,那么该页面将不会进入索引中。

具体配置说明

  1. 页面收录设置:可对整个小程序的索引进行关闭,小程序管理后台-功能-页面内容接入-页面收录开关;详情
  2. sitemap 配置:可对特定页面的索引进行关闭

sitemap 配置

小程序根目录下的 sitemap.json 文件用来配置小程序及其页面是否允许被微信索引。

完整配置项说明请参考小程序 sitemap 配置

例1:

{  "rules":[{    "action": "allow",    "page": "*"  }]}

所有页面都会被微信索引(默认情况)

例2:

{  "rules":[{    "action": "disallow",    "page": "path/to/page"  }]}

配置 path/to/page 页面不被索引,其余页面允许被索引

例3:

{  "rules":[{    "action": "allow",    "page": "path/to/page"  }, {    "action": "disallow",    "page": "*"  }]}

配置 path/to/page 页面被索引,其余页面不被索引

例4:

{  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "inclusive"  }, {    "action": "allow",    "page": "*"  }]}

包含 a 和 b 参数的 path/to/page 页面会被微信优先索引,其他页面都会被索引,例如:

  • path/to/page?a=1&b=2 => 优先被索引
  • path/to/page?a=1&b=2&c=3 => 优先被索引
  • path/to/page => 被索引
  • path/to/page?a=1 => 被索引
  • 其他页面都会被索引

例5:

{  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "inclusive"  }, {    "action": "disallow",    "page": "*"  }, {    "action": "allow",    "page": "*"  }]}
  • path/to/page?a=1&b=2 => 优先被索引
  • path/to/page?a=1&b=2&c=3 => 优先被索引
  • path/to/page => 不被索引
  • path/to/page?a=1 => 不被索引
  • 其他页面由于命中第二条规则,所以不会被索引
  • 由于优先级的问题,第三条规则是没有意义的

注:没有 sitemap.json 则默认所有页面都能被索引

注:{"action": "allow", "page": "*"} 是优先级最低的默认规则,未显式指明 "disallow" 的都默认被索引

如何调试

当在小程序项目中设置了 sitemap 的配置文件(默认为 sitemap.json)时,便可在开发者工具控制台上显示当前页面是否被索引的调试信息( 最新版本的开发者工具支持索引提示)

sitemap.png

注:sitemap 的索引提示是默认开启的,如需要关闭 sitemap 的索引提示,可在小程序项目配置文件 project.config.json 的 setting 中配置字段 checkSiteMap 为 false

注: sitemap 文件内容最大为 5120 个 UTF8 字符


场景值

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

场景值用来描述用户进入小程序的路径。完整场景值的含义请查看场景值列表

由于Android系统限制,目前还无法获取到按 Home 键退出到桌面,然后从桌面再次进小程序的场景值,对于这种情况,会保留上一次的场景值。

获取场景值

开发者可以通过下列方式获取场景值:

  • 对于小程序,可以在 App 的 onLaunch 和 onShow,或wx.getLaunchOptionsSync 中获取上述场景值。
  • 对于小游戏,可以在 wx.getLaunchOptionsSync 和 wx.onShow 中获取上述场景值

返回来源信息的场景

部分场景值下还可以获取来源应用、公众号或小程序的appId。获取方式请参考对应API的参考文档。

场景值场景appId含义
1020公众号 profile 页相关小程序列表来源公众号
1035公众号自定义菜单来源公众号
1036App 分享消息卡片来源App
1037小程序打开小程序来源小程序
1038从另一个小程序返回来源小程序
1043公众号模板消息来源公众号


注册小程序

每个小程序都需要在 app.js 中调用 App 方法注册小程序实例,绑定生命周期回调函数、错误监听和页面不存在监听函数等。

详细的参数含义和使用请参考 App 参考文档 。

// app.jsApp({  onLaunch (options) {    // Do something initial when launch.  },  onShow (options) {    // Do something when show.  },  onHide () {    // Do something when hide.  },  onError (msg) {    console.log(msg)  },  globalData: 'I am global data'})

整个小程序只有一个 App 实例,是全部页面共享的。开发者可以通过 getApp 方法获取到全局唯一的 App 实例,获取App上的数据或调用开发者注册在 App 上的函数。

// xxx.jsconst appInstance = getApp()console.log(appInstance.globalData) // I am global data


注册页面

对于小程序中的每个页面,都需要在页面对应的 js 文件中进行注册,指定页面的初始数据、生命周期回调、事件处理函数等。

使用 Page 构造器注册页面

简单的页面可以使用 Page() 进行构造。

代码示例:

//index.jsPage({  data: {    text: "This is page data."  },  onLoad: function(options) {    // 页面创建时执行  },  onShow: function() {    // 页面出现在前台时执行  },  onReady: function() {    // 页面首次渲染完毕时执行  },  onHide: function() {    // 页面从前台变为后台时执行  },  onUnload: function() {    // 页面销毁时执行  },  onPullDownRefresh: function() {    // 触发下拉刷新时执行  },  onReachBottom: function() {    // 页面触底时执行  },  onShareAppMessage: function () {    // 页面被用户分享时执行  },  onPageScroll: function() {    // 页面滚动时执行  },  onResize: function() {    // 页面尺寸变化时执行  },  onTabItemTap(item) {    // tab 点击时执行    console.log(item.index)    console.log(item.pagePath)    console.log(item.text)  },  // 事件响应函数  viewTap: function() {    this.setData({      text: 'Set some data for updating view.'    }, function() {      // this is setData callback    })  },  // 自由数据  customData: {    hi: 'MINA'  }})

详细的参数含义和使用请参考 Page 参考文档 。

在页面中使用 behaviors

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

页面可以引用 behaviors 。 behaviors 可以用来让多个页面有相同的数据字段和方法。

// my-behavior.jsmodule.exports = Behavior({  data: {    sharedText: 'This is a piece of data shared between pages.'  },  methods: {    sharedMethod: function() {      this.data.sharedText === 'This is a piece of data shared between pages.'    }  }})
// page-a.jsvar myBehavior = require('./my-behavior.js')Page({  behaviors: [myBehavior],  onLoad: function() {    this.data.sharedText === 'This is a piece of data shared between pages.'  }})

具体用法参见 behaviors 。

使用 Component 构造器构造页面

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

Page 构造器适用于简单的页面。但对于复杂的页面, Page 构造器可能并不好用。

此时,可以使用 Component 构造器来构造页面。 Component 构造器的主要区别是:方法需要放在 methods: { } 里面。

代码示例:

Component({  data: {    text: "This is page data."  },  methods: {    onLoad: function(options) {      // 页面创建时执行    },    onPullDownRefresh: function() {      // 下拉刷新时执行    },    // 事件响应函数    viewTap: function() {      // ...    }  }})

这种创建方式非常类似于 自定义组件 ,可以像自定义组件一样使用 behaviors 等高级特性。

具体细节请阅读 Component 构造器 章节。


生命周期

以下内容你不需要立马完全弄明白,不过以后它会有帮助。

下图说明了页面 Page 实例的生命周期。


页面路由

在小程序中所有页面的路由全部由框架进行管理。

页面栈

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

路由方式页面栈表现
初始化新页面入栈
打开新页面新页面入栈
页面重定向当前页面出栈,新页面入栈
页面返回页面不断出栈,直到目标返回页
Tab 切换页面全部出栈,只留下新的 Tab 页面
重加载页面全部出栈,只留下新的页面

开发者可以使用 getCurrentPages() 函数获取当前页面栈。

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

页面栈示例:页面栈遵循先进后出的规则,当前也在最上面。

路由方式

对于路由的触发方式以及页面生命周期函数如下:

路由方式触发时机路由前页面路由后页面
初始化小程序打开的第一个页面onLoad, onShow
打开新页面调用 API wx.navigateTo
使用组件 <navigator open-type="navigateTo"/>
onHideonLoad, onShow
页面重定向调用 API wx.redirectTo
使用组件 <navigator open-type="redirectTo"/>
onUnloadonLoad, onShow
页面返回调用 API wx.navigateBack
使用组件<navigator open-type="navigateBack">
用户按左上角返回按钮
onUnloadonShow
Tab 切换调用 API wx.switchTab
使用组件 <navigator open-type="switchTab"/>
用户切换 Tab
各种情况请参考下表
重启动调用 API wx.reLaunch
使用组件 <navigator open-type="reLaunch"/>
onUnloadonLoad, onShow

Tab 切换对应的生命周期(以 A、B 页面为 Tabbar 页面,C 是从 A 页面打开的页面,D 页面是从 C 页面打开的页面为例):

当前页面路由后页面触发的生命周期(按顺序)
AANothing happend
ABA.onHide(), B.onLoad(), B.onShow()
AB(再次打开)A.onHide(), B.onShow()
CAC.onUnload(), A.onShow()
CBC.onUnload(), B.onLoad(), B.onShow()
DBD.onUnload(), C.onUnload(), B.onLoad(), B.onShow()
D(从转发进入)AD.onUnload(), A.onLoad(), A.onShow()
D(从转发进入)BD.onUnload(), B.onLoad(), B.onShow()

Tips:

  • navigateToredirectTo 只能打开非 tabBar 页面。
  • switchTab 只能打开tabBar 页面。
  • reLaunch 可以打开任意页面。
  • 页面底部的 tabBar 由页面决定,即只要是定义为 tabBar 的页面,底部都有 tabBar
  • 调用页面路由带的参数可以在目标页面的onLoad中获取。


模块化

可以将一些公共的代码抽离成为一个单独的 js 文件,作为一个模块。模块只有通过 module.exports 或者 exports 才能对外暴露接口。

注意:

  • exports 是 module.exports 的一个引用,因此在模块里边随意更改 exports 的指向会造成未知的错误。所以更推荐开发者采用 module.exports 来暴露模块接口,除非你已经清晰知道这两者的关系。
  • 小程序目前不支持直接引入 node_modules , 开发者需要使用到 node_modules 时候建议拷贝出相关的代码到小程序的目录中,或者使用小程序支持的 npm 功能。
// common.jsfunction sayHello(name) {  console.log(`Hello ${name} !`)}function sayGoodbye(name) {  console.log(`Goodbye ${name} !`)}module.exports.sayHello = sayHelloexports.sayGoodbye = sayGoodbye

​在需要使用这些模块的文件中,使用 require 将公共代码引入

var common = require('common.js')Page({  helloMINA: function() {    common.sayHello('MINA')  },  goodbyeMINA: function() {    common.sayGoodbye('MINA')  }})

文件作用域

在 JavaScript 文件中声明的变量和函数只在该文件中有效;不同的文件中可以声明相同名字的变量和函数,不会互相影响。

通过全局函数 getApp 可以获取全局的应用实例,如果需要全局的数据可以在 App() 中设置,如:

// app.jsApp({  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)


API

小程序开发框架提供丰富的微信原生 API,可以方便的调起微信提供的能力,如获取用户信息,本地存储,支付功能等。详细介绍请参考 API 文档

通常,在小程序 API 有以下几种类型:

事件监听 API

我们约定,以 on 开头的 API 用来监听某个事件是否触发,如:wx.onSocketOpenwx.onCompassChange 等。

这类 API 接受一个回调函数作为参数,当事件触发时会调用这个回调函数,并将相关数据以参数形式传入。

代码示例

wx.onCompassChange(function (res) {  console.log(res.direction)})

同步 API

我们约定,以 Sync 结尾的 API 都是同步 API, 如 wx.setStorageSyncwx.getSystemInfoSync 等。此外,也有一些其他的同步 API,如 wx.createWorkerwx.getBackgroundAudioManager 等,详情参见 API 文档中的说明。

同步 API 的执行结果可以通过函数返回值直接获取,如果执行出错会抛出异常。

代码示例

try {  wx.setStorageSync('key', 'value')} catch (e) {  console.error(e)}

异步 API

大多数 API 都是异步 API,如 wx.requestwx.login 等。这类 API 接口通常都接受一个 Object 类型的参数,这个参数都支持按需指定以下字段来接收接口调用结果:

Object 参数说明

参数名类型必填说明
successfunction接口调用成功的回调函数
failfunction接口调用失败的回调函数
completefunction接口调用结束的回调函数(调用成功、失败都会执行)
其他Any-接口定义的其他参数

回调函数的参数

success,fail,complete 函数调用时会传入一个 Object 类型参数,包含以下字段:

属性类型说明
errMsgstring错误信息,如果调用成功返回 ${apiName}:ok
errCodenumber错误码,仅部分 API 支持,具体含义请参考对应 API 文档,成功时为 0
其他Any接口返回的其他数据

异步 API 的执行结果需要通过 Object 类型的参数中传入的对应回调函数获取。部分异步 API 也会有返回值,可以用来实现更丰富的功能,如 wx.requestwx.connectSocket 等。

代码示例

wx.login({  success(res) {    console.log(res.code)  }})

异步 API 返回 Promise

基础库 2.10.2 版本起,异步 API 支持 callback & promise 两种调用方式。当接口参数 Object 对象中不包含 success/fail/complete 时将默认返回 promise,否则仍按回调方式执行,无返回值。

注意事项

  1. 部分接口如 downloadFile, request, uploadFile, connectSocket, createCamera(小游戏)本身就有返回值, 它们的 promisify 需要开发者自行封装。
  2. 当没有回调参数时,异步接口返回 promise。此时若函数调用失败进入 fail 逻辑, 会报错提示 Uncaught (in promise),开发者可通过 catch 来进行捕获。
  3. wx.onUnhandledRejection 可以监听未处理的 Promise 拒绝事件。

代码示例

// callback 形式调用wx.chooseImage({  success(res) {    console.log('res:', res)  }})// promise 形式调用wx.chooseImage().then(res => console.log('res: ', res))


WXML

WXML(WeiXin Markup Language)是框架设计的一套标签语言,结合基础组件事件系统,可以构建出页面的结构。

要完整了解 WXML 语法,请参考WXML 语法参考

用以下一些简单的例子来看看 WXML 具有什么能力:

数据绑定

<!--wxml--><view> {{message}} </view>
// page.jsPage({  data: {    message: 'Hello MINA!'  }})

列表渲染

<!--wxml--><view wx:for="{{array}}"> {{item}} </view>
// page.jsPage({  data: {    array: [1, 2, 3, 4, 5]  }})

条件渲染

<!--wxml--><view wx:if="{{view == 'WEBVIEW'}}"> WEBVIEW </view><view wx:elif="{{view == 'APP'}}"> APP </view><view wx:else="{{view == 'MINA'}}"> MINA </view>
// page.jsPage({  data: {    view: 'MINA'  }})

模板

<!--wxml--><template name="staffName">  <view>    FirstName: {{firstName}}, LastName: {{lastName}}  </view></template><template is="staffName" data="{{...staffA}}"></template><template is="staffName" data="{{...staffB}}"></template><template is="staffName" data="{{...staffC}}"></template>
// page.jsPage({  data: {    staffA: {firstName: 'Hulk', lastName: 'Hu'},    staffB: {firstName: 'Shang', lastName: 'You'},    staffC: {firstName: 'Gideon', lastName: 'Lin'}  }})

引用

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

具体的能力以及使用方式在以下章节查看:

数据绑定列表渲染条件渲染模板引用


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/屏幕宽度)
iPhone51rpx = 0.42px1px = 2.34rpx
iPhone61rpx = 0.5px1px = 2rpx
iPhone6 Plus1rpx = 0.552px1px = 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" 的组件
elementview选择所有 view 组件
element, elementview, checkbox选择所有文档的 view 组件和所有的 checkbox 组件
::afterview::after在 view 组件后边插入内容
::beforeview::before在 view 组件前边插入内容

全局样式与局部样式

定义在 app.wxss 中的样式为全局样式,作用于每一个页面。在 page 的 wxss 文件中定义的样式为局部样式,只作用在对应的页面,并会覆盖 app.wxss 中相同的选择器。


WXS

WXS(WeiXin Script)是小程序的一套脚本语言,结合 WXML,可以构建出页面的结构。

注意

  1. WXS 不依赖于运行时的基础库版本,可以在所有版本的小程序中运行。
  2. WXS 与 JavaScript 是不同的语言,有自己的语法,并不和 JavaScript 一致。
  3. WXS 的运行环境和其他 JavaScript 代码是隔离的,WXS 中不能调用其他 JavaScript 文件中定义的函数,也不能调用小程序提供的API。
  4. WXS 函数不能作为组件的事件回调。
  5. 由于运行环境的差异,在 iOS 设备上小程序内的 WXS 会比 JavaScript 代码快 2 ~ 20 倍。在 android 设备上二者运行效率无差异。

以下是一些使用 WXS 的简单示例,要完整了解 WXS 语法,请参考WXS 语法参考

页面渲染

<!--wxml--><wxs module="m1">var msg = "hello world";module.exports.message = msg;</wxs><view> {{m1.message}} </view>

页面输出:

hello world

数据处理

// page.jsPage({  data: {    array: [1, 2, 3, 4, 5, 1, 2, 3, 4]  }})
<!--wxml--><!-- 下面的 getMax 函数,接受一个数组,且返回数组中最大的元素的值 --><wxs module="m1">var getMax = function(array) {  var max = undefined;  for (var i = 0; i < array.length; ++i) {    max = max === undefined ?      array[i] :      (max >= array[i] ? max : array[i]);  }  return max;}module.exports.getMax = getMax;</wxs><!-- 调用 wxs 里面的 getMax 函数,参数为 page.js 里面的 array --><view> {{m1.getMax(array)}} </view>

页面输出:

5


事件

什么是事件

  • 事件是视图层到逻辑层的通讯方式。
  • 事件可以将用户的行为反馈到逻辑层进行处理。
  • 事件可以绑定在组件上,当达到触发事件,就会执行逻辑层中对应的事件处理函数。
  • 事件对象可以携带额外信息,如 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函数响应事件。

事件详解

事件分类

事件分为冒泡事件和非冒泡事件:

  1. 冒泡事件:当一个组件上的事件被触发后,该事件会向父节点传递。
  2. 非冒泡事件:当一个组件上的事件被触发后,该事件不会向父节点传递。

WXML的冒泡事件列表:

类型触发条件最低版本
touchstart手指触摸动作开始
touchmove手指触摸后移动
touchcancel手指触摸动作被打断,如来电提醒,弹窗
touchend手指触摸动作结束
tap手指触摸后马上离开
longpress手指触摸后,超过350ms再离开,如果指定了事件回调函数并触发了这个事件,tap事件将不被触发1.5.0
longtap手指触摸后,超过350ms再离开(推荐使用longpress事件代替)
transitionend会在 WXSS transition 或 wx.createAnimation 动画结束后触发
animationstart会在一个 WXSS animation 动画开始时触发
animationiteration会在一个 WXSS animation 一次迭代结束时触发
animationend会在一个 WXSS animation 动画完成时触发
touchforcechange在支持 3D Touch 的 iPhone 设备,重按时会触发1.9.90

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

普通事件绑定

事件绑定的写法类似于组件的属性,如:

<view bindtap="handleTap">    Click here!</view>

如果用户点击这个 view ,则页面的 handleTap 会被调用。

事件绑定函数可以是一个数据绑定,如:

<view bindtap="{{ handlerName }}">    Click here!</view>

此时,页面的 this.data.handlerName 必须是一个字符串,指定事件处理函数名;如果它是个空字符串,则这个绑定会失效(可以利用这个特性来暂时禁用一些事件)。

自基础库版本 1.5.0 起,在大多数组件和自定义组件中, bind 后可以紧跟一个冒号,其含义不变,如 bind:tap 。基础库版本 2.8.1 起,在所有组件中开始提供这个支持。

绑定并阻止事件冒泡

除 bind 外,也可以用 catch 来绑定事件。与 bind 不同, catch 会阻止事件向上冒泡。

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

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

互斥事件绑定

自基础库版本 2.8.2 起,除 bind 和 catch 外,还可以使用 mut-bind 来绑定事件。一个 mut-bind 触发后,如果事件冒泡到其他节点上,其他节点上的 mut-bind 绑定函数不会被触发,但 bind 绑定函数和 catch 绑定函数依旧会被触发。

换而言之,所有 mut-bind 是“互斥”的,只会有其中一个绑定函数被触发。同时,它完全不影响 bind 和 catch 的绑定效果。

例如在下边这个例子中,点击 inner view 会先后调用 handleTap3 和 handleTap2 ,点击 middle view 会调用 handleTap2 和 handleTap1 。

<view id="outer" mut-bind:tap="handleTap1">  outer view  <view id="middle" bindtap="handleTap2">    middle view    <view id="inner" mut-bind:tap="handleTap3">      inner view    </view>  </view></view>

事件的捕获阶段

自基础库版本 1.5.0 起,触摸类事件支持捕获阶段。捕获阶段位于冒泡阶段之前,且在捕获阶段中,事件到达节点的顺序与冒泡阶段恰好相反。需要在捕获阶段监听事件时,可以采用capture-bind、capture-catch关键字,后者将中断捕获阶段和取消冒泡阶段。

在下面的代码中,点击 inner view 会先后调用handleTap2、handleTap4、handleTap3、handleTap1。

<view id="outer" bind:touchstart="handleTap1" capture-bind:touchstart="handleTap2">  outer view  <view id="inner" bind:touchstart="handleTap3" capture-bind:touchstart="handleTap4">    inner view  </view></view>

如果将上面代码中的第一个capture-bind改为capture-catch,将只触发handleTap2。

<view id="outer" bind:touchstart="handleTap1" capture-catch:touchstart="handleTap2">  outer view  <view id="inner" bind:touchstart="handleTap3" capture-bind:touchstart="handleTap4">    inner view  </view></view>

事件对象

如无特殊说明,当组件触发事件时,逻辑层绑定该事件的处理函数会收到一个事件对象。

BaseEvent 基础事件对象属性列表:

属性类型说明基础库版本
typeString事件类型
timeStampInteger事件生成时的时间戳
targetObject触发事件的组件的一些属性值集合
currentTargetObject当前组件的一些属性值集合
markObject事件标记数据2.7.1

CustomEvent 自定义事件对象属性列表(继承 BaseEvent):

属性类型说明
detailObject额外的信息

TouchEvent 触摸事件对象属性列表(继承 BaseEvent):

属性类型说明
touchesArray触摸事件,当前停留在屏幕中的触摸点信息的数组
changedTouchesArray触摸事件,当前变化的触摸点信息的数组

特殊事件: canvas 中的触摸事件不可冒泡,所以没有 currentTarget。

type

代表事件的类型。

timeStamp

页面打开到触发事件所经过的毫秒数。

target

触发事件的源组件。

属性类型说明
idString事件源组件的id
datasetObject事件源组件上由data-开头的自定义属性组成的集合

currentTarget

事件绑定的当前组件。

属性类型说明
idString当前组件的id
datasetObject当前组件上由data-开头的自定义属性组成的集合

说明: target 和 currentTarget 可以参考上例中,点击 inner view 时,handleTap3 收到的事件对象 target 和 currentTarget 都是 inner,而 handleTap2 收到的事件对象 target 就是 inner,currentTarget 就是 middle。

dataset

在组件节点中可以附加一些自定义数据。这样,在事件中可以获取这些自定义的节点数据,用于事件的逻辑处理。

在 WXML 中,这些自定义数据以 data- 开头,多个单词由连字符 - 连接。这种写法中,连字符写法会转换成驼峰写法,而大写字符会自动转成小写字符。如:

  • data-element-type ,最终会呈现为 event.currentTarget.dataset.elementType ;
  • data-elementType ,最终会呈现为 event.currentTarget.dataset.elementtype 。

示例:

<view data-alpha-beta="1" data-alphaBeta="2" bindtap="bindViewTap"> DataSet Test </view>
Page({  bindViewTap:function(event){    event.currentTarget.dataset.alphaBeta === 1 // - 会转为驼峰写法    event.currentTarget.dataset.alphabeta === 2 // 大写会转为小写  }})

mark

在基础库版本 2.7.1 以上,可以使用 mark 来识别具体触发事件的 target 节点。此外, mark 还可以用于承载一些自定义数据(类似于 dataset )。

当事件触发时,事件冒泡路径上所有的 mark 会被合并,并返回给事件回调函数。(即使事件不是冒泡事件,也会 mark 。)

代码示例:

<view mark:myMark="last" bindtap="bindViewTap">  <button mark:anotherMark="leaf" bindtap="bindButtonTap">按钮</button></view>

在上述 WXML 中,如果按钮被点击,将触发 bindViewTap 和 bindButtonTap 两个事件,事件携带的 event.mark 将包含 myMark 和 anotherMark 两项。

Page({  bindViewTap: function(e) {    e.mark.myMark === "last" // true    e.mark.anotherMark === "leaf" // true  }})

mark 和 dataset 很相似,主要区别在于: mark 会包含从触发事件的节点到根节点上所有的 mark: 属性值;而 dataset 仅包含一个节点的 data- 属性值。

细节注意事项:

  • 如果存在同名的 mark ,父节点的 mark 会被子节点覆盖。
  • 在自定义组件中接收事件时, mark 不包含自定义组件外的节点的 mark 。
  • 不同于 dataset ,节点的 mark 不会做连字符和大小写转换。

touches

touches 是一个数组,每个元素为一个 Touch 对象(canvas 触摸事件中携带的 touches 是 CanvasTouch 数组)。 表示当前停留在屏幕上的触摸点。

Touch 对象

属性类型说明
identifierNumber触摸点的标识符
pageX, pageYNumber距离文档左上角的距离,文档的左上角为原点 ,横向为X轴,纵向为Y轴
clientX, clientYNumber距离页面可显示区域(屏幕除去导航条)左上角距离,横向为X轴,纵向为Y轴

CanvasTouch 对象

属性类型说明特殊说明
identifierNumber触摸点的标识符
x, yNumber距离 Canvas 左上角的距离,Canvas 的左上角为原点 ,横向为X轴,纵向为Y轴

changedTouches

changedTouches 数据格式同 touches。 表示有变化的触摸点,如从无变有(touchstart),位置变化(touchmove),从有变无(touchend、touchcancel)。

detail

自定义事件所携带的数据,如表单组件的提交事件会携带用户的输入,媒体的错误事件会携带错误信息,详见组件定义中各个事件的定义。

点击事件的detail 带有的 x, y 同 pageX, pageY 代表距离文档左上角的距离。


WXS响应事件

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

背景

有频繁用户交互的效果在小程序上表现是比较卡顿的,例如页面有 2 个元素 A 和 B,用户在 A 上做 touchmove 手势,要求 B 也跟随移动,movable-view 就是一个典型的例子。一次 touchmove 事件的响应过程为:

a、touchmove 事件从视图层(Webview)抛到逻辑层(App Service)

b、逻辑层(App Service)处理 touchmove 事件,再通过 setData 来改变 B 的位置

一次 touchmove 的响应需要经过 2 次的逻辑层和渲染层的通信以及一次渲染,通信的耗时比较大。此外 setData 渲染也会阻塞其它脚本执行,导致了整个用户交互的动画过程会有延迟。

实现方案

本方案基本的思路是减少通信的次数,让事件在视图层(Webview)响应。小程序的框架分为视图层(Webview)和逻辑层(App Service),这样分层的目的是管控,开发者的代码只能运行在逻辑层(App Service),而这个思路就必须要让开发者的代码运行在视图层(Webview),如下图所示的流程:

使用 WXS 函数用来响应小程序事件,目前只能响应内置组件的事件,不支持自定义组件事件。WXS 函数的除了纯逻辑的运算,还可以通过封装好的ComponentDescriptor 实例来访问以及设置组件的 class 和样式,对于交互动画,设置 style 和 class 足够了。WXS 函数的例子如下:

var wxsFunction = function(event, ownerInstance) {    var instance = ownerInstance.selectComponent('.classSelector') // 返回组件的实例    instance.setStyle({        "font-size": "14px" // 支持rpx    })    instance.getDataset()    instance.setClass(className)    // ...    return false // 不往上冒泡,相当于调用了同时调用了stopPropagation和preventDefault}

其中入参 event 是小程序事件对象基础上多了 event.instance 来表示触发事件的组件的 ComponentDescriptor 实例。ownerInstance 表示的是触发事件的组件所在的组件的 ComponentDescriptor 实例,如果触发事件的组件是在页面内的,ownerInstance 表示的是页面实例。

ComponentDescriptor的定义如下:

方法参数描述最低版本
selectComponentselector对象返回组件的 ComponentDescriptor 实例。
selectAllComponentsselector对象数组返回组件的 ComponentDescriptor 实例数组。
setStyleObject/string设置组件样式,支持rpx。设置的样式优先级比组件 wxml 里面定义的样式高。不能设置最顶层页面的样式。
addClass/removeClass/ hasClassstring设置组件的 class。设置的 class 优先级比组件 wxml 里面定义的 class 高。不能设置最顶层页面的 class。
getDataset返回当前组件/页面的 dataset 对象
callMethod(funcName:string, args:object)调用当前组件/页面在逻辑层(App Service)定义的函数。funcName表示函数名称,args表示函数的参数。
requestAnimationFrameFunction和原生 requestAnimationFrame 一样。用于设置动画。
getState返回一个object对象,当有局部变量需要存储起来后续使用的时候用这个方法。
triggerEvent(eventName, detail)和组件的triggerEvent一致。
getComputedStyleArray.<string>参数与 SelectorQuery 的 computedStyle 一致。2.11.2

WXS 运行在视图层(Webview),里面的逻辑毕竟能做的事件比较少,需要有一个机制和逻辑层(App Service)开发者的代码通信,上面的 callMethod 是 WXS 里面调用逻辑层(App Service)开发者的代码的方法,而 WxsPropObserver 是逻辑层(App Service)开发者的代码调用 WXS 逻辑的机制。

使用方法

  • WXML定义事件:
<wxs module="test" src="./test.wxs"></wxs><view change:prop="{{test.propObserver}}" prop="{{propValue}}" bindtouchmove="{{test.touchmove}}" class="movable"></view>

上面的change:prop(属性前面带change:前缀)是在 prop 属性被设置的时候触发 WXS 函数,值必须用{{}}括起来。类似 Component 定义的 properties 里面的 observer 属性,在setData({propValue: newValue})调用之后会触发。

注意:WXS函数必须用{{}}括起来。当 prop 的值被设置 WXS 函数就会触发,而不只是值发生改变,所以在页面初始化的时候会调用一次WxsPropObserver的函数。

  • WXS文件test.wxs里面定义并导出事件处理函数和属性改变触发的函数:
module.exports = {    touchmove: function(event, instance) {        console.log('log event', JSON.stringify(event))    },    propObserver: function(newValue, oldValue, ownerInstance, instance) {        console.log('prop observer', newValue, oldValue)    }}

提示:

  1. 目前还不支持原生组件的事件、input和textarea组件的 bindinput 事件
  2. 1.02.1901170及以后版本的开发者工具上支持交互动画,最低版本基础库是2.4.4
  3. 目前在WXS函数里面仅支持console.log方式打日志定位问题,注意连续的重复日志会被过滤掉。


简易双向绑定

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

双向绑定语法

在 WXML 中,普通的属性的绑定是单向的。例如:

<input value="{{value}}" />

如果使用 this.setData({ value: 'leaf' }) 来更新 value ,this.data.value 和输入框的中显示的值都会被更新为 leaf ;但如果用户修改了输入框里的值,却不会同时改变 this.data.value 。

如果需要在用户输入的同时改变 this.data.value ,需要借助简易双向绑定机制。此时,可以在对应项目之前加入 model: 前缀:

<input model:value="{{value}}" />

这样,如果输入框的值被改变了, this.data.value 也会同时改变。同时, WXML 中所有绑定了 value 的位置也会被一同更新, 数据监听器 也会被正常触发。

用于双向绑定的表达式有如下限制:

    1.只能是一个单一字段的绑定,如

<input model:value="值为 {{value}}" /><input model:value="{{ a + b }}" />

都是非法的;

    2.目前,尚不能 data 路径,如

<input model:value="{{ a.b }}" />

这样的表达式目前暂不支持。

在自定义组件中传递双向绑定

双向绑定同样可以使用在自定义组件上。如下的自定义组件:

// custom-component.jsComponent({  properties: {    myValue: String  }})
<!-- custom-component.wxml --><input model:value="{{myValue}}" />

这个自定义组件将自身的 myValue 属性双向绑定到了组件内输入框的 value 属性上。这样,如果页面这样使用这个组件:

<custom-component model:my-value="{{pageValue}}" />

当输入框的值变更时,自定义组件的 myValue 属性会同时变更,这样,页面的 this.data.pageValue 也会同时变更,页面 WXML 中所有绑定了 pageValue 的位置也会被一同更新。

在自定义组件中触发双向绑定更新

自定义组件还可以自己触发双向绑定更新,做法就是:使用 setData 设置自身的属性。例如:

// custom-component.jsComponent({  properties: {    myValue: String  },  methods: {    update: function() {      // 更新 myValue      this.setData({        myValue: 'leaf'      })    }  }})

如果页面这样使用这个组件:

<custom-component model:my-value="{{pageValue}}" />

当组件使用 setData 更新 myValue 时,页面的 this.data.pageValue 也会同时变更,页面 WXML 中所有绑定了 pageValue 的位置也会被一同更新。


基础组件

框架为开发者提供了一系列基础组件,开发者可以通过组合这些基础组件进行快速开发。详细介绍请参考组件文档

什么是组件:

  • 组件是视图层的基本组成单元。
  • 组件自带一些功能与微信风格一致的样式。
  • 一个组件通常包括 开始标签 和 结束标签,属性 用来修饰这个组件,内容 在两个标签之内。
<tagname property="value">Content goes here ...</tagname>

注意:所有组件与属性都是小写,以连字符-连接

属性类型

类型描述注解
Boolean布尔值组件写上该属性,不管是什么值都被当作 true;只有组件上没有该属性时,属性值才为false
如果属性值为变量,变量的值会被转换为Boolean类型
Number数字12.5
String字符串"string"
Array数组[ 1, "string" ]
Object对象{ key: value }
EventHandler事件处理函数名"handlerName" 是 Page 中定义的事件处理函数名
Any任意属性

公共属性

所有组件都有以下属性:

属性名类型描述注解
idString组件的唯一标示保持整个页面唯一
classString组件的样式类在对应的 WXSS 中定义的样式类
styleString组件的内联样式可以动态设置的内联样式
hiddenBoolean组件是否显示所有组件默认显示
data-*Any自定义属性组件上触发的事件时,会发送给事件处理函数
bind* / catch*EventHandler组件的事件详见事件

特殊属性

几乎所有组件都有各自定义的属性,可以对该组件的功能或样式进行修饰,请参考各个组件的定义。


获取界面上的节点信息

WXML节点信息

节点信息查询 API 可以用于获取节点属性、样式、在界面上的位置等信息。

最常见的用法是使用这个接口来查询某个节点的当前位置,以及界面的滚动位置。

示例代码:

const query = wx.createSelectorQuery()query.select('#the-id').boundingClientRect(function(res){  res.top // #the-id 节点的上边界坐标(相对于显示区域)})query.selectViewport().scrollOffset(function(res){  res.scrollTop // 显示区域的竖直滚动位置})query.exec()

上述示例中, #the-id 是一个节点选择器,与 CSS 的选择器相近但略有区别,请参见 SelectorQuery.select 的相关说明。

在自定义组件或包含自定义组件的页面中,推荐使用 this.createSelectorQuery 来代替 wx.createSelectorQuery ,这样可以确保在正确的范围内选择节点。

WXML节点布局相交状态

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

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

  • 参照节点:监听的参照节点,取它的布局区域作为参照区域。如果有多个参照节点,则会取它们布局区域的 交集 作为参照区域。页面显示区域也可作为参照区域之一。
  • 目标节点:监听的目标,默认只能是一个节点(使用 selectAll 选项时,可以同时监听多个节点)。
  • 相交区域:目标节点的布局区域与参照区域的相交区域。
  • 相交比例:相交区域占参照区域的比例。
  • 阈值:相交比例如果达到阈值,则会触发监听器的回调函数。阈值可以有多个。

以下示例代码可以在目标节点(用选择器 .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 // 相交区域的高度    })  }})

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

在自定义组件或包含自定义组件的页面中,推荐使用 this.createIntersectionObserver 来代替 wx.createIntersectionObserver ,这样可以确保在正确的范围内选择节点。


响应显示区域变化

显示区域尺寸

显示区域指小程序界面中可以自由布局展示的区域。在默认情况下,小程序显示区域的尺寸自页面初始化起就不会发生变化。但以下两种方式都可以改变这一默认行为。

在手机上启用屏幕旋转支持

从小程序基础库版本 2.4.0 开始,小程序在手机上支持屏幕旋转。使小程序中的页面支持屏幕旋转的方法是:在 app.json 的 window 段中设置 "pageOrientation": "auto" ,或在页面 json 文件中配置 "pageOrientation": "auto" 。

以下是在单个页面 json 文件中启用屏幕旋转的示例。

代码示例:

{  "pageOrientation": "auto"}

如果页面添加了上述声明,则在屏幕旋转时,这个页面将随之旋转,显示区域尺寸也会随着屏幕旋转而变化。

从小程序基础库版本 2.5.0 开始, pageOrientation 还可以被设置为 landscape ,表示固定为横屏显示。

在 iPad 上启用屏幕旋转支持

从小程序基础库版本 2.3.0 开始,在 iPad 上运行的小程序可以支持屏幕旋转。使小程序支持 iPad 屏幕旋转的方法是:在 app.json 中添加 "resizable": true 。

代码示例:

{  "resizable": true}

如果小程序添加了上述声明,则在屏幕旋转时,小程序将随之旋转,显示区域尺寸也会随着屏幕旋转而变化。注意:在 iPad 上不能单独配置某个页面是否支持屏幕旋转。

Media Query

有时,对于不同尺寸的显示区域,页面的布局会有所差异。此时可以使用 media query 来解决大多数问题。

代码示例:

.my-class {  width: 40px;}@media (min-width: 480px) {  /* 仅在 480px 或更宽的屏幕上生效的样式规则 */  .my-class {    width: 200px;  }}

在 WXML 中,可以使用 match-media 组件来根据 media query 匹配状态展示、隐藏节点。

此外,可以在页面或者自定义组件 JS 中使用 this.createMediaQueryObserver() 方法来创建一个 MediaQueryObserver 对象,用于监听指定的 media query 的匹配状态。

屏幕旋转事件

有时,仅仅使用 media query 无法控制一些精细的布局变化。此时可以使用 js 作为辅助。

在 js 中读取页面的显示区域尺寸,可以使用 selectorQuery.selectViewport 。

页面尺寸发生改变的事件,可以使用页面的 onResize 来监听。对于自定义组件,可以使用 resize 生命周期来监听。回调函数中将返回显示区域的尺寸信息。(从基础库版本 2.4.0 开始支持。)

代码示例:

Page({  onResize(res) {    res.size.windowWidth // 新的显示区域宽度    res.size.windowHeight // 新的显示区域高度  }})
Component({  pageLifetimes: {    resize(res) {      res.size.windowWidth // 新的显示区域宽度      res.size.windowHeight // 新的显示区域高度    }  }})

此外,还可以使用 wx.onWindowResize 来监听(但这不是推荐的方式)。

Bug & tips:

  • Bug: Android 微信版本 6.7.3 中, live-pusher 组件在屏幕旋转时方向异常。


动画

界面动画的常见方式

在小程序中,通常可以使用 CSS 渐变 和 CSS 动画 来创建简易的界面动画。

动画过程中,可以使用 bindtransitionend bindanimationstart bindanimationiteration bindanimationend 来监听动画事件。

事件名含义
transitionendCSS 渐变结束或 wx.createAnimation 结束一个阶段
animationstartCSS 动画开始
animationiterationCSS 动画结束一个阶段
animationendCSS 动画结束

注意:这几个事件都不是冒泡事件,需要绑定在真正发生了动画的节点上才会生效。

同时,还可以使用 wx.createAnimation 接口来动态创建简易的动画效果。(新版小程序基础库中推荐使用下述的关键帧动画接口代替。)

关键帧动画

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

从小程序基础库 2.9.0 开始支持一种更友好的动画创建方式,用于代替旧的 wx.createAnimation 。它具有更好的性能和更可控的接口。

在页面或自定义组件中,当需要进行关键帧动画时,可以使用 this.animate 接口:

this.animate(selector, keyframes, duration, callback)

参数说明

属性类型默认值必填说明
selectorString选择器(同 SelectorQuery.select 的选择器格式)
keyframesArray关键帧信息
durationNumber动画持续时长(毫秒为单位)
callbackfunction动画完成后的回调函数

keyframes 中对象的结构

属性类型默认值必填说明
offsetNumber关键帧的偏移,范围[0-1]
easeStringlinear动画缓动函数
transformOriginString基点位置,即 CSS transform-origin
backgroundColorString背景颜色,即 CSS background-color
bottomNumber/String底边位置,即 CSS bottom
heightNumber/String高度,即 CSS height
leftNumber/String左边位置,即 CSS left
widthNumber/String宽度,即 CSS width
opacityNumber不透明度,即 CSS opacity
rightNumber右边位置,即 CSS right
topNumber/String顶边位置,即 CSS top
matrixArray变换矩阵,即 CSS transform matrix
matrix3dArray三维变换矩阵,即 CSS transform matrix3d
rotateNumber旋转,即 CSS transform rotate
rotate3dArray三维旋转,即 CSS transform rotate3d
rotateXNumberX 方向旋转,即 CSS transform rotateX
rotateYNumberY 方向旋转,即 CSS transform rotateY
rotateZNumberZ 方向旋转,即 CSS transform rotateZ
scaleArray缩放,即 CSS transform scale
scale3dArray三维缩放,即 CSS transform scale3d
scaleXNumberX 方向缩放,即 CSS transform scaleX
scaleYNumberY 方向缩放,即 CSS transform scaleY
scaleZNumberZ 方向缩放,即 CSS transform scaleZ
skewArray倾斜,即 CSS transform skew
skewXNumberX 方向倾斜,即 CSS transform skewX
skewYNumberY 方向倾斜,即 CSS transform skewY
translateArray位移,即 CSS transform translate
translate3dArray三维位移,即 CSS transform translate3d
translateXNumberX 方向位移,即 CSS transform translateX
translateYNumberY 方向位移,即 CSS transform translateY
translateZNumberZ 方向位移,即 CSS transform translateZ

示例代码

在开发者工具中预览效果

  this.animate('#container', [    { opacity: 1.0, rotate: 0, backgroundColor: '#FF0000' },    { opacity: 0.5, rotate: 45, backgroundColor: '#00FF00'},    { opacity: 0.0, rotate: 90, backgroundColor: '#FF0000' },    ], 5000, function () {      this.clearAnimation('#container', { opacity: true, rotate: true }, function () {        console.log("清除了#container上的opacity和rotate属性")      })  }.bind(this))  this.animate('.block', [    { scale: [1, 1], rotate: 0, ease: 'ease-out'  },    { scale: [1.5, 1.5], rotate: 45, ease: 'ease-in', offset: 0.9},    { scale: [2, 2], rotate: 90 },  ], 5000, function () {    this.clearAnimation('.block', function () {      console.log("清除了.block上的所有动画属性")    })  }.bind(this))

调用 animate API 后会在节点上新增一些样式属性覆盖掉原有的对应样式。如果需要清除这些样式,可在该节点上的动画全部执行完毕后使用 this.clearAnimation 清除这些属性。

this.clearAnimation(selector, options, callback)

参数说明

属性类型默认值必填说明
selectorString选择器(同 SelectorQuery.select 的选择器格式)
optionsObject需要清除的属性,不填写则全部清除
callbackFunction清除完成后的回调函数

滚动驱动的动画

我们发现,根据滚动位置而不断改变动画的进度是一种比较常见的场景,这类动画可以让人感觉到界面交互很连贯自然,体验更好。因此,从小程序基础库 2.9.0 开始支持一种由滚动驱动的动画机制。

基于上述的关键帧动画接口,新增一个 ScrollTimeline 的参数,用来绑定滚动元素(目前只支持 scroll-view)。接口定义如下:

this.animate(selector, keyframes, duration, ScrollTimeline)

ScrollTimeline 中对象的结构

属性类型默认值必填说明
scrollSourceString指定滚动元素的选择器(只支持 scroll-view),该元素滚动时会驱动动画的进度
orientationStringvertical指定滚动的方向。有效值为 horizontal 或 vertical
startScrollOffsetNumber指定开始驱动动画进度的滚动偏移量,单位 px
endScrollOffsetNumber指定停止驱动动画进度的滚动偏移量,单位 px
timeRangeNumber起始和结束的滚动范围映射的时间长度,该时间可用于与关键帧动画里的时间 (duration) 相匹配,单位 ms

示例代码

在开发者工具中预览效果

  this.animate('.avatar', [{    borderRadius: '0',    borderColor: 'red',    transform: 'scale(1) translateY(-20px)',    offset: 0,  }, {    borderRadius: '25%',    borderColor: 'blue',    transform: 'scale(.65) translateY(-20px)',    offset: .5,  }, {    borderRadius: '50%',    borderColor: 'blue',    transform: `scale(.3) translateY(-20px)`,    offset: 1  }], 2000, {    scrollSource: '#scroller',    timeRange: 2000,    startScrollOffset: 0,    endScrollOffset: 85,  })  this.animate('.search_input', [{    opacity: '0',    width: '0%',  }, {    opacity: '1',    width: '100%',  }], 1000, {    scrollSource: '#scroller',    timeRange: 1000,    startScrollOffset: 120,    endScrollOffset: 252  })

高级的动画方式

在一些复杂场景下,上述的动画方法可能并不适用。

WXS 响应事件 的方式可以通过使用 WXS 来响应事件的方法来动态调整节点的 style 属性。通过不断改变 style 属性的值可以做到动画效果。同时,这种方式也可以根据用户的触摸事件来动态地生成动画。

连续使用 setData 来改变界面的方法也可以达到动画的效果。这样可以任意地改变界面,但通常会产生较大的延迟或卡顿,甚至导致小程序僵死。此时可以通过将页面的 setData 改为 自定义组件 中的 setData 来提升性能。下面的例子是使用 setData 来实现秒表动画的示例。


初始渲染缓存

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

初始渲染缓存工作原理

小程序页面的初始化分为两个部分。

  • 逻辑层初始化:载入必需的小程序代码、初始化页面 this 对象(也包括它涉及到的所有自定义组件的 this 对象)、将相关数据发送给视图层。
  • 视图层初始化:载入必需的小程序代码,然后等待逻辑层初始化完毕并接收逻辑层发送的数据,最后渲染页面。

在启动页面时,尤其是小程序冷启动、进入第一个页面时,逻辑层初始化的时间较长。在页面初始化过程中,用户将看到小程序的标准载入画面(冷启动时)或可能看到轻微的白屏现象(页面跳转过程中)。

启用初始渲染缓存,可以使视图层不需要等待逻辑层初始化完毕,而直接提前将页面初始 data 的渲染结果展示给用户,这可以使得页面对用户可见的时间大大提前。它的工作原理如下:

  • 在小程序页面第一次被打开后,将页面初始数据渲染结果记录下来,写入一个持久化的缓存区域(缓存可长时间保留,但可能因为小程序更新、基础库更新、储存空间回收等原因被清除);
  • 在这个页面被第二次打开时,检查缓存中是否还存有这个页面上一次初始数据的渲染结果,如果有,就直接将渲染结果展示出来;
  • 如果展示了缓存中的渲染结果,这个页面暂时还不能响应用户事件,等到逻辑层初始化完毕后才能响应用户事件。

利用初始渲染缓存,可以:

  • 快速展示出页面中永远不会变的部分,如导航栏;
  • 预先展示一个骨架页,提升用户体验;
  • 展示自定义的加载提示;
  • 提前展示广告,等等。

支持的组件

在初始渲染缓存阶段中,复杂组件不能被展示或不能响应交互。

目前支持的内置组件:

  • <view />
  • <text />
  • <button />
  • <image />
  • <scroll-view />
  • <rich-text />

自定义组件本身可以被展示(但它们里面用到的内置组件也遵循上述限制)。

静态初始渲染缓存

若想启用初始渲染缓存,最简单的方法是在页面的 json 文件中添加配置项 "initialRenderingCache": "static" :

{  "initialRenderingCache": "static"}

如果想要对所有页面启用,可以在 app.json 的 window 配置段中添加这个配置:

{  "window": {    "initialRenderingCache": "static"  }}

添加这个配置项之后,在手机中预览小程序首页,然后杀死小程序再次进入,就会通过初始渲染缓存来渲染首页。

注意:这种情况下,初始渲染缓存记录的是页面 data 应用在页面 WXML 上的结果,不包含任何 setData 的结果。

例如,如果想要在页面中展示出“正在加载”几个字,这几个字受到 loading 数据字段控制:

<view wx:if="{{loading}}">正在加载</view>

这种情况下, loading 应当在 data 中指定为 true ,如:

// 正确的做法Page({  data: {    loading: true  }})

而不能通过 setData 将 loading 置为 true :

// 错误的做法!不要这么做!Page({  data: {},  onLoad: function() {    this.setData({      loading: true    })  }})

换而言之,这种做法只包含页面 data 的渲染结果,即页面的纯静态成分。

在初始渲染缓存中添加动态内容

有些场景中,只是页面 data 的渲染结果会比较局限。有时会想要额外展示一些可变的内容,如展示的广告图片 URL 等。

这种情况下可以使用“动态”初始渲染缓存的方式。首先,配置 "initialRenderingCache": "dynamic" :

{  "initialRenderingCache": "dynamic"}

此时,初始渲染缓存不会被自动启用,还需要在页面中调用 this.setInitialRenderingCache(dynamicData) 才能启用。其中, dynamicData 是一组数据,与 data 一起参与页面 WXML 渲染。

Page({  data: {    loading: true  },  onReady: function() {    this.setInitialRenderingCache({      loadingHint: '正在加载' // 这一部分数据将被应用于界面上,相当于在初始 data 基础上额外进行一次 setData    })  }})
<view wx:if="{{loading}}">{{loadingHint}}</view>

从原理上说,在动态生成初始渲染缓存的方式下,页面会在后台使用动态数据重新渲染一次,因而开销相对较大。因而要尽量避免频繁调用 this.setInitialRenderingCache ,如果在一个页面内多次调用,仅最后一次调用生效。

注意:

  • this.setInitialRenderingCache 调用时机不能早于 Page 的 onReady 或 Component 的 ready 生命周期,否则可能对性能有负面影响。
  • 如果想禁用初始渲染缓存,调用 this.setInitialRenderingCache(null) 。


小程序的运行环境

微信小程序运行在多种平台上:iOS(iPhone/iPad)微信客户端、Android 微信客户端、PC 微信客户端、Mac 微信客户端和用于调试的微信开发者工具。

各平台脚本执行环境以及用于渲染非原生组件的环境是各不相同的:

  • 在 iOS 上,小程序逻辑层的 javascript 代码运行在 JavaScriptCore 中,视图层是由 WKWebView 来渲染的,环境有 iOS 12、iOS 13 等;
  • 在 Android 上,小程序逻辑层的 javascript 代码运行在 V8 中,视图层是由自研 XWeb 引擎基于 Mobile Chrome 内核来渲染的;
  • 在 开发工具上,小程序逻辑层的 javascript 代码是运行在 NW.js 中,视图层是由 Chromium Webview 来渲染的。

平台差异

尽管各运行环境是十分相似的,但是还是有些许区别:

  • JavaScript 语法和 API 支持不一致:语法上开发者可以通过开启 ES6 转 ES5 的功能来规避(详情);此外,小程序基础库内置了必要的Polyfill,来弥补API的差异(详情)。
  • WXSS 渲染表现不一致:尽管可以通过开启样式补全来规避大部分的问题,还是建议开发者需要在 iOS 和 Android 上分别检查小程序的真实表现。

开发者工具仅供调试使用,最终的表现以客户端为准。


JavaScript 支持情况

运行限制

基于安全考虑,小程序中不支持动态执行 JS 代码,即:

  • 不支持使用 eval 执行 JS 代码
  • 不支持使用 new Function 创建函数

客户端 ES6 API 支持情况

微信小程序已经支持了绝大部分的 ES6 API,已支持的 API 如下(部分API依赖系统版本):

StringiOS8iOS9iOS10+Android
codePointAt
normalize
includes
startsWith
endsWith
repeat
String.fromCodePoint
ArrayiOS8iOS9iOS10+Android
copyWithin
find
findIndex
fill
entries
keys
values
includes
Array.from
Array.of
NumberiOS8iOS9iOS10+Android
isFinite
isNaN
parseInt
parseFloat
isInteger
EPSILON
isSafeInteger
MathiOS8iOS9iOS10+Android
trunc
sign
cbrt
clz32
imul
fround
hypot
expm1
log1p
log10
log2
sinh
cosh
tanh
asinh
acosh
atanh
ObjectiOS8iOS9iOS10+Android
is
assign
getOwnPropertyDescriptor
keys
getOwnPropertyNames
getOwnPropertySymbols

OtheriOS8iOS9iOS10+Android
Symbol
Set
Map
Proxy
Reflect
Promise


小程序运行机制

前台/后台状态

小程序启动后,界面被展示给用户,此时小程序处于前台状态。

当用户点击右上角胶囊按钮关闭小程序,或者按了设备 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 获得这些已保存数据。

代码示例:

{  "restartStrategy": "homePageAndLatestPage"}
Page({  onLoad: function() {    var prevExitState = this.exitState // 尝试获得上一次退出前 onSaveExitState 保存的数据    if (prevExitState !== undefined) { // 如果是根据 restartStrategy 配置进行的冷启动,就可以获取到      prevExitState.myDataField === 'myData'     }  },  onSaveExitState: function() {    var exitState = { myDataField: 'myData' } // 需要保存的数据    return {      data: exitState,      expireTimeStamp: Date.now() + 24 * 60 * 60 * 1000 // 超时时刻    }  }})

onSaveExitState 返回值可以包含两项:

字段名类型含义
dataAny需要保存的数据(只能是 JSON 兼容的数据)
expireTimeStampNumber超时时刻,在这个时刻后,保存的数据保证一定被丢弃,默认为 (当前时刻 + 1 天)


注意事项:

  • 如果超过 expireTimeStamp ,保存的数据将被丢弃,且冷启动时不遵循 restartStrategy 的配置,而是直接从首页冷启动。
  • expireTimeStamp 有可能被自动提前,如微信客户端需要清理数据的时候。
  • 在小程序存活期间, onSaveExitState 可能会被多次调用,此时以最后一次的调用结果作为最终结果。
  • 在某些特殊情况下(如微信客户端直接被系统杀死),这个方法将不会被调用,下次冷启动也不遵循 restartStrategy 的配置,而是直接从首页冷启动。


小程序更新机制

未启动时更新

开发者在管理后台发布新版本的小程序之后,如果某个用户本地有小程序的历史版本,此时打开的可能还是旧版本。微信客户端会有若干个时机去检查本地缓存的小程序有没有更新版本,如果有则会静默更新到新版本。总的来说,开发者在后台发布新版本之后,无法立刻影响到所有现网用户,但最差情况下,也在发布之后 24 小时之内下发新版本信息到用户。用户下次打开时会先更新最新版本再打开。

启动时更新

小程序每次冷启动时,都会检查是否有更新版本,如果发现有新版本,将会异步下载新版本的代码包,并同时用客户端本地的包进行启动,即新版本的小程序需要等下一次冷启动才会应用上。

如果需要马上应用最新版本,可以使用 wx.getUpdateManager API 进行处理。

const updateManager = wx.getUpdateManager()updateManager.onCheckForUpdate(function (res) {  // 请求完新版本信息的回调  console.log(res.hasUpdate)})updateManager.onUpdateReady(function () {  wx.showModal({    title: '更新提示',    content: '新版本已经准备好,是否重启应用?',    success(res) {      if (res.confirm) {        // 新的版本已经下载好,调用 applyUpdate 应用新版本并重启        updateManager.applyUpdate()      }    }  })})updateManager.onUpdateFailed(function () {  // 新版本下载失败})


组件模板和样式

类似于页面,自定义组件拥有自己的 wxml 模板和 wxss 样式。

组件模板

组件模板的写法与页面模板相同。组件模板与组件数据结合后生成的节点树,将被插入到组件的引用位置上。

在组件模板中可以提供一个 <slot> 节点,用于承载组件引用时提供的子节点。

代码示例:

<!-- 组件模板 --><view class="wrapper">  <view>这里是组件的内部节点</view>  <slot></slot></view>
<!-- 引用组件的页面模板 --><view>  <component-tag-name>    <!-- 这部分内容将被放置在组件 <slot> 的位置上 -->    <view>这里是插入到组件slot中的内容</view>  </component-tag-name></view>

注意,在模板中引用到的自定义组件及其对应的节点名需要在 json 文件中显式定义,否则会被当作一个无意义的节点。除此以外,节点名也可以被声明为抽象节点。

模板数据绑定

与普通的 WXML 模板类似,可以使用数据绑定,这样就可以向子组件的属性传递动态数据。

代码示例:

<!-- 引用组件的页面模板 --><view>  <component-tag-name prop-a="{{dataFieldA}}" prop-b="{{dataFieldB}}">    <!-- 这部分内容将被放置在组件 <slot> 的位置上 -->    <view>这里是插入到组件slot中的内容</view>  </component-tag-name></view>

在以上例子中,组件的属性 propA 和 propB 将收到页面传递的数据。页面可以通过 setData 来改变绑定的数据字段。

注意:这样的数据绑定只能传递 JSON 兼容数据。自基础库版本 2.0.9 开始,还可以在数据中包含函数(但这些函数不能在 WXML 中直接调用,只能传递给子组件)。

组件 wxml 的 slot

在组件的 wxml 中可以包含 slot 节点,用于承载组件使用者提供的 wxml 结构。

默认情况下,一个组件的 wxml 中只能有一个 slot 。需要使用多 slot 时,可以在组件 js 中声明启用。

Component({  options: {    multipleSlots: true // 在组件定义时的选项中启用多slot支持  },  properties: { /* ... */ },  methods: { /* ... */ }})

此时,可以在这个组件的 wxml 中使用多个 slot ,以不同的 name 来区分。

<!-- 组件模板 --><view class="wrapper">  <slot name="before"></slot>  <view>这里是组件的内部细节</view>  <slot name="after"></slot></view>

使用时,用 slot 属性来将节点插入到不同的 slot 上。

<!-- 引用组件的页面模板 --><view>  <component-tag-name>    <!-- 这部分内容将被放置在组件 <slot name="before"> 的位置上 -->    <view slot="before">这里是插入到组件slot name="before"中的内容</view>    <!-- 这部分内容将被放置在组件 <slot name="after"> 的位置上 -->    <view slot="after">这里是插入到组件slot name="after"中的内容</view>  </component-tag-name></view>

组件样式

组件对应 wxss 文件的样式,只对组件wxml内的节点生效。编写组件样式时,需要注意以下几点:

  • 组件和引用组件的页面不能使用id选择器(#a)、属性选择器([a])和标签名选择器,请改用class选择器。
  • 组件和引用组件的页面中使用后代选择器(.a .b)在一些极端情况下会有非预期的表现,如遇,请避免使用。
  • 子元素选择器(.a>.b)只能用于 view 组件与其子节点之间,用于其他组件可能导致非预期的情况。
  • 继承样式,如 font 、 color ,会从组件外继承到组件内。
  • 除继承样式外, app.wxss 中的样式、组件所在页面的的样式对自定义组件无效(除非更改组件样式隔离选项)。
#a { } /* 在组件中不能使用 */[a] { } /* 在组件中不能使用 */button { } /* 在组件中不能使用 */.a > .b { } /* 除非 .a 是 view 组件节点,否则不一定会生效 */

除此以外,组件可以指定它所在节点的默认样式,使用 :host 选择器(需要包含基础库 1.7.2 或更高版本的开发者工具支持)。

代码示例:

/* 组件 custom-component.wxss */:host {  color: yellow;}
<!-- 页面的 WXML --><custom-component>这段文本是黄色的</custom-component>

组件样式隔离

默认情况下,自定义组件的样式只受到自定义组件 wxss 的影响。除非以下两种情况:

  • app.wxss 或页面的 wxss 中使用了标签名选择器(或一些其他特殊选择器)来直接指定样式,这些选择器会影响到页面和全部组件。通常情况下这是不推荐的做法。
  • 指定特殊的样式隔离选项 styleIsolation 。
Component({  options: {    styleIsolation: 'isolated'  }})

styleIsolation 选项从基础库版本 2.6.5 开始支持。它支持以下取值:

  • isolated 表示启用样式隔离,在自定义组件内外,使用 class 指定的样式将不会相互影响(一般情况下的默认值);
  • apply-shared 表示页面 wxss 样式将影响到自定义组件,但自定义组件 wxss 中指定的样式不会影响页面;
  • shared 表示页面 wxss 样式将影响到自定义组件,自定义组件 wxss 中指定的样式也会影响页面和其他设置了 apply-shared 或 shared 的自定义组件。(这个选项在插件中不可用。)

使用后两者时,请务必注意组件间样式的相互影响。

如果这个 Component 构造器用于构造页面 ,则默认值为 shared ,且还有以下几个额外的样式隔离选项可用:

  • page-isolated 表示在这个页面禁用 app.wxss ,同时,页面的 wxss 不会影响到其他自定义组件;
  • page-apply-shared 表示在这个页面禁用 app.wxss ,同时,页面 wxss 样式不会影响到其他自定义组件,但设为 shared 的自定义组件会影响到页面;
  • page-shared 表示在这个页面禁用 app.wxss ,同时,页面 wxss 样式会影响到其他设为 apply-shared 或 shared 的自定义组件,也会受到设为 shared 的自定义组件的影响。

从小程序基础库版本 2.10.1 开始,也可以在页面或自定义组件的 json 文件中配置 styleIsolation (这样就不需在 js 文件的 options 中再配置)。例如:

{  "styleIsolation": "isolated"}

此外,小程序基础库版本 2.2.3 以上支持 addGlobalClass 选项,即在 Component 的 options 中设置 addGlobalClass: true 。 这个选项等价于设置 styleIsolation: apply-shared ,但设置了 styleIsolation 选项后这个选项会失效。

代码示例:

/* 组件 custom-component.js */Component({  options: {    addGlobalClass: true,  }})
<!-- 组件 custom-component.wxml --><text class="red-text">这段文本的颜色由 `app.wxss` 和页面 `wxss` 中的样式定义来决定</text>
/* app.wxss */.red-text {  color: red;}

外部样式类

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

有时,组件希望接受外部传入的样式类。此时可以在 Component 中用 externalClasses 定义段定义若干个外部样式类。

这个特性可以用于实现类似于 view 组件的 hover-class 属性:页面可以提供一个样式类,赋予 view 的 hover-class ,这个样式类本身写在页面中而非 view 组件的实现中。

注意:在同一个节点上使用普通样式类和外部样式类时,两个类的优先级是未定义的,因此最好避免这种情况。

代码示例:

/* 组件 custom-component.js */Component({  externalClasses: ['my-class']})
<!-- 组件 custom-component.wxml --><custom-component class="my-class">这段文本的颜色由组件外的 class 决定</custom-component>

这样,组件的使用者可以指定这个样式类对应的 class ,就像使用普通属性一样。在 2.7.1 之后,可以指定多个对应的 class 。

代码示例:

<!-- 页面的 WXML --><custom-component my-class="red-text" /><custom-component my-class="large-text" /><!-- 以下写法需要基础库版本 2.7.1 以上 --><custom-component my-class="red-text large-text" />
.red-text {  color: red;}.large-text {  font-size: 1.5em;}

引用页面或父组件的样式

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

即使启用了样式隔离 isolated ,组件仍然可以在局部引用组件所在页面的样式或父组件的样式。

例如,如果在页面 wxss 中定义了:

.blue-text {  color: blue;}

在这个组件中可以使用 ~ 来引用这个类的样式:

<view class="~blue-text"> 这段文本是蓝色的 </view>

如果在一个组件的父组件 wxss 中定义了:

.red-text {  color: red;}

在这个组件中可以使用 ^ 来引用这个类的样式:

<view class="^red-text"> 这段文本是红色的 </view>

也可以连续使用多个 ^ 来引用祖先组件中的样式。

注意:如果组件是比较独立、通用的组件,请优先使用外部样式类的方式,而非直接引用父组件或页面的样式。

虚拟化组件节点

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

默认情况下,自定义组件本身的那个节点是一个“普通”的节点,使用时可以在这个节点上设置 class style 、动画、 flex 布局等,就如同普通的 view 组件节点一样。

<!-- 页面的 WXML --><view style="display: flex">  <!-- 默认情况下,这是一个普通的节点 -->  <custom-component style="color: blue; flex: 1">蓝色、满宽的</custom-component></view>

但有些时候,自定义组件并不希望这个节点本身可以设置样式、响应 flex 布局等,而是希望自定义组件内部的第一层节点能够响应 flex 布局或者样式由自定义组件本身完全决定。

这种情况下,可以将这个自定义组件设置为“虚拟的”:

Component({  options: {    virtualHost: true  },  properties: {    style: { // 定义 style 属性可以拿到 style 属性上设置的值      type: String,    }  },  externalClass: ['class'], // 可以将 class 设为 externalClass})

这样,可以将 flex 放入自定义组件内:

<!-- 页面的 WXML --><view style="display: flex">  <!-- 如果设置了 virtualHost ,节点上的样式将失效 -->  <custom-component style="color: blue">不是蓝色的</custom-component></view>
<!-- custom-component.wxml --><view style="flex: 1">  满宽的  <slot></slot></view>

需要注意的是,自定义组件节点上的 class style 和动画将不再生效,但仍可以:

  • 将 style 定义成 properties 属性来获取 style 上设置的值;
  • 将 class 定义成 externalClasses 外部样式类使得自定义组件 wxml 可以使用 class 值。


Component 构造器

Component 构造器可用于定义组件,调用 Component 构造器时可以指定组件的属性、数据、方法等。

详细的参数含义和使用请参考 Component 参考文档

Component({  behaviors: [],  properties: {    myProperty: { // 属性名      type: String,      value: ''    },    myProperty2: String // 简化的定义方式  },    data: {}, // 私有数据,可用于模板渲染  lifetimes: {    // 生命周期函数,可以为函数,或一个在methods段中定义的方法名    attached: function () { },    moved: function () { },    detached: function () { },  },  // 生命周期函数,可以为函数,或一个在methods段中定义的方法名  attached: function () { }, // 此处attached的声明会被lifetimes字段中的声明覆盖  ready: function() { },  pageLifetimes: {    // 组件所在页面的生命周期函数    show: function () { },    hide: function () { },    resize: function () { },  },  methods: {    onMyButtonTap: function(){      this.setData({        // 更新属性和数据的方法与更新页面数据的方法类似      })    },    // 内部方法建议以下划线开头    _myPrivateMethod: function(){      // 这里将 data.A[0].B 设为 'myPrivateData'      this.setData({        'A[0].B': 'myPrivateData'      })    },    _propertyChange: function(newVal, oldVal) {    }  }})

使用 Component 构造器构造页面

事实上,小程序的页面也可以视为自定义组件。因而,页面也可以使用 Component 构造器构造,拥有与普通组件一样的定义段与实例方法。但此时要求对应 json 文件中包含 usingComponents 定义段。

此时,组件的属性可以用于接收页面的参数,如访问页面 /pages/index/index?paramA=123&paramB=xyz ,如果声明有属性 paramA 或 paramB ,则它们会被赋值为 123 或 xyz 。

页面的生命周期方法(即 on 开头的方法),应写在 methods 定义段中。

代码示例:

{  "usingComponents": {}}
Component({  properties: {    paramA: Number,    paramB: String,  },  methods: {    onLoad: function() {      this.data.paramA // 页面参数 paramA 的值      this.data.paramB // 页面参数 paramB 的值    }  }})

使用 Component 构造器来构造页面的一个好处是可以使用 behaviors 来提取所有页面中公用的代码段。

例如,在所有页面被创建和销毁时都要执行同一段代码,就可以把这段代码提取到 behaviors 中。

代码示例:

// page-common-behavior.jsmodule.exports = Behavior({  attached: function() {    // 页面创建时执行    console.info('Page loaded!')  },  detached: function() {    // 页面销毁时执行    console.info('Page unloaded!')  }})
// 页面 Avar pageCommonBehavior = require('./page-common-behavior')Component({  behaviors: [pageCommonBehavior],  data: { /* ... */ },  methods: { /* ... */ },})
// 页面 Bvar pageCommonBehavior = require('./page-common-behavior')Component({  behaviors: [pageCommonBehavior],  data: { /* ... */ },  methods: { /* ... */ },})


组件间通信与事件

组件间通信

组件间的基本通信方式有以下几种。

  • 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)    }  }})

触发事件的选项包括:

选项名类型是否必填默认值描述
bubblesBooleanfalse事件是否冒泡
composedBooleanfalse事件是否可以穿越组件边界,为false时,事件将只能在引用组件的节点树上触发,不进入其他任何组件内部
capturePhaseBooleanfalse事件是否拥有捕获阶段

关于冒泡和捕获阶段的概念,请阅读 事件 章节中的相关说明。

代码示例:

在开发者工具中预览效果

// 页面 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.jsComponent({  methods: {    onTap: function(){      this.triggerEvent('customevent', {}) // 只会触发 pageEventListener2      this.triggerEvent('customevent', {}, { bubbles: true }) // 会依次触发 pageEventListener2 、 pageEventListener1      this.triggerEvent('customevent', {}, { bubbles: true, composed: true }) // 会依次触发 pageEventListener2 、 anotherEventListener 、 pageEventListener1    }  }})

获取组件实例

可在父组件里调用 this.selectComponent ,获取子组件的实例对象。(插件的自定义组件将返回 null)

调用时需要传入一个匹配选择器 selector,如:this.selectComponent(".my-component")。

selector 详细语法可查看 selector 语法参考文档

代码示例:

// 父组件Page({  data: {},  getChildComponent: function () {    const child = this.selectComponent('.my-component');    console.log(child)  }})

在上例中,父组件将会获取 class 为 my-component 的子组件实例对象,即子组件的 this 。

若需要自定义 selectComponent 返回的数据,可使用内置 behavior: wx://component-export

从基础库版本 2.2.3 开始提供支持。

使自定义组件中支持 export 定义段,这个定义段可以用于指定组件被 selectComponent 调用时的返回值。

代码示例:

// 自定义组件 my-component 内部Component({  behaviors: ['wx://component-export'],  export() {    return { myField: 'myValue' }  }})
<!-- 使用自定义组件时 --><my-component id="the-id" />
// 父组件调用const child = this.selectComponent('#the-id') // 等于 { myField: 'myValue' }

在上例中,父组件获取 id 为 the-id 的子组件实例的时候,得到的是对象 { myField: 'myValue' } 。


组件生命周期

组件的生命周期,指的是组件自身的一些函数,这些函数在特殊的时间点或遇到一些特殊的框架事件时被自动触发。

其中,最重要的生命周期是 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
errorObject Error每当组件方法抛出错误时执行2.4.1

组件所在页面的生命周期

还有一些特殊的生命周期,它们并非与组件有很强的关联,但有时组件需要获知,以便组件内部处理。这样的生命周期称为“组件所在页面的生命周期”,在 pageLifetimes 定义段中定义。其中可用的生命周期包括:

生命周期参数描述最低版本
show组件所在的页面被展示时执行2.2.3
hide组件所在的页面被隐藏时执行2.2.3
resizeObject Size组件所在的页面尺寸变化时执行2.4.0

代码示例:

Component({  pageLifetimes: {    show: function() {      // 页面被展示    },    hide: function() {      // 页面被隐藏    },    resize: function(size) {      // 页面尺寸变化    }  }})


behaviors

behaviors 是用于组件间代码共享的特性,类似于一些编程语言中的 “mixins” 或 “traits”。

每个 behavior 可以包含一组属性、数据、生命周期函数和方法。组件引用它时,它的属性、数据和方法会被合并到组件中,生命周期函数也会在对应时机被调用。 每个组件可以引用多个 behavior ,behavior 也可以引用其它 behavior 。

详细的参数含义和使用请参考 Behavior 参考文档

组件中使用

组件引用时,在 behaviors 定义段中将它们逐个列出即可。

代码示例:

// my-component.jsvar myBehavior = require('my-behavior')Component({  behaviors: [myBehavior],  properties: {    myProperty: {      type: String    }  },  data: {    myData: 'my-component-data'  },  created: function () {    console.log('[my-component] created')  },  attached: function () {     console.log('[my-component] attached')  },  ready: function () {    console.log('[my-component] ready')  },  methods: {    myMethod: function () {      console.log('[my-component] log by myMethod')    },  }})

在上例中, my-component 组件定义中加入了 my-behavior,

而 my-behavior 结构为:

  • 属性:myBehaviorProperty
  • 数据字段:myBehaviorData
  • 方法:myBehaviorMethod
  • 生命周期函数:attached、created、ready

这将使 my-component 最终结构为:

  • 属性:myBehaviorProperty、myProperty
  • 数据字段:myBehaviorData、myData
  • 方法:myBehaviorMethod、myMethod
  • 生命周期函数:attached、created、ready

当组件触发生命周期时,上例生命周期函数执行顺序为:

  1. [my-behavior] created
  2. [my-component] created
  3. [my-behavior] attached
  4. [my-component] attached
  5. [my-behavior] ready
  6. [my-component] ready

详细规则参考 同名字段的覆盖和组合规则。

同名字段的覆盖和组合规则

组件和它引用的 behavior 中可以包含同名的字段,对这些字段的处理方法如下:

  • 如果有同名的属性 (properties) 或方法 (methods):若组件本身有这个属性或方法,则组件的属性或方法会覆盖 behavior 中的同名属性或方法;若组件本身无这个属性或方法,则在组件的 behaviors 字段中定义靠后的 behavior 的属性或方法会覆盖靠前的同名属性或方法;在 2 的基础上,若存在嵌套引用 behavior 的情况,则规则为:父 behavior 覆盖 子 behavior 中的同名属性或方法。
  • 如果有同名的数据字段 (data):若同名的数据字段都是对象类型,会进行对象合并;其余情况会进行数据覆盖,覆盖规则为:组件 > 父 behavior > 子 behavior 、 靠后的 behavior > 靠前的 behavior。(优先级高的覆盖优先级低的,最大的为优先级最高)
  • 生命周期函数不会相互覆盖,而是在对应触发时机被逐个调用:对于不同的生命周期函数之间,遵循组件生命周期函数的执行顺序;对于同种生命周期函数,遵循如下规则:behavior 优先于组件执行;子 behavior 优先于 父 behavior 执行;靠前的 behavior 优先于 靠后的 behavior 执行;如果同一个 behavior 被一个组件多次引用,它定义的生命周期函数只会被执行一次。

代码示例:

在开发者工具中预览效果

内置 behaviors

自定义组件可以通过引用内置的 behavior 来获得内置组件的一些行为。

Component({  behaviors: ['wx://form-field']})

在上例中, wx://form-field 代表一个内置 behavior ,它使得这个自定义组件有类似于表单控件的行为。

内置 behavior 往往会为组件添加一些属性。在没有特殊说明时,组件可以覆盖这些属性来改变它的 type 或添加 observer 。

wx://form-field

使自定义组件有类似于表单控件的行为。 form 组件可以识别这些自定义组件,并在 submit 事件中返回组件的字段名及其对应字段值。

详细用法以及代码示例可见:form 组件参考文档

wx://form-field-group

从基础库版本 2.10.2 开始提供支持。

使 form 组件可以识别到这个自定义组件内部的所有表单控件。

详细用法以及代码示例可见:form 组件参考文档

wx://form-field-button

从基础库版本 2.10.3 开始提供支持。

使 form 组件可以识别到这个自定义组件内部的 button 。如果自定义组件内部有设置了 form-type 的 button ,它将被组件外的 form 接受。

详细用法以及代码示例可见:form 组件参考文档

wx://component-export

从基础库版本 2.2.3 开始提供支持。

使自定义组件支持 export 定义段。这个定义段可以用于指定组件被 selectComponent 调用时的返回值。

详细用法以及代码示例可见:selectComponent 参考文档


组件间关系

定义和使用组件间关系

有时需要实现这样的组件:

<custom-ul>  <custom-li> item 1 </custom-li>  <custom-li> item 2 </custom-li></custom-ul>

这个例子中, custom-ul 和 custom-li 都是自定义组件,它们有相互间的关系,相互间的通信往往比较复杂。此时在组件定义时加入 relations 定义段,可以解决这样的问题。示例:

// path/to/custom-ul.jsComponent({  relations: {    './custom-li': {      type: 'child', // 关联的目标节点应为子节点      linked: function(target) {        // 每次有custom-li被插入时执行,target是该节点实例对象,触发在该节点attached生命周期之后      },      linkChanged: function(target) {        // 每次有custom-li被移动后执行,target是该节点实例对象,触发在该节点moved生命周期之后      },      unlinked: function(target) {        // 每次有custom-li被移除时执行,target是该节点实例对象,触发在该节点detached生命周期之后      }    }  },  methods: {    _getAllLi: function(){      // 使用getRelationNodes可以获得nodes数组,包含所有已关联的custom-li,且是有序的      var nodes = this.getRelationNodes('path/to/custom-li')    }  },  ready: function(){    this._getAllLi()  }})
// path/to/custom-li.jsComponent({  relations: {    './custom-ul': {      type: 'parent', // 关联的目标节点应为父节点      linked: function(target) {        // 每次被插入到custom-ul时执行,target是custom-ul节点实例对象,触发在attached生命周期之后      },      linkChanged: function(target) {        // 每次被移动后执行,target是custom-ul节点实例对象,触发在moved生命周期之后      },      unlinked: function(target) {        // 每次被移除时执行,target是custom-ul节点实例对象,触发在detached生命周期之后      }    }  }})

注意:必须在两个组件定义中都加入relations定义,否则不会生效。

关联一类组件

有时,需要关联的是一类组件,如:

<custom-form>  <view>    input    <custom-input></custom-input>  </view>  <custom-submit> submit </custom-submit></custom-form>

custom-form 组件想要关联 custom-input 和 custom-submit 两个组件。此时,如果这两个组件都有同一个behavior:

// path/to/custom-form-controls.jsmodule.exports = Behavior({  // ...})
// path/to/custom-input.jsvar customFormControls = require('./custom-form-controls')Component({  behaviors: [customFormControls],  relations: {    './custom-form': {      type: 'ancestor', // 关联的目标节点应为祖先节点    }  }})
// path/to/custom-submit.jsvar customFormControls = require('./custom-form-controls')Component({  behaviors: [customFormControls],  relations: {    './custom-form': {      type: 'ancestor', // 关联的目标节点应为祖先节点    }  }})

则在 relations 关系定义中,可使用这个behavior来代替组件路径作为关联的目标节点:

// path/to/custom-form.jsvar customFormControls = require('./custom-form-controls')Component({  relations: {    'customFormControls': {      type: 'descendant', // 关联的目标节点应为子孙节点      target: customFormControls    }  }})

relations 定义段

relations 定义段包含目标组件路径及其对应选项,可包含的选项见下表。

选项类型是否必填描述
typeString目标组件的相对关系,可选的值为 parent 、 child 、 ancestor 、 descendant
linkedFunction关系生命周期函数,当关系被建立在页面节点树中时触发,触发时机在组件attached生命周期之后
linkChangedFunction关系生命周期函数,当关系在页面节点树中发生改变时触发,触发时机在组件moved生命周期之后
unlinkedFunction关系生命周期函数,当关系脱离页面节点树时触发,触发时机在组件detached生命周期之后
targetString如果这一项被设置,则它表示关联的目标节点所应具有的behavior,所有拥有这一behavior的组件节点都会被关联


数据监听器

数据监听器可以用于监听和响应任何属性和数据字段的变化。从小程序基础库版本 2.6.1 开始支持。

使用数据监听器

有时,在一些数据字段被 setData 设置时,需要执行一些操作。

例如, this.data.sum 永远是 this.data.numberA 与 this.data.numberB 的和。此时,可以使用数据监听器进行如下实现。

Component({  attached: function() {    this.setData({      numberA: 1,      numberB: 2,    })  },  observers: {    'numberA, numberB': function(numberA, numberB) {      // 在 numberA 或者 numberB 被设置时,执行这个函数      this.setData({        sum: numberA + numberB      })    }  }})

监听字段语法

数据监听器支持监听属性或内部数据的变化,可以同时监听多个。一次 setData 最多触发每个监听器一次。

同时,监听器可以监听子数据字段,如下例所示。

Component({  observers: {    'some.subfield': function(subfield) {      // 使用 setData 设置 this.data.some.subfield 时触发      // (除此以外,使用 setData 设置 this.data.some 也会触发)      subfield === this.data.some.subfield    },    'arr[12]': function(arr12) {      // 使用 setData 设置 this.data.arr[12] 时触发      // (除此以外,使用 setData 设置 this.data.arr 也会触发)      arr12 === this.data.arr[12]    },  }})

如果需要监听所有子数据字段的变化,可以使用通配符 ** 。

Component({  observers: {    'some.field.**': function(field) {      // 使用 setData 设置 this.data.some.field 本身或其下任何子数据字段时触发      // (除此以外,使用 setData 设置 this.data.some 也会触发)      field === this.data.some.field    },  },  attached: function() {    // 这样会触发上面的 observer    this.setData({      'some.field': { /* ... */ }    })    // 这样也会触发上面的 observer    this.setData({      'some.field.xxx': { /* ... */ }    })    // 这样还是会触发上面的 observer    this.setData({      'some': { /* ... */ }    })  }})

特别地,仅使用通配符 ** 可以监听全部 setData 。

Component({  observers: {    '**': function() {      // 每次 setData 都触发    },  },})

提示:

  • 数据监听器监听的是 setData 涉及到的数据字段,即使这些数据字段的值没有发生变化,数据监听器依然会被触发。
  • 如果在数据监听器函数中使用 setData 设置本身监听的数据字段,可能会导致死循环,需要特别留意。
  • 数据监听器和属性的 observer 相比,数据监听器更强大且通常具有更好的性能。


纯数据字段

纯数据字段是一些不用于界面渲染的 data 字段,可以用于提升页面更新性能。从小程序基础库版本 2.8.2 开始支持。

组件数据中的纯数据字段

有些情况下,某些 data 中的字段(包括 setData 设置的字段)既不会展示在界面上,也不会传递给其他组件,仅仅在当前组件内部使用。

此时,可以指定这样的数据字段为“纯数据字段”,它们将仅仅被记录在 this.data 中,而不参与任何界面渲染过程,这样有助于提升页面更新性能。

指定“纯数据字段”的方法是在 Component 构造器的 options 定义段中指定 pureDataPattern 为一个正则表达式,字段名符合这个正则表达式的字段将成为纯数据字段。

代码示例:

Component({  options: {    pureDataPattern: /^_/ // 指定所有 _ 开头的数据字段为纯数据字段  },  data: {    a: true, // 普通数据字段    _b: true, // 纯数据字段  },  methods: {    myMethod() {      this.data._b // 纯数据字段可以在 this.data 中获取      this.setData({        c: true, // 普通数据字段        _d: true, // 纯数据字段      })    }  }})

上述组件中的纯数据字段不会被应用到 WXML 上:

<view wx:if="{{a}}"> 这行会被展示 </view><view wx:if="{{_b}}"> 这行不会被展示 </view>

组件属性中的纯数据字段

属性也可以被指定为纯数据字段(遵循 pureDataPattern 的正则表达式)。

属性中的纯数据字段可以像普通属性一样接收外部传入的属性值,但不能将它直接用于组件自身的 WXML 中。

代码示例:

Component({  options: {    pureDataPattern: /^_/  },  properties: {    a: Boolean,    _b: {      type: Boolean,      observer() {        // 不要这样做!这个 observer 永远不会被触发      }    },  }})

注意:属性中的纯数据字段的属性 observer 永远不会触发!如果想要监听属性值变化,使用 数据监听器 代替。

从小程序基础库版本 2.10.1 开始,也可以在页面或自定义组件的 json 文件中配置 pureDataPattern (这样就不需在 js 文件的 options 中再配置)。此时,其值应当写成字符串形式:

{  "pureDataPattern": "^_"}

使用数据监听器监听纯数据字段

数据监听器  可以用于监听纯数据字段(与普通数据字段一样)。这样,可以通过监听、响应纯数据字段的变化来改变界面。

下面的示例是一个将 JavaScript 时间戳转换为可读时间的自定义组件。

代码示例:

Component({  options: {    pureDataPattern: /^timestamp$/ // 将 timestamp 属性指定为纯数据字段  },  properties: {    timestamp: Number,  },  observers: {    timestamp: function () {      // timestamp 被设置时,将它展示为可读时间字符串      var timeString = new Date(this.data.timestamp).toLocaleString()      this.setData({        timeString: timeString      })    }  }})
<view>{{timeString}}</view>


抽象节点

这个特性自小程序基础库版本 1.9.6 开始支持。

在组件中使用抽象节点

有时,自定义组件模板中的一些节点,其对应的自定义组件不是由自定义组件本身确定的,而是自定义组件的调用者确定的。这时可以把这个节点声明为“抽象节点”。

例如,我们现在来实现一个“选框组”(selectable-group)组件,它其中可以放置单选框(custom-radio)或者复选框(custom-checkbox)。这个组件的 wxml 可以这样编写:

代码示例:

<!-- selectable-group.wxml --><view wx:for="{{labels}}">  <label>    <selectable disabled="{{false}}"></selectable>    {{item}}  </label></view>

其中,“selectable”不是任何在 json 文件的 usingComponents 字段中声明的组件,而是一个抽象节点。它需要在 componentGenerics 字段中声明:

{  "componentGenerics": {    "selectable": true  }}

使用包含抽象节点的组件

在使用 selectable-group 组件时,必须指定“selectable”具体是哪个组件:

<selectable-group generic:selectable="custom-radio" />

这样,在生成这个 selectable-group 组件的实例时,“selectable”节点会生成“custom-radio”组件实例。类似地,如果这样使用:

<selectable-group generic:selectable="custom-checkbox" />

“selectable”节点则会生成“custom-checkbox”组件实例。

注意:上述的 custom-radio 和 custom-checkbox 需要包含在这个 wxml 对应 json 文件的 usingComponents 定义段中。

{  "usingComponents": {    "custom-radio": "path/to/custom/radio",    "custom-checkbox": "path/to/custom/checkbox"  }}

抽象节点的默认组件

抽象节点可以指定一个默认组件,当具体组件未被指定时,将创建默认组件的实例。默认组件可以在 componentGenerics 字段中指定:

{  "componentGenerics": {    "selectable": {      "default": "path/to/default/component"    }  }}

提示:

  • 节点的 generic 引用 generic:xxx="yyy" 中,值 yyy 只能是静态值,不能包含数据绑定。因而抽象节点特性并不适用于动态决定节点名的场景。


自定义组件扩展

为了更好定制自定义组件的功能,可以使用自定义组件扩展机制。从小程序基础库版本 2.2.3 开始支持。

扩展后的效果

为了更好的理解扩展后的效果,先举一个例子:

// behavior.jsmodule.exports = Behavior({  definitionFilter(defFields) {    defFields.data.from = 'behavior'  },})// component.jsComponent({  data: {    from: 'component'  },  behaviors: [require('behavior.js')],  ready() {    console.log(this.data.from) // 此处会发现输出 behavior 而不是 component  }})

通过例子可以发现,自定义组件的扩展其实就是提供了修改自定义组件定义段的能力,上述例子就是修改了自定义组件中的 data 定义段里的内容。

使用扩展

Behavior() 构造器提供了新的定义段 definitionFilter ,用于支持自定义组件扩展。 definitionFilter 是一个函数,在被调用时会注入两个参数,第一个参数是使用该 behavior 的 component/behavior 的定义对象,第二个参数是该 behavior 所使用的 behavior 的 definitionFilter 函数列表。

以下举个例子来说明:

// behavior3.jsmodule.exports = Behavior({    definitionFilter(defFields, definitionFilterArr) {},})// behavior2.jsmodule.exports = Behavior({  behaviors: [require('behavior3.js')],  definitionFilter(defFields, definitionFilterArr) {    // definitionFilterArr[0](defFields)  },})// behavior1.jsmodule.exports = Behavior({  behaviors: [require('behavior2.js')],  definitionFilter(defFields, definitionFilterArr) {},})// component.jsComponent({  behaviors: [require('behavior1.js')],})

上述代码中声明了1个自定义组件和3个 behavior,每个 behavior 都使用了 definitionFilter 定义段。那么按照声明的顺序会有如下事情发生:

  1. 当进行 behavior2 的声明时就会调用 behavior3 的 definitionFilter 函数,其中 defFields 参数是 behavior2 的定义段, definitionFilterArr 参数即为空数组,因为 behavior3 没有使用其他的 behavior 。
  2. 当进行 behavior1 的声明时就会调用 behavior2 的 definitionFilter 函数,其中 defFields 参数是 behavior1 的定义段, definitionFilterArr 参数是一个长度为1的数组,definitionFilterArr[0] 即为 behavior3 的 definitionFilter 函数,因为 behavior2 使用了 behavior3。用户在此处可以自行决定在进行 behavior1 的声明时要不要调用 behavior3 的 definitionFilter 函数,如果需要调用,在此处补充代码 definitionFilterArr[0](defFields) 即可,definitionFilterArr 参数会由基础库补充传入。
  3. 同理,在进行 component 的声明时就会调用 behavior1 的 definitionFilter 函数。

简单概括,definitionFilter 函数可以理解为当 A 使用了 B 时,A 声明就会调用 B 的 definitionFilter 函数并传入 A 的定义对象让 B 去过滤。此时如果 B 还使用了 C 和 D ,那么 B 可以自行决定要不要调用 C 和 D 的 definitionFilter 函数去过滤 A 的定义对象。

真实案例

下面利用扩展简单实现自定义组件的计算属性功能:

// behavior.jsmodule.exports = Behavior({  lifetimes: {    created() {      this._originalSetData = this.setData // 原始 setData      this.setData = this._setData // 封装后的 setData    }  },  definitionFilter(defFields) {    const computed = defFields.computed || {}    const computedKeys = Object.keys(computed)    const computedCache = {}    // 计算 computed    const calcComputed = (scope, insertToData) => {      const needUpdate = {}      const data = defFields.data = defFields.data || {}      for (let key of computedKeys) {        const value = computed[key].call(scope) // 计算新值        if (computedCache[key] !== value) needUpdate[key] = computedCache[key] = value        if (insertToData) data[key] = needUpdate[key] // 直接插入到 data 中,初始化时才需要的操作      }      return needUpdate    }    // 重写 setData 方法    defFields.methods = defFields.methods || {}    defFields.methods._setData = function (data, callback) {      const originalSetData = this._originalSetData // 原始 setData      originalSetData.call(this, data, callback) // 做 data 的 setData      const needUpdate = calcComputed(this) // 计算 computed      originalSetData.call(this, needUpdate) // 做 computed 的 setData    }    // 初始化 computed    calcComputed(defFields, true) // 计算 computed  }})

在组件中使用:

const beh = require('./behavior.js')Component({  behaviors: [beh],  data: {    a: 0,  },  computed: {    b() {      return this.data.a + 100    },  },  methods: {    onTap() {      this.setData({        a: ++this.data.a,      })    }  }})
<view>data: {{a}}</view><view>computed: {{b}}</view><button bindtap="onTap">click</button>

实现原理很简单,对已有的 setData 进行二次封装,在每次 setData 的时候计算出 computed 里各字段的值,然后设到 data 中,已达到计算属性的效果。

此实现只是作为一个简单案例来展示,请勿直接在生产环境中使用。

官方扩展包


开发第三方自定义组件

小程序从基础库版本 2.2.1 开始支持使用 npm 安装第三方包,因此也支持开发和使用第三方自定义组件包。关于 npm 功能的详情可先阅读[相关文档]((npm 支持))。

准备

开发一个开源的自定义组件包给他人使用,首先需要明确他人是要如何使用这个包的,如果只是拷贝小程序目录下直接使用的话,可以跳过此文档。此文档中后续内容是以 npm 管理自定义组件包的前提下进行说明的。

在开发之前,要求开发者具有基础的 node.js 和 npm 相关的知识,同时需要准备好支持 npm 功能的开发者工具,点此下载。

下载模板

为了方便开发者能够快速搭建好一个可用于开发、调试、测试的自定义组件包项目,官方提供了一个项目模板,下载使用模板的方式有三种:

  • 直接从 github 上下载 zip 文件并解压。
  • 直接将 github 上的仓库 clone 下来。
  • 使用官方提供的命令行工具初始化项目,下面会进行介绍。

项目模板中的构建是基于 gulp + webpack 来执行的,支持开发、构建、测试等命令,详情可参阅项目模板的 README.md 文件。

命令行工具

官方提供了命令行工具,用于快速初始化一个项目。执行如下命令安装命令行工具:

npm install -g @wechat-miniprogram/miniprogram-cli

然后新建一个空目录作为项目根目录,在此根目录下执行:

miniprogram init --type custom-component

命令执行完毕后会发现项目根目录下生成了许多文件,这是根据官方的项目模板生成的完整项目,之后开发者可直接在此之上进行开发修改。

命令行工具的更多用法可以查看 github 仓库上的 README.md 文件。

PS:第一次使用 miniprogram init 初始化项目会去 github 上拉取模板,因此需要保证网络畅通。

测试工具

针对自定义组件的单元测试,可参阅文档单元测试

自定义组件示例

以下为官方提供的自定义组件,可以参考并使用:

自定义组件扩展示例

以下为官方提供的自定义组件扩展,可以参考并使用:


单元测试

在编写高质量的自定义组件过程中,单元测试是永远避不开的一个话题。完善的测试用例是提高自定义组件可用性的保证,同时测试代码覆盖率也是必不可少的一个环节。小程序从基础库版本 2.2.1 开始拥抱开源,支持使用 npm 安装自定义组件,那针对自定义组件的单元测试也是必须支持的。

以下就来介绍如何对自定义组件进行单元测试。

测试框架

现在市面上流行的测试框架均可使用,只要它能兼顾 nodejs 端和 dom 环境。因为我们需要依赖到 nodejs 的一些库来完善测试环境,同时 dom 环境也是必须的,因为我们需要建成完整的 dom 树结构,才能更好的模拟自定义组件的运行。例如可以选用 mocha + jsdom 的组合,亦可选用 jest,下述例子选用 jest 作为测试框架来说明。

自定义组件测试工具集

小程序的运行环境比较特殊,不同于常见的浏览器环境,它采用的是双线程的架构。而在进行单元测试时,我们并不需要用到这样复杂的架构带来的利好,我们进行的是功能测试而无需苛求性能、安全等因素,因此我们提供了一个测试工具集以支持自定义组件在 nodejs 单线程中也能运行起来。

我们先安装一下测试工具集——miniprogram-simulate

npm i --save-dev miniprogram-simulate

编写测试用例

假设我们有如下自定义组件:

<!-- /components/index.wmxl --><view class="index">{{prop}}</view>
// /components/index.jsComponent({  properties: {    prop: {      type: String,      value: 'index.properties'    },  },})
/* /components/index.wxss */.index {  color: green;}

我们想要测试渲染的结果,可以按照如下方式编写测试用例:

// /test/components/index.test.jsconst simulate = require('miniprogram-simulate')test('components/index', () => {    const id = simulate.load('/components/index') // 此处必须传入绝对路径    const comp = simulate.render(id) // 渲染成自定义组件树实例    const parent = document.createElement('parent-wrapper') // 创建父亲节点    comp.attach(parent) // attach 到父亲节点上,此时会触发自定义组件的 attached 钩子    const view = comp.querySelector('.index') // 获取子组件 view    expect(view.dom.innerHTML).toBe('index.properties') // 测试渲染结果    expect(window.getComputedStyle(view.dom).color).toBe('green') // 测试渲染结果})
PS:测试工具集中的 wx 对象和内置组件都不会实现真正的功能,如果需要测试一些特殊场景的话,可以自行覆盖掉测试工具集中的 api 接口和内置组件。PS:目前因为有部分自定义组件功能仍未支持(如抽象节点等),故测试工具暂无法全部覆盖自定义组件的特性,后续会继续完善。

测试工具集中提供了一些方便测试的接口,比如:

  • 模拟 touch 事件、自定义事件触发
  • 选取子节点
  • 更新自定义组件数据
  • 触发生命周期
  • ...

更多详细的用法可以参阅 github 仓库上的文档。


开发插件

开发插件前,请阅读了解《小程序插件接入指南》了解开通流程及开放范围,并开通插件功能。如果未开通插件功能,将无法上传插件。

创建插件项目

插件类型的项目可以在开发者工具中直接创建。

创建插件

新建插件类型的项目后,如果创建示例项目,则项目中将包含三个目录:

  • plugin 目录:插件代码目录。
  • miniprogram 目录:放置一个小程序,用于调试插件。
  • doc 目录:用于放置插件开发文档。

miniprogram 目录内容可以当成普通小程序来编写,用于插件调试、预览和审核。下面的内容主要介绍 plugin 中的插件代码及 doc 中的插件开发文档。

我们提供了一个可以直接在微信开发者工具中查看的完整插件示例,开发者可以和本文互相对照以便理解。请注意:

  1. 由于插件需要 appid 才能工作,请填入一个 appid;
  2. 由于当前代码片段的限制,打开该示例后请 手动将 appid 填写到 miniprogram/app.json 中(如下图)使示例正常运行。

手动填写 appid

插件目录结构

一个插件可以包含若干个自定义组件、页面,和一组 js 接口。插件的目录内容如下:

plugin├── components│   ├── hello-component.js   // 插件提供的自定义组件(可以有多个)│   ├── hello-component.json│   ├── hello-component.wxml│   └── hello-component.wxss├── pages│   ├── hello-page.js        // 插件提供的页面(可以有多个,自小程序基础库版本 2.1.0 开始支持)│   ├── hello-page.json│   ├── hello-page.wxml│   └── hello-page.wxss├── index.js                 // 插件的 js 接口└── plugin.json              // 插件配置文件

插件配置文件

向使用者小程序开放的所有自定义组件、页面和 js 接口都必须在插件配置文件 plugin.json 列出,格式如下:

代码示例:

{  "publicComponents": {    "hello-component": "components/hello-component"  },  "pages": {    "hello-page": "pages/hello-page"  },  "main": "index.js"}

这个配置文件将向使用者小程序开放一个自定义组件 hello-component,一个页面 hello-page 和 index.js 下导出的所有 js 接口。

进行插件开发

请注意:在插件开发中,只有部分接口可以直接调用;另外还有部分能力(如 获取用户信息 和 发起支付 等)可以通过插件功能页的方式使用。

自定义组件

插件可以定义若干个自定义组件,这些自定义组件都可以在插件内相互引用。但提供给使用者小程序使用的自定义组件必须在配置文件的 publicComponents 段中列出(参考上文)。

除去接口限制以外,自定义组件的编写和组织方式与一般的自定义组件相同,每个自定义组件由 wxml, wxss, js 和 json 四个文件组成。具体可以参考自定义组件的文档

页面

插件从小程序基础库版本 2.1.0 开始支持页面。插件可以定义若干个插件页面,可以从本插件的自定义组件、其他页面中跳转,或从使用者小程序中跳转。所有页面必须在配置文件的 pages 段中列出(参考上文)。

除去接口限制以外,插件的页面编写和组织方式与一般的页面相同,每个页面由 wxml, wxss, js 和 json 四个文件组成。具体可以参考其他关于页面的文档。

插件执行页面跳转的时候,可以使用 navigator 组件。当插件跳转到自身页面时, url 应设置为这样的形式:plugin-private://PLUGIN_APPID/PATH/TO/PAGE 。需要跳转到其他插件时,也可以这样设置 url 。

代码示例:

<navigator url="plugin-private://wxidxxxxxxxxxxxxxx/pages/hello-page">  Go to pages/hello-page!</navigator>

自基础库版本 2.2.2 开始,在插件自身的页面中,插件还可以调用 wx.navigateTo 来进行页面跳转, url 格式与使用 navigator 组件时相仿。

接口

插件可以在接口文件(在配置文件中指定,详情见上文)中 export 一些 js 接口,供插件的使用者调用,如:

代码示例:

module.exports = {  hello: function() {    console.log('Hello plugin!')  }}

获取小程序导出

从基础库 2.11.1 起,在插件中有全局函数 requireMiniProgram,可以获取由使用者小程序导出的内容。

例如,使用者小程序做了如下导出:

// 使用者小程序module.exports = {  greeting() {    return 'Greetings from Wechat MiniProgram!';  }}

那么在插件中,可以这样获得内容:

// 插件const miniProgramExports = requireMiniProgram();miniProgramExports.greeting(); // 'Greetings from Wechat MiniProgram!'

预览、上传和发布

插件可以像小程序一样预览和上传,但插件没有体验版。

插件会同时有多个线上版本,由使用插件的小程序决定具体使用的版本号。

手机预览和提审插件时,会使用一个特殊的小程序来套用项目中 miniprogram 文件夹下的小程序,从而预览插件。

  • (建议的方式)如果当前开发者有测试号,则会使用这个测试号;在测试号的设置页中可以看到测试号的 appid 、 appsecret 并设置域名列表。
  • 否则,将使用“插件开发助手”,它具有一个特定的 appid 。

在开发版小程序中测试

通常情况下,可以将 miniprogram 下的代码当做使用插件的小程序代码,来进行插件的调试和测试。

但有时,需要将插件的代码放在实际运行的小程序中进行调试、测试。此时,可以使用开发版的小程序直接引用开发版插件。方法如下:

  1. 在开发者工具的插件项目中上传插件,此时,在上传成功的通知信息中将包含这次上传获得的插件开发版 ID (一个英文、数字组成的随机字符串);
  2. 点击开发者工具右下角的通知按钮,可以打开通知栏,看到新生成的 ID ;
  3. 在使用这个插件的任意小程序项目中,可以将插件 version 设置为 "version": "dev-[开发版ID]" 的形式,如 "version": "dev-abcdef0123456789abcdef0123456789" ;
  4. 这样就会引用到这次上传的开发版插件;
  5. 注意,再次上传插件时, ID 可能会改变。

如果开发版小程序引用了开发版插件,此时这个小程序就不能上传发布了。必须要将插件版本设为正式版本之后,小程序才可以正常上传、发布。

插件开发文档

在使用者小程序使用插件时,插件代码并不可见。因此,除了插件代码,我们还支持插件开发者上传一份插件开发文档。这份开发文档将展示在插件详情页,供其他开发者在浏览插件和使用插件时进行阅读和参考。插件开发者应在插件开发文档中对插件提供的自定义组件、页面、接口等进行必要的描述和解释,方便使用者小程序正确使用插件。

插件开发文档必须放置在插件项目根目录中的 doc 目录下,目录结构如下:

doc├── README.md   // 插件文档,应为 markdown 格式└── picture.jpg // 其他资源文件,仅支持图片

其中,README.md 的编写有一定的 限制条件,具体来说:

  1. 引用到的图片资源不能是网络图片,且必须放在这个目录下;
  2. 文档中的链接只能链接到:微信开发者社区(developers.weixin.qq.com)微信公众平台(mp.weixin.qq.com)GitHub(github.com)

编辑 README.md 之后,可以在开发者工具左侧资源管理器的文件栏中右键单击 README.md,并选择上传文档。发布上传文档后,文档不会立刻发布。此时可以使用帐号和密码登录 管理后台 ,在 小程序插件 > 基本设置 中预览、发布插件文档。

其他注意事项

插件间互相调用

插件不能直接引用其他插件。但如果小程序引用了多个插件,插件之间是可以互相调用的。

一个插件调用另一个插件的方法,与插件调用自身的方法类似。可以使用 plugin-private://APPID 访问插件的自定义组件、页面(暂不能使用 plugin:// )。

对于 js 接口,可使用 requirePlugin ,但目前尚不能在文件一开头就使用 requirePlugin ,因为被依赖的插件可能还没有初始化,请考虑在更晚的时机调用 requirePlugin ,如接口被实际调用时、组件 attached 时。(未来会修复这个问题。)

插件请求签名

插件在使用 wx.request 等 API 发送网络请求时,将会额外携带一个签名 HostSign ,用于验证请求来源于小程序插件。这个签名位于请求头中,形如:

X-WECHAT-HOSTSIGN: {"noncestr":"NONCESTR", "timestamp":"TIMESTAMP", "signature":"SIGNATURE"}

其中, NONCESTR 是一个随机字符串, TIMESTAMP 是生成这个随机字符串和 SIGNATURE 的 UNIX 时间戳。它们是用于计算签名 SIGNATRUE 的参数,签名算法为:

SIGNATURE = sha1([APPID, NONCESTR, TIMESTAMP, TOKEN].sort().join(''))

其中,APPID 是 所在小程序 的 AppId (可以从请求头的 referrer 中获得);TOKEN 是插件 Token,可以在小程序插件基本设置中找到。

网络请求的 referer 格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 appid,{version} 为小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本。

插件开发者可以在服务器上按以下步骤校验签名:

  1. sort 对 APPID NONCESTR TIMESTAMP TOKEN 四个值表示成字符串形式,按照字典序排序(同 JavaScript 数组的 sort 方法);
  2. join 将排好序的四个字符串直接连接在一起;
  3. 对连接结果使用 sha1 算法,其结果即 SIGNATURE 。

自基础库版本 2.0.7 开始,在小程序运行期间,若网络状况正常, NONCESTR 和 TIMESTAMP 会每 10 分钟变更一次。如有必要,可以通过判断 TIMESTAMP 来确定当前签名是否依旧有效。


使用插件

添加插件

在使用插件前,首先要在小程序管理后台的“设置-第三方服务-插件管理”中添加插件。开发者可登录小程序管理后台,通过 appid 查找插件并添加。如果插件无需申请,添加后可直接使用;否则需要申请并等待插件开发者通过后,方可在小程序中使用相应的插件。

引入插件代码包

使用插件前,使用者要在 app.json 中声明需要使用的插件,例如:

代码示例:

{  "plugins": {    "myPlugin": {      "version": "1.0.0",      "provider": "wxidxxxxxxxxxxxxxxxx"    }  }}

如上例所示, plugins 定义段中可以包含多个插件声明,每个插件声明以一个使用者自定义的插件引用名作为标识,并指明插件的 appid 和需要使用的版本号。其中,引用名(如上例中的 myPlugin)由使用者自定义,无需和插件开发者保持一致或与开发者协调。在后续的插件使用中,该引用名将被用于表示该插件。

在分包内引入插件代码包

如果插件只在一个分包内用到,可以将插件仅放在这个分包内,例如:

{  "subpackages": [    {      "root": "packageA",      "pages": [        "pages/cat",        "pages/dog"      ],      "plugins": {        "myPlugin": {          "version": "1.0.0",          "provider": "wxidxxxxxxxxxxxxxxxx"        }      }    }  ]}

在分包内使用插件有如下限制:

  • 仅能在这个分包内使用该插件;
  • 同一个插件不能被多个分包同时引用;
  • 如果基础库版本低于 2.9.0 ,不能从分包外的页面直接跳入分包内的插件页面,需要先跳入分包内的非插件页面、再跳入同一分包内的插件页面。

使用插件

使用插件时,插件的代码对于使用者来说是不可见的。为了正确使用插件,使用者应查看插件详情页面中的“开发文档”一节,阅读由插件开发者提供的插件开发文档,通过文档来明确插件提供的自定义组件、页面名称及提供的 js 接口规范等。

自定义组件

使用插件提供的自定义组件,和使用普通自定义组件的方式相仿。在 json 文件定义需要引入的自定义组件时,使用 plugin:// 协议指明插件的引用名和自定义组件名,例如:

代码示例:

{  "usingComponents": {    "hello-component": "plugin://myPlugin/hello-component"  }}

出于对插件的保护,插件提供的自定义组件在使用上有一定的限制:

  • 默认情况下,页面中的 this.selectComponent 接口无法获得插件的自定义组件实例对象;
  • wx.createSelectorQuery 等接口的 >>> 选择器无法选入插件内部。

页面

插件的页面从小程序基础库版本 2.1.0 开始支持。

需要跳转到插件页面时,url 使用 plugin:// 前缀,形如 plugin://PLUGIN_NAME/PLUGIN_PAGE, 如:

代码示例:

<navigator url="plugin://myPlugin/hello-page">  Go to pages/hello-page!</navigator>

js 接口

使用插件的 js 接口时,可以使用 requirePlugin 方法。例如,插件提供一个名为 hello 的方法和一个名为 world 的变量,则可以像下面这样调用:

var myPluginInterface = requirePlugin('myPlugin');myPluginInterface.hello();var myWorld = myPluginInterface.world;

导出到插件

从基础库 2.11.1 起,使用插件的小程序可以导出一些内容,供插件获取。具体来说,在声明使用插件时,可以通过 export 字段来指定一个文件,如:

{  "myPlugin": {    "version": "1.0.0",    "provider": "wxidxxxxxxxxxxxxxxxx",    "export": "index.js"  }}

则该文件(上面的例子里是 index.js)导出的内容可以被这个插件用全局函数获得。例如,在上面的文件中,使用插件的小程序做了如下导出:

// index.jsmodule.exports = { whoami: 'Wechat MiniProgram' }

那么插件就可以获得上面导出的内容:

// pluginrequireMiniProgram().whoami // 'Wechat MiniProgram'

具体导出什么内容,可以阅读插件开发文档,和插件的开发者做好约定。

当插件在分包中时,这个特性也可以使用,但指定的文件的路径是相对于分包的。例如在 root: packageA 的分包中指定了 export: exports/plugin.js,那么被指定的文件在文件系统上应该是 /packageA/exports/plugin.js。

使用的多个插件的导出互不影响,两个插件可以导出同一个文件,也可以是不同的文件。但导出同一个文件时,如果一个插件对导出内容做了修改,那么另一个插件也会被影响,请注意这一点。

请谨慎导出 wx 对象或某个具体的 wx API,这将使插件可以以使用者小程序的身份调用 API。


插件调用 API 的限制

插件可以调用的 API 与小程序不同,主要有两个区别:

  • 插件的请求域名列表与小程序相互独立;
  • 一些 API 不允许插件调用(这些函数不存在于 wx 对象下)。

有些接口虽然在插件中不能使用,但可以通过插件功能页来达到目的,请参考插件功能页。

目前,允许插件调用的 API 及其对应版本要求如下:

基础

API最低版本备注
wx.arrayBufferToBase64
wx.base64ToArrayBuffer

发起请求

API最低版本备注
wx.request1.9.6

上传、下载

API最低版本备注
wx.downloadFile1.9.6
wx.uploadFile1.9.6

WebSocket

API最低版本备注
wx.connectSocket1.9.6

图片

API最低版本备注
wx.previewImage1.9.6
wx.chooseImage1.9.6
wx.getImageInfo1.9.6
wx.saveImageToPhotosAlbum1.9.6

录音

API最低版本备注
wx.startRecord1.9.6
wx.stopRecord1.9.6

实时音视频

API最低版本备注
wx.createLivePlayerContext1.9.6
wx.createLivePusherContext1.9.6

录音管理

API最低版本备注
wx.getRecorderManager1.9.94

音频播放控制

API最低版本备注
wx.pauseVoice1.9.6
wx.playVoice1.9.6
wx.stopVoice1.9.6

音乐播放控制

API最低版本备注
wx.onBackgroundAudioPlay1.9.6
wx.getBackgroundAudioPlayerState1.9.6
wx.onBackgroundAudioStop1.9.6
wx.stopBackgroundAudio1.9.6
wx.onBackgroundAudioPause1.9.6
wx.seekBackgroundAudio1.9.6
wx.playBackgroundAudio1.9.6
wx.pauseBackgroundAudio1.9.6

背景音频播放管理

API最低版本备注
wx.getBackgroundAudioManager1.9.6

音频组件控制

API最低版本备注
wx.createInnerAudioContext1.9.6
wx.createAudioContext1.9.6

视频

API最低版本备注
wx.chooseVideo1.9.6
wx.saveVideoToPhotosAlbum1.9.6

视频组件控制

API最低版本备注
wx.createVideoContext1.9.6

相机组件控制

API最低版本备注
wx.createCameraContext1.9.6

数据缓存

API最低版本备注
wx.setStorage1.9.6
wx.getStorage1.9.6
wx.removeStorage1.9.6
wx.setStorageSync1.9.6
wx.getStorageSync1.9.6
wx.removeStorageSync1.9.6

获取位置

API最低版本备注
wx.getLocation1.9.6
wx.chooseLocation1.9.6
wx.onLocationChange2.8.0
wx.offLocationChange2.9.1
wx.stopLocationUpdate2.8.0
wx.startLocationUpdate2.8.0

查看位置

API最低版本备注
wx.openLocation1.9.6

地图组件控制

API最低版本备注
wx.createMapContext1.9.6

系统信息

API最低版本备注
wx.getSystemInfoSync1.9.6
wx.getSystemInfo1.9.6

屏幕亮度

API最低版本备注
wx.setKeepScreenOn1.9.6
wx.setScreenBrightness1.9.6
wx.getScreenBrightness1.9.6

用户截屏事件

API最低版本备注
wx.onUserCaptureScreen1.9.6仅限插件页面中调用
wx.offUserCaptureScreen2.9.1仅限插件页面中调用

振动

API最低版本备注
wx.vibrateLong1.9.6
wx.vibrateShort1.9.6

手机联系人

API最低版本备注
wx.addPhoneContact1.9.6

NFC

API最低版本备注
wx.sendHCEMessage2.1.0
wx.stopHCE2.1.0
wx.onHCEMessage2.1.0
wx.offHCEMessage2.9.1
wx.startHCE2.1.0
wx.getHCEState2.1.0

网络状态

API最低版本备注
wx.onNetworkStatusChange1.9.6
wx.offNetworkStatusChange2.9.1
wx.getNetworkType1.9.6

加速度计

API最低版本备注
wx.startAccelerometer1.9.6
wx.stopAccelerometer1.9.6
wx.onAccelerometerChange1.9.6
wx.offAccelerometerChange2.9.1

设备方向

API最低版本备注
wx.startDeviceMotionListening2.9.1
wx.stopDeviceMotionListening2.9.1
wx.offDeviceMotionChange2.9.1
wx.onDeviceMotionChange2.9.1

陀螺仪

API最低版本备注
wx.startGyroscope2.9.1
wx.stopGyroscope2.9.1
wx.offGyroscopeChange2.9.1
wx.onGyroscopeChange2.9.1

罗盘

API最低版本备注
wx.onCompassChange1.9.6
wx.offCompassChange2.9.1
wx.stopCompass1.9.6
wx.startCompass1.9.6

拨打电话

API最低版本备注
wx.makePhoneCall1.9.6

扫码

API最低版本备注
wx.scanCode1.9.6

剪贴板

API最低版本备注
wx.setClipboardData1.9.6
wx.getClipboardData1.9.6

蓝牙

API最低版本备注
wx.writeBLECharacteristicValue1.9.6
wx.startBluetoothDevicesDiscovery1.9.6
wx.getConnectedBluetoothDevices1.9.6
wx.notifyBLECharacteristicValueChange1.9.6
wx.onBluetoothDeviceFound1.9.6
wx.offBluetoothDeviceFound2.9.1
wx.readBLECharacteristicValue1.9.6
wx.openBluetoothAdapter1.9.6
wx.getBLEDeviceCharacteristics1.9.6
wx.stopBluetoothDevicesDiscovery1.9.6
wx.onBLEConnectionStateChange1.9.6
wx.getBluetoothDevices1.9.6
wx.getBluetoothAdapterState1.9.6
wx.onBluetoothAdapterStateChange1.9.6
wx.offBluetoothAdapterStateChange2.9.1
wx.getBLEDeviceServices1.9.6
wx.onBLECharacteristicValueChange1.9.6
wx.offBLECharacteristicValueChange2.9.1
wx.createBLEConnection1.9.6
wx.closeBluetoothAdapter1.9.6
wx.closeBLEConnection1.9.6
wx.notifyBLECharacteristicValueChange1.9.6
wx.onBLEConnectionStateChange1.9.6
wx.offBLEConnectionStateChange2.9.1

iBeacon

API最低版本备注
wx.getBeacons1.9.6
wx.startBeaconDiscovery1.9.6
wx.onBeaconServiceChange1.9.6
wx.offBeaconServiceChange2.9.1
wx.onBeaconUpdate1.9.6
wx.offBeaconUpdate2.9.1
wx.stopBeaconDiscovery1.9.6

Wi-Fi

API最低版本备注
wx.connectWifi2.9.1
wx.getConnectedWifi2.9.1
wx.getWifiList2.9.1
wx.offGetWifiList2.9.1
wx.offWifiConnected2.9.1
wx.onEvaluateWifi2.9.1
wx.onGetWifiList2.9.1
wx.onWifiConnected2.9.1
wx.presetWifiList2.9.1
wx.setWifiList2.9.1
wx.startWifi2.9.1
wx.stopWifi2.9.1

交互反馈

API最低版本备注
wx.hideLoading1.9.6
wx.showActionSheet1.9.6
wx.showLoading1.9.6
wx.hideToast1.9.6
wx.showToast1.9.6
wx.showModal1.9.6

设置导航条

API最低版本备注
wx.showNavigationBarLoading2.1.0仅限插件页面中调用
wx.hideNavigationBarLoading2.1.0仅限插件页面中调用
wx.setNavigationBarColor2.1.0仅限插件页面中调用
wx.setNavigationBarTitle2.1.0仅限插件页面中调用

背景

API最低版本备注
wx.setBackgroundColor2.4.0仅限插件页面中调用
wx.setBackgroundTextStyle2.4.0仅限插件页面中调用

WXML节点信息

API最低版本备注
wx.createSelectorQuery1.9.6

WXML节点布局相交状态

API最低版本备注
wx.createIntersectionObserver1.9.6

导航

API最低版本备注
wx.navigateBack2.1.0仅限插件页面中调用
wx.navigateTo2.2.2仅限插件页面中调用
wx.redirectTo2.2.2仅限插件页面中调用
wx.switchTab2.3.1仅限插件页面中调用
wx.reLaunch2.3.1仅限插件页面中调用

动画

API最低版本备注
wx.createAnimation1.9.6

位置

API最低版本备注
wx.pageScrollTo2.1.0仅限插件页面中调用

绘图

API最低版本备注
wx.createOffscreenCanvas2.7.1
wx.canvasPutImageData1.9.6
wx.canvasToTempFilePath1.9.6
wx.createCanvasContext1.9.6
wx.canvasGetImageData1.9.6

下拉刷新

API最低版本备注
wx.stopPullDownRefresh2.1.0仅限插件页面中调用
wx.startPullDownRefresh2.1.0仅限插件页面中调用

当前帐号信息

API最低版本备注
wx.getAccountInfoSync2.2.2

转发

API最低版本备注
wx.hideShareMenu2.1.0仅限插件页面中调用
wx.getShareInfo2.1.0仅限插件页面中调用
wx.showShareMenu2.1.0仅限插件页面中调用
wx.updateShareMenu2.1.0仅限插件页面中调用

其他

API最低版本备注
wx.getSetting2.6.3
wx.openSetting2.10.3
wx.reportAnalytics1.9.6见下方备注

登录和获取用户信息

这一组接口仅限在用户信息功能页中获得用户授权之后调用。否则将返回 fail 。详见 用户信息功能页 。

API最低版本备注
wx.login2.3.1
wx.getUserInfo2.3.1

提示:

  • wx.reportAnalytics 可以被正常调用,但目前不会进行统计展示。


插件使用组件的限制

在插件开发中,以下组件不能在插件页面中使用:

  • 开放能力(open-type)为以下之一的 button

    • contact(打开客服会话)
    • getPhoneNumber(获取用户手机号)
    • getUserInfo(获取用户信息)
  • open-data
  • web-view

以下组件的使用对基础库版本有要求:


插件功能页

插件功能页从小程序基础库版本 2.1.0 开始支持。

某些接口不能在插件中直接调用(如 wx.login),但插件开发者可以使用插件功能页的方式来实现功能。目前,插件功能页包括:

  • 获取用户信息,包括 openid 和昵称等(相当于 wx.login 和 wx.getUserInfo 的功能),详见用户信息功能页;
  • 支付(相当于 wx.requestPayment),详见支付功能页;
  • 获取收货地址(相当于 wx.chooseAddress),详见收货地址功能页。

要使用插件功能页,需要先激活功能页特性,配置对应的功能页函数,再使用 functional-page-navigator 组件跳转到插件功能页,从而实现对应的功能。详情请参考下文。

插件所有者小程序

开始开发之前,我们需要知道,插件功能页是指 插件所有者小程序 中的一个特殊页面。

插件所有者小程序,指的是与插件 AppID 相同的小程序。例如,“小程序示例”小程序开发了一个“小程序示例插件”,那么无论这个插件被哪个小程序使用,这个插件的 插件所有者小程序 都是“小程序示例”。下文中会继续使用 插件所有者小程序 这个说法。

插件所有者小程序开发方法

通常,在开始使用插件功能页的时候,需要开启两个开发者工具窗口,其中一个打开插件项目,另一个打开插件所有者小程序的小程序项目。例如,一个打开“小程序示例插件”项目,另一个打开“小程序示例”项目。

这两个窗口,前者用于编辑插件,后者用于编辑插件所有者小程序。下文中所有需要编辑插件所有者小程序的内容,都是在后者中进行。

激活功能页特性

要在插件中调用插件功能页,需要先激活插件所有者小程序的功能页特性。具体来说,在插件所有者小程序的 app.json 文件中添加 functionalPages 定义段,并令其值为 true ,例如:

代码示例:

{  "functionalPages": {    "independent": true  }}

目前,兼容旧式写法:

{  "functionalPages": true}

旧式写法将在未来将被移除支持,未来将不能编译上传。

这两种写法的区别在于,新式的写法 "independent": true 会使得插件功能页的代码独立于其他代码,这意味着插件功能页可以被独立下载、加载,具有更好的性能表现。 但也同时使得插件功能页目录 functional-pages/ (支付功能页会使用其中的文件)不能 require 这个目录以外的文件(反之亦然:这个目录以外的文件也不能调用这个目录内的)。

注意,新增或改变这个字段时,需要这个小程序发布新版本,才能在正式环境中使用插件功能页。

跳转到功能页

功能页不能使用 wx.navigateTo 来进行跳转,而是需要一个名为 functional-page-navigator 的组件。以获取用户信息为例,可以在插件中放置如下的 functional-page-navigator:

代码示例:

<functional-page-navigator name="loginAndGetUserInfo" args="" version="develop" bind:success="loginSuccess">  <button>登录到插件</button></functional-page-navigator>

用户在点击这个 navigator 时,会自动跳转到插件所有者小程序的对应功能页。功能页会提示用户进行登录或其他相应的操作。操作结果会以组件事件的方式返回。

functional-page-navigator 的参数和详细使用方法可以参考组件说明 。

从小程序基础库版本 2.4.0 开始,支持插件所有者小程序跳转到自己的功能页。在基础库版本低于 2.4.0 时,点击跳转到自己的功能页的 functional-page-navigator 将没有任何反应。

真机开发测试的常规步骤

目前,功能页的跳转目前不支持在开发者工具中调试,请在真机上测试。初次进行真机开发测试时,通常步骤如下:

  1. 在开发者工具上打开插件所有者小程序项目,并点击“预览”;
  2. 用测试用的真机扫一下预览二维码,此时会进入插件所有者小程序,进入后就可以直接退出这个小程序;
  3. 在开发者工具上打开插件项目,将插件中 functional-page-navigator 中的 version 属性设置为 develop;
  4. 点击预览可以生成插件预览二维码,用测试用的真机扫码即可预览功能页;如果更改了插件代码,重新生成并扫描插件的预览二维码即可;
  5. 如果过了一段时间之后,跳转功能页时出现“开发版已过期”这样的提示,从第1步开始重试一次。

注意:functional-page-navigator 的 version=develop 仅用于调试,因此在插件提审前,需要:

  1. 确保已发布设置了 "functionalPages": true 的插件所有者小程序;
  2. 确保所有的 functional-page-navigator 组件属性设置为 version="release" 。

功能页常见问题 FAQ

如何正确编辑插件所有者小程序?

  • 应该在开发者工具的“小程序”类型项目中编辑,而不是在“插件”类型的项目中编辑。比如,“小程序示例插件”的所有者小程序是“小程序示例”,它们的 AppID 都是 wxidxxxxxxxxxxxxxx ,如果是初次开发“小程序示例”小程序,可以在开发者工具中创建一个小程序项目,其 AppID 为 wxidxxxxxxxxxxxxxx ;如果之前开发过“小程序示例”小程序,直接打开之前的小程序项目即可。

点击 functional-page-navigator 之后没有任何反应。

  • 请检查引用插件的小程序和插件本身是不是同一个 AppID ,如果是,跳转到自己的功能页需要基础库 2.4.0 支持,否则使用 functional-page-navigator 不会有任何反应。

点击 functional-page-navigator 之后,展示了一个页面提示“页面不存在”。

  • 这种情况是因为插件所有者小程序没有正确设置 "functionalPages": true 。如果 functional-page-navigator 的 version="develop" ,这部手机需要扫码并进入插件所有者小程序一次;如果 version="release" ,请确保包含 "functionalPages": true 的插件所有者小程序已被发布。

点击 <functional-page-navigator version="develop"> 之后,弹窗提示“小程序开发版已过期”。

  • 遇到这种情况,重新扫码并进入插件所有者小程序一次即可。

点击 <functional-page-navigator name="requestPayment"> 之后,展示了一个页面提示“该功能无法使用”。

  • 在使用插件功能页时,小程序不能是个人小程序,同时,插件也需要额外的步骤申请开通插件支付权限(位于 管理后台 -> 小程序插件 -> 基本设置 -> 支付能力 )。

点击 <functional-page-navigator name="requestPayment"> 之后,点击页面中的“支付”按钮,立刻退出了支付功能页。

  • 这通常是因为没有找到功能页函数 beforeRequestPayment ,请检查插件所有者小程序的 functional-pages/request-payment.js 文件和其中的 beforeRequestPayment 函数是否存在。

点击 functional-page-navigator 之后,展示了一个仅有返回按钮的页面。

  • 请检查 functional-page-navigator 的 name 属性是否被正确设置。

开发版可以正常跳转,但审核反馈不能跳转。

  • 请发布设置了 "functionalPages": true 的插件所有者小程序,且所有的 functional-page-navigator 组件属性设置为 version="release" 。

Bugs & Tips

  • 功能页是插件所有者小程序中的一个特殊页面,开发者不能自定义这个页面的外观。
  • 插件所有者小程序本身也可以引用这个插件,此时,functional-page-navigator 组件的 version 属性将不会生效,而是取决于当前运行的插件所有者小程序的版本。
  • functional-page-navigator 可以在开发者工具中使用,但功能页的跳转目前不支持在开发者工具中调试,请在真机上测试。
  • Bug:在微信版本 6.6.7 中,功能页被拉起时会触发 App 的部分生命周期并使得功能页启动时间变得比较长。在后续的微信版本中这一行为会发生变更,使 App 生命周期不再被触发。

用户信息功能页

用户信息功能页用于帮助插件获取用户信息,包括 openid 和昵称等,相当于 wx.login 和 wx.getUserInfo 的功能。

此外,自基础库版本 2.3.1 起,用户在这个功能页中授权之后,插件就可以直接调用 wx.login 和 wx.getUserInfo 。无需再次进入功能页获取用户信息。自基础库版本 2.6.3 起,可以使用 wx.getSetting 来查询用户是否授权过。

调用参数

用户信息功能页使用 functional-page-navigator 进行跳转时,对应的参数 name 应为固定值 loginAndGetUserInfo,其余参数与 wx.getUserInfo 相同,具体来说:

args参数说明:

参数名类型必填说明
withCredentialsBoolean是否带上登录态信息
langString指定返回用户信息的语言,zh_CN 简体中文,zh_TW 繁体中文,en 英文。默认为en。
timeoutNumber超时时间,单位 ms

注:当 withCredentials 为 true 时,返回的数据会包含 encryptedData, iv 等敏感信息。

bindsuccess返回参数说明:

参数类型说明
codeString同 wx.login 获得的用户登录凭证(有效期五分钟)。开发者需要在开发者服务器后台调用 api,使用 code 换取 openid 和 session_key 等信息
errMsgString调用结果
userInfoOBJECT用户信息对象,不包含 openid 等敏感信息
rawDataString不包括敏感信息的原始数据字符串,用于计算签名。
signatureString使用 sha1( rawData + sessionkey ) 得到字符串,用于校验用户信息,参考文档 signature。
encryptedDataString包括敏感数据在内的完整用户信息的加密数据,详细见加密数据解密算法
ivString加密算法的初始向量,详细见加密数据解密算法

userInfo参数说明:

参数类型说明
nickNameString用户昵称
avatarUrlString用户头像,最后一个数值代表正方形头像大小(有0、46、64、96、132数值可选,0代表132*132正方形头像),用户没有头像时该项为空。若用户更换头像,原有头像URL将失效。
genderString用户的性别,值为1时是男性,值为2时是女性,值为0时是未知
cityString用户所在城市
provinceString用户所在省份
countryString用户所在国家
languageString用户的语言,简体中文为zh_CN

代码示例:

<!--plugin/components/hello-component.wxml-->  <functional-page-navigator    name="loginAndGetUserInfo"    args="{{ args }}"    version="develop"    bind:success="loginSuccess"    bind:fail="loginFail"  >    <button class="login">登录到插件</button>  </functional-page-navigator>
// plugin/components/hello-component.jsComponent({  properties: {},  data: {    args: {      withCredentials: true,      lang: 'zh_CN'    }  },  methods: {    loginSuccess: function (res) {      console.log(res.detail);    },    loginFail: function (res) {      console.log(res);    }  }});

用户点击该 navigator 后,将跳转到如下的用户信息功能页:

用户信息功能页

在微信开发者工具中查看示例:

  1. 由于插件需要 appid 才能工作,请填入一个 appid;
  2. 由于当前代码片段的限制,打开该示例后请 手动将 appid 填写到 miniprogram/app.json 中(如下图)使示例正常运行。

手动填写 appid


支付功能页

支付功能页用于帮助插件完成支付,相当于 wx.requestPayment 的功能。

需要注意的是:插件使用支付功能,需要进行额外的权限申请,申请位置位于管理后台的“小程序插件 -> 基本设置 -> 支付能力”设置项中。另外,无论是否通过申请,主体为个人小程序在使用插件时,都无法正常使用插件里的支付功能。

调用参数

支付功能页使用 functional-page-navigator 进行跳转时,对应的参数 name 应为固定值 requestPayment,其他参数如下:

args参数说明:

参数名类型必填说明
feeNumber需要显示在页面中的金额,单位为分
paymentArgsObject任意数据,传递给功能页中的响应函数
currencyTypeString需要显示在页面中的货币符号的代码,默认为 CNY

currencyType 的合法值:

说明最低版本
CNY货币符号 ¥
USD货币符号 US$
JPY货币符号 J¥
EUR货币符号 €
HKD货币符号 HK$
GBP货币符号 £
AUD货币符号 A$
MOP货币符号 MOP$
KRW货币符号 ₩

代码示例:

<!-- plugin/components/pay.wxml --><!-- 上线时,version 应改为 "release",并确保插件所有者小程序已经发布 --><functional-page-navigator  version="develop"  name="requestPayment"  args="{{ args }}"  bind:success="paymentSuccess"  bind:fail="paymentFailed">  <button class="payment-button">支付 0.01 元</button></functional-page-navigator>
// plugin/components/pay.jsComponent({  data: {    args: {      fee: 1,             // 支付金额,单位为分      paymentArgs: 'A', // 将传递到功能页函数的自定义参数      currencyType: 'USD' // 货币符号,页面显示货币简写 US$     }  },  methods: {    // 支付成功的回调接口    paymentSuccess: function (e) {      console.log(e);      e.detail.extraData.timeStamp // 用 extraData 传递数据,详见下面功能页函数代码    },    // 支付失败的回调接口    paymentFailed: function (e) {      console.log(e);    }  }})

用户点击该 navigator 后,将跳转到如下的支付功能页:

支付功能页

配置功能页函数

支付功能页需要插件开发者在插件所有者小程序中提供一个函数来响应插件中的支付调用。即,在插件中跳转到支付功能页时,这个函数就会在合适的时机被调用,来帮助完成支付。如果不提供功能页函数,功能页调用将通过 fail 事件返回失败。

支付功能页函数应以导出函数的形式提供在插件所有者小程序的根目录下的 functional-pages/request-payment.js 文件中,名为 beforeRequestPayment。该函数应接收两个参数:

参数名类型说明
paymentArgsObject即通过 functional-page-navigator 的 arg 参数中的 paymentArgs 字段传递到功能页的自定义数据
callbackFunction回调函数,调用该函数后,小程序将发起支付(类似于 wx.requestPayment)

callback函数的参数:

参数名类型说明
errorObject失败信息,若无失败,应返回 null
requestPaymentArgsObject支付参数,用于调用 wx.requestPayment,参数如下

reqeustPaymentArgs 的参数:

用于发起支付,和 wx.requestPayment 的参数相同,但没有回调函数(success, fail, complete):

参数类型必填说明
timeStampString时间戳从1970年1月1日00:00:00至今的秒数,即当前的时间
nonceStrString随机字符串,长度为32个字符以下。
packageString统一下单接口返回的 prepay_id 参数值,提交格式如:prepay_id=***
signTypeString签名算法,暂支持 MD5
paySignString签名,具体签名方案参见小程序支付接口文档;
extraDataany由开发者决定的自定义数据段,该字段将被无修改地透传到支付成功的回调参数中,具体见代码示例中的使用方法。基础库 2.9.1 开始支持

了解更多信息,请查看微信支付接口文档

功能页函数代码示例:

// functional-pages/request-payment.jsexports.beforeRequestPayment = function (paymentArgs, callback) {  // 注意:  // 功能页函数(这个函数)不应 require 其他非 functional-pages 目录中的文件,  // 其他非 functional-pages 目录中的文件也不应 require 这个目录中的文件,  // 这样的 require 调用在未来将不被支持。  //  // 同在 functional-pages 中的文件可以 require  var getOpenIdURL = require('./URL').getOpenIdURL;  var paymentURL = require('./URL').paymentURL;  // 自定义的参数,此处应为从插件传递过来的 'A'  var customArgument = paymentArgs.customArgument;  // 第一步:调用 wx.login 方法获取 code,然后在服务端调用微信接口使用 code 换取下单用户的 openId  // 具体文档参考 https://mp.weixin.qq.com/debug/wxadoc/dev/api/api-login.html?t=20161230#wxloginobject  wx.login({    success: function (data) {      wx.request({        url: getOpenIdURL,        data: { code: data.code },        success: function (res) {          // 拉取用户 openid 成功          // 第二步:在服务端调用支付统一下单,返回支付参数。这里的开发和普通的 wx.requestPayment 相同          // 文档可以参考 https://pay.weixin.qq.com/wiki/doc/api/wxa/wxa_api.php?chapter=7_4&index=3          wx.request({            url: paymentURL,            data: { openid: res.data.openid },            method: 'POST',            success: function (res) {              console.log('unified order success, response is:', res);              var payargs = res.data.payargs;              // 第三步:调用回调函数 callback 进行支付              // 在 callback 中需要返回两个参数: err 和 requestPaymentArgs:              // err 应为 null (或者一些失败信息);              // requestPaymentArgs 将被用于调用 wx.requestPayment,除了 success/fail/complete 不被支持外,              // 应与 wx.requestPayment 参数相同。              var error = null;              var requestPaymentArgs = {                timeStamp: payargs.timeStamp,                nonceStr: payargs.nonceStr,                package: payargs.package,                signType: payargs.signType,                paySign: payargs.paySign,                extraData: { // 用 extraData 传递自定义数据                  timeStamp: payargs.timeStamp                },              };              callback(error, requestPaymentArgs);            }          });        },        fail: function (res) {          console.log('拉取用户openid失败,将无法正常使用开放接口等服务', res);          // callback 第一个参数为错误信息,返回错误信息          callback(res);        }      });    },    fail: function (err) {      console.log('wx.login 接口调用失败,将无法正常使用开放接口等服务', err)      // callback 第一个参数为错误信息,返回错误信息      callback(err);    }  });}

注意:功能页函数不应 require 其他非 functional-pages 目录中的文件,其他非 functional-pages 目录中的文件也不应 require 这个目录中的文件。这样的 require 调用在未来将不被支持。

这个目录和文件应当被放置在插件所有者小程序代码中(而非插件代码中),它是插件所有者小程序的一部分(而非插件的一部分)。 如果需要新增或更改这段代码,需要发布插件所有者小程序,才能在正式版中生效;需要重新预览插件所有者小程序,才能在开发版中生效。


收货地址功能页

收货地址功能页用于展示用户的收货地址列表,用户可以选择其中的收货地址。自基础库版本 2.4.0 开始支持。

调用参数

用户信息功能页使用 functional-page-navigator 进行跳转时,对应的参数 name 应为固定值 chooseAddress ,返回参数与 wx.chooseAddress 相同。

bindsuccess返回参数说明:

属性类型说明最低版本
userNamestring收货人姓名
postalCodestring邮编
provinceNamestring国标收货地址第一级地址
cityNamestring国标收货地址第一级地址
countyNamestring国标收货地址第一级地址
detailInfostring详细收货地址信息
nationalCodestring收货地址国家码
telNumberstring收货人手机号码
errMsgstring错误信息

代码示例:

<!--plugin/components/hello-component.wxml-->  <functional-page-navigator    name="chooseAddress"    version="develop"    bind:success="onSuccess"    bind:fail="onFail"  >    <button>选择收货地址</button>  </functional-page-navigator>
// plugin/components/hello-component.jsComponent({  methods: {    onSuccess: function (res) {      console.log(res.detail);    },    onFail: function (res) {      console.log(res);    }  }});


网络

在小程序/小游戏中使用网络相关的 API 时,需要注意下列问题,请开发者提前了解。

1. 服务器域名配置

每个微信小程序需要事先设置通讯域名,小程序只可以跟指定的域名进行网络通信。包括普通 HTTPS 请求(wx.request)、上传文件(wx.uploadFile)、下载文件( wx.downloadFile) 和 WebSocket 通信(wx.connectSocket)。

从基础库 2.4.0 开始,网络接口允许与局域网 IP 通信,但要注意 不允许与本机 IP 通信。

从 2.7.0 开始,提供了 UDP 通信(wx.createUDPSocket)。

配置流程

服务器域名请在 「小程序后台-开发-开发设置-服务器域名」 中进行配置,配置时需要注意:

  • 域名只支持 https (wx.request、wx.uploadFile、wx.downloadFile) 和 wss (wx.connectSocket) 协议;
  • 域名不能使用 IP 地址(小程序的局域网 IP 除外)或 localhost;
  • 可以配置端口,如 https://myserver.com:8080,但是配置后只能向 https://myserver.com:8080 发起请求。如果向 https://myserver.com、https://myserver.com:9091 等 URL 请求则会失败。
  • 如果不配置端口。如 https://myserver.com,那么请求的 URL 中也不能包含端口,甚至是默认的 443 端口也不可以。如果向 https://myserver.com:443 请求则会失败。
  • 域名必须经过 ICP 备案;
  • 出于安全考虑,api.weixin.qq.com 不能被配置为服务器域名,相关API也不能在小程序内调用。 开发者应将 AppSecret 保存到后台服务器中,通过服务器使用 getAccessToken 接口获取 access_token,并调用相关 API;
  • 对于每个接口,分别可以配置最多 20 个域名。

2. 网络请求

超时时间

  • 默认超时时间和最大超时时间都是 60s;
  • 超时时间可以在 app.json 或 game.json 中通过 networktimeout 配置。

使用限制

  • 网络请求的 referer header 不可设置。其格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 appid,{version} 为小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本;
  • wx.request、wx.uploadFile、wx.downloadFile 的最大并发限制是 10 个;
  • wx.connectSocket 的最大并发限制是 5 个。
  • 小程序进入后台运行后,如果 5s 内网络请求没有结束,会回调错误信息 fail interrupted;在回到前台之前,网络请求接口调用都会无法调用。

返回值编码

  • 建议服务器返回值使用 UTF-8 编码。对于非 UTF-8 编码,小程序会尝试进行转换,但是会有转换失败的可能。
  • 小程序会自动对 BOM 头进行过滤(只过滤一个BOM头)。

回调函数

  • 只要成功接收到服务器返回,无论 statusCode 是多少,都会进入 success 回调。请开发者根据业务逻辑对返回值进行判断。

3. 常见问题

HTTPS 证书

小程序必须使用 HTTPS/WSS 发起网络请求。请求时系统会对服务器域名使用的 HTTPS 证书进行校验,如果校验失败,则请求不能成功发起。由于系统限制,不同平台对于证书要求的严格程度不同。为了保证小程序的兼容性,建议开发者按照最高标准进行证书配置,并使用相关工具检查现有证书是否符合要求。

对证书要求如下:

  • HTTPS 证书必须有效;证书必须被系统信任,即根证书被已系统内置部署 SSL 证书的网站域名必须与证书颁发的域名一致证书必须在有效期内证书的信任链必需完整(需要服务器配置)
  • iOS 不支持自签名证书;
  • iOS 下证书必须满足苹果 App Transport Security (ATS) 的要求;
  • TLS 必须支持 1.2 及以上版本。部分旧 Android 机型还未支持 TLS 1.2,请确保 HTTPS 服务器的 TLS 版本支持 1.2 及以下版本;
  • 部分 CA 可能不被操作系统信任,请开发者在选择证书时注意小程序和各系统的相关通告。
证书有效性可以使用 openssl s_client -connect example.com:443 命令验证,也可以使用其他在线工具。

除了网络请求 API 外,小程序中其他 HTTPS 请求如果出现异常,也请按上述流程进行检查。如 https 的图片无法加载、音视频无法播放等。

跳过域名校验

在微信开发者工具中,可以临时开启 开发环境不校验请求域名、TLS版本及HTTPS证书 选项,跳过服务器域名的校验。此时,在微信开发者工具中及手机开启调试模式时,不会进行服务器域名的校验。

在服务器域名配置成功后,建议开发者关闭此选项进行开发,并在各平台下进行测试,以确认服务器域名配置正确。

如果手机上出现 “打开调试模式可以发出请求,关闭调试模式无法发出请求” 的现象,请确认是否跳过了域名校验,并确认服务器域名和证书配置是否正确。

局域网通信

基础库 2.4.0 提供了 wx.startLocalServiceDiscovery 等一系列 mDNS API,可以用来获取局域网内提供 mDNS 服务的设备的 IP。 wx.request/wx.connectSocket/wx.uploadFile/wx.downloadFile 的 url 参数允许为 ${IP}:${PORT}/${PATH} 的格式,当且仅当 IP 与手机 IP 处在同一网段且不与本机 IP 相同(一般来说,就是同一局域网,如连接在同一个 wifi 下)时,请求/连接才会成功。

在这种情况下,不会进行安全域的校验,不要求必须使用 https/wss,也可以使用 http/ws。

wx.request({  url: 'http://10.9.176.40:828'  // 省略其他参数})wx.connectSocket({  url: 'ws://10.9.176.42:828'  // 省略其他参数})

基础库 2.7.0 开始,提供了 wx.createUDPSocket 接口用于进行 UDP 通信。通信规则同上,仅允许同一局域网下的非本机 IP。

mDNS

目前小程序只支持通过 mDNS 协议获取局域网内其他设备的 IP。iOS 上 mDNS API 的实现基于 Bonjour,Android 上则是基于 Android 系统接口。

serviceType

发起 mDNS 服务搜索 wx.startLocalServiceDiscovery 的接口有 serviceType 参数,指定要搜索的服务类型。

serviceType 的格式和规范,iOS Bonjour Overview 在 Bonjour Names for Existing Service Types 有提及。

Bonjour serviceType.png

Android 文档 对此也有提及。

Android serviceType.png


存储

每个微信小程序都可以有自己的本地缓存,可以通过 wx.setStorage/wx.setStorageSyncwx.getStorage/wx.getStorageSyncwx.clearStorage/wx.clearStorageSyncwx.removeStorage/wx.removeStorageSync 对本地缓存进行读写和清理。

隔离策略

同一个微信用户,同一个小程序 storage 上限为 10MB。storage 以用户维度隔离,同一台设备上,A 用户无法读取到 B 用户的数据;不同小程序之间也无法互相读写数据。

清理策略

本地缓存的清理时机跟代码包一样,只有在代码包被清理的时候本地缓存才会被清理。


文件系统

文件系统是小程序提供的一套以小程序和用户维度隔离的存储以及一套相应的管理接口。通过 wx.getFileSystemManager() 可以获取到全局唯一的文件系统管理器,所有文件系统的管理操作通过 FileSystemManager 来调用。

var fs = wx.getFileSystemManager()

文件主要分为两大类:

  • 代码包文件:代码包文件指的是在项目目录中添加的文件。
  • 本地文件:通过调用接口本地产生,或通过网络下载下来,存储到本地的文件。

其中本地文件又分为三种:

  1. 本地临时文件:临时产生,随时会被回收的文件。不限制存储大小。
  2. 本地缓存文件:小程序通过接口把本地临时文件缓存后产生的文件,不能自定义目录和文件名。跟本地用户文件共计,普通小程序最多可存储 10MB,游戏类目的小程序最多可存储 50MB。
  3. 本地用户文件:小程序通过接口把本地临时文件缓存后产生的文件,允许自定义目录和文件名。跟本地缓存文件共计,普通小程序最多可存储 10MB,游戏类目的小程序最多可存储 50MB。

代码包文件

由于代码包文件大小限制,代码包文件适用于放置首次加载时需要的文件,对于内容较大或需要动态替换的文件,不推荐用添加到代码包中,推荐在小游戏启动之后再用下载接口下载到本地。

访问代码包文件

代码包文件的访问方式是从项目根目录开始写文件路径,不支持相对路径的写法。如:/a/b/c、a/b/c 都是合法的,./a/b/c ../a/b/c 则不合法。 image.png

修改代码包文件

代码包内的文件无法在运行后动态修改或删除,修改代码包文件需要重新发布版本。

本地文件

本地文件指的是小程序被用户添加到手机后,会有一块独立的文件存储区域,以用户维度隔离。即同一台手机,每个微信用户不能访问到其他登录用户的文件,同一个用户不同 appId 之间的文件也不能互相访问。 本地文件沙盒.png

本地文件的文件路径均为以下格式:

{{协议名}}://文件路径
其中,协议名在 iOS/Android 客户端为 "wxfile",在开发者工具上为 "http",开发者无需关注这个差异,也不应在代码中去硬编码完整文件路径。

本地临时文件

本地临时文件只能通过调用特定接口产生,不能直接写入内容。本地临时文件产生后,仅在当前生命周期内有效,重启之后即不可用。因此,不可把本地临时文件路径存储起来下次使用。如果需要下次在使用,可通过 FileSystemManager.saveFile() 或 FileSystemManager.copyFile() 接口把本地临时文件转换成本地缓存文件或本地用户文件。

示例
wx.chooseImage({  success: function (res) {    var tempFilePaths = res.tempFilePaths // tempFilePaths 的每一项是一个本地临时文件路径  }})

本地缓存文件

本地缓存文件只能通过调用特定接口产生,不能直接写入内容。本地缓存文件产生后,重启之后仍可用。本地缓存文件只能通过 FileSystemManager.saveFile() 接口将本地临时文件保存获得。

示例
fs.saveFile({  tempFilePath: '', // 传入一个本地临时文件路径  success(res) {    console.log(res.savedFilePath) // res.savedFilePath 为一个本地缓存文件路径  }})

注意:本地缓存文件是最初的设计,1.7.0 版本开始,提供了功能更完整的本地用户文件,可以完全覆盖本地缓存文件的功能,如果不需要兼容低于 1.7.0 版本,可以不使用本地缓存文件。

本地用户文件

本地用户文件是从 1.7.0 版本开始新增的概念。我们提供了一个用户文件目录给开发者,开发者对这个目录有完全自由的读写权限。通过 wx.env.USER_DATA_PATH 可以获取到这个目录的路径。

示例
// 在本地用户文件目录下创建一个文件 hello.txt,写入内容 "hello, world"const fs = wx.getFileSystemManager()fs.writeFileSync(`${wx.env.USER_DATA_PATH}/hello.txt`, 'hello, world', 'utf8')

读写权限

接口、组件
代码包文件
本地临时文件
本地缓存文件
本地用户文件

清理策略

  • 本地临时文件只保证在小程序当前生命周期内,一旦小程序被关闭就可能被清理,即下次冷启动不保证可用。
  • 本地缓存文件和本地用户文件的清理时机跟代码包一样,只有在代码包被清理的时会被清理。


Canvas 画布

所有在 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)

第三步:画图

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

ctx.draw()

结果:

坐标系

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

在上一节,我们用了这个方法 fillRect(0, 0, 150, 75)。

它的含义为:从左上角(0, 0)开始,画一个150 x 75px 的矩形。

代码示例

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

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

当你把手指放到 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 gradientconst grd = ctx.createLinearGradient(0, 0, 200, 0)grd.addColorStop(0, 'red')grd.addColorStop(1, 'white')// Fill with gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()

使用 createCircularGradient()

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


分包加载

微信客户端 6.6.0,基础库 1.7.3 及以上版本开始支持。开发者工具请使用 1.01.1712150 及以上版本,可点此下载

某些情况下,开发者需要将小程序划分成不同的子包,在构建时打包成不同的分包,用户在使用时按需进行加载。

在构建小程序分包项目时,构建会输出一个或多个分包。每个使用分包小程序必定含有一个主包。所谓的主包,即放置默认启动页面/TabBar 页面,以及一些所有分包都需用到公共资源/JS 脚本;而分包则是根据开发者的配置进行划分。

在小程序启动时,默认会下载主包并启动主包内页面,当用户进入分包内某个页面时,客户端会把对应分包下载下来,下载完成后再进行展示。

目前小程序分包大小有以下限制:

  • 整个小程序所有分包大小不超过 16M
  • 单个分包/主包大小不能超过 2M

对小程序进行分包,可以优化小程序首次启动的下载时间,以及在多团队共同开发时可以更好的解耦协作。

具体使用方法请参考:

1、使用分包

配置方法

假设支持分包的小程序目录结构如下:

├── app.js├── app.json├── app.wxss├── packageA│   └── pages│       ├── cat│       └── dog├── packageB│   └── pages│       ├── apple│       └── banana├── pages│   ├── index│   └── logs└── utils

开发者通过在 app.json subpackages 字段声明项目分包结构:

写成 subPackages 也支持。
{  "pages":[    "pages/index",    "pages/logs"  ],  "subpackages": [    {      "root": "packageA",      "pages": [        "pages/cat",        "pages/dog"      ]    }, {      "root": "packageB",      "name": "pack2",      "pages": [        "pages/apple",        "pages/banana"      ]    }  ]}

subpackages 中,每个分包的配置有以下几项:

字段类型说明
rootString分包根目录
nameString分包别名,分包预下载时可以使用
pagesStringArray分包页面路径,相对与分包根目录
independentBoolean分包是否是独立分包

打包原则

  • 声明 subpackages 后,将按 subpackages 配置路径进行打包,subpackages 配置路径外的目录将被打包到 app(主包) 中
  • app(主包)也可以有自己的 pages(即最外层的 pages 字段)
  • subpackage 的根目录不能是另外一个 subpackage 内的子目录
  • tabBar 页面必须在 app(主包)内

引用原则

  • packageA 无法 require packageB JS 文件,但可以 require app、自己 package 内的 JS 文件
  • packageA 无法 import packageB 的 template,但可以 require app、自己 package 内的 template
  • packageA 无法使用 packageB 的资源,但可以使用 app、自己 package 内的资源

低版本兼容

由微信后台编译来处理旧版本客户端的兼容,后台会编译两份代码包,一份是分包后代码,另外一份是整包的兼容代码。 新客户端用分包,老客户端还是用的整包,完整包会把各个 subpackage 里面的路径放到 pages 中。

示例项目

下载 小程序示例(分包加载版)源码



2、独立分包

微信客户端 6.7.2,基础库 2.3.0 及以上版本开始支持。开发者工具请使用 1.02.1808300 及以上版本,可点此下载

独立分包是小程序中一种特殊类型的分包,可以独立于主包和其他分包运行。从独立分包中页面进入小程序时,不需要下载主包。当用户进入普通分包或主包内页面时,主包才会被下载。

开发者可以按需将某些具有一定功能独立性的页面配置到独立分包中。当小程序从普通的分包页面启动时,需要首先下载主包;而独立分包不依赖主包即可运行,可以很大程度上提升分包页面的启动速度。

一个小程序中可以有多个独立分包。

小游戏不支持独立分包。

配置方法

假设小程序目录结构如下:

├── app.js├── app.json├── app.wxss├── moduleA│   └── pages│       ├── rabbit│       └── squirrel├── moduleB│   └── pages│       ├── pear│       └── pineapple├── pages│   ├── index│   └── logs└── utils

开发者通过在app.json的subpackages字段中对应的分包配置项中定义independent字段声明对应分包为独立分包。

{  "pages": [    "pages/index",    "pages/logs"  ],  "subpackages": [    {      "root": "moduleA",      "pages": [        "pages/rabbit",        "pages/squirrel"      ]    }, {      "root": "moduleB",      "pages": [        "pages/pear",        "pages/pineapple"      ],      "independent": true    }  ]}

限制

独立分包属于分包的一种。普通分包的所有限制都对独立分包有效。独立分包中插件、自定义组件的处理方式同普通分包。

此外,使用独立分包时要注意:

  • 独立分包中不能依赖主包和其他分包中的内容,包括js文件、template、wxss、自定义组件、插件等。主包中的app.wxss对独立分包无效,应避免在独立分包页面中使用 app.wxss 中的样式;
  • App 只能在主包内定义,独立分包中不能定义 App,会造成无法预期的行为;
  • 独立分包中暂时不支持使用插件。

注意事项

(1)关于 getApp()

与普通分包不同,独立分包运行时,App 并不一定被注册,因此 getApp() 也不一定可以获得 App 对象:

  • 当用户从独立分包页面启动小程序时,主包不存在,App也不存在,此时调用 getApp() 获取到的是 undefined。 当用户进入普通分包或主包内页面时,主包才会被下载,App 才会被注册。
  • 当用户是从普通分包或主包内页面跳转到独立分包页面时,主包已经存在,此时调用 getApp() 可以获取到真正的 App。

由于这一限制,开发者无法通过 App 对象实现独立分包和小程序其他部分的全局变量共享。

为了在独立分包中满足这一需求,基础库 2.2.4 版本开始 getApp支持 [allowDefault]参数,在 App 未定义时返回一个默认实现。当主包加载,App 被注册时,默认实现中定义的属性会被覆盖合并到真正的 App 中。

示例代码:

  • 独立分包中
const app = getApp({allowDefault: true}) // {}app.data = 456app.global = {}
  • app.js 中
App({  data: 123,  other: 'hello'})console.log(getApp()) // {global: {}, data: 456, other: 'hello'}

(2)关于 App 生命周期

当从独立分包启动小程序时,主包中 App 的 onLaunch 和首次 onShow 会在从独立分包页面首次进入主包或其他普通分包页面时调用。

由于独立分包中无法定义 App,小程序生命周期的监听可以使用 wx.onAppShow,wx.onAppHide 完成。App 上的其他事件可以使用 wx.onError,wx.onPageNotFound 监听。

低版本兼容

在低于6.7.2版本的微信中运行时,独立分包视为普通分包处理,不具备独立运行的特性。

注意:在兼容模式下,主包中的 app.wxss 可能会对独立分包中的页面产生影响,因此应避免在独立分包页面中使用 app.wxss 中的样式。



3、分包预下载

基础库 2.3.0 开始支持,低版本需做兼容处理。 开发者工具请使用 1.02.1808300 及以上版本,可点此下载

开发者可以通过配置,在进入小程序某个页面时,由框架自动预下载可能需要的分包,提升进入后续分包页面时的启动速度。对于独立分包,也可以预下载主包。

分包预下载目前只支持通过配置方式使用,暂不支持通过调用API完成。

vConsole 里有preloadSubpackages开头的日志信息,可以用来验证预下载的情况。

配置方法

预下载分包行为在进入某个页面时触发,通过在 app.json 增加 preloadRule 配置来控制。

{  "pages": ["pages/index"],  "subpackages": [    {      "root": "important",      "pages": ["index"],    },    {      "root": "sub1",      "pages": ["index"],    },    {      "name": "hello",      "root": "path/to",      "pages": ["index"]    },    {      "root": "sub3",      "pages": ["index"]    },    {      "root": "indep",      "pages": ["index"],      "independent": true    }  ],  "preloadRule": {    "pages/index": {      "network": "all",      "packages": ["important"]    },    "sub1/index": {      "packages": ["hello", "sub3"]    },    "sub3/index": {      "packages": ["path/to"]    },    "indep/index": {      "packages": ["__APP__"]    }  }}

preloadRule 中,key 是页面路径,value 是进入此页面的预下载配置,每个配置有以下几项:

字段类型必填默认值说明
packagesStringArray进入页面后预下载分包的 root 或 name__APP__ 表示主包。
networkStringwifi在指定网络下预下载,可选值为:
all: 不限网络
wifi: 仅wifi下预下载

限制

同一个分包中的页面享有共同的预下载大小限额 2M,限额会在工具中打包时校验。

如,页面 A 和 B 都在同一个分包中,A 中预下载总大小 0.5M 的分包,B中最多只能预下载总大小 1.5M 的分包。


多线程 Worker

一些异步处理的任务,可以放置于 Worker 中运行,待运行结束后,再把结果返回到小程序主线程。Worker 运行于一个单独的全局上下文与线程中,不能直接调用主线程的方法。

Worker 与主线程之间的数据传输,双方使用 Worker.postMessage() 来发送数据,Worker.onMessage() 来接收数据,传输的数据并不是直接共享,而是被复制的。

使用流程

1. 配置 Worker 信息

在 app.json 中可配置 Worker 代码放置的目录,目录下的代码将被打包成一个文件:

配置示例:

{  "workers": "workers"}

2. 添加 Worker 代码文件

根据步骤 1 中的配置,在代码目录下新建以下两个入口文件:

workers/request/index.jsworkers/request/utils.jsworkers/response/index.js

添加后,目录结构如下:

├── app.js├── app.json├── project.config.json└── workers    ├── request    │   ├── index.js    │   └── utils.js    └── response        └── index.js

3. 编写 Worker 代码

在 workers/request/index.js 编写 Worker 响应代码

const utils = require('./utils')// 在 Worker 线程执行上下文会全局暴露一个 worker 对象,直接调用 worker.onMeesage/postMessage 即可worker.onMessage(function (res) {  console.log(res)})

4. 在主线程中初始化 Worker

在主线程的代码 app.js 中初始化 Worker

const worker = wx.createWorker('workers/request/index.js') // 文件名指定 worker 的入口文件路径,绝对路径

5. 主线程向 Worker 发送消息

worker.postMessage({  msg: 'hello worker'})

worker 对象的其它接口请看 worker接口说明

注意事项

  1. Worker 最大并发数量限制为 1 个,创建下一个前请用 Worker.terminate() 结束当前 Worker
  2. Worker 内代码只能 require 指定 Worker 路径内的文件,无法引用其它路径
  3. Worker 的入口文件由 wx.createWorker() 时指定,开发者可动态指定 Worker 入口文件
  4. Worker 内不支持 wx 系列的 API
  5. Workers 之间不支持发送消息


后端 API

小程序还提供了一系列在后端服务器使用 HTTPS 请求调用的 API,帮助开发者在后台完成各类数据分析、管理和查询等操作。如 getAccessToken,code2Session 等。

access_token

access_token 是小程序全局唯一后台接口调用凭据,调用绝大多数后台接口时都需使用。开发者可以通过 getAccessToken 接口获取并进行妥善保存。

为了 access_token 的安全性,后端 API 不能直接在小程序内通过 wx.request 调用,即 api.weixin.qq.com 不能被配置为服务器域名。开发者应在后端服务器使用getAccessToken获取 access_token,并调用相关 API;

请求参数说明

  • 对于 GET 请求,请求参数应以 QueryString 的形式写在 URL 中。
  • 对于 POST 请求,部分参数需以 QueryString 的形式写在 URL 中(一般只有 access_token,如有额外参数会在文档里的 URL 中体现),其他参数如无特殊说明均以 JSON 字符串格式写在 POST 请求的 body 中。

返回参数说明

注意:当API调用成功时,部分接口不会返回 errcode 和 errmsg,只有调用失败时才会返回。


消息推送

接入微信小程序消息推送服务,可以两种方式选择其一:

  1. 开发者服务器接收消息推送
  2. 云函数接收消息推送

开发者服务器接收消息推送

开发者需要按照如下步骤完成:

  1. 填写服务器配置
  2. 验证服务器地址的有效性
  3. 据接口文档实现业务逻辑,接收消息和事件

第一步:填写服务器配置

登录小程序后台后,在「开发」-「开发设置」-「消息推送」中,管理员扫码启用消息服务,填写服务器地址(URL)、令牌(Token) 和 消息加密密钥(EncodingAESKey)等信息。

  • URL: 开发者用来接收微信消息和事件的接口 URL。开发者所填写的URL 必须以 http:// 或 https:// 开头,分别支持 80 端口和 443 端口。
  • Token: 可由开发者可以任意填写,用作生成签名(该 Token 会和接口 URL 中包含的 Token 进行比对,从而验证安全性)。
  • EncodingAESKey: 由开发者手动填写或随机生成,将用作消息体加解密密钥。

同时,开发者可选择消息加解密方式:明文模式(默认)、兼容模式和安全模式。可以选择消息数据格式:XML 格式(默认)或 JSON 格式。

填写服务器配置

模式的选择与服务器配置在提交后都会立即生效,请开发者谨慎填写及选择。切换加密方式和数据格式需要提前配置好相关代码,详情请参考 消息加解密说明。

第二步:验证消息的确来自微信服务器

开发者提交信息后,微信服务器将发送GET请求到填写的服务器地址URL上,GET请求携带参数如下表所示:

参数描述
signature微信加密签名,signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。
timestamp时间戳
nonce随机数
echostr随机字符串

开发者通过检验 signature 对请求进行校验(下面有校验方式)。若确认此次 GET 请求来自微信服务器,请原样返回 echostr 参数内容,则接入生效,成为开发者成功,否则接入失败。加密/校验流程如下:

  1. 将token、timestamp、nonce三个参数进行字典序排序
  2. 将三个参数字符串拼接成一个字符串进行sha1加密
  3. 开发者获得加密后的字符串可与signature对比,标识该请求来源于微信

验证URL有效性成功后即接入生效,成为开发者。

检验signature的PHP示例代码:

private function checkSignature(){    $signature = $_GET["signature"];    $timestamp = $_GET["timestamp"];    $nonce = $_GET["nonce"];    $token = TOKEN;    $tmpArr = array($token, $timestamp, $nonce);    sort($tmpArr, SORT_STRING);    $tmpStr = implode( $tmpArr );    $tmpStr = sha1( $tmpStr );    if ($tmpStr == $signature ) {        return true;    } else {        return false;    }}

PHP示例代码下载:下载

第三步:接收消息和事件

当某些特定的用户操作引发事件推送时(如用户向小程序客服发送消息、或者进入会话等情况),微信服务器会将消息(或事件)的数据包以 POST 请求发送到开发者配置的 URL,开发者可以依据自身业务逻辑进行响应。

微信服务器在将用户的消息发给开发者服务器地址后,微信服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次。如果在调试中,发现用户无法收到响应的消息,可以检查是否消息处理超时。关于重试的消息排重,有 msgid 的消息推荐使用 msgid 排重。事件类型消息推荐使用 FromUserName + CreateTime 排重。

服务器收到请求必须做出下述回复,这样微信服务器才不会对此作任何处理,并且不会发起重试,否则,将出现严重的错误提示。详见下面说明:

  1. 直接回复success(推荐方式)
  2. 直接回复空串(指字节长度为0的空字符串,而不是结构体中content字段的内容为空)
  3. 若接口文档有指定返回内容,应按文档说明返回

对于客服消息,一旦遇到以下情况,微信会在小程序会话中向用户下发系统提示“该小程序客服暂时无法提供服务,请稍后再试”:

  1. 开发者在5秒内未回复任何内容
  2. 开发者回复了异常数据

如果开发者希望增强安全性,可以在开发者中心处开启消息加密,这样,用户发给小程序的消息以及小程序被动回复用户消息都会继续加密,详见消息加解密说明。

云函数接收消息推送

需开发者工具版本至少 1.02.1906252

开通了云开发的小程序可以使用云函数接收消息推送,目前仅支持客服消息推送。

接入步骤如下:

  1. 开发者工具中填写配置并上传
  2. 云函数中处理消息

第一步:开发者工具云开发控制台中增加配置

打开云开发控制台,到设置 tab 中选择全局设置 - 添加消息推送配置。消息类型对应收包的 MsgType,事件类型对应收包的 Event,同一个 <消息类型, 事件类型> 二元组只能推到一个环境的一个云函数。例如客服消息文本消息对应的就是消息类型为 text,事件类型为空。具体值请查看各个消息的消息格式。

第二步:云函数中处理消息

云函数被触发时,其 event 参数即是接口所定义的 JSON 结构的对象(统一 JSON 格式,不支持 XML 格式)。

以客服消息为例,接收到客服消息推送时,event 结构如下:

{  "FromUserName": "ohl4L0Rnhq7vmmbT_DaNQa4ePaz0",  "ToUserName": "wx3d289323f5900f8e",  "Content": "测试",  "CreateTime": 1555684067,  "MsgId": "49d72d67b16d115e7935ac386f2f0fa41535298877_1555684067",  "MsgType": "text"}

此时可调用客服消息发送接口回复消息,一个简单的接收到消息后统一回复 “收到” 的示例如下:

// 云函数入口文件const cloud = require('wx-server-sdk')cloud.init()// 云函数入口函数exports.main = async (event, context) => {  const wxContext = cloud.getWXContext()    await cloud.openapi.customerServiceMessage.send({    touser: wxContext.OPENID,    msgtype: 'text',    text: {      content: '收到',    },  })  return 'success'}


自定义 tabBar

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

自定义 tabBar 可以让开发者更加灵活地设置 tabBar 样式,以满足更多个性化的场景。

在自定义 tabBar 模式下

  • 为了保证低版本兼容以及区分哪些页面是 tab 页,tabBar 的相关配置项需完整声明,但这些字段不会作用于自定义 tabBar 的渲染。
  • 此时需要开发者提供一个自定义组件来渲染 tabBar,所有 tabBar 的样式都由该自定义组件渲染。推荐用 fixed 在底部的 cover-view + cover-image 组件渲染样式,以保证 tabBar 层级相对较高。
  • 与 tabBar 样式相关的接口,如 wx.setTabBarItem 等将失效。
  • 每个 tab 页下的自定义 tabBar 组件实例是不同的,可通过自定义组件下的 getTabBar 接口,获取当前页面的自定义 tabBar 组件实例。

注意:如需实现 tab 选中态,要在当前页面下,通过 getTabBar 接口获取组件实例,并调用 setData 更新选中态。可参考底部的代码示例。

使用流程

1. 配置信息

  • 在 app.json 中的 tabBar 项指定 custom 字段,同时其余 tabBar 相关配置也补充完整。
  • 所有 tab 页的 json 里需声明 usingComponents 项,也可以在 app.json 全局开启。

示例:

{  "tabBar": {    "custom": true,    "color": "#000000",    "selectedColor": "#000000",    "backgroundColor": "#000000",    "list": [{      "pagePath": "page/component/index",      "text": "组件"    }, {      "pagePath": "page/API/index",      "text": "接口"    }]  },  "usingComponents": {}}

2. 添加 tabBar 代码文件

在代码根目录下添加入口文件:

custom-tab-bar/index.jscustom-tab-bar/index.jsoncustom-tab-bar/index.wxmlcustom-tab-bar/index.wxss

3. 编写 tabBar 代码

用自定义组件的方式编写即可,该自定义组件完全接管 tabBar 的渲染。另外,自定义组件新增 getTabBar 接口,可获取当前页面下的自定义 tabBar 组件实例。


周期性更新

基础库 2.8.0 开始支持,低版本需做兼容处理
生效条件:用户七天内使用过的小程序

周期性更新能够在用户未打开小程序的情况下,也能从服务器提前拉取数据,当用户打开小程序时可以更快地渲染页面,减少用户等待时间,增强在弱网条件下的可用性。

使用流程

1. 配置数据下载地址

登录小程序 MP 管理后台,进入设置 -> 开发设置 -> 数据周期性更新,点击开启,填写数据下载地址。

2. 设置 TOKEN

第一次启动小程序时,调用 wx.setBackgroundFetchToken() 设置一个 TOKEN 字符串,可以跟用户态相关,会在后续微信客户端向开发者服务器请求时带上,便于给后者校验请求合法性。

示例:

App({  onLaunch() {    wx.setBackgroundFetchToken({      token: 'xxx'    })  }})

3. 微信客户端定期拉取数据

微信客户端会在一定的网络条件下,每隔 12 小时(以上一次成功更新的时间为准)向配置的数据下载地址发起一个 HTTP GET 请求,其中包含的 query 参数如下,数据获取到后会将整个 HTTP body 缓存到本地。

参数类型说明
appidString小程序标识
tokenString前面设置的 TOKEN
timestampNumber时间戳,微信客户端发起请求的时间
query 参数会使用 urlencode 处理
开发者服务器接口返回的数据类型应为字符串,且大小应不超过 256KB,否则将无法缓存数据

4. 读取数据

用户启动小程序时,调用 wx.getBackgroundFetchData() 获取已缓存到本地的数据。

示例:

App({  onLaunch() {    wx.getBackgroundFetchData({      fetchType: 'periodic',      success(res) {        console.log(res.fetchedData) // 缓存数据        console.log(res.timeStamp) // 客户端拿到缓存数据的时间戳      }    })  }})

调试方法

由于微信客户端每隔 12 个小时才会发起一次请求,调试周期性更新功能会显得不太方便。 因此为了方便调试周期性数据,工具提供了下面的调试能力给到开发者。


数据预拉取

预拉取能够在小程序冷启动的时候通过微信后台提前向第三方服务器拉取业务数据,当代码包加载完时可以更快地渲染页面,减少用户等待时间,从而提升小程序的打开速度 。

使用流程

1. 配置数据下载地址

登录小程序 MP 管理后台,进入设置 -> 开发设置 -> 数据预加载,点击开启,填写数据下载地址,只支持 HTTPS 。

2. 设置 TOKEN

第一次启动小程序时,调用 wx.setBackgroundFetchToken() 设置一个 TOKEN 字符串,可以跟用户态相关,会在后续微信客户端向开发者服务器请求时带上,便于给后者校验请求合法性。

示例:

App({  onLaunch() {    wx.setBackgroundFetchToken({      token: 'xxx'    })  }})

3. 微信客户端提前拉取数据

当用户打开小程序时,微信服务器将向开发者服务器(上面配置的数据下载地址)发起一个 HTTP GET 请求,其中包含的 query 参数如下,数据获取到后会将整个 HTTP body 缓存到本地。

参数类型必填说明
appidString小程序标识。
tokenString前面设置的 TOKEN。
codeString用户登录凭证,未设置TOKEN时由微信侧预生成,可在开发者后台调用 auth.code2Session,换取 openid 等信息。
timestampNumber时间戳,微信客户端发起请求的时间
pathString打开小程序的路径。
queryString打开小程序的query。
sceneNumber打开小程序的场景值。
query 参数会使用 urlencode 处理
token和code只会存在一个,用于标识用户身份。
开发者服务器接口返回的数据类型应为字符串,且大小应不超过 256KB,否则将无法缓存数据

4. 读取数据

用户启动小程序时,调用 wx.getBackgroundFetchData() 获取已缓存到本地的数据。

示例:

App({  onLaunch() {    wx.getBackgroundFetchData({      fetchType: 'pre',      success(res) {        console.log(res.fetchedData) // 缓存数据        console.log(res.timeStamp) // 客户端拿到缓存数据的时间戳        console.log(res.path) // 页面路径        console.log(res.query) // query 参数        console.log(res.scene) // 场景值      }    })  }})

调试方法

为了方便调试数据预拉取,工具提供了下面的调试能力给到开发者。


DarkMode 适配指南

微信从iOS客户端 7.0.12、Android客户端 7.0.13 开始正式支持 DarkMode,小程序也从基础库 v2.11.0、开发者工具 1.03.2004271 开始,为开发者提供小程序内的 DarkMode 适配能力。

开启 DarkMode

在app.json中配置darkmode为true,即表示当前小程序已适配 DarkMode,所有基础组件均会根据系统主题展示不同的默认样式,navigation bar 和 tab bar 也会根据下面的配置自动切换。

相关配置

当app.json中配置darkmode为true时,小程序部分配置项可通过变量的形式配置,在变量配置文件中定义不同主题下的颜色或图标,方法如下:

  1. 在app.json中配置themeLocation,指定变量配置文件theme.json路径,例如:在根目录下新增theme.json,需要配置"themeLocation":"theme.json"
  2. 在theme.json中定义相关变量;
  3. 在app.json中以@开头引用变量。

支持通过变量配置的属性:

  • 全局配置的 window 属性与页面配置下的属性navigationBarBackgroundColornavigationBarTextStylebackgroundColorbackgroundTextStylebackgroundColorTopbackgroundColorBottom
  • 全局配置 window.tabBar 的属性colorselectedColorbackgroundColorborderStylelisticonPathselectedIconPath

变量配置文件 theme.json

theme.json用于颜色主题相关的变量定义,需要先在themeLocation中配置theme.json的路径,否则无法读取变量配置。

配置文件须包含以下属性:

属性类型必填描述
lightobject浅色模式下的变量定义
darkobject深色模式下的变量定义

light和dark下均可以key: value的方式定义变量名和值,例如:

{  "light": {    "navBgColor": "#f6f6f6",    "navTxtStyle": "black"  },  "dark": {    "navBgColor": "#191919",    "navTxtStyle": "white"  }}

完成定义后,可在全局配置或页面配置的相关属性中以@开头引用,例如:

// 全局配置{  "window": {    "navigationBarBackgroundColor": "@navBgColor",    "navigationBarTextStyle": "@navTxtStyle"  }}// 页面配置{  "navigationBarBackgroundColor": "@navBgColor",  "navigationBarTextStyle": "@navTxtStyle"}

配置完成后,小程序框架会自动根据系统主题,为小程序展示对应主题下的颜色。

配置示例

app.json(示例省略了主题相关以外的配置项)

{    "window": {        "navigationBarBackgroundColor": "@navBgColor",        "navigationBarTextStyle": "@navTxtStyle",        "backgroundColor": "@bgColor",        "backgroundTextStyle": "@bgTxtStyle",        "backgroundColorTop": "@bgColorTop",        "backgroundColorBottom": "@bgColorBottom"    },    "tabBar": {        "color": "@tabFontColor",        "selectedColor": "@tabSelectedColor",        "backgroundColor": "@tabBgColor",        "borderStyle": "@tabBorderStyle",        "list": [{            "iconPath": "@iconPath1",            "selectedIconPath": "@selectedIconPath1"        }, {            "iconPath": "@iconPath2",            "selectedIconPath": "@selectedIconPath2"        }]    }}

theme.json

{    "light": {        "navBgColor": "#f6f6f6",        "navTxtStyle": "black",        "bgColor": "#ffffff",        "bgTxtStyle": "light",        "bgColorTop": "#eeeeee",        "bgColorBottom": "#efefef",        "tabFontColor": "#000000",        "tabSelectedColor": "#3cc51f",        "tabBgColor": "#ffffff",        "tabBorderStyle": "black",        "iconPath1": "image/icon1_light.png",        "selectedIconPath1": "image/selected_icon1_light.png",        "iconPath2": "image/icon2_light.png",        "selectedIconPath2": "image/selected_icon2_light.png",    },    "dark": {        "navBgColor": "#191919",        "navTxtStyle": "white",        "bgColor": "#1f1f1f",        "bgTxtStyle": "dark",        "bgColorTop": "#191919",        "bgColorBottom": "#1f1f1f",        "tabFontColor": "#ffffff",        "tabSelectedColor": "#51a937",        "tabBgColor": "#191919",        "tabBorderStyle": "white",        "iconPath1": "image/icon1_dark.png",        "selectedIconPath1": "image/selected_icon1_dark.png",        "iconPath2": "image/icon2_dark.png",        "selectedIconPath2": "image/selected_icon2_dark.png",    }}

获取当前系统主题

如果app.json中声明了"darkmode": true,wx.getSystemInfo或wx.getSystemInfoSync的返回结果中会包含theme属性,值为light或dark。

如果app.json未声明"darkmode": true,则无法获取到theme属性(即theme为undefined)。

监听主题切换事件

支持2种方式:

  1. 在App()中传入onThemeChange回调方法,主题切换时会触发此回调
  2. 通过wx.onThemeChange监听主题变化,wx.offThemeChange取消监听

WXSS 适配

WXSS中,支持通过媒体查询 prefers-color-scheme 适配不同主题,与 Web 中适配方式一致,例如:

/* 一般情况下的样式 begin */.some-background {    background: white;}.some-text {    color: black;}/* 一般情况下的样式 end */@media (prefers-color-scheme: dark) {    /* DarkMode 下的样式 start */    .some-background {        background: #1b1b1b;    }    .some-text {        color: #ffffff;    }    /* DarkMode 下的样式 end */}

开发者工具调试

微信开发者工具 1.03.2004271 版本开始已支持 DarkMode 调试,在模拟器顶部可以切换 深色/浅色 模式进行,如图:

darkmode_devtool

Bug & Tip

  1. tip: 需要注意的是,WXSS 中的媒体查询不受app.json中的darkmode开关配置影响,只要微信客户端(iOS 7.0.12、Android 7.0.13)支持 DarkMode,无论是否配置"darkmode": true,在系统切换到 DarkMode 时,媒体查询都将生效。
  2. tip: 主题切换事件需要在配置"darkmode": true时,才会触发。
  3. bug: iOS 7.0.12 在 light 模式中配置 tabBar 的borderStyle为white时可能会出现黑色背景的 bug,后续版本将会修复。


大屏适配指南

目前市面上的用户设备大致可分为小屏的手机端、中屏的平板、大屏的 PC 端三类,而在这三类设备中又会有细小的尺寸差别,也称作屏幕碎片化。

随着小程序能够在越来越多的设备终端上运行,开发者也应该针对不同的屏幕尺寸进行相应的适配。

按照一般的适配原则,结合小程序特点,通常在以下三种情况中需要进行适配:

1. 同一类设备下,尺寸有细微差别

使用小程序提供的 rpx 单位,在尺寸差别不大的情况下对页面布局进行等比缩放。

2. 在允许屏幕旋转的情况下,可分为横屏与竖屏

手机端设置 "pageOrientation": "auto" 或 iPad 上设置 "resizable": true 时会允许屏幕旋转,此时使用 Page 的 onResize 事件或者 wx.onWindowResize 方法可对该操作进行监听,进而判断是使用横屏还是竖屏布局。

3. 不同类设备或者能够自由拖拽窗口的 PC 小程序

小程序目前是基于 Webview 实现,利用CSS 媒体查询可实时监听屏幕尺寸大小,在不同的屏幕下展现不同的 UI 布局,结合Flex 弹性布局、Grid 网格布局便能实现更加响应式的适配方案。

matchMedia - 抽象式媒体查询

小程序基础库基于 window.matchMedia API 新增了一组过程式与定义式接口 match-media 。开发者可以通过 <match-media></match-media> 和 wx.createMediaQueryObserver 来显式地使用媒体查询能力,对于多端适配来说,它有以下优势:

  1. 开发者能够更方便、显式地使用 Media Query 能力,而不是耦合在 CSS 文件中,难以复用。
  2. 能够在 WXML 中结合数据绑定动态地使用,不仅能做到组件的显示或隐藏,在过程式 API 中可塑性更高,例如能够根据尺寸变化动态地添加 class 类名,改变样式。
  3. 能够嵌套式地使用 Media Query 组件,即能够满足局部组件布局样式的改变。
  4. 组件化之后,封装性更强,能够隔离样式、模版以及绑定在模版上的交互事件,还能够提供更高的可复用性。
  5. 浏览器内置 API ,能够在所有基于 Webview 的小程序上使用,兼容性良好。 match-media 具体使用方法可参考相关 API 文档

4. 自适应布局

为了让开发者更好的自适应大屏,小程序提供了 row/col 组件 供开发者使用。

自适应的主要特性是:

  • 整行最多只有 24 份,对于的排列会自动向下换行
  • 每个尺寸设置并不会影响到其它尺寸的布局

设计指引与代码示例

关于如何在设计、用户体验上实现更好的多端适配小程序。

同时我们也提供了多端适配示例小程序 ,基于 row/col 组件 简单实现了常见的适配场景,例如:

  1. 屏幕越大,布局不变,模块左右伸缩

  1. 屏幕越大,内容越多,模块内容换行排列

  1. 屏幕越大,布局改变,模块内容可折叠 / 展现

体验路径:“扩展能力” -> “多端适配(需在PC端体验)”


蓝牙

iOS 微信客户端 6.5.6 版本开始支持,Android 6.5.7 版本开始支持

蓝牙适配器模块生效周期为调用 wx.openBluetoothAdapter 至调用 wx.closeBluetoothAdapter 或小程序被销毁为止。

在小程序蓝牙适配器模块生效期间,开发者才能够正常调用蓝牙相关的小程序 API,并收到蓝牙模块相关的事件回调。

注意

  • 由于系统限制,Android 上获取到的 deviceId 为设备 MAC 地址,iOS 上则为设备 uuid。因此 deviceId 不能硬编码到代码中。
  • 目前不支持在开发者工具上进行蓝牙功能的调试,需要使用真机才能正常调用小程序蓝牙接口。

低功耗蓝牙(BLE)注意事项

  • iOS 上对特征值的 read、write、notify操作,由于系统需要获取特征值实例,传入的 serviceId 与 characteristicId 必须由 wx.getBLEDeviceServices 与 wx.getBLEDeviceCharacteristics 中获取到后才能使用。建议双平台统一在建立连接后先执行 wx.getBLEDeviceServices 与 wx.getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互。


NFC

支持 HCE(基于主机的卡模拟)模式,即将安卓手机模拟成实体智能卡。 支持 NFC 读写,即手机作为读卡器使用。

  • 适用机型:支持 NFC 功能,且系统版本为 Android 5.0 及以上的手机
  • 适用卡范围:符合ISO 14443-4 标准的 CPU 卡
  • 支持 Reader/Writer(读取器/写入器)模式,即支持 NFC 设备读取和/或写入被动 NFC 标签和贴纸。
  • 适用机型:支持 NFC 功能,且系统版本为 Android 5.0 及以上的手机
  • 适用范围:支持NFC-A (ISO 14443-3A)/NFC-B (ISO 14443-3B)/NFC-F (JIS 6319-4)/NFC-V (ISO 15693)/ISO-DEP (ISO 14443-4)标准的读写(部分Android手机)支持MIFARE Classic/MIFARE Ultralight标签的读写支持对NDEF格式的NFC标签上的NDEF数据的读写

基本流程

以往NFC-A卡片写入apdu指令为例

  • 调用wx.getNFCAdapter()获取NFC适配器实例
  • 调用NFCAdapter.onDiscovered(function callback)注册贴卡监听回调
  • 调用NFCAdapter.startDiscovery(Object object)开始监听贴卡
  • 贴卡,onDiscovered回调根据onDiscovered回调res对象的techs字段匹配到卡片支持NFC-A标准通过NFCAdapter.getNfcA()获取NfcA实例
  • 使用NfcA实例进行读写调用NfcA.connect()和NFC卡片建立连接调用NfcA.transceive(Object object)往NFC卡片写入apdu指令并接收卡片返回数据读写完毕,调用NfcA.close()断开连接
  • 调用NFCAdapter.stopDiscovery(Object object)结束监听贴卡


Wi-Fi

在小程序中支持搜索周边的 Wi-Fi,同时可以针对指定 Wi-Fi,传入密码发起连接。

该系列接口为系统原生能力,如需查看「微信连Wi-Fi」能力及配置跳转小程序,请参考文档。

连接指定 Wi-Fi 接口调用时序:

  • Android:startWifi —> connectWifi —> onWifiConnected
  • iOS(仅iOS 11及以上版本支持):startWifi —> connectWifi —> onWifiConnected

连周边 Wi-Fi 接口调用时序:

  • Android:startWifi —> getWifiList —> onGetWifiList —> connectWifi —> onWifiConnected
  • iOS(iOS 11.0及11.1版本因系统原因暂不支持):startWifi —> getWifiList —> onGetWifiList —> setWifiList —> onWifiConnected

注意:

  • Wi-Fi 相关接口暂不可用 wx.canIUse 接口判断。
  • Android 6.0 以上版本,在没有打开定位开关的时候会导致设备不能正常获取周边的 Wi-Fi 信息。


小程序登录

小程序可以通过微信官方提供的登录能力方便地获取微信提供的用户身份标识,快速建立小程序内的用户体系。

登录流程时序

说明:

  1. 调用 wx.login() 获取 临时登录凭证code ,并回传到开发者服务器。
  2. 调用 auth.code2Session 接口,换取 用户唯一标识 OpenID 和 会话密钥 session_key。

之后开发者服务器可以根据用户标识来生成自定义登录态,用于后续业务逻辑中前后端交互时识别用户身份。

注意:

  1. 会话密钥 session_key 是对用户数据进行 加密签名 的密钥。为了应用自身的数据安全,开发者服务器不应该把会话密钥下发到小程序,也不应该对外提供这个密钥。
  2. 临时登录凭证 code 只能使用一次


UnionID 机制说明

如果开发者拥有多个移动应用、网站应用、和公众帐号(包括小程序),可通过 UnionID 来区分用户的唯一性,因为只要是同一个微信开放平台帐号下的移动应用、网站应用和公众帐号(包括小程序),用户的 UnionID 是唯一的。换句话说,同一用户,对同一个微信开放平台下的不同应用,UnionID是相同的。

UnionID获取途径

绑定了开发者帐号的小程序,可以通过以下途径获取 UnionID。

  1. 调用接口 wx.getUserInfo,从解密数据中获取 UnionID。注意本接口需要用户授权,请开发者妥善处理用户拒绝授权后的情况。
  2. 如果开发者帐号下存在同主体的公众号,并且该用户已经关注了该公众号。开发者可以直接通过 wx.login + code2Session 获取到该用户 UnionID,无须用户再次授权。
  3. 如果开发者帐号下存在同主体的公众号或移动应用,并且该用户已经授权登录过该公众号或移动应用。开发者也可以直接通过 wx.login + code2Session 获取到该用户 UnionID ,无须用户再次授权。
  4. 用户在小程序(暂不支持小游戏)中支付完成后,开发者可以直接通过getPaidUnionId接口获取该用户的 UnionID,无需用户授权。注意:本接口仅在用户支付完成后的5分钟内有效,请开发者妥善处理。
  5. 小程序端调用云函数时,如果开发者帐号下存在同主体的公众号,并且该用户已经关注了该公众号,可在云函数中通过 cloud.getWXContext 获取 UnionID。
  6. 小程序端调用云函数时,如果开发者帐号下存在同主体的公众号或移动应用,并且该用户已经授权登录过该公众号或移动应用,也可在云函数中通过 cloud.getWXContext 获取 UnionID。

微信开放平台绑定小程序流程

登录微信开放平台 — 管理中心 — 小程序 — 绑定小程序

img


授权

部分接口需要经过用户授权同意才能调用。我们把这些接口按使用范围分成多个 scope ,用户选择对 scope 来进行授权,当授权给一个 scope 之后,其对应的所有接口都可以直接使用。

此类接口调用时:

  • 如果用户未接受或拒绝过此权限,会弹窗询问用户,用户点击同意后方可调用接口;
  • 如果用户已授权,可以直接调用接口;
  • 如果用户已拒绝授权,则不会出现弹窗,而是直接进入接口 fail 回调。请开发者兼容用户拒绝授权的场景。

获取用户授权设置

开发者可以使用 wx.getSetting 获取用户当前的授权状态。

打开设置界面

用户可以在小程序设置界面(「右上角」 - 「关于」 - 「右上角」 - 「设置」)中控制对该小程序的授权状态。

开发者可以调用 wx.openSetting 打开设置界面,引导用户开启授权。

提前发起授权请求

开发者可以使用 wx.authorize 在调用需授权 API 之前,提前向用户发起授权请求。

scope 列表

scope对应接口描述
scope.userInfowx.getUserInfo用户信息
scope.userLocationwx.getLocation, wx.chooseLocation地理位置
scope.userLocationBackgroundwx.startLocationUpdateBackground后台定位
scope.addresswx.chooseAddress通讯地址
scope.invoiceTitlewx.chooseInvoiceTitle发票抬头
scope.invoicewx.chooseInvoice获取发票
scope.werunwx.getWeRunData微信运动步数
scope.recordwx.startRecord录音功能
scope.writePhotosAlbumwx.saveImageToPhotosAlbum, wx.saveVideoToPhotosAlbum保存到相册
scope.cameracamera 组件摄像头

授权有效期

一旦用户明确同意或拒绝过授权,其授权关系会记录在后台,直到用户主动删除小程序。

最佳实践

在真正需要使用授权接口时,才向用户发起授权申请,并在授权申请中说明清楚要使用该功能的理由。

注意事项

  1. wx.authorize({scope: "scope.userInfo"}),不会弹出授权窗口,请使用 <button open-type="getUserInfo"/>
  2. 需要授权 scope.userLocation、scope.userLocationBackground 时必须配置地理位置用途说明。

后台定位

与其它类型授权不同的是,scope.userLocationBackground 不会弹窗提醒用户。需要用户在设置页中,主动将“位置信息”选项设置为“使用小程序期间和离开小程序后”。开发者可以通过调用wx.openSetting,打开设置页。

background-location


服务端获取开放数据

小程序可以通过各种前端接口获取微信提供的开放数据。考虑到开发者服务端也需要获取这些开放数据,微信提供了两种获取方式:

  • 方式一:开发者后台校验与解密开放数据
  • 方式二:云调用直接获取开放数据(云开发

方式一:开发者后台校验与解密开放数据

微信会对这些开放数据做签名和加密处理。开发者后台拿到开放数据后可以对数据进行校验签名和解密,来保证数据不被篡改。

签名校验以及数据加解密涉及用户的会话密钥 session_key。 开发者应该事先通过 wx.login 登录流程获取会话密钥 session_key 并保存在服务器。为了数据不被篡改,开发者不应该把 session_key 传到小程序客户端等服务器外的环境。

数据签名校验

为了确保开放接口返回用户数据的安全性,微信会对明文数据进行签名。开发者可以根据业务需要对数据包进行签名校验,确保数据的完整性。

  1. 通过调用接口(如 wx.getUserInfo)获取数据时,接口会同时返回 rawData、signature,其中 signature = sha1( rawData + session_key )
  2. 开发者将 signature、rawData 发送到开发者服务器进行校验。服务器利用用户对应的 session_key 使用相同的算法计算出签名 signature2 ,比对 signature 与 signature2 即可校验数据的完整性。

如 wx.getUserInfo的数据校验:

接口返回的rawData:

{  "nickName": "Band",  "gender": 1,  "language": "zh_CN",  "city": "Guangzhou",  "province": "Guangdong",  "country": "CN",  "avatarUrl": "http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"}

用户的 session-key:

HyVFkGl5F5OQWJZZaNzBBg==

用于签名的字符串为:

{"nickName":"Band","gender":1,"language":"zh_CN","city":"Guangzhou","province":"Guangdong","country":"CN","avatarUrl":"http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"}HyVFkGl5F5OQWJZZaNzBBg==

使用sha1得到的结果为

75e81ceda165f4ffa64f4068af58c64b8f54b88c

加密数据解密算法

接口如果涉及敏感数据(如wx.getUserInfo当中的 openId 和 unionId),接口的明文内容将不包含这些敏感数据。开发者如需要获取敏感数据,需要对接口返回的加密数据(encryptedData) 进行对称解密。 解密算法如下:

  1. 对称解密使用的算法为 AES-128-CBC,数据采用PKCS#7填充。
  2. 对称解密的目标密文为 Base64_Decode(encryptedData)。
  3. 对称解密秘钥 aeskey = Base64_Decode(session_key), aeskey 是16字节。
  4. 对称解密算法初始向量 为Base64_Decode(iv),其中iv由数据接口返回。

微信官方提供了多种编程语言的示例代码((点击下载)。每种语言类型的接口名字均一致。调用方式可以参照示例。

另外,为了应用能校验数据的有效性,会在敏感数据加上数据水印( watermark )

watermark参数说明:

参数类型说明
appidString敏感数据归属 appId,开发者可校验此参数与自身 appId 是否一致
timestampInt敏感数据获取的时间戳, 开发者可以用于数据时效性校验

如接口 wx.getUserInfo 敏感数据当中的 watermark:

{    "openId": "OPENID",    "nickName": "NICKNAME",    "gender": GENDER,    "city": "CITY",    "province": "PROVINCE",    "country": "COUNTRY",    "avatarUrl": "AVATARURL",    "unionId": "UNIONID",    "watermark":    {        "appid":"APPID",        "timestamp":TIMESTAMP    }}

注:

  1. 解密后得到的json数据根据需求可能会增加新的字段,旧字段不会改变和删减,开发者需要预留足够的空间

会话密钥 session_key 有效性

开发者如果遇到因为 session_key 不正确而校验签名失败或解密失败,请关注下面几个与 session_key 有关的注意事项。

  1. wx.login 调用时,用户的 session_key 可能会被更新而致使旧 session_key 失效(刷新机制存在最短周期,如果同一个用户短时间内多次调用 wx.login,并非每次调用都导致 session_key 刷新)。开发者应该在明确需要重新登录时才调用 wx.login,及时通过 auth.code2Session 接口更新服务器存储的 session_key。
  2. 微信不会把 session_key 的有效期告知开发者。我们会根据用户使用小程序的行为对 session_key 进行续期。用户越频繁使用小程序,session_key 有效期越长。
  3. 开发者在 session_key 失效时,可以通过重新执行登录流程获取有效的 session_key。使用接口 wx.checkSession可以校验 session_key 是否有效,从而避免小程序反复执行登录流程。
  4. 当开发者在实现自定义登录态时,可以考虑以 session_key 有效期作为自身登录态有效期,也可以实现自定义的时效性策略。

方式二:云调用直接获取开放数据

接口如果涉及敏感数据(如wx.getWeRunData),接口的明文内容将不包含这些敏感数据,而是在返回的接口中包含对应敏感数据的 cloudID 字段,数据可以通过云函数获取。完整流程如下:

1. 获取 cloudID

使用 2.7.0 或以上版本的基础库,如果小程序已开通云开发,在开放数据接口的返回值中可以通过 cloudID 字段获取(与 encryptedData 同级),cloudID 有效期五分钟。

2. 调用云函数

调用云函数时,对传入的 data 参数,如果有顶层字段的值为通过 wx.cloud.CloudID 构造的 CloudID,则调用云函数时,这些字段的值会被替换为 cloudID 对应的开放数据,一次调用最多可替换 5 个 CloudID。

示例:

在小程序获取到 cloudID 之后发起调用:

wx.cloud.callFunction({  name: 'myFunction',  data: {    weRunData: wx.cloud.CloudID('xxx'), // 这个 CloudID 值到云函数端会被替换    obj: {      shareInfo: wx.cloud.CloudID('yyy'), // 非顶层字段的 CloudID 不会被替换,会原样字符串展示    }  }})

在云函数收到的 event 示例:

// event{  // weRunData 的值已被替换为开放数据  "weRunData": {    "cloudID": "xxx",    "data": {      "stepInfoList": [        {          "step": 5000,          "timestamp": 1554814312,        }      ],      "watermark": {        "appid": "wx1111111111",        "timestamp": 1554815786      }    }  },  "obj": {    // 非顶层字段维持原样    "shareInfo": "yyy",  }}

如果 cloudID 非法或过期,则在 event 中获取得到的将是一个有包含错误码、错误信息和原始 cloudID 的对象。过期 cloudID 换取结果示例:

// event{  "weRunData": {    "cloudID": "xxx",    "errCode": -601006,    "errMsg": "cloudID expired."  },  // ...}


获取手机号

获取微信用户绑定的手机号,需先调用wx.login接口。

因为需要用户主动触发才能发起获取手机号接口,所以该功能不由 API 来调用,需用 button 组件的点击来触发。

注意:目前该接口针对非个人开发者,且完成了认证的小程序开放(不包含海外主体)。需谨慎使用,若用户举报较多或被发现在不必要场景下使用,微信有权永久回收该小程序的该接口权限。

使用方法

需要将 button 组件 open-type 的值设置为 getPhoneNumber,当用户点击并同意之后,可以通过 bindgetphonenumber 事件回调获取到微信服务器返回的加密数据, 然后在第三方服务端结合 session_key 以及 app_id 进行解密获取手机号。

注意

在回调中调用 wx.login 登录,可能会刷新登录态。此时服务器使用 code 换取的 sessionKey 不是加密时使用的 sessionKey,导致解密失败。建议开发者提前进行 login;或者在回调中先使用 checkSession 进行登录态检查,避免 login 刷新登录态。

代码示例

<button open-type="getPhoneNumber" bindgetphonenumber="getPhoneNumber"></button>
Page({  getPhoneNumber (e) {    console.log(e.detail.errMsg)    console.log(e.detail.iv)    console.log(e.detail.encryptedData)  }})

返回参数说明

参数类型说明最低版本
encryptedDataString包括敏感数据在内的完整用户信息的加密数据,详细见加密数据解密算法
ivString加密算法的初始向量,详细见加密数据解密算法
cloudIDstring敏感数据对应的云 ID,开通云开发的小程序才会返回,可通过云调用直接获取开放数据,详细见云调用直接获取开放数据基础库 2.8.0

获取得到的开放数据为以下 json 结构:

{    "phoneNumber": "13580006666",    "purePhoneNumber": "13580006666",    "countryCode": "86",    "watermark":    {        "appid":"APPID",        "timestamp": TIMESTAMP    }}
参数类型说明
phoneNumberString用户绑定的手机号(国外手机号会有区号)
purePhoneNumberString没有区号的手机号
countryCodeString区号


生物认证

小程序通过 SOTER 提供以下生物认证方式。

目前暂时只支持指纹识别认证。设备支持的生物认证方式可使用 wx.checkIsSupportSoterAuthentication 查询

调用流程

流程步骤说明

  1. 调用 wx.startSoterAuthentication,获取 resultJSON 和 resultJSONSignature
  2. (可选)签名校验。此处 resultJSONSignature 使用 SHA256withRSA/PSS 作为签名算法进行验签。此公式数学定义如下: bool 验签结果=verify(用于签名的原串,签名串,验证签名的公钥)
  3. 微信提供后台接口用于可信的密钥验签服务,微信将保证该接口返回的验签结果的正确性与可靠性,并且对于 Android root 情况下该接口具有上述特征(将返回是否保证root情况安全性)。

接口地址:

POST http://api.weixin.qq.com/cgi-bin/soter/verify_signature?access_token=%access_token

post 数据内容(JSON 编码):

{"openid":"$openid", "json_string" : "$resultJSON", "json_signature" : "$resultJSONSignature" }

请求返回数据内容(JSON 编码):

// 验证成功返回{"is_ok":true}// 验证失败返回{"is_ok":false}// 接口调用失败{"errcode":"xxx,"errmsg":"xxxxx"}


分享到朋友圈(Beta)

从基础库 2.11.3 开始支持
此功能为beta版,暂仅在Android平台支持

可将小程序页面分享到朋友圈。适用于内容型页面的分享,不适用于有较多交互的页面分享。

设置分享状态

小程序页面默认不可被分享到朋友圈,开发者需主动设置“分享到朋友圈”。页面允许被分享到朋友圈,需满足两个条件:

  1. 首先,页面需设置允许“发送给朋友”。具体参考 Page.onShareAppMessage 接口文档
  2. 满足条件 1 后,页面需设置允许“分享到朋友圈”,同时可自定义标题、分享图等。具体参考 Page.onShareTimeline 接口文档

满足上述两个条件的页面,可被分享到朋友圈。

单页模式

用户在朋友圈打开分享的小程序页面,并不会真正打开小程序,而是进入一个“小程序单页模式”的页面,“单页模式”有以下特点:

  1. “单页模式”下,页面顶部固定有导航栏,标题显示为当前页面 JSON 配置的标题。底部固定有操作栏,点击操作栏的“前往小程序”可打开小程序的当前页面。顶部导航栏与底部操作栏均不支持自定义样式。
  2. “单页模式”默认运行的是小程序页面内容,但由于页面固定有顶部导航栏与底部操作栏,很可能会影响小程序页面的布局。因此,请开发者特别注意适配“单页模式”的页面交互,以实现流畅完整的交互体验。
  3. “单页模式”下,一些组件或接口存在一定限制,详情见下文单页模式下的限制章节

avatar

页面适配

可通过判断场景值等于 1154 的方法来进行页面适配。另外,在单页模式下,可设置顶部导航栏与页面的相交状态,具体参考 navigationBarFit 配置。

还需留意的是,在单页模式下,wx.getSystemInfo 接口返回的 safeArea 为整个屏幕空间。

单页模式下的限制

小程序“单页模式”适用于纯内容展示场景,可实现的交互与接口能力有限,因此存在如下限制:

  1. 页面无登录态,与登录相关的接口,如 wx.login 均不可用;云开发资源需开启未登录访问方可在单页模式下使用,详见未登录模式。
  2. 不允许跳转到其它页面,包括任何跳小程序页面、跳其它小程序、跳微信原生页面
  3. 不允许横屏使用
  4. 若页面包含 tabBar,tabBar 不会渲染,包括自定义 tabBar
  5. 本地存储与小程序普通模式不共用

对于一些会产生交互的组件或接口,在点击后调用时,会弹 toast 提示“请前往小程序使用完整服务”。为达到良好的用户体验,请注意适配单页模式的接口能力,请勿大量使用被禁用的接口或组件。

禁用能力列表:

分类功能点
组件button open-type 、 camera 、 editor 、 form 、 functional-page-navigator 、 live-pusher 、 navigator 、 navigation-bar 、 official-account 、 open-data 、 web-view
路由wx.redirectTo 、 wx.reLaunch 、 wx.navigateTo 、 wx.switchTab 、 wx.navigateBack
界面导航栏 、 Tab Bar
网络mDNS 、 UDP 通信
数据缓存周期性更新
媒体VoIP 、 wx.chooseMedia 、 wx.chooseImage 、 wx.saveImageToPhotosAlbum 、 wx.chooseVideo 、 wx.saveVideoToPhotosAlbum 、 wx.getVideoInfo 、 wx.compressVideo
位置wx.openLocation 、 wx.chooseLocation 、 wx.startLocationUpdateBackground 、 wx.startLocationUpdate
转发wx.getShareInfo 、 wx.showShareMenu 、 wx.hideShareMenu 、 wx.updateShareMenu
文件wx.openDocument
开放接口登录 、 小程序跳转 、 用户信息 、 支付 、 授权 、 设置 、 收货地址 、 卡券 、 发票 、 生物认证 、 微信运动 、 微信红包
设备蓝牙 、 iBeacon 、 Wi-Fi 、 NFC 、 联系人 、 剪贴板 、 电话 、 扫码
广告ad 、 wx.createRewardedVideoAd 、 wx.createInterstitialAd

运营须知

分享朋友圈能力是为了满足纯内容场景的分享诉求,滥用于营销、诱导等行为将会被打击。

  1. 小程序提供的服务中,不得存在滥用分享违规行为。如强制用户分享行为;分享立即获得利益的诱导行为;以及通过明示或暗示的样式来达到诱导分享目的的行为等。详见《微信小程序平台运营规范》
  2. 在“单页模式”下,不得诱导或强制用户点击“打开小程序”,应在“单页模式”中尽可能呈现完整的内容

提示:

  1. 低版本微信客户端打开时,会进入一个升级提示页面
  2. 不支持在小程序页面内直接发起分享
  3. 自定义分享内容时不支持自定义页面路径
  4. 存在 web-view 组件的页面不支持发起分享
  5. 支持打开开发版、体验版,无权限人员进入时页面会提示无权限


转发

获取更多转发信息

通常开发者希望转发出去的小程序被二次打开的时候能够获取到一些信息,例如群的标识。现在通过调用 wx.showShareMenu 并且设置 withShareTicket 为 true ,当用户将小程序转发到任一群聊之后,此转发卡片在群聊中被其他用户打开时,可以在 App.onLaunch 或 App.onShow 获取到一个 shareTicket。通过调用 wx.getShareInfo 接口传入此 shareTicket 可以获取到转发信息。

页面内发起转发

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

通过给 button 组件设置属性 open-type="share",可以在用户点击按钮后触发 Page.onShareAppMessage 事件,相关组件:button。

使用指引

转发按钮,旨在帮助用户更流畅地与好友分享内容和服务。转发,应是用户自发的行为,且在需要时触手可及。开发者在使用时若遵从以下指引,会得到更佳的用户体验。

  1. 含义清晰:明确、一目了然的图形按钮,将为用户减少理解的时间。在我们的资源下载中心,你可以找到这样的按钮素材并直接使用。或者你可以根据自己业务的设计风格,灵活设计含义清晰的按钮的样式。当然,你也可以直接使用带文案的按钮,“转发给好友”,它也足够明确。
  2. 方便点击:按钮点击热区不宜过小,亦不宜过大。同时,转发按钮与其他按钮一样,热区也不宜过密,以免用户误操作。
  3. 按需出现:并非所有页面都适合放置转发按钮,涉及用户隐私的非公开内容,或可能打断用户完成当前操作体验的场景,该功能并不推荐使用。同时,由于转发过程中,我们将截取用户屏幕图像作为配图,因此,需要注意帮助用户屏蔽个人信息。
  4. 尊重意愿:理所当然,并非所有的用户,都喜欢与朋友分享你的小程序。因此,它不应该成为一个诱导或强制行为,如转发后才能解锁某项功能等。请注意,这类做法不仅不被推荐,还可能违反我们的《运营规范》,我们强烈建议你在使用前阅读这部分内容。

以上,我们陈列了最重要的几点,如果你有时间,可以完整浏览《设计指南》,相信会有更多的收获。

提示:

  1. 不自定义转发图片的情况下,默认会取当前页面,从顶部开始,高度为 80% 屏幕宽度的图像作为转发图片。
  2. 转发的调试支持请查看 普通转发的调试支持 和 带 shareTicket 的转发
  3. 只有转发到群聊中打开才可以获取到 shareTickets 返回值,单聊没有 shareTickets
  4. shareTicket 仅在当前小程序生命周期内有效
  5. 由于策略变动,小程序群相关能力进行调整,开发者可先使用 wx.getShareInfo 接口中的群 ID 进行功能开发。
  6. 微信7.0.12开始,支持群主转发小程序时同时把消息设为该群的群待办消息,群待办消息会以气泡形式出现在聊天窗口底部。默认每次转发一个群待办消息,都会生成一个待办消息气泡。通过 wx.updateShareMenu 接口修改toDoActivityId属性可以把多个待办消息聚合为同一个,即转发相同toDoActivityId的群待办消息,只会出现一个待办消息气泡。toDoActivityId需要在转发前通过 updatableMessage.createActivityId 接口创建。

动态消息

从基础库 2.4.0 开始,支持转发动态消息。动态消息对比普通消息,有以下特点:

  1. 消息发出去之后,开发者可以通过后台接口修改部分消息内容。
  2. 消息有对应的提醒按钮,用户点击提醒按钮可以订阅提醒,开发者可以通过后台修改消息状态并推送一次提醒消息给订阅了提醒的用户

消息属性

动态消息有状态、文字内容、文字颜色。

状态

消息有两个状态,分别有其对应的文字内容和颜色。其中状态 0 可以转移到状态 0 和 1,状态 1 无法再转移。

状态文字内容颜色允许转移的状态
0"成员正在加入,当前 {member_count}/{room_limit} 人"#FA9D390, 1
1"已开始"#CCCCCC

状态参数

每个状态转移的时候可以携带参数,具体参数说明如下。

参数类型说明
member_countstring状态 0 时有效,文字内容模板中 member_count 的值
room_limitstring状态 0 时有效,文字内容模板中 room_limit 的值
pathstring状态 1 时有效,点击「进入」启动小程序时使用的路径。对于小游戏,没有页面的概念,可以用于传递查询字符串(query),如 "?foo=bar"
version_typestring状态 1 时有效,点击「进入」启动小程序时使用的版本。有效参数值为:develop(开发版),trial(体验版),release(正式版)

使用方法

一、创建 activity_id

每条动态消息可以理解为一个活动,活动发起前需要通过 updatableMessage.createActivityId 接口创建 activity_id。后续转发动态消息以及更新动态消息都需要传入这个 activity_id。

活动的默认有效期是 24 小时。活动结束后,消息内容会变成统一的样式:

  • 文字内容:“已结束”
  • 文字颜色:#00ff00

二、在转发之前声明消息类型为动态消息

通过调用 wx.updateShareMenu 接口,传入 isUpdatableMessage: true,以及 templateInfo、activityId 参数。其中 activityId 从步骤一中获得。

wx.updateShareMenu({  withShareTicket: true,  isUpdatableMessage: true,  activityId: '', // 活动 ID  templateInfo: {    parameterList: [{      name: 'member_count',      value: '1'    }, {      name: 'room_limit',      value: '3'    }]  }})

三、修改动态消息内容

动态消息发出去之后,可以通过 updatableMessage.setUpdatableMsg 修改消息内容。

低版本兼容

对于不支持动态消息的客户端版本,收到动态消息后会展示成普通消息


收藏

安卓 7.0.15 版本起支持,iOS 暂不支持

小程序菜单增加收藏功能,可收藏某个页面至收藏夹。点开小程序右上角胶囊,点击收藏按钮会触发 Page.onAddToFavorites 事件。


多人音视频对话

用于实现小程序内多人音视频对话的功能。

申请开通

小程序管理后台,「开发」-「接口设置」中自助开通该组件权限。相关接口 wx.joinVoIPChat 和组件 voip-room。

调用流程

开发者仅需提供房间唯一标识,即可加入到指定的房间。传入相同唯一标识的用户,会进到相同的房间。为了保证前端传入的 groupId 可信,wx.joinVoIPChat 接口要求传入签名。详见下文 签名算法。当加入视频房间时,可结合 voip-room 组件显示成员画面。

前端接口

签名算法

生成签名需要传入四个参数:

参数名说明
appId小游戏的 appId
groupId游戏房间的唯一标识,由游戏自己保证唯一
nonceStr随机字符串,长度应小于 128
timeStamp生成这个随机字符串的 UNIX 时间戳(精确到秒)

签名算法为:

signature = hmac_sha256([appId, groupId, nonceStr, timeStamp].sort().join(''), sessionKey)

具体来说,这个算法分为几个步骤:

  1. 对 appId groupId nonceStr timeStamp 四个值表示成字符串形式,按照字典序排序;
  2. 将排好序的四个字符串拼接在一起;
  3. 使用 session_key 作为 key,使用 hmac_sha256 算法对 2 中的结果字符串做计算,所得结果即为 signature

示例:

appId = 'wx20afc706a711eefc'groupId = '1559129713_672975982'nonceStr = '8AP6DT9ybtniUJfb'timeStamp = '1559129714'session_key = 'gDyVgzwa0mFz9uUP7M6GQQ=='str = [appId, groupId, nonceStr, timeStamp].sort().join('') = '1559129713_67297598215591297148AP6DT9ybtniUJfbwx20afc706a711eefc'signature = hmac_sha256('1559129713_67297598215591297148AP6DT9ybtniUJfbwx20afc706a711eefc', sessionKey) = 'b002b824688dd8593a6079e11d8c5e8734fbcb39a6d5906eb347bfbcad79c617'

使用云开发完成签名

在云开发中,无法获取 session_key,但提供了单独的函数 cloud.getVoIPSign 来计算签名。

const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  const signature = cloud.getVoIPSign({    groupId: 'xxx',    timestamp: 123,    nonce: 'yyy'  })  return signature}

人数限制

每个房间最多同时加入 10 个人。

频率限制

对于每个小程序,每天最多允许创建 100000 个房间。当所有人退出房间时,房间即被销毁。此时如果传入之前用过的 groupId 重新加入房间,会被计算为新开一个房间。


打开 App

此功能需要用户主动触发才能打开 APP,所以不由 API 来调用,需要用 open-type 的值设置为 launchApp 的 button 组件的点击来触发。

当小程序从 APP 分享消息卡片的场景打开(场景值 1036,APP 分享小程序文档 iOS / Android) 或从 APP 打开的场景打开时(场景值 1069),小程序会获得打开 APP 的能力,此时用户点击按钮可以打开分享该小程序卡片/拉起该小程序的 APP。即小程序不能打开任意 APP,只能 跳回 APP。

在一个小程序的生命周期内,只有在特定条件下,才具有打开 APP 的能力。

在基础库 < 2.5.1 的版本,这个能力的规则如下:

当小程序从 1069 场景打开时,可以打开 APP。

当小程序从非 1069 的打开时,会在小程序框架内部会管理的一个状态,为 true 则可以打开 APP,为 false 则不可以打开 APP。这个状态的维护遵循以下规则:

  • 当小程序从 App 分享消息卡片(场景值1036)打开时,该状态置为 true。
  • 当小程序从以下场景打开时,保持上一次打开小程序时打开 App 能力的状态:从其他小程序返回小程序(场景值1038)时(基础库 2.2.4 及以上版本支持)小程序从聊天顶部场景(场景值1089)中的「最近使用」内打开时长按小程序右上角菜单唤出最近使用历史(场景值1090)打开时
  • 当小程序从非以上场景打开时,不具有打开 APP 的能力,该状态置为 false。

在基础库 >= 2.5.1 时,这个能力的规则如下:

当小程序从任意场景打开时,会在小程序框架内部会管理的一个状态,为 true 则可以打开 APP,为 false 则不可以打开 APP。这个状态的维护遵循以下规则:

  • 当小程序从 App 分享消息卡片(场景值1036)或从 APP 打开的场景打开时(场景值 1069)打开时,该状态置为 true。
  • 当小程序从以下场景打开时,保持上一次打开小程序时打开 App 能力的状态:从其他小程序返回小程序(场景值1038)时(基础库 2.2.4 及以上版本支持)小程序从聊天顶部场景(场景值1089)中的「最近使用」内打开时长按小程序右上角菜单唤出最近使用历史(场景值1090)打开时
  • 当小程序从非以上场景打开时,不具有打开 APP 的能力,该状态置为 false。

使用方法

小程序端

需要将 button 组件 open-type 的值设置为 launchApp。如果需要在打开 APP 时向 APP 传递参数,可以设置 app-parameter 为要传递的参数。通过 binderror 可以监听打开 APP 的错误事件。

app 端

APP 需要接入 OpenSDK。 文档请参考 iOS / Android

Android 第三方 app 需要处理 ShowMessageFromWX.req 的微信回调,iOS 则需要将 appId 添加到第三方 app 工程所属的 plist 文件 URL types 字段。 app-parameter 的获取方法,参数解析请参考 Android SDKSample 中 WXEntryActivity 中的 onResp 方法以及 iOS SDKSample  中 WXApiDelegate 中的 onResp 方法。

代码示例

<button open-type="launchApp" app-parameter="wechat" binderror="launchAppError">打开APP</button>
Page({  launchAppError (e) {    console.log(e.detail.errMsg)  }})

error 事件参数说明

说明
invalid scene调用场景不正确,即此时的小程序不具备打开 APP 的能力。


小程序订阅消息

功能介绍

消息能力是小程序能力中的重要组成,我们为开发者提供了订阅消息能力,以便实现服务的闭环和更优的体验。

  • 订阅消息推送位置:服务通知
  • 订阅消息下发条件:用户自主订阅
  • 订阅消息卡片跳转能力:点击查看详情可跳转至该小程序的页面

intro

使用说明

步骤一:获取模板 ID

在微信公众平台手动配置获取模板 ID:登录 https://mp.weixin.qq.com 获取模板,如果没有合适的模板,可以申请添加新模板,审核通过后可使用。

intro

步骤二:获取下发权限

详见小程序端消息订阅接口 wx.requestSubscribeMessage

步骤三:调用接口下发订阅消息

详见服务端消息发送接口 subscribeMessage.send


统一服务消息

为便于开发者对用户进行服务消息触达,简化小程序和公众号模板消息下发流程,小程序提供统一的服务消息下发接口。

相关接口


客服消息

在页面使用客服消息

需要将 button 组件 open-type 的值设置为 contact,当用户点击后就会进入客服会话,如果用户在会话中点击了小程序消息,则会返回到小程序,开发者可以通过 bindcontact 事件回调获取到用户所点消息的页面路径 path 和对应的参数 query。

代码示例

<button open-type="contact" bindcontact="handleContact"></button>
Page({    handleContact (e) {        console.log(e.detail.path)        console.log(e.detail.query)    }})

返回参数说明

参数类型说明
pathString小程序消息指定的路径
queryObject小程序消息指定的查询参数

后台接入消息服务

用户向小程序客服发送消息、或者进入会话等情况时,开发者填写的服务器配置 URL (如果使用的是云开发,则是配置的云函数)将得到微信服务器推送过来的消息和事件,开发者可以依据自身业务逻辑进行响应。接入和使用方式请参考消息推送


接收消息和事件

在页面中使用 <button open-type="contact" /> 可以显示进入客服会话按钮。

当用户在客服会话发送消息、或由某些特定的用户操作引发事件推送时,微信服务器会将消息或事件的数据包发送到开发者填写的 URL,如果使用的是云开发,则可以推送到指定的云函数(详情请参考消息推送)。开发者收到请求后可以使用 发送客服消息 接口进行异步回复。

各消息类型的推送JSON、XML数据包结构如下。

文本消息

用户在客服会话中发送文本消息时将产生如下数据包:

XML 格式

<xml>   <ToUserName><![CDATA[toUser]]></ToUserName>   <FromUserName><![CDATA[fromUser]]></FromUserName>   <CreateTime>1482048670</CreateTime>   <MsgType><![CDATA[text]]></MsgType>   <Content><![CDATA[this is a test]]></Content>   <MsgId>1234567890123456</MsgId></xml>

JSON 格式

{  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "text",  "Content": "this is a test",  "MsgId": 1234567890123456}

参数说明

参数说明
ToUserName小程序的原始ID
FromUserName发送者的openid
CreateTime消息创建时间(整型)
MsgTypetext
Content文本消息内容
MsgId消息id,64位整型

图片消息

用户在客服会话中发送图片消息时将产生如下数据包:

XML 格式

<xml>      <ToUserName><![CDATA[toUser]]></ToUserName>      <FromUserName><![CDATA[fromUser]]></FromUserName>      <CreateTime>1482048670</CreateTime>      <MsgType><![CDATA[image]]></MsgType>      <PicUrl><![CDATA[this is a url]]></PicUrl>      <MediaId><![CDATA[media_id]]></MediaId>      <MsgId>1234567890123456</MsgId></xml>

JSON 格式

{  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "image",  "PicUrl": "this is a url",  "MediaId": "media_id",  "MsgId": 1234567890123456}

参数说明

参数说明
ToUserName小程序的原始ID
FromUserName发送者的openid
CreateTime消息创建时间(整型)
MsgTypeimage
PicUrl图片链接(由系统生成)
MediaId图片消息媒体id,可以调用[获取临时素材]((getTempMedia)接口拉取数据。
MsgId消息id,64位整型

小程序卡片消息

用户在客服会话中发送小程序卡片消息时将产生如下数据包:

XML 格式

<xml>  <ToUserName><![CDATA[toUser]]></ToUserName>  <FromUserName><![CDATA[fromUser]]></FromUserName>  <CreateTime>1482048670</CreateTime>  <MsgType><![CDATA[miniprogrampage]]></MsgType>  <MsgId>1234567890123456</MsgId>  <Title><![CDATA[Title]]></Title>  <AppId><![CDATA[AppId]]></AppId>  <PagePath><![CDATA[PagePath]]></PagePath>  <ThumbUrl><![CDATA[ThumbUrl]]></ThumbUrl>  <ThumbMediaId><![CDATA[ThumbMediaId]]></ThumbMediaId></xml>

JSON 格式

{  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "miniprogrampage",  "MsgId": 1234567890123456,  "Title":"title",  "AppId":"appid",  "PagePath":"path",  "ThumbUrl":"",  "ThumbMediaId":""}

参数说明

参数说明
ToUserName小程序的原始ID
FromUserName发送者的openid
CreateTime消息创建时间(整型)
MsgTypeminiprogrampage
MsgId消息id,64位整型
Title标题
AppId小程序appid
PagePath小程序页面路径
ThumbUrl封面图片的临时cdn链接
ThumbMediaId封面图片的临时素材id

进入会话事件

用户在小程序“客服会话按钮”进入客服会话时将产生如下数据包:

XML 格式

<xml>    <ToUserName><![CDATA[toUser]]></ToUserName>    <FromUserName><![CDATA[fromUser]]></FromUserName>    <CreateTime>1482048670</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[user_enter_tempsession]]></Event>    <SessionFrom><![CDATA[sessionFrom]]></SessionFrom></xml>

JSON 格式

{  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "event",  "Event": "user_enter_tempsession",  "SessionFrom": "sessionFrom"}

参数说明

参数说明
ToUserName小程序的原始ID
FromUserName发送者的openid
CreateTime事件创建时间(整型)
MsgTypeevent
Event事件类型,user_enter_tempsession
SessionFrom开发者在客服会话按钮设置的 session-from 属性

发送客服消息

当用户和小程序客服产生特定动作的交互时(具体动作列表请见下方说明),微信将会把消息数据推送给开发者,开发者可以在一段时间内(目前为 48 小时)调用客服接口,通过调用 发送客服消息接口 来发送消息给普通用户。此接口主要用于客服等有人工消息处理环节的功能,方便开发者为用户提供更加优质的服务。

目前允许的动作列表如下,不同动作触发后,允许的客服接口下发消息条数和下发时限不同。

用户动作允许下发条数限制下发时限
用户发送消息5 条48 小时

转发客服消息

如果小程序设置了消息推送,普通微信用户向小程序客服发消息时,微信服务器会先将消息 POST 到开发者填写的 URL 上,如果希望将消息转发到网页版客服工具,则需要开发者在响应包中返回 MsgType 为 transfer_customer_service 的消息,微信服务器收到响应后会把当次发送的消息转发至客服系统。

用户被客服接入以后,客服关闭会话以前,处于会话过程中时,用户发送的消息均会被直接转发至客服系统。当会话超过 30 分钟客服没有关闭时,微信服务器会自动停止转发至客服,而将消息恢复发送至开发者填写的 URL 上。

用户在等待队列中时,用户发送的消息仍然会被推送至开发者填写的 URL 上。

这里特别要注意,只针对微信用户发来的消息才进行转发,而对于其他事件(比如用户从小程序唤起客服会话)都不应该转发,否则客服在客服系统上就会看到一些无意义的消息了。

消息转发到网页版客服工具

开发者只要在响应包中返回 MsgType 为 transfer_customer_service 的消息,微信服务器收到响应后就会把当次发送的消息转发至客服系统。

如果是使用自有服务器接收的消息推送,则需返回如下格式的 XML 数据:

<xml>    <ToUserName><![CDATA[touser]]></ToUserName>    <FromUserName><![CDATA[fromuser]]></FromUserName>    <CreateTime>1399197672</CreateTime>    <MsgType><![CDATA[transfer_customer_service]]></MsgType></xml>

参数说明

参数是否必须描述
ToUserName接收方帐号(收到的OpenID)
FromUserName开发者微信号
CreateTime消息创建时间 (整型)
MsgTypetransfer_customer_service

如果是使用云函数接收的消息推送,则需在云函数被客服消息触发后返回同样格式的 JSON 数据:

// ...exports.main = async (event, context) => {  // 判断处理客服消息 ...  // 最后返回 JSON  return {    MsgType: 'transfer_customer_service',    ToUserName: 'touser',    FromUserName: 'fromuser',    CreateTime: parseInt(+new Date / 1000),  }}

客服输入状态

开发者可通过调用 客服输入状态接口,返回客服当前输入状态给用户。

  1. 此接口需要客服消息接口权限。
  2. 如果不满足发送客服消息的触发条件,则无法下发输入状态。
  3. 下发输入状态,需要客服之前 30 秒内跟用户有过消息交互。
  4. 在输入状态中(持续 15 秒),不可重复下发输入态。
  5. 在输入状态中,如果向用户下发消息,会同时取消输入状态。

在客服消息中使用临时素材

开发者可在接收和发送客服消息的过程中获取或上传临时素材。

获取临时素材

接收到用户消息之后,可通过 获取临时素材接口 获取消息中的临时素材

上传临时素材

通过 上传临时素材接口 可以上传临时素材,并在 发送消息接口 中使用。


位置消息

微信客户端 7.0.9 及以上版本支持,iOS 暂不支持

为了让用户更便 捷地使用小程序的打车服务,我们在位置消息详情页的菜单中,新增了打车小程序入口。

  1. 打开聊天中的位置消息,点击详情页右下角绿色按钮,菜单中会展示符合条件的打车小程序,用户可以直接发起目的地为该位置的打车服务。
  2. 小程序的注册类目为“打车(网约车)”,且有用户最近使用的记录,才可以出现在该菜单中。
  3. 在此处点击打开小程序后,需要直接进入到发起打车页面。

1. 位置消息入口声明

开发者需要在全局配置app.json声明支持从位置消息入口进入小程序。

配置示例:

"entranceDeclare": {    "locationMessage": {        "path": "pages/index/index",        "query": "foo=bar"    }}

配置项

属性类型必填描述最低版本
entranceDeclareObject入口声明信息7.0.9

entranceDeclare参数列表

属性类型必填描述最低版本
locationMessageObject声明“位置消息”场景进入小程序的启动页面7.0.9

locationMessage参数列表

属性类型必填描述最低版本
pathstring启动页路径,必须是在pages中已经定义7.0.9
querystring启动页参数7.0.9

2. 从启动参数获取位置信息

示例代码:

//app.jsApp({  onLaunch: function (options){    console.log(options)    var scene = options.scene     if (scene == 1146) { // 位置消息场景值      var location = options.locationInfo      var x = location.latitude      var y = location.longitude      var name = location.name    }  },})

Object 启动参数

属性类型描述
scenenumber启动小程序的场景值,“位置消息”的启动场景值为1146
locationInfoObject特殊场景的启动信息

locationInfo 的结构

属性类型描述
latitudenumber纬度,范围为 -90~90,负数表示南纬
longtitudenumber经度,范围为 -180~180,负数表示西经
namestringPOI名称

3. 工具调试

Nightly v1.02.1912062 版本已支持条件编译增加位置消息入口。选择场景值 1146: 位置消息中用小程序打车,传入POI点名称和经纬度信息后可用真机预览调试。


卡券

说明

小程序卡券接口支持在小程序中领取/查看/使用公众号 AppId 创建的会员卡、票、券(含通用卡)。更多使用方法可参考 小程序&卡券打通

使用条件

目前只有认证小程序才能使用卡券接口,可参考 指引 进行认证。

接口

小程序内可以通过 wx.addCard 接口给用户添加卡券。通过 wx.openCard 让用户选择已有卡券。


会员卡组件

开发者可以在小程序内调用该接口拉起会员开卡组件,方便用户快速填写会员注册信息并领卡。该接口拉起开卡组件无须提前将开卡组件和发起小程序绑定至同一个公众号,开发者直接调用即可。

调用前开发者须完成以下步骤:

  1. 创建一张微信会员卡并设置为一键激活模式;
  2. 设置开卡字段;
  3. 获取开卡组件参数;

详情查看会员开卡组件介绍:会员开卡组件

参数说明

参数名类型是否必填参数说明
appIdString填写 wxeb490c6f9b154ef9,固定为此appid
extraDataObject开卡组件参数,由第3步获取,包含以下三个参数
encrypt_card_idString加密 card_id,传入前须 urldecode
outer_strString会员卡领取渠道值,会在卡券领取事件回传给商户
bizString商户公众号标识参数,传入前须 urldecode
successFunction接口调用成功的回调函数
failFunction接口调用失败的回调函数
completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

返回参数

参数名类型参数说明
errMsgString调用结果

示例代码

wx.navigateToMiniProgram({  appId: 'wxeb490c6f9b154ef9', //固定为此 appid,不可改动  extraData: data, // 包括 encrypt_card_id, outer_str, biz三个字段,须从 step3 中获得的链接中获取参数  success: function() {  },  fail: function() {  },  complete: function() {  }})

navigateToMiniProgram接口即将废弃,新版本中请使用navigator组件来使用此功能

<navigator target="miniProgram" app-id="wxeb490c6f9b154ef9" extra-data="{{data}}">会员卡开卡</navigator>

返回说明

在 App.onShow 里判断从会员开卡小程序返回的数据data

  1. 判断 data.referrerInfo.appId 是否为开卡小程序 appId wxeb490c6f9b154ef9,如果不是则中止判断
  2. 判断是否有 data.referrerInfo.extraData 是否有数据,如果没有,表示用户未激活直接左滑/点返回键返回,或者用户已经激活
  3. 若用户激活成功,可以从 data.referrerInfo.extraData 中获取 activate_ticket,card_id,code 参数用于下一步操作

提示:

  1. 在开发者工具上调用此 API 并不会真实的跳转到另外的小程序,但是开发者工具会校验本次调用跳转是否成功详情
  2. 开发者工具上支持被跳转的小程序处理接收参数的调试详情
  3. 开卡组件是使用wx.navigateToMiniProgram开发的官方组件,跳转时无须绑定同一个公众号,直接调用即可


获取小程序码

通过后台接口可以获取小程序任意页面的小程序码,扫描该小程序码可以直接进入小程序对应的页面,所有生成的小程序码永久有效,可放心使用。 我们推荐生成并使用小程序码,它具有更好的辨识度,且拥有展示“公众号关注组件”等高级能力。 生成的小程序码如下所示:

可以使用开发工具 1.02.1803130 及以后版本通过二维码编译功能调试所获得的二维码

为满足不同需求和场景,这里提供了两个接口,开发者可挑选适合自己的接口。

获取小程序二维码(不推荐使用)

通过后台接口可以获取小程序任意页面的小程序二维码,生成的小程序二维码如下所示:

  • 接口 C:适用于需要的码数量较少的业务场景
    • 生成二维码,可接受 path 参数较长,生成个数受限,数量限制见 注意事项。

      获取小程序码(一物一码)

      微信一物一码 支持生成小程序码。微信通过“一物一码”接口发放的二维码相比较普通链接二维码更安全、支持更小的印刷面积,支持跳转到指定小程序页面,且无数量限制。

      注意事项

      1. 接口只能生成已发布的小程序的二维码
      2. 接口 A 加上接口 C,总共生成的码数量限制为 100,000,请谨慎调用。
      3. 接口 B 调用分钟频率受限(5000次/分钟),如需大量小程序码,建议预生成。



    数据分析接口

    开发者通过数据分析接口,可获取到小程序的各项数据指标,便于进行数据存储和整理。数据分析详细功能介绍及指标解释参见数据分析文档

    相关接口


    附近的小程序

    概述

    附近的小程序 API,提供给需快速批量创建附近地点的小程序开发者使用,使用前请先调高附近地点额度。 调高附近地点额度申请方式如下:

    下载 《调高地点额度申请表》,填写后发送至 placeofminiprogram@qq.com。

    邮件主题为:“帐号名称”申请调高附近地点额度。审核通过后可调高额度。

    管理接口


    快递接口(商家必看)

    1. 产品介绍

    快递接口是微信官方为小程序提供的免费物流接口。接入后,你可使用本接口在多家快递公司获取电子面单单号等信息,再通过热敏打印机完成电子面单打印,即可将快件交给快递公司上门揽收。

    2. 接入快递接口有什么好处

    可批量生成电子面单本接口已对接多家快递公司下单接口,使用本接口可在各快递公司批量生成电子面单;

    可回传物流轨迹给你经由快递接口下的单,微信会将物流轨迹返回给你,便于你实时掌握快件运输路径;

    用户可收到物流通知经由快递接口下的单,微信官方会通过服务通知推送快件状态给用户,提升用户体验;

    完全免费的官方接口快递接口为微信官方接口,统一对接多家物流公司,服务稳定,免费开放。

    增加用户回流小程序入口接入快递接口后,用户可通过两个方式回访你的小程序: 

    3.目前支持的快递公司


    4. 如何使用物流助手

    前往微信公众平台→【物流助手】→【去接入】查看接入流程指引 


    步骤1:绑定签约的快递网点账号

    在微信公众平台-小程序管理后台,点击【物流助手】→【去接入】→【去绑定】,选择和你签约过的物流公司,输入和网点签约时分配给你的账号密码,提交绑定; 


    绑定说明

    (1) 若当前无账号密码,请先线下联系物流公司网点完成签约获得账号和密码,再进行绑定;(2) 上述绑定账号即为调用快递接口Api下单时,选择物流公司后需填写的Bizid;(3) 若事先没有和物流公司签约,准备发散单,则无需在该页面绑定物流公司,调用物流接口下单时填写现付的Bizid即可,下单成功后系统会通知快递员上门取件,运费现结。目前两家物流公司支持下散单,对应Bizid如下:

    快递公司名称快递公司ID现付的BizID
    顺丰速运SFSF_CASH
    德邦快递DBDB_CASH

    步骤2:对接快递接口(商家必看)Api

    (1)查看接口文档

    (2)开发接口文档:你可自行开发或授权服务商开发,遇到问题可前往微信开放社区提问;

    (3)测试下单:自行填写测试的收发货人信息和商品信息,看是否可成功调用本接口下单、成功生成电子面单、获取面单数据、打印面单和接收服务通知,全流程走通则说明接口已调通。

    步骤3:打印电子面单

    用快递接口Api下单后,可选择以下任一方式打印电子面单

    • 使用微信物流助手对接的第三方打单软件打印面单,当前已支持的第三方打单软件为: 快递管家 点击获取对接指引更多第三方持续对接中,请期待
    • 使用物流公司接口或收件员上门打印电子面单;
    • 使用 getOrder 拉取电子面单 html,使用热敏打印机打印(可能存在格式兼容问题,需调试);
    • 使用 getOrder 拉取电子面单的waybill_data,自行构造面单并打印(可能存在格式兼容问题,需调试);
    • 安装使用微信打单PC软件:目前支持 Windows XP 及以上版本。点此下载

    步骤4:快递员上门揽件

    快递员上门揽件后,商家即可通过物流助手Api接收物流轨迹,微信会给用户推送已揽件、派件中、已签收/签收异常的服务通知,便于用户了解运单轨迹。


    附录:快递接口流程图


    微信物流助手(快递侧)

    物流助手,帮助有物流需求的开发者,快速高效对接多家物流公司。对接后用户可通过微信服务通知接收实时物流状态,提升用户体验。

    产品优势

    1. 承接微信生态订单:通过微信统一接口,一次性服务微信生态内有寄件需求的商户。
    2. 提升用户回访:关键物流状态会通过微信服务通知发送给用户,用户点击后可回访快递公司小程序查看该订单的物流状态或进行后续操作。

    接入说明

    目前物流助手采用定向邀请方式接入物流公司。

    接入准备

    1. 小程序

    用户收到轨迹更新消息后,可以间接跳转到快递小程序的轨迹详情页。至少需要提供两个页面:

    1. 快递轨迹详情页,路径可以参考pages/info/info?from=wx&no=12345678901234。微信做跳转时,会传入运单号。
    2. 快递投诉页面

    2. 小程序事件服务

    事件服务用于接收微信的推送,目前有审核商户、查询余额、下单、取消运单等事件。

    3. 面单模板和示例

    标注各个区域的尺寸、字号等。可参考模板示例

    相关接口

    相关事件


    物流助手-打单软件

    介绍

    商户可以通过打单软件,自助打印面单

    使用说明

    1. 通过 updatePrinter API 更新打印员。
    2. 打印员扫码登录、选择商户。
    3. 配置热敏打印机(PC端需安装打印机驱动,并选择203dpi分辨率)。
    4. 拉取面单,打印需要的面单;或启用自动打印,新订单下单成功即会自动打印。

    最新版本下载地址

    Windows

    支持 Windows XP 及以上版本。

    更新日志

    v1.0.0 (2019.01.16)

    1. 支持打印员扫码登录。
    2. 支持不同快递配置独立打印机。
    3. 支持手动拉取订单,保存或打印面单。
    4. 支持自动拉取订单、自动打印面单。

    其它打印方式

    你也可以使用微信物流助手对接的第三方打单软件打印面单,当前已支持的第三方打单软件为:


    常见问题

    问题1. 快递接口是什么?

    快递接口是微信官方提供的免费物流接口工具,帮助有物流需求的开发者快速高效对接多家物流公司。

    问题2. 使用快递接口有什么好处?

    商家通过本接口可调用各物流公司电子面单接口批量下单、打印电子面单和获取物流轨迹,减少逐一对接物流公司的成本,提高物流效率;用户通过你的小程序下单后,微信会通过服务通知告知用户关键物流动态,包括快递公司已揽件、快件派件中、快件已签收和运单异常四种状态,提升用户物流体验。

    问题3. 快递接口需要收费吗?

    快递接口是微信官方提供的基础能力,是完全免费的。

    问题4. 如何使用快递接口服务?

    前往微信公众平台→【物流助手】→【去接入】查看接入流程指引 


    步骤1:绑定签约的快递网点账号


    在微信公众平台-小程序管理后台,点击【物流助手】→【去接入】→【去绑定】,选择和你签约过的物流公司,输入和网点签约时分配给你的账号密码,提交绑定; 


    绑定说明


    (1) 若当前无账号密码,请先线下联系物流公司网点完成签约获得账号和密码,再进行绑定;(2) 上述绑定账号即为调用快递接口Api下单时,选择物流公司后需填写的Bizid;(3) 若事先没有和物流公司签约,准备发散单,则无需在该页面绑定物流公司,调用物流接口下单时填写现付的Bizid即可,下单成功后系统会通知快递员上门取件,运费现结。目前有三家物流公司支持下散单,对应Bizid如下:

    快递公司名称快递公司ID现付的BizID
    顺丰速运SFSF_CASH
    德邦快递DBDB_CASH

    步骤2:对接快递接口(商家必看)Api


    (1)查看接口文档

    (2)开发接口文档:你可自行开发或授权服务商开发,遇到问题可前往微信开放社区提问;

    (3)测试下单:自行填写测试的收发货人信息和商品信息,看是否可成功调用本接口下单、成功生成电子面单、获取面单数据、打印面单和接收服务通知,全流程走通则说明接口已调通。

    步骤3:打印电子面单用快递接口Api下单后,可选择以下任一方式打印电子面单

    安装微信打单PC软件:目前支持 Windows XP 及以上版本。点此下载
    • 使用物流公司接口或收件员上门打印电子面单;
    • 使用 getOrder 拉取电子面单 html,使用热敏打印机打印(可能存在格式兼容问题,需调试);
    • 使用 getOrder 拉取电子面单的waybill_data,自行构造面单并打印(可能存在格式兼容问题,需调试);

    步骤4:快递员上门揽件



    快递员上门揽件后,商家即可通过快递接口Api接收物流轨迹,微信会给用户推送已揽件、派件中、已签收/签收异常的服务通知,便于用户了解运单轨迹。



    问题5. 我此前没有和快递公司签约,怎么使用快递接口?

    如果你希望和快递公司签约,可先线下和发货仓附近的物流网点签约,拿到签约的账号和密码后再使用微信快递接口服务;

    若事先没有和物流公司签约,可以发现付单,调用物流接口下单时填写现付的Bizid即可(无需填写密码),下单成功后通知快递员上门取件,运费现结。目前三家物流公司支持下散单,对应Bizid如下:

    快递公司名称快递公司ID现付的BizID
    顺丰速运SFSF_CASH
    德邦快递DBDB_CASH

    问题6. 我已经在某家快递网点购买了大量的快递单号,如何使用快递接口?

    你可以在微信公众平台小程序后台-【物流助手】中,绑定该网点合作账号和密码,下单时即可扣减该物流公司账号内的预充值账号。

    问题7. 快递费怎么结算?

    快递接口帮助商户在信息流层面对接物流公司,具体的运单费用取决于你与快递公司签约的价格。

    问题8. 我在小程序后台绑定了快递公司,为什么没有办法下单?

    绑定快递公司后,你需要进行快递接口文档开发,才可完整使用快递接口服务,[接口文档] (https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/express/getallaccount.html "接口文档")

    问题9. 目前支持哪些快递公司?

    目前支持的公司如下,更多快递公司持续接入中,请期待。

    问题10. 目前所有微信内的订单都可以使用快递接口吗?

    当前可支持小程序内的订单(小游戏除外),后续将陆续开放公众号、H5的订单,请期待。

    问题11. 用快递接口下的单,快递员就会上门来揽件吗?

    快递接口可帮助你批量下单和打印面单。快递员上门的时间若与你此前有约定,则继续按照约定上门揽件,若此前没有约定,请和发件网点的快递员联系上门揽件。

    问题12. 打印电子面单必须使用快递接口提供的打单软件吗?

    优先推荐使用官方打单软件,可更好兼容各家物流公司格式要求,此外也可选择物流公司上门打单。 若需使用热敏打印机或自行构造面单并打印,可能会存在格式兼容问题,请调试后再使用。

    你也可以使用微信物流助手对接的第三方打单软件打印面单,当前已支持的第三方打单软件为:

    问题13. 开发过程中遇到问题怎么办?

    请前往微信开发者社区提问,我们会第一时间解答你的问题。


    网络快递沙盒环境指引

    为了方便商家接入自测,我们提供了测试的沙盒环境,商户可以通过下面的流程来模拟下单,修改订单状态,体验服务通知。

    接入须知

    1. 此环境只能用于测试下单,禁止用于其它用途。
    2. 为了防止骚扰用户,openid只能配置为小程序的管理员,运营者或者开发者
    3. 下单调用次数有限制,每天不能超时10次
    4. 只能使用以下测试信息进行测试!!!测试运力delivery_id="TEST"测试商户biz_id="test_biz_id"服务类型service.service_type=1服务类型service.service_name="test_service_name"

    测试流程

    1. 商户调用微信平台提供的api接口进行下单,查询订单,取消订单等操作
    2. 调用模拟更新订单接口来改变订单状态,收件人将收到相应的揽件单,派送,配送完成通知


    联系我们

    开发过程中遇到任何问题,请前往微信开放社区提问。提问时,建议标题以【物流助手】开头,我们会第一时间解答你的疑问。


    微信物流助手(快递侧)

    物流助手,帮助有物流需求的开发者,快速高效对接多家物流公司。对接后用户可通过微信服务通知接收实时物流状态,提升用户体验。

    产品优势

    1. 承接微信生态订单:通过微信统一接口,一次性服务微信生态内有寄件需求的商户。
    2. 提升用户回访:关键物流状态会通过微信服务通知发送给用户,用户点击后可回访快递公司小程序查看该订单的物流状态或进行后续操作。

    接入说明

    目前物流助手采用定向邀请方式接入物流公司。

    接入准备

    1. 小程序

    用户收到轨迹更新消息后,可以间接跳转到快递小程序的轨迹详情页。至少需要提供两个页面:

    1. 快递轨迹详情页,路径可以参考pages/info/info?from=wx&no=12345678901234。微信做跳转时,会传入运单号。
    2. 快递投诉页面

    2. 小程序事件服务

    事件服务用于接收微信的推送,目前有审核商户、查询余额、下单、取消运单等事件。

    3. 面单模板和示例

    标注各个区域的尺寸、字号等。可参考模板示例

    相关接口

    相关事件


    即时配送接口(商家查看)

    1. 概述

    即时配送接口,微信官方免费接口,旨在解决餐饮、生鲜、超市等小程序的外卖配送需求。接入后小程序商家可通过统一的接口获得多家配送公司的配送服务,提高经营效率。

    2. 接入有什么好处

    满足多品类配送需求可满足餐饮、生鲜、商超等多品类的配送需求

    接口完全免费即时配送接口是官方提供的基础能力,完全免费开放

    提升用户收货体验配送详情将通过微信服务通知下发给用户,提升收货体验。服务通知包括骑手已接单,骑手已取货、配送中,配送完成和配送异常四种状态

    统一对接节约成本本接口已统一对接多家配送公司下单接口,可直接生成配送单

    增加用户回访小程序入口配送详情的服务通知可跳转商家小程序,提升用户回访率  

    640

    3. 支持的配送公司

    hMoZQW4FiEmmm3uHSmtgVxDv7VNbS1FW-XoJ7X5Xvf4woN77msehMXVwQ6Xj-nJj51gXUzCV1bOx1dOvfBBWUQ

    4. 对接流程

    前提:商家需先和配送公司已达成合作关系,签约了账号才可使用本接口下单。例如:选择闪送下单,需事先和闪送沟通,在闪送创建一个合作账号以后,再来对接微信即时配送Api。

    步骤1:登录微信公众平台,授权绑定配送公司的签约账号,流程拆解为:

    (1)商家登录微信公众平台,点击右侧菜单【物流助手】——点击【即时配送】tab——去接入;(2)选择已经有合作账号的配送公司,如合作公司为闪送,跳转闪送的授权登录页面,输入在闪送的合作账号和密码后,授权登录;(3)合作的运力公司返回授权结果,商家后续即可使用该授权过的合作账号下单。

    步骤2:对接即时配送Api(商家查看),预计需要2-3天

    (1)查看接口文档(2)开发接口文档:你可自行开发或授权服务商开发,遇到问题可前往微信开放社区提问;

    步骤3:测试联调

    我们提供了稳定的沙盒环境供你开发过程进行调试,请先在沙盒环境调试完毕后再正式调用接口发单,测试指引需补充。

    步骤4:上线发单

    调试通过后即可上线,骑手接单后,你和用户均可接收配送详情的推送。


    版本说明

    • 2019.9.2 配送公司信息新增关于收取件码的规则 预下配送单接口新增各家配送公司返回字段的说明 预下配送单下配送单接口expected_delivery_time number 、expected_finish_time number、expected_pick_time number参数说明修订
    • 2019年8月11日 达达上线
    • 2019年7月23日 即时配送接口上线,支持已和配送公司签约的商户下单


    配送公司信息

    1. 配送公司基础信息

    配送公司配送公司ID配送服务代码获取Appkey和Appsecret的方式获取门店编号(shop_no)的方式
    顺丰同城急送SFTC不填第1步:登录顺丰同城开放平台
    第2步:点击顶部导航条的“开发者中心”
    第3步:Appkey即开发者ID,Appsecret 即密钥
    商家在入驻顺丰同城急送时时提供的门店编号
    闪送SS1 (闪送专送)第1步:打开闪送商家版官网
    第2步:登录账号
    第3步:点击左侧导航栏->基本设置->AppKey授权
    第4步:即可查看Appkey(开发者ID),Appsecret(密钥)
    商家在入驻闪送时提供的门店编号
    美团配送MTPS4002(飞速达:实时接单,45分钟内完成配送)

    4011(快速达:实时接单,60分钟内完成配送)

    4012(及时达:实时接单,120分钟内完成配送)

    4013(集中送:商家集中备货,固定时间推送订单,骑手上门取货后120分钟内完成配送)
    第1步:打开美团配送开放平台
    第2步:登录合作方账号
    第3步:点击左侧导航商户管理->开发管理
    第4步:获取线上环境Appkey(开发者ID)和AppSecret(密钥)
    商家在入驻美团配送时提供的门店编号
    达达DADA不填点击这里查看指引商家在入驻达达时提供的门店编号

    2. 配送公司业务规则说明

    配送公司多门店shop_no多门店发件人地址直拿直送保价规则收取件码规则加小费规则订单取消规则
    顺丰同城急送必传必传不支持,不填支持保价,需提前在顺丰同城急送系统中配置支持收取货码,支持微信接口传入,下单时返回。
    骑手接单后顺丰同城会短信下发取货码给商家,取货后短信下发收货码给收货人
    不支持加小费配送完成前任意节点可取消配送单
    闪送必传必传支持,全部为直拿直送不支持支持收取货码,以商家在闪送后台的开关设置状态为准。
    骑手接单后闪送会短信下发取货码给商家,取货后短信下发收货码给收货人。
    支持加小费
    小费规则:骑手接单前可加小费,需按固定档位加小费,档位为2、3、5、10、15、20、50、100;
    配送完成前任意节点可取消配送单
    美团配送必传不传不支持,不填支持保价,需线下和美团配送签订保价合同不支持收取货码不支持加小费配送完成前任意节点可取消配送单
    达达必传不传支持,选填支持仅支持收货码,支持微信接口传入,下单时返回。
    骑手取货后达达会短信下发给收货人
    支持加小费
    小费规则:可以对待接单状态的订单增加小费。订单的小费,以最新一次加小费动作的金额为准,故下一次增加小费额必须大于上一次小费额。(单位:元,精确小数点后一位)
    骑手取货前可以取消


    开发必读

    商家接入准备

    1. 小程序进行微信认证
    2. 开通事件推送,设置事件地址:登录小程序后台,开发->开发设置->消息推送->启用
    3. 消息加密方式使用安全模式,数据格式选JSON
    4. 如果授权给第三方,则不需要步骤2
    5. 在配送公司注册帐号,并在小程序后台进行授权绑定

    名称解释

    1. appkey: 一般为商家在登录配送公司开放平后分配的相应的appkey值
    2. AppSecret: 一般为商家在登录配送公司开放平后分配的相应的秘钥
    3. shopid:微信平台字段,对应配送公司的appkey
    4. shop_no:商家对不同门店进行的编号,需要在配送公司系统有过登记,比如商家自己门店系统中有100个门店,编号是1-100,在顺丰同城的系统中有登记过这100个门店,且在顺丰同城登记的编号也是1-100,那么下单的时候传shop_no=1,就是编号为1 的门店下的配送单
    5. shop:下单请求的一个字段,商家信息,会展示到物流通知消息中,如下图所示640 (1)
    6. 下单请求的取货码和收货码:取货码是指骑手在商家这里取货时,商家出示取货码,骑手才能完成取货;收货码指骑手送达给用户时,用户出示收货码,骑手才算配送完成。商家可在配送公司开放平台设置是否需要开启取货码和收货码

    调用api接口说明

    1. 编码方式:UTF-8
    2. 数据格式:JSON
    3. 提交方式:POST
    4. 下单需要使用绑定的shopid和AppSecret,其中shopid即配送公司帐号的appkey,AppSecret即配送公司帐号对应的秘钥
    5. resultcode错误码和resultmsg错误描述由运力方定义,微信侧负责透传,只统一定义code=0表示成功
    6. 除了平台本身的加解密和签名,和订单相关的请求还需要带上运力侧签名delivery_sign,签名规则为
    7. 如果接口请求里有字段shop_order_id ,则delivery_sign=SHA1(shopid + shop_order_id + AppSecret),其中shopid对应运力侧的appkey,shop_order_id对应订单id,AppSecret即配送公司帐号对应的秘钥
    8. 如果请求里没有字段shop_order_id ,则delivery_sign=SHA1(shopid + AppSecret),其中shopid对应运力侧的appkey,AppSecret即配送公司帐号对应的秘钥
    9. 示例:shopid=“test_shop_id”,shop_order_id =“test_shop_order_id”, AppSecret=“test_app_secrect”,则delivery_sign=“a93d8d6bae9a9483c1b1d4e8670e7f6226ec94cb”

    错误码说明

    错误码错误描述
    930555微信平台系统错误
    930556配送公司超时
    930557配送公司系统错误
    930558配送公司逻辑错误
    930559openid无效
    930560未绑定的商户号
    930561参数错误
    930562配送单已经存在
    930563配送单不存在
    930564调用无配额
    930565配送单已结束
    9300535shop字段商品缩略图 url、商品名称为空或者非法,或者商品数量为0
    其他错误码配送公司返回的错误码


    品类表

    一级类目二级类目
    美食夜宵零食小吃
    香锅/烤鱼
    西餐
    日韩料理
    海鲜/烧烤
    快餐/地方菜
    小龙虾
    披萨
    甜品饮料甜品
    奶茶果汁
    咖啡
    面包/糕点
    冰淇淋
    蛋糕蛋糕
    日用百货便利店
    水站/奶站
    零食/干果
    五金日用
    粮油调味
    文具店
    酒水行
    地方特产
    进口食品
    宠物用品
    超市
    书店
    宠物食品用品
    办公家居用品
    果蔬生鲜果蔬
    海鲜水产
    冷冻速食
    鲜花鲜花
    医药健康送药
    器材器具
    美妆护肤日化美妆
    母婴孕婴用品
    文件或票务保单
    票务文件
    政府文件
    证件
    服饰鞋帽服饰鞋帽综合
    洗涤脏衣服收
    干净衣服派
    珠宝奢侈品珠宝饰品
    奢侈品
    家居家装家具
    装修建材
    厨房卫浴
    数码产品数码产品
    配件器材配件器材
    电商电视购物
    线上商城
    现场勘查现场勘查
    快递业务快递配送
    其他其他


    order_status 枚举值

    说明
    101配送公司接单阶段——等待分配骑手,即初始状态
    102配送公司接单阶段——分配骑手成功
    103配送公司接单阶段——商家取消订单, 订单结束
    201骑手取货阶段——骑手到店开始取货
    202骑手取货阶段——取货成功
    203骑手取货阶段——取货失败,商家取消订单, 订单结束
    204骑手取货阶段——取货失败,骑手因自身原因取消订单, 订单结束
    205骑手取货阶段——取货失败,骑手因商家原因取消订单, 订单结束
    301骑手配送阶段——配送中
    302骑手配送阶段——配送成功, 订单结束
    303骑手配送阶段——商家取消订单,配送物品开始返还商家
    304骑手配送阶段——无法联系收货人,配送物品开始返还商家
    305骑手配送阶段——收货人拒收,配送物品开始返还商家
    401骑手返回配送货品阶段——货品返还商户成功, 订单结束
    501因运力系统原因取消, 订单结束
    502因不可抗拒因素(天气,道路管制等原因)取消,订单结束

    说明

    1. 最终状态包括成功状态302,失败状态: 103,203,204,205,401,501,502。
    2. 当状态更新时,我们会在关键节点给收件用户推送服务通知,告知配送状态,同一配送单常态下会收到三条通知,即【骑手已接单】、【骑手已取货,配送中】、【配送已完成】,配送异常时会下发【配送异常】服务通知。

    不同服务通知对应的 order_status 枚举值为

    服务通知对应的order_status值
    骑手已接单102
    骑手已取货,配送中202或301
    配送已完成302
    配送异常203、204、205、303、304、305、501、502


    即时配送沙盒环境指引

    为了方便商家接入自测,我们提供了测试的沙盒环境,商户可以通过下面的流程来模拟下单,修改订单状态,体验服务通知。

    接入须知

    1. 此环境只能用于测试下单,禁止用于其它用途。
    2. 为了防止骚扰用户,openid只能配置为小程序的管理员,运营者或者开发者
    3. 下单调用次数有限制,每天不能超时500次
    4. 只能使用以下测试信息进行测试测试运力delivery_id="TEST"测试商户shopid="test_shop_id"测试商户AppSecret="test_app_secrect"

    测试流程

    1. 商户调用微信平台提供的api接口进行预下单,下单,查询订单,取消订单等操作
    2. 调用模拟配送公司更新订单接口来改变订单状态,收件人将收到相应的接单,派送,配送完成通知


    常见问题

    问题1. 即时配送是什么?

    即时配送是微信官方免费接口,旨在解决餐饮、生鲜、超市等小程序的外卖配送需求。接入后小程序商家可通过统一的接口获得多家配送公司的配送服务,提高经营效率。

    问题2. 使用即时配送有什么好处?

    满足多品类配送需求可满足餐饮、生鲜、商超等多品类的配送需求

    接口完全免费即时配送接口是官方提供的基础能力,完全免费开放

    提升用户收货体验配送详情将通过微信服务通知下发给用户,提升收货体验。服务通知包括骑手已接单,骑手已取货、配送中,配送完成和配送异常四种状态

    统一对接节约成本本接口已统一对接多家配送公司下单接口,可直接生成配送单

    增加用户回访小程序入口配送详情的服务通知可跳转商家小程序,提升用户回访率  

    640 (2)

    问题3. 接口收费吗?

    即时配送是微信官方接口能力,完全免费的。

    问题4. 目前已经支持哪些配送公司了?

    640

    问题5. 配送费用怎么结算?

    目前商家使用即时配送的前提是商家已经是本接口支持的配送公司的客户。结算模式按原有商家和配送公司的结算模式来进行。

    问题6. 接入即时配送的流程是怎么样的?

    前提:商家需先和配送公司已达成合作关系,签约了账号才可使用本接口下单。 例如:选择闪送下单,需事先和闪送沟通,在闪送创建一个合作账号以后,再来对接微信即时配送Api。

    步骤1:登录微信公众平台,授权绑定配送公司的签约账号,流程拆解为:

    1. 商家登录微信公众平台,点击右侧菜单【物流助手】——点击【即时配送】tab——去接入;
    2. 选择已经有合作账号的配送公司,如合作公司为闪送,跳转闪送的授权登录页面,输入在闪送的合作账号和密码后,授权登录;
    3. 合作的运力公司返回授权结果,商家后续即可使用该授权过的合作账号下单。

    步骤2:对接即时配送Api(商家查看),预计需要2-3天

    1. 查看相关接口和事件
    2. 开发接口文档:你可自行开发或授权服务商开发,遇到问题可前往微信开放社区提问;

    步骤3:测试联调 我们提供了稳定的沙盒环境供你开发过程进行调试,请先在沙盒环境调试完毕后再正式调用接口发单,测试指引需补充。

    步骤4:上线发单 调试通过后即可上线,骑手接单后,你和用户均可接收配送详情的推送。

    问题7. 商家没有开发能力,可以让服务商代开发吗?

    可以的,服务商代开发的流程为:

    1. 商家登录微信公众平台,点击右侧菜单【物流助手】——点击【即时配送】tab——去接入;
    2. 选择已经有合作账号的配送公司,如合作公司为闪送,跳转闪送的授权登录页面,输入在闪送的合作账号和密码后,授权登录;
    3. 商家将整体即时配送权限集授权给服务商;
    4. 服务商对接Api,完成后续流程开发;
    5. 备注:服务商可以通过getBindAccount接口,查询到商家已授权绑定的配送公司合作账号。

    问题8. 怎么获取我在配送公司的appkey和appsecret?

    详见配送公司信息

    问题9. 用户会收到哪些配送通知?

    当状态更新时,我们会在关键节点给收件用户推送服务通知,告知配送状态,同一配送单常态下会收到三条通知,即【骑手已接单】、【骑手已取货,配送中】、【配送已完成】,配送异常时会下发【配送异常】服务通知。

    问题10. 达达开放平台授权绑定提示“已开通其他渠道”

    达达的商户号只能绑定一个渠道,请检查是否已经绑定达达开放平台的开发者帐号,需要先解绑。

    问题11. 开发过程中遇到问题怎么办?

    请前往微信开放社区提问,提问时请以【物流助手】开头,我们会第一时间解答你的问题。


    联系我们

    开发过程中遇到任何问题,请前往微信开放社区提问。 提问时,建议标题以【物流助手】开头,会第一时间解答你的疑问。


    Banner 广告

    小程序广告流量主操作指引:文档地址

    开发者可以使用 ad 组件创建 Banner 广告组件,Banner 广告组件在创建后会自动拉取广告数据并显示。

    广告尺寸设置

    Banner 广告不允许直接设置样式属性,默认宽度为100%(width: 100%),高度会自动等比例计算,因此开发者可以设置广告外层组件的宽度调整广告的尺寸。 广告外层组件的宽度不允许小于300px,当宽度小于300px时,Banner 广告的宽度会强制调整为300px。

    /* 外层组件的宽度可设置成100%或具体数值 */.adContainer {  width: 100%;}
    <view class="adContainer">  <ad unit-id="xxxx"></ad></view>

    广告事件监听

    Banner 广告在创建后会自动拉取广告。开发者可以通过 ad 组件的 onload 和 onerror 事件监听广告拉取成功或失败,可以通过 onclose 事件监听广告被关闭。

    <view class="adContainer">  <ad unit-id="xxxx" bindload="adLoad" binderror="adError" bindclose="adClose"></ad></view>
    Page({  adLoad() {    console.log('Banner 广告加载成功')  },  adError(err) {    console.log('Banner 广告加载失败', err)  },  adClose() {    console.log('Banner 广告关闭')  }})

    广告定时刷新

    开发者可以在创建 Banner 广告时传入 ad-intervals 参数实现广告的定时刷新,ad-intervals 参数为数字类型,单位为秒。注意:自动刷新的间隔不能低于30秒,因此 ad-intervals 的参数值必须大于或等于30。

    <view class="adContainer">  <ad unit-id="xxxx" ad-intervals="30"></ad></view>


    激励视频广告

    小程序广告流量主操作指引:文档地址

    激励视频广告组件是由客户端原生的图片、文本、视频控件组成的,层级最高,会覆盖在普通组件上。

    开发者可以调用 wx.createRewardedVideoAd 创建激励视频广告组件。该方法返回的是一个单例,该实例仅对当前页面有效,不允许跨页面使用。

    广告创建

    激励视频广告组件默认是隐藏的,因此可以提前创建,以提前初始化组件。开发者可以在小程序页面的 onLoad 事件回调中创建广告实例,并在该页面的生命周期内重复调用该广告实例。

    let rewardedVideoAd = nullPage({  onLoad() {    if(wx.createRewardedVideoAd){      rewardedVideoAd = wx.createRewardedVideoAd({ adUnitId: 'xxxx' })      rewardedVideoAd.onLoad(() => {        console.log('onLoad event emit')      })      rewardedVideoAd.onError((err) => {        console.log('onError event emit', err)      })      rewardedVideoAd.onClose((res) => {        console.log('onClose event emit', res)      })    }  }})

    为避免滥用广告资源,目前每个用户每天可观看激励式视频广告的次数有限,建议展示广告按钮前先判断广告是否拉取成功。

    显示/隐藏

    激励视频广告组件默认是隐藏的,在用户主动触发广告后,开发者需要调用 RewardedVideoAd.show() 进行显示。

    rewardedVideoAd.show() 

    只有在用户点击激励视频广告组件上的 关闭广告 按钮时,广告才会关闭。开发者不可控制激励视频广告组件的隐藏。

    广告拉取成功与失败

    激励视频广告组件是自动拉取广告并进行更新的。在组件创建后会拉取一次广告,用户点击 关闭广告 后会去拉取下一条广告。

    如果拉取成功,通过 RewardedVideoAd.onLoad() 注册的回调函数会执行,RewardedVideoAd.show() 返回的 Promise 也会是一个 resolved Promise。两者的回调函数中都没有参数传递。

    rewardedVideoAd.onLoad(() => {  console.log('激励视频 广告加载成功')})rewardedVideoAd.show().then(() => console.log('激励视频 广告显示'))

    如果拉取失败,通过 RewardedVideoAd.onError() 注册的回调函数会执行,回调函数的参数是一个包含错误信息的对象。

    rewardedVideoAd.onError(err => {  console.log(err)})

    RewardedVideoAd.show() 返回的 Promise 也会是一个 rejected Promise。

    rewardedVideoAd.show().catch(err => console.log(err))

    拉取失败,重新拉取

    如果组件的某次自动拉取失败,那么之后调用的 show() 将会被 reject。此时可以调用 RewardedVideoAd.load() 手动重新拉取广告。

    rewardedVideoAd.show().catch(() => {    rewardedVideoAd.load()    .then(() => rewardedVideoAd.show())    .catch(err => {      console.log('激励视频 广告显示失败')    })})

    如果组件的自动拉取是成功的,那么调用 load() 方法会直接返回一个 resolved Promise,而不会去拉取广告。

    rewardedVideoAd.load().then(() => rewardedVideoAd.show())

    监听用户关闭广告

    只有在用户点击激励视频广告组件上的 关闭广告 按钮时,广告才会关闭。这个事件可以通过 RewardedVideoAd.onClose() 监听。

    RewardedVideoAd.onClose() 的回调函数会传入一个参数 res,res.isEnded 描述广告被关闭时的状态。

    属性类型说明
    isEndedboolean视频是否是在用户完整观看的情况下被关闭的,true 表示用户是在视频播放完以后关闭的视频,false 表示用户在视频播放过程中关闭了视频

    开发者需要根据 res.isEnded 判断是否视频是否播放结束、可以向用户下发奖励。

    rewardedVideoAd.onClose(res => {    // 用户点击了【关闭广告】按钮    if (res && res.isEnded) {      // 正常播放结束,可以下发游戏奖励    } else {      // 播放中途退出,不下发游戏奖励    }})

    注意事项

    多次调用 RewardedVideoAd.onLoad()、RewardedVideoAd.onError()、RewardedVideoAd.onClose() 等方法监听广告事件会产生多次事件回调,建议在创建广告后监听一次即可,或者先取消原有的监听事件再重新监听。


    插屏广告

    插屏广告组件是由客户端原生的图片、文本、视频控件组成的,层级最高,会覆盖在普通组件上。

    开发者可以调用 wx.createInterstitialAd 创建插屏广告组件。每调用一次该方法,返回的都是一个全新实例,该实例仅对当前页面有效,不允许跨页面使用。

    广告创建

    插屏广告组件默认是隐藏的,因此可以提前创建,以提前初始化组件。开发者可以在小程序页面的 onLoad 事件回调中创建广告实例,并在该页面的生命周期内重复调用该广告实例。

    let interstitialAd = nullPage({  onLoad() {    if(wx.createInterstitialAd){      interstitialAd = wx.createInterstitialAd({ adUnitId: 'xxxx' })      interstitialAd.onLoad(() => {        console.log('onLoad event emit')      })      interstitialAd.onError((err) => {        console.log('onError event emit', err)      })      interstitialAd.onClose((res) => {        console.log('onClose event emit', res)      })    }  }})

    显示/隐藏

    插屏广告组件默认是隐藏的,开发者需要调用 InterstitialAd.show() 进行显示。如果广告拉取失败或触发频率限制,InterstitialAd.show() 方法会返回一个rejected Promise,开发者可自行监听错误信息。

    interstitialAd.show().catch((err) => {  console.error(err)})

    用户可以主动关闭插屏广告。开发者不可控制插屏广告组件的隐藏。

    广告拉取成功与失败

    插屏广告组件是自动拉取广告并进行更新的。在组件创建后会拉取一次广告,用户关闭广告后会去拉取下一条广告。

    如果拉取成功,通过 InterstitialAd.onLoad() 注册的回调函数会执行,回调函数没有参数传递。

    interstitialAd.onLoad(() => {  console.log('插屏 广告加载成功')})

    如果拉取失败,通过 InterstitialAd.onError() 注册的回调函数会执行,回调函数的参数是一个包含错误信息的对象。常见异常错误参考文档

    interstitialAd.onError(err => {  console.log(err)})

    监听用户关闭广告

    如果广告被关闭,通过 InterstitialAd.onClose() 注册的回调函数会执行,回调函数没有参数传递。

    interstitialAd.onClose(res => {    console.log('插屏 广告关闭')})

    注意事项

    多次调用 InterstitialAd.onLoad()InterstitialAd.onError()InterstitialAd.onClose() 等方法监听广告事件会产生多次事件回调,建议在创建广告后监听一次即可,或者先取消原有的监听事件再重新监听。

    在插屏广告展示过程中如果快速切换页面,可能会出现插屏广告展示在非调用页面的情况,如有需要请在页面切换完成后进行插屏广告展示。


    小程序视频广告

    小程序广告流量主操作指引:文档地址

    开发者可以使用 ad 组件创建小程序视频广告组件,视频广告组件在创建后会自动拉取广告数据并显示。暂时仅支持在同层渲染模式下使用,且不支持嵌套使用。

    广告尺寸设置

    小程序视频广告不允许直接设置样式属性,默认宽度为100%(width: 100%),高度会自动等比例计算,因此开发者可以设置广告外层组件的宽度调整广告的尺寸。 广告外层组件的宽度不允许小于屏幕宽度90%,当宽度小于屏幕宽度的90%时,视频广告组件的宽度会强制调整为屏幕宽度的90%。

    /* 外层组件的宽度可设置成100%或具体数值 */.adContainer {  width: 100%;}
    <view class="adContainer">  <ad unit-id="xxxx" ad-type="video" ad-theme="white"></ad></view>

    广告主题样式设置

    小程序视频广告组件提供黑、白两种主题样式,开发者可以在创建视频广告时传入ad-theme参数实现主题样式选择,ad-theme参数为字符串类型,参数值可选white, black

    <view class="adContainer">  <ad unit-id="xxxx" ad-type="video" ad-theme="white"></ad></view>
    <view class="adContainer">  <ad unit-id="xxxx" ad-type="video" ad-theme="black"></ad></view>

    广告事件监听

    视频广告在创建后会自动拉取广告。开发者可以通过 ad 组件的 onload 和 onerror 事件监听广告拉取成功或失败,可以通过 onclose 事件监听广告被关闭。

    <view class="adContainer">  <ad unit-id="xxxx" ad-type="video" ad-theme="white" bindload="adLoad" binderror="adError" bindclose="adClose"></ad></view>
    Page({  adLoad() {    console.log('小程序视频广告加载成功')  },  adError(err) {    console.log('小程序视频广告加载失败', err)  },  adClose() {    console.log('小程序视频广告关闭')  }})

    广告定时刷新

    小程序视频广告组件不适用于定时刷新参数ad-intervals


    视频前贴广告

    小程序广告流量主操作指引:文档地址

    开发者可以在 video 组件中添加属性配置,创建小程序视频前贴广告组件,视频广告组件在创建后会自动拉取广告数据,视频播放前展示广告。

    广告样式

    展示样式在开发者所设置的video组件中,以16:9的比例,垂直或者水平居中

    广告创建

    在 video 组件中添加了以下广告相关的属性配置,设置ad-unit-id后可以展示对应广告

    属性类型默认值必填说明
    ad-unit-idstring广告单元id,可在小程序管理后台的流量主模块新建
    bindadloadeventhandle广告加载成功的回调
    bindaderroreventhandle广告加载失败的回调,返回码同ad组件
    bindadcloseeventhandle广告关闭的回调
    bindadplayeventhandle广告开始,结束播放的回调 event.detail = {type: 'begin/end'}

    添加广告单元,绑定广告事件

    <video   class="xxx"  src="xxx"  bindadplay="onAdplay"  bindadload="onAdload"  bindadclose="onAdclose"  bindaderror="onAdError"  ad-unit-id="xxx"></video>

    监听广告事件

    Page({  onAdplay(e) {    console.log('onAdplay', e)  },  onAdload(e){    console.log('onAdload', e)  },  onAdclose(e) {    console.log('onAdclose', e)  },  onAdError(e) {    console.log('onAdError', e)  },})

    广告预加载

    开发者可以调用 wx.preloadVideoAd 的方式进行广告的预加载

    const adUnitId1 = 'xxx'const adUnitId2 = 'xxx'wx.preloadVideoAd([adUnitId1, adUnitId2])

    错误码

    错误码是通过bindaderror回调获取到的错误信息,前贴广告再普通广告组件ad错误码基础上新增了以下错误码。

    代码异常情况解决方案
    3001命中频控策略按照没有广告处理
    3002命中频控策略按照没有广告处理
    3003命中频控策略按照没有广告处理
    3004命中频控策略按照没有广告处理

    注意事项

    1、支持视频预加载能力:文档地址

    2、仅支持同层渲染模式下的video组件。

    3、开发者可监听bindadplay事件获取广告播放状态,做出相应处理。

    4、ad-unit-id不支持异步设置,只支持设置在wxml或者js文件的data属性里,通过setData设置的无效。

    5、全屏模式下不展示视频前贴广告。


    Grid 广告

    小程序广告流量主操作指引:文档地址

    开发者可以使用 ad 组件创建 Grid 广告组件,Grid 广告组件在创建后会自动拉取广告数据并显示。

    广告尺寸设置

    Grid 广告不允许直接设置样式属性,默认宽度为100%(width: 100%),高度会自动等比例计算,因此开发者可以设置广告外层组件的宽度调整广告的尺寸。格子广告有最小尺寸限制,5个的形态为331px,8个的形态为294px。

    /* 外层组件的宽度可设置成100%或具体数值 */.adContainer {  width: 100%;}
    <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" ad-theme="white" grid-count="5"></ad></view>

    广告事件监听

    Grid 广告在创建后会自动拉取广告。开发者可以通过 ad 组件的 onload 和 onerror 事件监听广告拉取成功或失败,可以通过 onclose 事件监听广告被关闭。

    <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" ad-theme="white" grid-count="5" bindload="adLoad" binderror="adError" bindclose="adClose"></ad></view>
    Page({  adLoad() {    console.log('Grid 广告加载成功')  },  adError(err) {    console.log('Grid 广告加载失败', err)  },  adClose() {    console.log('Grid 广告关闭')  }})

    广告主题样式设置

    小程序视频广告组件提供黑、白两种主题样式,开发者可以在创建视频广告时传入ad-theme参数实现主题样式选择,ad-theme参数为字符串类型,参数值可选white, black

    <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" ad-theme="white"></ad></view>
    <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" ad-theme="black"></ad></view>

    广告格子个数设置

    小程序视频广告组件提供黑、白两种主题样式,开发者可以在创建视频广告时传入grid-count参数实现主题样式选择,grid-count参数为数字类型,参数值可选5, 8

    <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" grid-count="5"></ad></view>
    <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" grid-count="8"></ad></view>


    原生模板 广告

    小程序广告流量主操作指引:文档地址

    开发者可以使用 ad-custom 组件创建 原生模板 广告组件,原生模板 广告组件在创建后会自动拉取广告数据并显示。

    广告尺寸设置

    原生模板 广告不允许直接设置样式属性,默认宽度为100%(width: 100%),高度会自动等比例计算,因此开发者可以设置广告外层组件的宽度调整广告的尺寸。 广告外层组件的宽度和具体模板相关,具体可以参考模板编辑器文档。

    /* 外层组件的宽度可设置成100%或具体数值 */.adContainer {  width: 100%;}
    <view class="adContainer">  <ad-custom unit-id="xxxx"></ad-custom></view>

    广告事件监听

    原生模板 广告在创建后会自动拉取广告。开发者可以通过 ad-custom 组件的 onload 和 onerror 事件监听广告拉取成功或失败。

    <view class="adContainer">  <ad-custom unit-id="xxxx" bindload="adLoad" binderror="adError"></ad-custom></view>
    Page({  adLoad() {    console.log('原生模板广告加载成功')  },  adError(err) {    console.log('原生模板广告加载失败', err)  }})

    广告定时刷新

    开发者可以在创建 原生模板 广告时传入 ad-intervals 参数实现广告的定时刷新,ad-intervals 参数为数字类型,单位为秒。注意:自动刷新的间隔不能低于30秒,因此 ad-intervals 的参数值必须大于或等于30。

    <view class="adContainer">  <ad-custom unit-id="xxxx" ad-intervals="30"></ad-custom></view>


    广告分析数据接口说明

    向所有成为流量主的公众号、小程序、小游戏开发者开放数据接口。通过数据接口,开发者可以获取与公众平台官网统计模块类似但更灵活的数据,还可根据需要进行高级处理。

    请注意:

    1. 接口侧数据库中仅存储了2016年1月1日之后的数据,将无法查询到此前的数据,即使查到,也是不可信的脏数据;
    2. 建议开发者在调用接口获取数据后,将数据保存在自身数据库中,以最大化访问的效率,也降低微信侧接口调用的不必要损耗;
    3. 由于数据量较大, 所有接口采取分页获取的方式, 每页最大获取量为90。(eg:total_num 为100,则当page = 1,page_size = 10,则返回前10条;page = 1,page_size = 20,则返回前20条;page = 2,page_size = 10,则返回第11条到第20条)
    4. 广告位枚举值变更说明由于多个接口都使用了广告位参数,为保证体验的一致性和参数的可读性,我们做了一些变更,所有接口均支持以 广告位类型名称(ad_slot) 传递参数,回包时新增这个名称来代表相关含义。此前的参数 slot_id 也可继续使用并回传。具体为:
    广告位类型名称(ad_slot)广告位类型
    SLOT_ID_BIZ_BOTTOM公众号底部广告
    SLOT_ID_BIZ_MID_CONTEXT公众号文中广告
    SLOT_ID_BIZ_VIDEO_END公众号视频后贴
    SLOT_ID_BIZ_SPONSOR公众号互选广告
    SLOT_ID_BIZ_CPS公众号返佣商品
    SLOT_ID_WEAPP_BANNER小程序banner
    SLOT_ID_WEAPP_REWARD_VIDEO小程序激励视频
    SLOT_ID_WEAPP_INTERSTITIAL小程序插屏广告
    SLOT_ID_WEAPP_VIDEO_FEEDS小程序视频广告
    SLOT_ID_WEAPP_VIDEO_BEGIN小程序视频前贴
    SLOT_ID_WEAPP_BOX小程序格子广告
    SLOT_ID_WEAPP_TEMPLATE小程序原生模板广告

    接口总览

    广告分析接口目前可用于获得“公众平台 → 流量主 → 数据统计”页面展示的部分广告数据和“公众平台 → 流量主 → 财务管理”页面展示的部分收入数据,与小程序相关的接口列表如下:

    接口名称用途最大时间跨度接口调用地址(必须使用https)
    publisher_adpos_general获取小程序广告汇总数据90天https://api.weixin.qq.com/publisher/stat?action=publisher_adpos_general&access_token=ACCESS_TOKEN
    publisher_adunit_general获取小程序广告细分数据90天https://api.weixin.qq.com/publisher/stat?action=publisher_adunit_general&access_token=ACCESS_TOKEN
    get_adunit_list获取小程序广告位清单https://api.weixin.qq.com/publisher/stat?action=get_adunit_list&access_token=ACCESS_TOKEN
    publisher_settlement获取小程序结算收入数据及结算主体信息https://api.weixin.qq.com/publisher/stat?action=publisher_settlement&access_token=ACCESS_TOKEN

    接口调用请求说明

    一、获取小程序广告汇总数据(publisher_adpos_general)

    需要向相应接口调用地址增加以下GET请求参数:

    参数是否必须说明
    page返回第几页数据
    page_size当页返回数据条数
    start_date获取数据的开始时间 yyyy-mm-dd
    end_date获取数据的结束时间 yyyy-mm-dd
    ad_slot广告位类型名称

    请注意: 如果不传递广告位类型名称,将默认返回全部类型广告位的数据。


    返回参数说明(publisher_adpos_general)

    参数说明
    err_msg返回错误信息
    ret错误码
    list: slot_id广告位类型id
    list: ad_slot广告位类型名称
    list: date日期
    list: req_succ_count拉取量
    list: exposure_count曝光量
    list: exposure_rate曝光率
    list: click_count点击量
    list: click_rate点击率
    list: income收入(分)
    list: ecpm广告千次曝光收益(分)
    summary: req_succ_count总拉取量
    summary: exposure_count总曝光量
    summary: exposure_rate总曝光率
    summary: click_count总点击量
    summary: click_rate总点击率
    summary: income总收入(分)
    summary: ecpm广告千次曝光收益(分)
    total_numlist返回总条数

    返回数据包示例(publisher_adpos_general)

    {    "base_resp":{        "err_msg":"ok",        "ret":0    },    "list":[        {            "slot_id":3030046789020061,            "ad_slot":"SLOT_ID_WEAPP_INTERSTITIAL",            "date":"2020-04-13",            "req_succ_count":443610,            "exposure_count":181814,            "exposure_rate":0.409850995,            "click_count":10095,            "click_rate":0.055523777,            "income":52175,            "ecpm":286.969100289        }    ],    "summary":{        "req_succ_count":4406394,        "exposure_count":1797225,        "exposure_rate":0.407867522,        "click_count":100167,        "click_rate":0.055734257,        "income":578003,        "ecpm":321.608591022    },    "total_num":1}

    二、获取小程序广告细分数据(publisher_adunit_general)

    需要向相应接口调用地址增加以下GET请求参数:

    参数是否必须说明
    page返回第几页数据
    page_size当页返回数据条数
    start_date获取数据的起始日期 yyyy-mm-dd
    end_date获取数据的结束时间 yyyy-mm-dd
    ad_slot广告位类型名称
    ad_unit_id广告位id

    请注意: 当需要获取全部广告位的细分数据时,无需传递广告位类型名称及广告位id;当需要获取某类型广告位的细分数据时,仅需传递广告位类型名称;当需要获取某广告位id的细分数据时,仅需传递广告位id。


    返回参数说明(publisher_adunit_general)

    参数说明
    err_msg返回错误信息
    ret错误码
    list: ad_unit_id广告位id
    list: ad_unit_name广告位名称
    list: stat_item: ad_slot广告位类型名称
    list: stat_item :date数据日期
    list: stat_item :req_succ_count拉取量
    list: stat_item :exposure_count曝光量
    list: stat_item: exposure_rate曝光率
    list: stat_item :click_count点击量
    list: stat_item :click_rate点击率
    list: stat_item :income收入
    list: stat_item :ecpm广告千次曝光收益(分)
    total_num请求返回总数

    返回数据包示例(publisher_adunit_general)

    {    "base_resp":{        "err_msg":"ok",        "ret":0    },    "list":[        {            "ad_unit_id":"adunit-9cedd8514XXXX",            "ad_unit_name":"激励视频长广告",            "stat_item":{                "ad_slot":"SLOT_ID_WEAPP_REWARD_VIDEO",                "date":"2020-04-10",                "req_succ_count":138250,                "exposure_count":74771,                "exposure_rate":0.54083906,                "click_count":2242,                "click_rate":0.029984887,                "income":93883,                "ecpm":6.790813743            }        }    ],    "total_num":1}

    三、获取小程序广告位清单(get_adunit_list)

    需要向相应接口调用地址增加以下GET请求参数:

    参数是否必须说明
    page返回第几页数据
    page_size当页返回数据条数
    ad_slot广告位类型名称
    ad_unit_id广告位id

    请注意: 当需要获取全部广告位的清单时,无需传递广告位类型名称及广告位id;当需要获取某类型广告位的清单时,仅需传递广告位类型名称;当需要获取某广告位id的数据时,仅需传递广告位id。


    返回参数说明(get_adunit_list)

    参数说明
    err_msg返回错误信息
    ret错误码
    ad_slot广告位类型名称
    ad_unit_id广告位ID
    ad_unit_name广告位名称
    ad_unit_size广告位尺寸
    ad_unit_status广告位状态

    返回数据包示例(get_adunit_list)

    {    "base_resp":{        "err_msg":"ok",        "ret":0    },    "ad_unit":[        {            "ad_slot":"SLOT_ID_WEAPP_REWARD_VIDEO",            "ad_unit_id":"adunit-e9418ee19XXXXX",            "ad_unit_name":"rewaXXXX",            "ad_unit_size":[                {                    "height":166,                    "width":582                }            ],            "ad_unit_status":"AD_UNIT_STATUS_ON",            "ad_unit_type":"AD_UNIT_TYPE_REWARED_VIDEO",            "appid":"wx0afc78670fXXXX",            "video_duration_max":30,            "video_duration_min":6        }    ],    "total_num":1}

    四、获取小程序结算收入数据及结算主体信息(publisher_settlement)

    需要向相应接口调用地址增加以下GET请求参数:

    参数是否必须说明
    page数据返回页数
    page_size每页返回数据条数
    start_date获取数据的开始时间 yyyy-mm-dd
    end_date获取数据的结束时间 yyyy-mm-dd

    请注意: 只要与获取数据的起止时间有重合,结算区间对应的数据都将返回。例如,请求2月11日至3月26日的数据,将会返回2月上半月、2月下半月、3月上半月、3月下半月四个结算区间的数据。


    返回参数说明(publisher_settlement)

    参数说明
    err_msg返回错误信息
    ret错误码
    body主体名称
    revenue_all累计收入
    penalty_all扣除金额
    settled_revenue_all已结算金额
    settlement_list: date数据更新时间
    settlement_list: zone日期区间
    settlement_list: month收入月份
    settlement_list: order1 = 上半月,2 = 下半月
    settlement_list: sett_status1 = 结算中;2、3 = 已结算;4 = 付款中;5 = 已付款
    settlement_list: settled_revenue区间内结算收入
    settlement_list: sett_no结算单编号
    settlement_list: mail_send_cnt申请补发结算单次数
    settlement_list: slot_revenue: slot_id产生收入的广告位
    settlement_list: slot_revenue: slot_settled_revenue该广告位结算金额
    total_num请求返回总条数

    返回数据包示例(publisher_settlement)

    {    "base_resp":{        "err_msg":"ok",        "ret":0    },    "body":"深圳市腾讯计算机系统有限公司",    "penalty_all":0,    "revenue_all":5178368698,    "settled_revenue_all":2613696765,    "settlement_list":[        {            "date":"2020-03-25",            "zone":"2020年3月1日至15日"            "month":"202003",            "order":1,            "sett_status":1,            "settled_revenue":718926045,            "sett_no":"XXX",            "mail_send_cnt":"0",            "slot_revenue":[                {                    "slot_id":"SLOT_ID_WEAPP_BANNER",                    "slot_settled_revenue":34139443                },                {                    "slot_id":"SLOT_ID_WEAPP_REWARD_VIDEO",                    "slot_settled_revenue":684786602                }            ]        }    ],    "total_num":1}

    错误码说明

    错误码返回值含义
    45009请求过于频繁, 请稍后尝试
    45010无效的接口名
    1701参数错误
    2009无效的流量主


    安全指引

    开发原则与注意事项

    本文档整理了部分小程序开发中常见的安全风险和漏洞,用于帮助开发者在开发环节中发现和修复相关漏洞,避免在上线后对业务和数据造成损失。开发者在开发环节中必须基于以下原则:

    1. 互不信任原则,不要信任用户提交的数据,包括第三方系统提供的数据,必要的数据校验必须放在后台校验。
    2. 最小权限原则,代码、模块等只拥有可以完成任务的最小权限,不赋予不必要的权限。
    3. 禁止明文保存用户敏感数据。
    4. 小程序代码(不包括云函数代码)跟传统 Web 应用的前端代码类似,可被外部获取及进行反混淆,重要业务逻辑应放在后台代码或云函数中进行。
    5. 后台接口调用以及云函数调用,必须进行有效的身份鉴权。


      通用

      接口鉴权

      接口鉴权是指后台接口(包括自建后台接口与云函数)在被调用时需要对本次接口调用进行权限校验,否则容易发生越权行为。如商品删除接口,后台在收到请求时应当校验调用者的身份信息(如 openid、 ip 地址、开发者自定义的登录信息等),只有指定用户才可以通过校验进行删除。

      越权通常分为平行越权和垂直越权:

      • 平行越权 
        平行越权是指相同角色之间的越权。 A1、 A2 都是普通用户, A1 通过请求后台接口 userinfo.php?id=A1 来获取用户 A1 自己的信息,如果 userinfo.php 没有进行权限校验,用户 A1 把请求改为 userinfo.php?id=A2 便可以获取到 A2 用户的信息,造成 A2 用户信息的泄露。
      • 垂直越权 
        垂直越权是指不同角色之间的越权。 B1 是管理员, B2 是普通用户,管理员 B1 通过请求后台接口 getalluserinfo.php 可以获取所有注册用户的信息,如果 getalluserinfo.php 没有进行权限校验, B2 用户也可以请求 getalluserinfo.php 来获取所有注册用户的信息,出现越权行为。

      开发建议:

      1. 敏感数据、能力相关接口需要在后台进行鉴权。通常可校验 openid、 IP 地址、自定义登陆态等信息。
      2. 鉴权逻辑应放在后台进行,不应在小程序前端以隐藏页面、隐藏按钮等方式来代替。参照原则4。
      3. 鉴权代码示例(仅供参考)
        1. 自建后台鉴
          function actionDelete(){    $item_id = $_POST["item_id"];     $openid = $_POST["openid"];    $ip = $_SERVER['REMOTE_ADDR'];    $user_role = $_SESSION["user_role"];    if ($openid === "xxx" &&        $ip === "192.168.0.101" &&        $user_role === "admin") {            // 进行删除操作            // ...            return 0;        } else {            // 记录非法请求            // ...            return -1;        }}
        2. 云函数接口鉴权

          exports.main = async (event, context) => {    const { OPENID, APPID, UNIONID } = cloud.getWXContext();    if (OPENID === "xxx") {        // 进行删除操作        // ...    } else {        // 记录非法请求        // ...    }}

        代码管理与泄漏

        1. 当使用 git、 svn 等版本管理工具时,会产生 .git 等目录。某些编辑器或软件也会在运行过程中生成临时文件。若这些目录或文件被带到生产环境,则可能发生源码泄漏。
        2. 使用小程序代码管理平台或 github 等第三方平台时需要注意项目权限,不要公开敏感、内部项目。

        开发建议:

        1. 备份文件和版本管理工具产生的文件不要同步到 Web 目录下。
        2. 禁止外部访问 .git 等目录与文件。
        3. 小程序代码管理平台等管理平台内配置适当的访问权限。

        小程序

        信息泄露

        敏感信息是指一旦泄露可能会对开发者的业务、合作伙伴和用户带来利益损害的数据,包括但不限于帐号 Appsecret、特权帐号信息、后台加密密钥、登录账户密码、用户身份证号、手机号、银行卡号等。

        开发建议:

        1. 敏感信息不应以明文、注释、可逆的编码方式(如 base64)、不安全散列函数(如 MD5、 SHA1)等形式出现在小程序文件内。
        2. 部分敏感信息如用户的银行卡号、手机号等需要用于展示的,需要进行脱敏处理。常用脱敏规范如下: 
          敏感信息类型展示样例
          姓名名字只有两个字,对第一个字打码,如:*三。 多于两个字,只保留第一个和最后一个,其余都打码,如:王*四、欧**五
          身份证只显示第一位和最后一位,如:3****************1
          手机号除去手机国际码后,手机号位数不少于10位时,只显示前三位和最后两位,如:156******77。手机号位数少于10位时,只显示前两位和后两位,如:12*****89。国家码可以完全显示。
          银行卡只显示最后4位,如:************1234
        3. 如果小程序存在敏感信息泄露的问题,微信开放平台将有可能下架该小程序,并暂停该小程序的相关服务。


        后台(包括云函数与自建后台)

        注入漏洞

        注入漏洞(SQL、 命令等)通常指用户绕过后台代码限制,直接在数据库、 shell 内执行自定义代码。

        常见的注入漏洞有:

        SQL 注入

        SQL 注入是指 Web 程序代码中对于用户提交的参数未做有效过滤就直接拼接到 SQL 语句中执行,导致参数中的特殊字符打破了 SQL 语句原有逻辑,黑客可以利用该漏洞执行任意 SQL 语句。

        开发建议:

        1. 使用数据库提供的参数化查询来进行数据库操作,不允许直接通过拼接字符串的方式来合成 SQL 语句。
        2. 如果存在部分情况需要通过拼接的方式来合成 SQL ,拼接的变量必须要经过处理:对于整数,需要判断变量是否为整数类型。对于字符串,需要对单引号、双引号等做转义处理。
        3. 避免 Web 应用显示 SQL 的报错信息。
        4. 保证 Web 应用里每一数据层的编码统一。

        命令注入

        命令注入漏洞是指 Web 应用未对用户可控参数进行有效过滤,攻击者可以构造恶意参数拼接到命令上来执行任意命令。

        开发建议:

        • 对用户输入的数据(如 ;、|、&等)进行过滤或转义。

        弱口令

        弱口令指管理后台的用户名密码设置得较为简单或者使用默认帐号。攻击者可以通过登录这些帐号修改后台数据或进行下一步的入侵操作。

        开发建议:

        1. 后台服务禁用默认帐号,修改后台弱口令。
        2. 敏感服务增加二次验证机制,如短信验证码、邮箱验证码等。

        文件上传漏洞

        文件上传漏洞是指 Web 应用允许用户上传指定文件,但未对文件类型、格式等做合法性校验,导致可以上传非预期格式的文件。

        开发建议:

        • 正确解析上传文件的文件类型,通过白名单的方式限制可上传的文件类型。

        文件下载

        文件下载漏洞是指 Web 应用允许用户通过指定路径和文件名的方式来下载对应的文件,但未正确限制可下载文件所在的目录范围,导致预期范围外的文件被下载泄露。

        开发建议:

        1. 正确限制可下载文件所在的目录范围
        2. 通过指定文件 id 的方式来查找下载对应的文件

        目录遍历

        目录遍历是指由后台服务对用户输入验证不足或配置不严谨导致的服务器目录内容泄漏。外部可能通过目录遍历获取系统文件、后台代码等敏感文件。

        开发建议:

        1. web 服务配置
          1. 服务端禁止展示目录
          2. 设置目录访问权限
          3. 在每个目录下放置一个空的 index.html 页面
        2. web 应用代码
          1. 严格检查文件路径参数,限定文件的范围

        条件竞争

        条件竞争比较常见的例子是攻击者通过并发 https 请求而达到多次获奖、多次收获、多次获赠等非正常逻辑所能触发的效果。

        • 漏洞代码示例 
          // 从DB里查询该用户剩余获奖次数,初始值为1int remain_times = SelectRemainTimes();if(remain_times > 0){    EarnRewards();          // 用户获得奖励    ClearRemainTimes();     // 在DB里把该用户的剩余获奖次数清零}

          开发者的设计本意是只允许用户获得一次奖励,但当出现并发请求时,有可能出现请求 A 和请求 B 都刚好执行完第2行代码的情况,此时两个请求的 remain_times 都为1,也就是可以通过第4行代码的判断,获得两次奖励。

        开发建议:

        • 对关键(完整)逻辑加锁操作或把关键逻辑以队列任务的形式去进行处理。


        调试

        vConsole

        在真机上,如果想要查看 console API 输出的日志内容和额外的调试信息,需要在点击屏幕右上角的按钮打开的菜单里选择「打开调试」。此时小程序/小游戏会退出,重新打开后会右下角会出现一个 vConsole 按钮。点击 vConsole 按钮可以打开日志面板。

        小程序和小游戏的 vConsole 展示内容会有一定差别,下图左边是小程序 vConsole,右边是小游戏 vConsole

         

        vConsole 使用说明

        由于实现机制的限制,开发者调用 console API 打印的日志内容,是转换成 JSON 字符串后传输给 vConsole 的,导致 vConsole 中展示的内容会有一些限制:

        • 除了 Number、String、Boolean、null 外,其他类型都会被作为 Object 处理展示,打印对象及原型链中的 Enumerable 属性。
        • Infinity 和 NaN 会显示为 null。
        • undefined、ArrayBuffer、Function 类型无法显示
        • 无法打印存在循环引用的对象
          let a = {}a.b = aconsole.log(a) // 2.3.2 以下版本,会打印 `An object width circular reference can't be logged`

        针对上述问题,小程序/小游戏在使用 vConsole 时做了一些处理

        • 2.3.2 及以上版本,支持打印循环引用对象。循环引用的对象属性会显示引用路径,@表示对象本身。
          const circular = { x: {}, c: {} }circular.x = [{ promise: Promise.resolve() }]circular.a = circularcircular.c.x0 = circular.x[0]console.log(circular)// "{a: '<Circular: @>', c: {x0: '<Circular: @.x[0]>'}, x: [{promise: '<Promise>'}]}"
        • 2.3.1 及以上版本,支持展示所有类型的数据。基础库会对日志内容进行一次转换,经过转换的内容会使用<>包裹。如:
          • <Function: func>
          • <Undefined>
          • <Infinity>
          • <Map: size=0>
          • <ArrayBuffer: byteLength=10>
          • ...
        • 2.2.3 ~ 2.3.0 版本中,可以展示 ArrayBuffer 和 Function 类型,undefined 会被打印为字符串 'undefined'

        注:尽量避免在非调试情景下打印结构过于复杂或内容过长的日志内容(如游戏引擎中的精灵或材质对象等),可能会带来额外耗时。为了防止异常发生,日志内容超过一定长度会被替换为<LOG_EXCEED_MAX_LENGTH>,此时需要开发者裁剪日志内容。

        Source Map

        目前只在 iOS 6.7.2 及以上版本支持

        小程序/小游戏在打包时,会将所有 js 代码打包成一个文件,为了便于开发者在手机上调试时定位错误位置,小程序/小游戏提供了 Source Map 支持。

        在开发者工具中开启 ES6 转 ES5、代码压缩时,会生成 Source Map 的 .map 文件。开发版小程序中,基础库会使用代码包中的 .map 文件,对 vConsole 中展示的错误信息堆栈进行重新映射(只对开发者代码文件进行)。

        如果使用外部的编译脚本对源文件进行处理,只需将对应生成的 Source Map 文件放置在源文件的相同目录下

        如:

        pages/index.js
        pages/index.js.map
        app.js
        app.js.map

        开发者工具会读取、解析 Source Map 文件,并进行将其上传

        后续可以在小程序后台的运营中心可以利用上传的 Source Map 文件进行错误分析

        1. Source Map 文件不计入代码包大小计算。
        2. 开发版代码包中由于包含了 .map 文件,实际代码包大小会比体验版和正式版大。

        真机调试

        真机远程调试功能可以实现直接利用开发者工具,通过网络连接,对手机上运行的小程序进行调试,帮助开发者更好的定位和查找在手机上出现的问题。


        启动性能

        小程序启动是小程序用户体验中极为重要的一环,启动耗时过长会造成小程序用户流失。

        本章节的启动只包括小程序冷启动,不包括小程序后台切前台的热启动。

        一、启动流程

        在进行启动优化之前,先简单介绍以下小程序的启动过程。在小程序启动过程中,主要包括以下几个方面:

        • 注 1:小程序启动的这些部分不是串行完成的,会尽可能的并行进行。
        • 注 2:小程序启动各部分不是每次启动都完整进行的,会尽可能的利用缓存。

        1. 资源准备

        1.1 小程序相关信息准备

        在用户访问小程序时,微信客户端需要从微信后台获取小程序的配置、版本、权限等相关信息,以对小程序进行必要的版本管理、权限控制和校验等。

        对启动耗时的影响

        信息的获取和更新会影响小程序的启动耗时,尤其体现在用户首次访问小程序时。

        为了在尽量降低影响启动耗时的情况下保证信息的实时性,这些信息会在本地缓存,并通过一定的机制定期进行更新。

        1.2 小程序运行环境准备

        在执行小程序代码之前,微信客户端需要准备小程序运行的基础环境。

        小程序的运行环境包括小程序进程、原生部分的 UI 元素(如 导航栏、tabBar等)、渲染页面使用的 WebView 容器、运行开发者 JS 代码的 JS 引擎、小程序基础库等等。

        对启动耗时的影响

        运行环境的准备耗时较长,对小程序的启动耗时有明显影响。

        为了尽可能的降低运行环境准备对启动耗时的影响,微信客户端会根据用户的使用场景和设备资源的使用情况,提前对运行环境进行部分地预加载。但由于受到设备资源和操作系统调度的影响,目前很难保证每次小程序启动时都有预加载的环境。

        1.3 小程序代码包准备

        小程序启动时需要从服务器获取代码包地址、下载小程序代码包,并对代码包进行校验。根据小程序页面所在分包和使用的插件不同,一次启动可能需要下载多个代码包或插件包。

        当小程序版本发生更新时,微信客户端还需要对代码包进行增量更新。

        对启动耗时的影响

        下载耗时是启动耗时中的重要瓶颈,与代码包或增量包的体积正相关。微信采用 ZSTD 算法对小程序代码包进行压缩,以尽可能降低下载过程中传输的数据量。

        考虑到包大小对用户体验的影响,平台限制单个代码包的大小上限为 2M。代码包上限的增加对于开发者来说,能够实现更丰富的功能,但对于用户来说,也增加了下载流量和本地空间的占用。为了保证启动速度,开发者应该尽可能的控制代码包大小。

        2. 开发者代码注入(逻辑层)

        小程序启动时需要从代码包内读取小程序的配置和代码,并注入到 JS 引擎中。在主包代码注入过程中,会触发小程序的 App.onLaunch 和首次 App.onShow 生命周期。在开发者代码注入完成后,框架侧会根据用户访问的页面进行一些页面数据初始化工作,触发首页的 Page.onLoad, Page.onShow 事件。

        对启动耗时的影响

        开发者代码的注入耗时直接影响小程序的启动耗时。在主流的 JS 引擎中,代码注入耗时包括编译和执行等环节,代码量、同步接口调用和一些复杂的计算,都会影响注入耗时。

        由于首页渲染需要使用逻辑层发送的数据,如果开发者代码注入耗时过长,也会延迟首页渲染开始的时间。

        在部分平台上,微信客户端会使用 V8 引擎的 Code Caching 技术对代码编译结果进行缓存,降低二次注入时的编译耗时。

        3. 开发者代码注入(渲染层)

        开发者的 wxss 和 wxml 会经过编译注入到渲染层,包含页面渲染需要的页面结构和样式信息。渲染层的注入耗时主要和页面结构复杂度和使用的自定义组件数量有关。

        渲染层和逻辑层的开发者代码注入是并行进行的。

        对启动耗时的影响

        由于首页渲染需要使用渲染层的页面结构和样式信息,如果开发者代码注入耗时过长,会延迟首页渲染开始的时间。

        4. 首页(初次)渲染

        在开发者代码注入完成后,结合逻辑层得到的数据和渲染层得到的页面结构和样式信息,小程序框架会进行小程序首页的渲染,展示小程序首屏,并触发首页的 Page.onReady 事件。Page.onReady 事件触发标志小程序启动过程完成。

        对启动耗时的影响

        首页渲染耗时主要受页面结构和参与渲染的数据量影响。

        二、关键概念

        在讨论小程序启动耗时时,需要明确几个概念:

        1. 小程序首屏渲染完成

        从开发者角度看,小程序首屏渲染完成的标志是首页 Page.onReady 事件触发。

        从框架的角度来说,小程序的首屏的内容是基于小程序的初始数据,以及在渲染开始前到达的 setData 数据渲染的。

        首屏渲染完成不表示小程序页面一定有完整内容,开发者触发的 setData(例如通过 wx.request 异步请求数据)不一定能参与到首屏渲染中。

        由于框架和启动流程的差异,小程序定义的首屏渲染完成不等同于浏览器的 load 事件。

        2. 小程序启动阶段

        从用户点击访问小程序到小程序首屏渲染完成(首页 Page.onReady 事件触发)。

        3. 打开率/到达率

        小程序首屏渲染完成 PV 与 用户点击访问小程序 PV 的比值。流失率 = 1 - 打开率

        三、启动性能优化

        在启动流程中,小程序代码包准备、开发者代码注入和首页渲染是与开发者相关的,开发者可以进行一定的优化工作。其他部分目前开发者暂时无法干预,框架侧负责进行持续的优化。

        1. 小程序代码包优化

        代码包优化的核心手段是降低代码包大小,代码包大小直接影响了下载耗时,影响用户启动小程序时的体验。

        开发者可以采取以下手段优化代码包大小:

        1.1 分包加载

        使用 分包加载 是优化小程序启动耗时效果最明显的手段。建议开发者按照功能划分,将小程序的功能按使用频率和场景拆分成分包,实现代码包的按需加载。

        分包加载具有以下优势:

        • 承载更多功能:小程序单个代码包的体积上限为 2M,使用分包可以提升小程序代码包总体积上限,承载更多的功能与服务。
        • 降低代码包下载耗时:使用分包后可以显著启动时需要下载的代码包大小,在不影响功能正常使用的前提下明显提升启动耗时。
        • 降低开发者代码注入耗时:小程序启动时会一次性注入全部的开发者代码,使用分包后可以降低注入的代码量,从而降低注入耗时。
        • 降低页面渲染耗时

        此外,结合分包加载的几个扩展功能,可以进一步优化启动耗时:

        分包预下载

        在使用「分包加载」后,虽然能够显著提升小程序的启动速度,但是当用户在使用小程序过程中跳转到分包内页面时,需要等待分包下载完成后才能进入页面,造成页面切换的延迟,影响小程序的使用体验。分包预下载便是为了解决首次进入分包页面时的延迟问题而设计的。

        独立分包

        但小程序中的某些场景(如广告页、活动页、支付页等),通常功能不是很复杂且相对独立,对启动性能有很高的要求。独立分包可以独立于主包和其他分包运行。从独立分包中页面进入小程序时,不需要下载主包。建议开发者将部分对启动性能要求很高的页面放到特殊的独立分包中。

        独立分包和分包预下载可以配合使用,获得更好的效果,详情请参考独立分包与分包预下载教程

        1.2 代码重构和优化

        通过代码重构,降低代码冗余。在使用如 Webpack 等打包工具时,要尽量利用 tree-shaking 等特性去除冗余代码,也要注意防止打包时引入不需要的库和依赖。

        1.3 控制代码包内图片等资源

        避免在代码包中包含或在 WXSS 中使用 base64 内联过多、过大的图片,应尽量采用网络图片。代码包内的图片一般应只包含一些体积较小的图标。声音、视频等其他类型的资源应尽量避免放到代码包中。

        小程序代码包在下载时会使用 ZSTD 算法进行压缩,降低下载时传输的数据量。这些资源文件会占用大量代码包体积,并且通常难以进一步被压缩,对于下载耗时的影响比代码文件大得多。

        1.4 及时清理没有使用到的代码和资源

        在日常开发的时候,我们可能引入了一些新的库文件,而过了一段时间后,由于各种原因又不再使用这个库了,我们常常会只是去掉了代码里的引用,而忘记删掉这类库文件了。

        目前小程序打包是会将工程下所有文件都打入代码包内,也就是说,这些没有被实际使用到的库文件和资源也会被打入到代码包里,从而影响到整体代码包的大小。

        2. 开发者代码注入优化

        开发者代码注入的优化可以从优化执行耗时和优化代码量两部分着手。

        2.1 减少启动过程的同步调用

        在小程序启动流程中,会注入开发者代码并顺序同步执行 App.onLaunch, App.onShow, Page.onLoad, Page.onShow。在小程序初始化代码(Page,App 定义之外的内容)和启动相关的几个生命周期中,应避免执行复杂的计算逻辑或过度使用Sync结尾的同步API,如 wx.getStorageSync,wx.getSystemInfoSync 等。对于 getSystemInfo, getSystemInfoSync 的结果应进行缓存,避免重复调用。

        2.2 使用懒注入

        通常情况下,在小程序启动时,启动页面所在分包和主包(独立分包除外)的所有JS代码会全部合并注入,包括其他未访问的页面以及未用到自定义组件,造成很多没有使用的代码注入到小程序运行环境中,影响注入耗时和内存占用。

        自基础库版本 2.11.1 起,小程序支持仅注入当前页面需要的自定义组件和当前页面代码,以降低小程序的启动时间和运行时内存。开发者可以在 app.json 中配置:

        {  "lazyCodeLoading": "requiredComponents"}

        注意:添加这项配置后,未使用到的代码文件将不被执行。

        3. 页面渲染优化

        3.1 提前首屏数据请求

        大部分小程序在渲染首页时,需要依赖服务端的接口数据,小程序为开发者提供了提前发起数据请求的能力:

        • 数据预拉取:能够在小程序冷启动的时候通过微信后台提前向第三方服务器拉取业务数据,当代码包加载完时可以更快地渲染页面,减少用户等待时间,从而提升小程序的打开速度。
        • 周期性更新:在用户未打开小程序的情况下,也能从服务器提前拉取数据,当用户打开小程序时可以更快地渲染页面,减少用户等待时间。

        3.2 骨架屏

        在页面数据未准备好时(如需要通过网络获取),尽量避免展示空白页面,应先通过骨架屏展示页面的大致结构,请求数据返回后在进行页面更新。以提升用户的等待意愿。

        3.3 缓存请求数据

        小程序提供了wx.setStorage、wx.getStorage等读写本地缓存的能力,数据存储在本地,返回的会比网络请求快。如果开发者基于某些原因无法采用数据预拉取与周期性更新,我们推荐优先从缓存中获取数据来渲染视图,等待网络请求返回后进行更新。

        3.4 精简首屏数据

        我们推荐开发者延迟请求非关键渲染数据,与视图层渲染无关的数据尽量不要放在 data 中,加快页面渲染完成时间。

        四、启动性能分析

        1. 性能数据获取

        1.1 小程序助手「性能分析」板块

        小程序管理后台的性能数据还没有更新,正在规划改版中,建议在改版完成前开发者以小程序助手的性能数据为准。

        建议开发者使用小程序助手中「性能分析」板块,持续关注小程序性能。性能分析从 启动性能、运行性能和网络性能 三个维度提供性能数据,供开发者根据平台、机型、网络环境和访问来源等条件做精细化分析。扫描下方小程序码即可立即体验。

        目前,小程序助手中只包括微信客户端 >= 7.0.3 版本的正式版小程序数据。

        1.2 通过 API 在小程序内获取

        开发者可以在小程序中根据自身业务需有进行性能打点,也可以使用 wx.getPerformance ,获取当前小程序性能相关的信息。

        在获取信息后,开发者可以自行上报或使用 wx.reportPerformance 进行测速。

        1.3 体验评分

        小程序工具中提供了体验评分工具,方便开发者能够及时发现小程序的体验问题。

        2. 影响启动性能的因素

        根据「启动流程」一节介绍的启动流程来看,影响小程序启动耗时的因素众多,分析小程序启动性能是一个比较复杂的过程。

        对于同一个小程序,以下因素会直接影响平均启动耗时:

        • 平台: 不同平台下(安卓、iOS、PC等)设备性能、操作系统、框架实现、优化方案存在较大差异,启动耗时也存在较大的差异。只有分平台比较启动耗时(包括各阶段的耗时)才有意义。
        • 下载比例:代码包下载和更新都会显著影响小程序启动耗时,在其他流程耗时稳定的情况下,下载比例升高会影响大盘启动耗时。
        • 入口页面:不同页面启动时,根据所在分包的不同,需要下载的代码包数量和大小和代码注入量都存在差异。不同页面渲染耗时也存在差异。
        • 机型分布:启动耗时和设备性能有较强关联,不同小程序或使用场景用户群体的差异可能导致机型分布的差异,进而影响大盘启动耗时。
        • 网络环境:网络环境主要影响网络请求的耗时,如小程序信息获取、代码包下载等。

        此外,下列情况也会间接影响启动耗时:

        • 场景/访问来源:不同场景用户访问的页面不同,访问的目的性和自身的等待意愿也有差异,对启动耗时和打开率都有一定影响。
        • 首次访问用户比例:用户首次访问小程序时,需要完整的进行小程序信息准备、代码包下载的流程、代码缓存也需要重新生成,启动耗时会比非首次访问高。
        • 小程序版本更新:小程序版本更新时,用户需要更新小程序信息和代码包,代码缓存也需要重新生成,启动耗时会出现上涨。

        关于「性能分析」板块数据

        小程序助手中提供了启动过程中和开发者相关的下载耗时、js注入耗时和初次渲染耗时供开发者优化参考。

        这里需要注意的是,启动总耗时 ≠ 下载耗时 + js 注入耗时 + 初次渲染耗时。在启动过程中,下载不一定发生,也不一定只下载一个代码包。js 注入耗时和渲染耗时也会受缓存更新而发生波动。

        各阶段耗时的下降不一定反应在总耗时的下降。例如小程序新版本发布后,即使各阶段耗时都下降,下载比例的升高反而可能导致总耗时的上升。

        3. 影响打开率的因素

        启动性能用户的等待意愿是影响打开率的两个关键因素。在部分场景下,如果用户等待意愿较低,即使启动耗时很低,也不一定能获得较高的打开率。


        运行时性能

        setData

        setData 是小程序开发中使用最频繁的接口,也是最容易引发性能问题的接口。在介绍常见的错误用法前,先简单介绍一下 setData 背后的工作原理。

        工作原理

        小程序的视图层目前使用 WebView 作为渲染载体,而逻辑层是由独立的 JavascriptCore 作为运行环境。在架构上,WebView 和 JavascriptCore 都是独立的模块,并不具备数据直接共享的通道。当前,视图层和逻辑层的数据传输,实际上通过两边提供的 evaluateJavascript 所实现。即用户传输的数据,需要将其转换为字符串形式传递,同时把转换后的数据内容拼接成一份 JS 脚本,再通过执行 JS 脚本的形式传递到两边独立环境。

        而 evaluateJavascript 的执行会受很多方面的影响,数据到达视图层并不是实时的。

        常见的 setData 操作错误

        1. 频繁的去 setData

        在我们分析过的一些案例里,部分小程序会非常频繁(毫秒级)的去setData,其导致了两个后果:

        • Android 下用户在滑动时会感觉到卡顿,操作反馈延迟严重,因为 JS 线程一直在编译执行渲染,未能及时将用户操作事件传递到逻辑层,逻辑层亦无法及时将操作处理结果及时传递到视图层;
        • 渲染有出现延时,由于 WebView 的 JS 线程一直处于忙碌状态,逻辑层到页面层的通信耗时上升,视图层收到的数据消息时距离发出时间已经过去了几百毫秒,渲染的结果并不实时;

        2. 每次 setData 都传递大量新数据

        由setData的底层实现可知,我们的数据传输实际是一次 evaluateJavascript 脚本过程,当数据量过大时会增加脚本的编译执行时间,占用 WebView JS 线程,

        3. 后台态页面进行 setData

        当页面进入后台态(用户不可见),不应该继续去进行setData,后台态页面的渲染用户是无法感受的,另外后台态页面去setData也会抢占前台页面的执行。

        图片资源

        目前图片资源的主要性能问题在于大图片和长列表图片上,这两种情况都有可能导致 iOS 客户端内存占用上升,从而触发系统回收小程序页面。

        图片对内存的影响

        在 iOS 上,小程序的页面是由多个 WKWebView 组成的,在系统内存紧张时,会回收掉一部分 WKWebView。从过去我们分析的案例来看,大图片和长列表图片的使用会引起 WKWebView 的回收。

        图片对页面切换的影响

        除了内存问题外,大图片也会造成页面切换的卡顿。我们分析过的案例中,有一部分小程序会在页面中引用大图片,在页面后退切换中会出现掉帧卡顿的情况。

        当前我们建议开发者尽量减少使用大图片资源。


        性能 Trace 工具

        微信 Andoid 6.5.10 开始,我们提供了 Trace 导出工具,开发者可以在开发者工具 Trace Panel 中使用该功能。

        使用方法

        1. PC 上需要先安装 adb 工具,可以参考一些主流教程进行安装,Mac 上可使用 brew 直接安装。
        2. 确定 adb 工具已成功安装后,在开发者工具上打开 Trace Panel,将 Android 手机通过 USB 连接上 PC,点击「Choose Devices」,此时手机上可能弹出连接授权框,请点击「允许」。
        3. 选择设备后,在手机上打开你需要调试的开发版小程序,通过右上角菜单,打开性能监控面板,重启小程序;
        4. 重启后,在小程序上进行操作,完成操作后,通过右上角菜单,导出 Trace 数据;
        5. 此时开发者工具 Trace Panel 上会自动拉取 Trace 文件,选择你要分析的 Trace 文件即可;
        可以通过 adb devices 命令确定设备是否已和 PC 建立起连接

        image

        性能面板

        从微信 6.5.8 开始,我们提供了性能面板让开发者了解小程序的性能。开发者可以在开发版小程序下打开性能面板,打开方法:进入开发版小程序,进入右上角更多按钮,点击「显示性能窗口」。

        image

        性能面板指标说明

        指标说明
        CPU小程序进程的 CPU 占用率,仅 Android 下提供
        内存小程序进程的内存占用(Total Pss),仅 Android 下提供
        启动耗时小程序启动总耗时
        下载耗时小程序包下载耗时,首次打开或资源包需更新时会进行下载
        页面切换耗时小程序页面切换的耗时
        帧率/FPS
        首次渲染耗时页面首次渲染的耗时
        再次渲染耗时页面再次渲染的耗时(通常由开发者的 setData 操作触发)
        数据缓存小程序通过 Storage 接口储存的缓存大小


        体验评分是一项给小程序的体验好坏打分的功能,它会在小程序运行过程中实时检查,分析出一些可能导致体验不好的地方,并且定位出哪里有问题,以及给出一些优化建议。

        运行环境要求

        • 下载并安装 1.02.1808300 或以上版本的开发者工具,下载地址
        • 基础库需要切到 2.2.0 或以上版本。

        使用流程

        1. 打开开发者工具,在详情里切换基础库到 2.2.0 或以上版本。
        2. 在调试器区域切换到 Audits 面板。
        3. 点击”开始“按钮,然后自行操作小程序界面,运行过的页面就会被“体验评分”检测到。

        start

        1. 点击 “停止" 则结束检测,在当前面板显示相应的检测报告,开发者可根据报告中的建议对相应功能进行优化。
        2. 如需再次运行体验评分,可点击报告上方的“清空体验评分”恢复初始状态。请注意,目前系统不提供报告存储服务,一旦清空体验评分,将无法再查看本次评分结果。

        start

        自动运行

        为了方便开发者能够及时发现小程序的体验问题,从开发者工具 1.02.1811150 版本起支持体验评分的 “自动运行” 功能。

        该功能会在开发调试小程序时,实时检查,一旦发现体验分数低于 70 分时,系统会在 console 面板打印一个 warning 信息提示开发者,此时开发者可以切到 Audits 面板查看详情。

        开发者在工具的右上角 “详情” 面板的 本地设置 中勾选 “自动运行体验评分” 选项即可开启。

        autorun

        评分规则

        具体的评分细则和详情的规则说明可参考下列文档:

        1、评分方法


        目前体验评分共有27条规则,共分为三类:性能、体验、最佳实践,满足规则要求得分(100分),否则不得分(0分),最后根据各规则权重和公式计算出总得分。

        权重为0的规则,表示该规则不参与评分,仅作为提示项。开发者可在开发者工具中可以点击“忽略”。各规则的得分条件也可能会随小程序的版本更新有一定的调整。

        权重如下表

        分类规则权重
        性能脚本执行时间7
        首屏时间6
        渲染时间6
        setData调用频率6
        setData数据大小6
        WXML节点数6
        请求耗时5
        网络请求数5
        图片请求数5
        图片缓存4
        图片大小4
        网络请求缓存2
        体验开启惯性滚动8
        避免使用:active伪类来实现点击态8
        保持图片大小比例4
        可点击元素的响应区域3
        iPhone X兼容3
        合理的颜色搭配0
        最佳实践避免JS异常3
        避免网络请求异常3
        废弃接口2
        使用HTTPS1
        避免setData数据冗余1
        最低基础库版本0
        移除不可访问到的页面0
        WXSS使用率0
        及时回收定时器0


        2、性能


        1. 首屏时间

        首屏时间是指用户从打开小程序看到第一屏主要内容的时间,首屏时间太长会导致用户长时间看到的都是白屏,影响使用体验。

        优化首屏时间,可以分为以下几种情况:

        1. 首屏渲染的内容较多,需要集合多份数据进行渲染。这种情况需要开发者把内容分优先级,把优先级高的内容做优先展示,缩短白屏时间;
        2. 首屏内容依赖的数据从服务端请求的时间太长。开发者需要从服务端侧具体分析服务端数据返回的时间长的原因;
        3. 一次性渲染数据太大或依赖的计算过于复杂。减少渲染的数据量、优化渲染相关数据的算法可以解决这类问题。

        得分条件:首屏时间不超过 5 秒

        2. 渲染时间

        渲染时间指的是首次渲染或因数据变化带来的页面结构变化的渲染花费的时间。

        渲染界面的耗时过长会让用户觉得卡顿,体验较差,出现这一情况时,需要校验下是否同时渲染的区域太大(例如列表过长),或渲染依赖的计算是否过于复杂。

        得分条件:渲染时间不超过 500ms

        3. 脚本执行时间

        脚本执行时间是指JS脚本在一次同步执行中消耗的时间,比如生命周期回调、事件处理函数的同步执行时间。

        执行脚本的耗时过长会让用户觉得卡顿,体验较差,出现这一情况时,需要确认并优化脚本的逻辑

        得分条件:一个执行周期内脚本运行时间不超过 1 秒

        4. setData调用频率

        setData接口的调用涉及逻辑层与渲染层间的线程通信,通信过于频繁可能导致处理队列阻塞,界面渲染不及时而导致卡顿,应避免无用的频繁调用。

        得分条件:每秒调用setData的次数不超过 20 次

        5. setData数据大小

        由于小程序运行逻辑线程与渲染线程之上,setData的调用会把数据从逻辑层传到渲染层,数据太大会增加通信时间。

        得分条件:setData的数据在JSON.stringify后不超过 256KB

        6. WXML节点数

        建议一个页面使用少于 1000 个 WXML 节点,节点树深度少于 30 层,子节点数不大于 60 个。一个太大的 WXML 节点树会增加内存的使用,样式重排时间也会更长,影响体验。

        得分条件:页面WXML节点少于 1000 个,节点树深度少于 30 层,子节点数不大于 60 个

        7. 图片缓存

        开启 HTTP 缓存控制后,下一次加载同样的图片,会直接从缓存读取,大大提升加载速度。

        得分条件:所有图片均开启 HTTP 缓存

        8. 图片大小

        图片太大会增加下载时间和内存的消耗,应根据显示区域大小合理控制图片大小。

        得分条件:图片宽高乘积 <= 实际显示宽高乘积 * (设备像素比 ^ 2)

        9. 请求耗时

        请求的耗时太长会让用户一直等待甚至离开,应当优化好服务器处理时间、减小回包大小,让请求快速响应。

        得分条件:所有网络请求都在 1 秒内返回结果

        10. 网络请求数

        短时间内发起太多请求会触发小程序并行请求数量的限制,同时太多请求也可能导致加载慢等问题,应合理控制请求数量,甚至做请求的合并等。

        得分条件:通过wx.request发起的耗时超过 300ms 的请求并发数不超过 10 个

        11. 图片请求数

        短时间内发起太多图片请求会触发浏览器并行加载的限制,可能导致图片加载慢,用户一直处理等待。应该合理控制数量,可考虑使用雪碧图技术或在屏幕外的图片使用懒加载。

        得分条件:同域名耗时超过 100ms 的图片请求并发数不超过 20 个

        12. 网络请求缓存

        发起网络请求总会让用户等待,可能造成不好的体验,应尽量避免多余的请求,比如对同样的请求进行缓存

        得分条件:3 分钟以内同一个url请求不出现两次回包大于 128KB 且一模一样的内容


        3、体验


        1. 开启惯性滚动

        惯性滚动会使滚动比较顺畅,在安卓下默认有惯性滚动,而在 iOS 下需要额外设置-webkit-overflow-scrolling: touch的样式;

        得分条件:wxss中带有overflow: scroll的元素,在 iOS 下需要设置-webkit-overflow-scrolling: touch样式

        2. 避免使用:active伪类来实现点击态

        使用 css :active伪类来实现点击态,很容易触发,并且滚动或滑动时点击态不会消失,体验较差。建议使用小程序内置组件的 'hover-class' 属性来实现

        得分条件:不使用:active伪类,并使用hover-class替换:active

        3. 保持图片大小比例

        图片若没有按原图宽高比例显示,可能导致图片歪曲,不美观,甚至导致用户识别困难。可根据情况设置 image 组件的 mode 属性,以保持原图宽高比。

        得分条件:显示的高/宽与原图的高/宽不超过 15%

        4. 可点击元素的响应区域

        我们应该合理地设置好可点击元素的响应区域大小,如果过小会导致用户很难点中,体验很差。

        得分条件:可点击元素的宽高都不小于 20px

        5. iPhone X 兼容

        对于position: fixed的可交互组件,如果渲染在iPhone X的安全区域外,容易误触 Home Indicator,应当把可交互的部分都渲染到安全区域内。

        建议使用以下wxss进行兼容

        padding-bottom: constant(safe-area-inset-bottom);padding-bottom: env(safe-area-inset-bottom);

        得分条件:position: fixed且高度小于 68px 的可交互组件渲染在安全区域内

        6. 合理的颜色搭配

        文字颜色与背景色需要搭配得当,适宜的颜色对比度可以让用户更好地阅读,提升小程序的用户体验。

        由于颜色搭配的计算方法较为复杂,目前算法还在不断优化中。因此该指标仅作为评分的提醒项,不计入总分中。

        判断标准:

        1. 对于较大字体(font-size >= 24px,或同时满足font-size >= 19px与font-weight >= 700),文字颜色和背景颜色的对比度不小于3

        2. 其他字体,文字颜色和背景颜色的对比度不小于4.5

        对比度计算方法参考W3C标准


        4、最佳实践


        1. 避免JS异常

        出现 JavaScript 异常可能导致程序的交互无法进行下去,我们应当追求零异常,保证程序的高鲁棒性和高可用性。

        得分条件:不出现任何JS异常

        2. 避免网络请求异常

        请求失败可能导致程序的交互无法进行下去,应当保证所有请求都能成功。

        得分条件:所有已授权网络请求都正常返回,未授权网络请求需要给出 401 或 403 这两种状态码

        3. 不使用废弃接口

        使用即将废弃或已废弃接口,可能导致小程序运行不正常。一般而言,接口不会立即去掉,但保险起见,建议不要使用,避免后续小程序突然运行异常。

        得分条件:不使用任何文档中提示废弃的接口

        4. 使用HTTPS

        使用HTTPS,可以让你的小程序更加安全,而HTTP是明文传输的,存在可能被篡改内容的风险

        得分条件:所有网络请求都使用HTTPS

        5. 避免setData数据冗余

        setData操作会引起框架处理一些渲染界面相关的工作,一个未绑定的变量意味着与界面渲染无关,传入setData会造成不必要的性能消耗。

        得分条件:setData传入的所有数据都在模板渲染中有相关依赖

        6. 最低基础库版本

        当使用的组件/API 的支持版本大于配置的线上最低基础库版本时,可能导致相应功能不可用。开发者可通过调整最低基础库版本或在代码上兼容的方式解决该问题。

        由于用户可以通过代码兼容的方式解决该问题,因此该指标仅作为评分的提醒项,不计入总分中。

        判断标准:不存在使用的组件/API 的支持版本大于配置的线上最低基础库版本

        7. 移除不可访问到的页面

        小程序的包大小会影响加载时间,应该尽量控制包体积大小,避免将不会被使用的文件打包进去。

        由于该项指标依赖开发者的操作路径,因此仅作为评分的提醒项,不计入总分中。

        判断标准:不存在访问不到的页面被打包到小程序中

        8. WXSS使用率

        我们应该按需引入 wxss 资源,如果小程序中存在大量未使用的样式,会增加小程序包体积大小,从而在一定程度上影响加载速度。

        由于该项指标依赖开发者的操作路径,因此仅作为评分的提醒项,不计入总分中。

        判断标准:每个 wxss 资源的未使用部分不超过 2KB

        9. 及时回收定时器

        定时器是全局的,并不是跟页面绑定的,当小程序从一个页面路由到另一个页面之后,前一个页面定时器应注意手动回收。

        由于该项指标依赖开发者的操作路径,因此仅作为评分的提醒项,不计入总分中。

        判断标准:所有定时器的回调执行时所在的页面都与设置定时器的页面一致


        基础库版本分布

        更新时间:2020 年 7 月 29 日

        占比低于 0.01% 的版本已隐藏,占比低于 1% 的版本以灰色显示。灰度发布中的版本也会显示。

        基础库版本安卓版本安卓用户占比iOS版本iOS用户占比总体占比
        2.12.07.0.1587.76%7.0.1382.81%86.60%
        2.11.3-0.06%-0.02%0.05%
        2.11.27.0.133.54%7.0.126.51%4.24%
        2.11.0-0.16%--0.12%
        2.10.47.0.95.69%7.0.95.21%5.58%
        2.10.3-0.01%--0.01%
        2.9.57.0.70.62%7.0.71.98%0.94%
        2.9.3-0.02%--0.01%
        2.8.37.0.50.84%7.0.50.87%0.84%
        2.7.77.0.40.42%7.0.40.69%0.49%
        2.6.67.0.30.48%7.0.30.78%0.55%
        2.5.27.0.00.14%7.0.00.29%0.17%
        2.4.46.7.30.13%6.7.30.45%0.20%
        2.3.26.7.20.02%6.7.20.10%0.04%
        2.2.56.6.70.05%6.7.00.10%0.06%
        2.1.3--6.6.70.04%0.01%
        2.0.96.6.60.02%6.6.60.06%0.03%
        1.9.976.6.20.02%6.6.20.04%0.03%
        1.9.96.6.10.01%6.6.10.02%0.01


        兼容

        小程序的功能不断的增加,但是旧版本的微信客户端并不支持新功能,所以在使用这些新能力的时候需要做兼容。

        开发者可以通过以下方式进行低版本的兼容:

        1. 版本号比较

        微信客户端和小程序基础库的版本号风格为 Major.Minor.Patch(主版本号.次版本号.修订版本号)。

        文档中会在组件,API等页面描述中带上各个功能所要求的最低基础库版本号。

        开发者可以在小程序中通过调用 wx.getSystemInfo 或者 wx.getSystemInfoSync 获取到当前小程序运行的基础库的版本号。通过版本号比较的方式进行运行低版本兼容逻辑。

        版本号比较适用于所有情况。部分场景下也可以使用后面提到的方法完成。

        注意:不要直接使用字符串比较的方法进行版本号比较。

        版本号比较可以参考以下代码:

        function compareVersion(v1, v2) {  v1 = v1.split('.')  v2 = v2.split('.')  const len = Math.max(v1.length, v2.length)  while (v1.length < len) {    v1.push('0')  }  while (v2.length < len) {    v2.push('0')  }  for (let i = 0; i < len; i++) {    const num1 = parseInt(v1[i])    const num2 = parseInt(v2[i])    if (num1 > num2) {      return 1    } else if (num1 < num2) {      return -1    }  }  return 0}compareVersion('1.11.0', '1.9.9') // 1
        const version = wx.getSystemInfoSync().SDKVersionif (compareVersion(version, '1.1.0') >= 0) {  wx.openBluetoothAdapter()} else {  // 如果希望用户在最新版本的客户端上体验您的小程序,可以这样子提示  wx.showModal({    title: '提示',    content: '当前微信版本过低,无法使用该功能,请升级到最新微信版本后重试。'  })}

        2. API 存在判断

        对于新增的 API,可以通过判断该API是否存在来判断是否支持用户使用的基础库版本。例如:

        if (wx.openBluetoothAdapter) {  wx.openBluetoothAdapter()} else {  // 如果希望用户在最新版本的客户端上体验您的小程序,可以这样子提示  wx.showModal({    title: '提示',    content: '当前微信版本过低,无法使用该功能,请升级到最新微信版本后重试。'  })}

        3. wx.canIUse

        除了直接通过版本号判断,也可以通过 wx.canIUse 来判断是否可以在该基础库版本下直接使用。例如:

        API 参数或返回值

        对于 API 的参数或者返回值有新增的参数,可以判断用以下代码判断。

        wx.showModal({  success: function(res) {    if (wx.canIUse('showModal.success.cancel')) {      console.log(res.cancel)    }  }})

        组件

        对于组件,新增的组件或属性在旧版本上不会被处理,不过也不会报错。如果特殊场景需要对旧版本做一些降级处理,可以这样子做。

        Page({  data: {    canIUse: wx.canIUse('cover-view')  }})
        <video controls="{{!canIUse}}">  <cover-view wx:if="{{canIUse}}">play</cover-view></video>
        canIUse 的数据文件随基础库进行更新,新版本中的新功能可能出现遗漏的情况,建议开发者在使用时提前测试。

        设置最低基础库版本

        需要 iOS 6.5.8 / 安卓 6.5.7 及以上版本微信客户端支持

        为便于开发者解决低版本基础库无法兼容小程序的新功能的问题,开发者可设置小程序最低基础库版本要求。

        开发者可以登录小程序管理后台,进入「设置 - 基本设置 - 基础库最低版本设置」进行配置。在配置前,开发者可查看近 30 天内访问当前小程序的用户所使用的基础库版本占比,以帮助开发者了解当前用户使用的情况。

        设置后,若用户基础库版本低于设置值,则无法正常打开小程序,并提示用户更新客户端版本。


        实时日志

        背景

        为帮助小程序开发者快捷地排查小程序漏洞、定位问题,我们推出了实时日志功能。从基础库2.7.1开始,开发者可通过提供的接口打印日志,日志汇聚并实时上报到小程序后台。开发者可从小程序管理后台“开发->运维中心->实时日志”进入日志查询页面,查看开发者打印的日志信息。

        如何使用

        1、调用相关接口。打日志的接口是wx.getRealtimeLogManager,为了兼容旧的版本,建议使用如下代码封装一下,例如封装在log.js文件里面:

        var log = wx.getRealtimeLogManager ? wx.getRealtimeLogManager() : nullmodule.exports = {  info() {    if (!log) return    log.info.apply(log, arguments)  },  warn() {    if (!log) return    log.warn.apply(log, arguments)  },  error() {    if (!log) return    log.error.apply(log, arguments)  },  setFilterMsg(msg) { // 从基础库2.7.3开始支持    if (!log || !log.setFilterMsg) return    if (typeof msg !== 'string') return    log.setFilterMsg(msg)  },  addFilterMsg(msg) { // 从基础库2.8.1开始支持    if (!log || !log.addFilterMsg) return    if (typeof msg !== 'string') return    log.addFilterMsg(msg)  }}

        2、在页面的具体位置打印日志:

        var log = require('./log.js') // 引用上面的log.js文件log.info('hello test hahaha') // 日志会和当前打开的页面关联,建议在页面的onHide、onShow等生命周期里面打log.warn('warn')log.error('error')log.setFilterMsg('filterkeyword')log.setFilterMsg('addfilterkeyword')

        完整的例子可以参考代码片段:https://developers.weixin.qq.com/s/i42NbKmp76bJ

        如何查看日志

        登录小程序管理后台,从“开发->运维中心->实时日志”进入日志查询页面。开发者可通过设置时间、微信号/OpenID、页面链接、FilterMsg内容(基础库2.7.3及以上支持setFilterMsg)等筛选条件查询指定用户的日志信息。

        ./log.png

        注意事项

        由于后台资源限制,“实时日志”使用规则如下:

        1. 为了定位问题方便,日志是按页面划分的,某一个页面,在onShow到onHide(切换到其它页面、右上角圆点退到后台)之间打的日志,会聚合成一条日志上报,并且在小程序管理后台上可以根据页面路径搜索出该条日志
        2. 每个小程序账号每天限制500万条日志,日志会保留7天,建议遇到问题及时定位。
        3. 一条日志的上限是5KB,最多包含200次打印日志函数调用(info、warn、error调用都算),所以要谨慎打日志,避免在循环里面调用打日志接口,避免直接重写console.log的方式打日志。
        4. 意见反馈里面的日志,可根据OpenID搜索日志。
        5. setFilterMsg可以设置过滤的Msg。这个接口的目的是提供某个场景的过滤能力,例如 setFilterMsg('scene1'),则在MP上可输入scene1查询得到该条日志。比如上线过程中,某个监控有问题,可以根据FilterMsg过滤这个场景下的具体的用户日志。FilterMsg仅支持大小写字母。如果需要添加多个关键字,建议使用addFilterMsg替代setFilterMsg。

        filtermsg  

        小程序测速

        为帮助开发者优化小程序性能,我们推出了"小程序测速"功能。"小程序测速"可以简单方便地统计小程序内某一事件的实时耗时情况,并可根据地域、运营商、操作系统、网络类型、机型等关键维度进行实时交叉分析。从基础库2.9.2开始,开发者通过“测速上报”接口上报某一指标的耗时情况后,可在小程序管理后台"开发 -运维中心 -小程序测速" 查看各指标耗时趋势,并支持分钟级数据实时查看。

        新建监控 ID

        为了实现对某一指标的耗时监控,开发者需要先定义监控指标。在小程序管理后台 :"开发 -运维中心 -小程序测速"中新建监控 ID,并填写监控指标的名称和解释。

        img

        点击"新建"可以新建 ID ,你需要选择指标类型,并填写指标名称和指标对应的解释。 监控指标分为两类:

        网络请求类: 此类耗时主要受网络环境影响,包含操作系统、运营商、网络环境、地区等统计维度。如:网络 api 耗时、云调用耗时、网络数据读写耗时等。注意此类指标最多可创建20个。

        加载/渲染类:此类耗时主要受设备性能影响,包含操作系统、机型类别等统计维度。可以用来测量页面切换耗时、组件渲染耗时等。 注意此类指标最多可创建20个。

        img

        新建后,可以看到上报需要使用的监控 ID 。

        img

        测速上报

        开发者定义监控ID后,需要在小程序代码中调用 wx.reportPerformance 接口上报耗时数值,才可实现耗时监控:

        上报方法1: 使用 canIUse 进行判断

        // * 需要使用 canIUse 判断接口是否可用if (wx.canIUse('reportPerformance')) {  wx.reportPerformance(id, val)}

        上报方法2:使用 compareVersion 进行判断

        // * 需要先使用 compareVersion 判断接口是否可用const sdkVersion = wx.getSystemInfoSync().SDKVersionif (compareVersion(sdkVersion, '2.9.2') >= 0) {  wx.reportPerformance(id, val)}

        ​id 和 val 均为 uint32 类型,其中 id 为小程序管理后台定义的监控 ID,val 为本次要上报的耗时数值(由开发者自行计算)。接口调用需要基础库的版本号高于 2.9.2,否则在一些低版本基础库可能报错。

        (compareVersion 定义)

        数据观察

        完成代码上报后,可在小程序管理后台"开发 -运维中心 -小程序测速" 查看各指标耗时趋势。目前线上数据约有15分钟数据时延,上报数据保留 7 天,可按照 1 分钟 - 1 小时等不同的时间粒度进行聚合。

        每个指标可以观察到两条曲线,分别为平均值曲线和上报次数曲线。

        ​ img

        ​同时对于不同维度的数据,我们提供了交叉对比功能,以帮助大家快速便捷的完成分析,注意交叉对比的曲线数最多不能超过10条。 img

        ​对于网络请求类指标,我们提供了区域地图,以帮助大家快速的定位区域资源问题。 img

        自定义维度(可选功能)

        对于更复杂的用户场景,用户可能需要将测速数据根据url、页面等维度进行细分,所以我们提供了自定义维度,用户可以将一些业务层面的维度字符串填入至自定义维度中,以方便业务分析。 目前每个指标的自定义纬度值的数量需要限制在50以内(超限制的数据会被丢弃),自定义维度值的长度需要限制在256字节内(超限制的值会被截断)。自定义维度的使用效果如下: img想要使用自定义维度,只需要给wx.reportPerformance加上第三个参数dimensions,即可上报自定义维度:

        wx.reportPerformance(id, value, dimensions)

        (wx.reportPerformance 文档)

        Q&A

        Q : 测速系统可以在哪些场景发挥作用?

        A : 可以测量网络类指标(如网络调用/云调用耗时、网络数据读写速度等)和非网络类指标(页面切换加载速度、组件渲染速度等)。可以查看这些指标在不同维度下的数量分布和性能差异。在一些计算视频首屏时延、帧率等场景也可以发挥作用。

        Q :上报API需要的基础库版本是多少?

        A : 需要基础库版本 2.9.2 以上。在一些低版本基础库上可能报错,后续会支持用 canIUse 接口来进行判断。

        Q: 系统是否可以再测试版使用?上报的时延大概是多少?数据保存的时间是多久?

        A : 可以在测试版使用,目前上报的时延为 15 分钟左右。数据会保存 7 天。

        Q: 我可以定义多少指标 ID?

        A : 单个小程序每个类别可以定义 20 个 ID。


        小程序搜索优化指南

        爬虫访问小程序内页面时,会携带特定的 user-agent "mpcrawler" 及场景值:1129

        判断请求是否来源于官方搜索爬虫的方法:

        签名算法与小程序消息推送接口的签名算法一致。

        参数在请求的header里设置,分别是: X-WXApp-Crawler-Timestamp X-WXApp-Crawler-Nonce X-WXApp-Crawler-Signature

        签名流程如下: 1.将token、X-WXApp-Crawler-Timestamp、X-WXApp-Crawler-Nonce三个参数进行字典序排序 2.将三个参数字符串拼接成一个字符串进行sha1加密 3.开发者获得加密后的字符串可与X-WXApp-Crawler-Signature对比,标识该请求来源于微信

        1. 小程序里跳转的页面 (url) 可被直接打开。

        小程序页面内的跳转url是我们爬虫发现页面的重要来源,且搜索引擎召回的结果页面 (url) 是必须能直接打开,不依赖上下文状态的。 特别的:建议页面所需的参数都包含在url

        2. 页面跳转优先采用navigator组件。

        小程序提供了两种页面路由方式:a. navigator 组件b. 路由 API,包括 navigateTo / redirectTo / switchTab / navigateBack / reLaunch 建议使用 navigator 组件,若不得不使用API,可在爬虫访问时屏蔽针对点击设置的时间锁或变量锁。

        3. 清晰简洁的页面参数。

        结构清晰、简洁、参数有含义的 querystring 对抓取以及后续的分析都有很大帮助,但是将 JSON 数据作为参数的方式是比较糟糕的实现。

        4. 必要的时候才请求用户进行授权、登录、绑定手机号等。

        建议在必须的时候才要求用户授权(比如阅读文章可以匿名,而发表评论需要留名)。

        5. 我们不收录 web-view 中的任何内容。

        我们暂时做不到这一点,长期来看,我们可能也做不到。

        6. 利用 sitemap 配置引导爬虫抓取,同时屏蔽无搜索价值的路径。

        https://www.51coolma.cn/weixinapp/weixinapp-cspq38rh.html

        7. 设置一个清晰的标题和页面缩略图。

        页面标题和缩略图对于我们理解页面和提高曝光转化有重要的作用。 通过 wx.setNavigationBarTitle 或 自定义转发内容 onShareAppMessage 对页面的标题和缩略图设置,另外也为 video、audio 组件补齐 poster / poster-for-crawler 属性。

        8. 使用页面路径推送能力

        可极大丰富微信可以收录的内容,进而提高小程序内容的曝光机会。请参考:

        https://www.51coolma.cn/weixinapp/weixinapp-it7838x9.html


        商品数据接入(内测)

        商品数据应用场景

        商品数据目前应用于 微信扫一扫识物功能、小程序商品搜索功能 和 扫条码 三个功能。 这些功能可以很好的满足微信用户对商品的信息获取诉求,同时也能为商家小程序带来曝光流量和建立用户品牌认知的机会。

        扫一扫识物- 效果图

         

        小程序商品搜索- 效果图

         

        扫一扫商品条码- 效果图

        商品数据接入

        目前微信已经爬得部分商品详情页,并对页面的商品信息进行了一定的分析理解。商家小程序可以配合接入商品数据,帮助微信更好地发现更多更丰富的商品信息,提高商品的曝光机会。

        成功接入需要完成以下三步:

        第一步:开启「爬虫开关」

        确保爬虫开关处于开启状态,保证小程序页面内容获得被微信收录的机会。爬虫开关在微信公众平台上设置,可参考如下示意图。

        第二步:推送「页面路径」

        通过接口主动推送商品详情页的页面路径至微信后台,保证推送页面被微信爬虫及时发现,获得曝光机会。具体参考:小程序search.submitPages接口文档

        第三步:接入「数据更新协议」

        接入数据更新协议,可支持微信实时的获取到商品的价格、上下架状态等最新信息,避免由于信息不准确而影响商品的曝光效果。

        具体参考文档: 小程序商品数据实时更新文档

        完成以上三步后,商家小程序的商品详情页将被收录,获得在“扫一扫识物功能”、“小程序商品搜索功能”和“扫条码”的曝光机会。

        此外,我们建议商家小程序还可继续标记页面结构化内容和优化页面结构:

        一、标记「页面结构化内容」

        通过对页面结构化内容的标记,帮助微信爬虫更好的理解页面信息,提高页面的召回排序精准度和曝光转化率。具体参考:页面标记商品结构化数据文档

        二、优化页面结构设计

        基于小程序搜索优化指南,优化页面结构设计,提高页面对爬虫的友好度。具体参考:小程序SEO建议

        如本文档版本过旧,请访问Git查看最新版本:点我


        小程序直播

        小程序直播是微信官方提供的商家经营工具。通过调用该组件,商家可以在小程序中实现直播互动与商品销售闭环。

        按照下面的使用说明接入,在你的小程序中引入直播组件即可实现直播功能。使用过程中如遇到问题,可在小程序直播社区发帖交流。

        使用方法说明

        1. 【直播组件】如何引入

        版本限制:微信客户端版本 7.0.7 及以上(基础库版本2.9.x及以上支持同层渲染)可以观看直播及使用直播间的功能,低版本刚进入直播间时会提示用户升级微信客户端版本(低版本只能观看直播,无法使用直播间的功能)。

        支持在主包或分包内引入【直播组件】 live-player-plugin 代码包(注:直播组件不计入代码包体积),项目根目录的 app.json 引用,示例代码如下:

        (1) 主包引入

        "plugins": {    "live-player-plugin": {        "version": "1.1.4", // 注意填写该直播组件最新版本号,微信开发者工具调试时可获取最新版本号(复制时请去掉注释)        "provider": "wx2b03c6e691cd7370" // 必须填该直播组件appid,该示例值即为直播组件appid(复制时请去掉注释)    }}

        (2) 分包引入

        "subpackages": [    {        "plugins": {            "live-player-plugin": {                "version": "1.1.4", // 注意该直播组件最新版本号,微信开发者工具调试时可获取最新版本号(复制时请去掉注释)                "provider": "wx2b03c6e691cd7370" // 必须填该直播组件appid,该示例值即为直播组件appid(复制时请去掉注释)            }        }    }]

        2. 【直播组件】如何使用

        按第1步的方法把组件代码包配置引入后,即可直接通过链接地址跳转到直播组件页面(即为进直播间页面)链接地址需要带上直播房间 id;房间 id 可通过下面 获取直播房间列表 API 获取。

        示例代码如下:

        (1) 使用 navigator 组件跳转进入直播间

        index.js
        let roomId = [直播房间id] // 填写具体的房间号,可通过下面【获取直播房间列表】 API 获取let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数(如示例中的path和pid参数),后续可以在分享卡片链接和跳转至商详页时获取,详见【获取自定义参数】、【直播间到商详页面携带参数】章节(上限600个字符,超过部分会被截断)this.setData({    roomId,    customParams})
        index.wxml
        <navigator url="plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id={{roomId}}&custom_params={{customParams}}"></navigator>// 其中wx2b03c6e691cd7370是直播组件appid不能修改

        (2) 使用 navigateTo 方法跳转进入直播间

        index.js
        let roomId = [直播房间id] // 填写具体的房间号,可通过下面【获取直播房间列表】 API 获取let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数(如示例中的path和pid参数),后续可以在分享卡片链接和跳转至商详页时获取,详见【获取自定义参数】、【直播间到商详页面携带参数】章节(上限600个字符,超过部分会被截断)wx.navigateTo({    url: `plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=${roomId}&custom_params=${customParams}`})// 其中wx2b03c6e691cd7370是直播组件appid不能修改

        通过该链接可跳转到直播组件页面(当前页面入口仅开放‘live-player-plugin’)。

        示例效果图如下:

        直播组件页面

        直播组件和接口

        【组件接口】

        通过在主包/分包中引入直播组件,开发者可以很方便的实现订阅、获取直播状态、获取用户openid以及获取分享卡片链接参数等功能。

        【服务端接口】

        服务端接口包含直播间接口和商品管理接口。

        • 直播间管理接口是小程序直播提供给开发者对直播间进行批量操作的接口能力。开发者可以批量创建直播间,获取回放源视频,获取直播间列表等。
        • 商品管理接口是小程序直播提供给开发者对直播商品进行批量操作的接口能力。开发者可以对商品批量进行添加、提审、删除以及更新等操作。
        类别名称功能说明
        组件接口订阅组件 subscribe用户进入直播间内,可对一场未开播的直播进行单次订阅,开播时直播组件会自动下发开播提醒给用户
        获取直播状态  getLiveStatus首次获取立马返回直播状态,往后间隔1分钟或更慢的频率去轮询获取直播状态
        获取用户openid参数getOpenid在直播组件版本 1.1.4 及以上版本通过该接口获取用户openid参数
        获取分享卡片链接参数getShareParams在直播组件版本 1.1.4 及以上版本通过该接口获取以下参数,开发者可以根据这些参数建立用户、直播间、商品之间的映射关系
        直播小窗控制参数 close_picture_in_picture_mode通过参数设置是否关闭小窗
        携带参数( 直播间到商详页面, 从群分享卡片返回直播间直播组件版本 1.1.4 及以上支持携带以下参数,可用这些参数建立用户、直播间、商品之间的映射关系。
        服务端接口创建直播间该接口可直接创建直播间,创建成功后直播间将在直播间列表展示
        后台获取直播房间列表该接口可获取直播房间列表
        后台获取回放源视频该接口可在直播结束后拿到回放源视频
        往指定直播间导入已入库商品调用此接口往指定直播间导入已入库的商品
        商品添加并提审调用此接口上传并提审需要直播的商品信息,审核通过后商品录入【小程序直播】商品库
        撤回商品审核调用此接口,可撤回直播商品的提审申请,消耗的提审次数不返还
        重新提交商品审核调用此接口可以对已撤回提审的商品再次发起提审申请
        删除商品调用此接口,可删除【小程序直播】商品库中的商品,删除后直播间上架的该商品也将被同步删除,不可恢复
        更新商品调用此接口可以更新商品信息,审核通过的商品仅允许更新价格类型与价格,审核中的商品不允许更新,未审核的商品允许更新所有字段, 只传入需要更新的字段
        获取商品状态调用此接口可获取商品的信息与审核状态
        获取商品列表调用此接口可获取商品列表


        【小程序直播】直播间管理接口

        名称功能说明
        创建直播间该接口可直接创建直播间,创建成功后直播间将在直播间列表展示
        获取直播房间列表该接口可获取直播房间列表
        获取直播间回放该接口可在直播结束后拿到回放源视频
        直播间导入商品调用此接口往指定直播间导入已入库的商品

        一、简介

        直播间管理接口,是小程序直播提供给开发者对直播房间进行批量操作的接口能力。 开发者可以创建直播间、获取直播间信息、获取直播间回放以及往直播间导入商品。

        二、接口文档

        1.创建直播间

        接口说明:

        调用此接口创建直播间,创建成功后将在直播间列表展示

        调用频率

        调用额度:10000次/一天

        请求方式

        POST

        请求URL

        https://api.weixin.qq.com/wxaapi/broadcast/room/create?access_token=

        请求参数示例: json

        {      name: "测试直播房间1",  // 房间名字      coverImg: "",   // 通过 uploadfile 上传,填写 mediaID      startTime: 1588237130,   // 开始时间      endTime: 1588237130 , // 结束时间      anchorName: "zefzhang1",  // 主播昵称      anchorWechat: "WxgQiao_04",  // 主播微信号      shareImg: "" ,  //通过 uploadfile 上传,填写 mediaID      type: 1 , // 直播类型,1 推流 0 手机直播      screenType: 0,  // 1:横屏 0:竖屏      closeLike: 0 , // 是否 关闭点赞 1 关闭      closeGoods: 0, // 是否 关闭商品货架,1:关闭      closeComment: 0 // 是否开启评论,1:关闭}

        请求参数含义

        参数类型必填说明
        nameString直播间名字,最短3个汉字,最长17个汉字,1个汉字相当于2个字符
        coverImgString背景图,填入mediaID(mediaID获取后,三天内有效);图片mediaID的获取,请参考以下文档: https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html;直播间背景图,图片规则:建议像素1080*1920,大小不超过2M
        startTimeNumber直播计划开始时间(开播时间需要在当前时间的10分钟后 并且 开始时间不能在 6 个月后)
        endTimeNumber直播计划结束时间(开播时间和结束时间间隔不得短于30分钟,不得超过24小时)
        anchorNameString主播昵称,最短2个汉字,最长15个汉字,1个汉字相当于2个字符
        anchorWechatString主播微信号,如果未实名认证,需要先前往“小程序直播”小程序进行实名验证, 小程序二维码链接:https://res.wx.qq.com/op_res/BbVNeczA1XudfjVqCVoKgfuWe7e3aUhokktRVOqf_F0IqS6kYR--atCpVNUUC3zr
        subAnchorWechatString主播副号微信号,如果未实名认证,需要先前往“小程序直播”小程序进行实名验证, 小程序二维码链接:https://res.wx.qq.com/op_res/BbVNeczA1XudfjVqCVoKgfuWe7e3aUhokktRVOqf_F0IqS6kYR--atCpVNUUC3zr
        createrWechatString创建者微信号
        shareImgString分享图,填入mediaID(mediaID获取后,三天内有效);图片mediaID的获取,请参考以下文档: https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html;直播间分享图,图片规则:建议像素800*640,大小不超过1M;
        feedsImgString购物直播频道封面图,填入mediaID(mediaID获取后,三天内有效);图片mediaID的获取,请参考以下文档: https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html; 购物直播频道封面图,图片规则:建议像素800*800,大小不超过100KB;
        isFeedsPublicNumber是否开启官方收录 【1: 开启,0:关闭】,默认开启收录
        typeNumber直播间类型 【1: 推流,0:手机直播】
        screenTypeNumber横屏、竖屏 【1:横屏,0:竖屏】(横屏:视频宽高比为16:9、4:3、1.85:1 ;竖屏:视频宽高比为9:16、2:3)
        closeLikeNumber是否关闭点赞 【0:开启,1:关闭】(若关闭,直播开始后不允许开启)
        closeGoodsNumber是否关闭货架 【0:开启,1:关闭】(若关闭,直播开始后不允许开启)
        closeCommentNumber是否关闭评论 【0:开启,1:关闭】(若关闭,直播开始后不允许开启)
        closeReplayNumber是否关闭回放 【0:开启,1:关闭】默认关闭回放
        closeShareNumber是否关闭分享 【0:开启,1:关闭】默认开启分享(直播开始后不允许修改)
        closeKfNumber是否关闭客服 【0:开启,1:关闭】 默认关闭客服

        正确返回示例

        {    "roomId": 33, //房间ID    "errcode": 0} 

        返回参数含义

        参数说明
        roomId房间ID
        qrcode_url"小程序直播" 小程序码

        2.获取直播间列表

        接口说明

        调用此接口获取直播间列表及直播间信息

        调用频率

        调用额度:100000次/一天(与获取回放接口共用次数)

        请求方式

        POST

        请求URL

        https://api.weixin.qq.com/wxa/business/getliveinfo?access_token=

        请求参数示例: json

        {    "start": 0, // 起始拉取房间,start = 0 表示从第 1 个房间开始拉取    "limit": 10 // 每次拉取的个数上限,不要设置过大,建议 100 以内}

        请求参数含义

        参数类型必填说明
        startNumber起始房间,0表示从第1个房间开始拉取
        limitNumber每次拉取的房间数量,建议100以内

        正确返回示例

        {    "errcode": 0,    // 错误码,0代表成功,1代表未创建直播间    "errmsg": "ok"   // 错误信息    "room_info":[{        "name":"直播房间名"        "roomid": 1,        "cover_img":"http://http://mmbiz.qpic.cn/mmbiz_jpgRl1RuuhdstSfZa8EEljedAYcbtX3Ejpdl2et1tPAQ37bdicnxoVialDLCKKDcPBy8Iic0kCiaiaalXg3EbpNKoicrweQ/0?wx_fmt=jpeg",        "share_img":"http://http://mmbiz.qpic.cn/mmbiz_jpgRl1RuuhdstSfZa8EEljedAYcbtX3Ejpdl2et1tPAQ37bdicnxoVialDLCKKDcPBy8Iic0kCiaiaalXg3EbpNKoicrweQ/0?wx_fmt=jpeg",        "live_status": 101,        "start_time": 1568128900,        "end_time": 1568131200,        "anchor_name":"里斯",        "goods":[{             "cover_img":"http://http://mmbiz.qpic.cn/mmbiz_jpg/Rl1RuuhdstSfZa8EEljedAYcbtX3Ejpdl2et1tPAQ37bdicnxoVialDLCKKDcPBy8Iic0kCiaiaalXg3EbpNKoicrweQ/0?wx_fmt=jpeg",             "url":"pages/index/index.html",             "price":1100,             "name":"茶杯"}],        "total":1    }]}

        返回参数含义

        房间参数

        参数说明
        name直播间名称
        roomid直播间ID
        cover_img直播间背景图链接
        share_img直播间分享图链接
        live_status直播间状态。101:直播中,102:未开始,103已结束,104禁播,105:暂停,106:异常,107:已过期
        start_time直播间开始时间,列表按照start_time降序排列
        end_time直播计划结束时间
        anchor_name主播名
        total拉取房间总数

        商品参数

        参数说明
        cover_img商品封面图链接
        url商品小程序路径
        price商品价格
        name商品名称

        3.获取直播间回放

        接口说明

        调用接口获取已结束直播间的回放源视频(一般在直播结束后10分钟内生成,源视频无评论等内容)

        调用频率

        调用额度:100000次/一天

        请求方法

        POST

        请求URL

        https://api.weixin.qq.com/wxa/business/getliveinfo?access_token=

        请求参数示例: json

        {     "action": "get_replay",       "room_id": 354,        "start": 0,        "limit": 10        }

        请求参数含义

        参数类型必填说明
        actionString获取回放
        room_idNumber直播间ID
        startNumber起始拉取视频,0表示从第一个视频片段开始拉取
        limitNumber每次拉取的数量,建议100以内

        正确返回示例

        {     "live_replay":[{         "expire_time":"",         "create_time":"",         "media_url":""      }],      "errcode": 0,      "total": 1,      "errmsg":"ok"}

        返回参数含义

        参数说明
        expire_time回放视频url过期时间
        create_time回放视频创建时间
        media_url回放视频链接
        total回放视频片段个数

        4.直播间导入商品

        接口说明

        调用接口往指定直播间导入已入库的商品

        调用频率

        调用额度:10000次/一天

        请求方法

        POST

        请求URL

        https://api.weixin.qq.com/wxaapi/broadcast/room/addgoods?access_token=

        请求参数示例: json

        {    "ids": [1150, 1111],  // 数组列表,可传入多个,里面填写 商品 ID    "roomId": 2554}

        请求参数含义

        参数类型必填说明
        idsArray<Number>数组列表,可传入多个,里面填写 商品 ID
        roomIdNumber房间ID

        正确返回示例

        {   "errcode": 0 // 0:成功}

        附录:错误码

        -1:系统错误

        1:未创建直播间

        1003:商品id不存在

        47001:入参格式不符合规范

        200002:入参错误

        300001:禁止创建/更新商品 或 禁止编辑&更新房间

        300002:名称长度不符合规则

        300006:图片上传失败(如:mediaID过期)

        300022:此房间号不存在

        300023:房间状态 拦截(当前房间状态不允许此操作)

        300024:商品不存在

        300025:商品审核未通过

        300026:房间商品数量已经满额

        300027:导入商品失败

        300028:房间名称违规

        300029:主播昵称违规

        300030:主播微信号不合法

        300031:直播间封面图不合规

        300032:直播间分享图违规

        300033:添加商品超过直播间上限

        300034:主播微信昵称长度不符合要求

        300035:主播微信号不存在

        300036: 主播微信号未实名认证

        300037:购物直播频道封面图不合规

        300038:未在小程序管理后台配置客服

        300039:主播副号微信号不合法

        300040:名称含有非限定字符(含有特殊字符)

        300041:创建者微信号不合法

        9410000: 直播间列表为空

        9410001: 获取房间失败

        9410002: 获取商品失败

        9410003: 获取回放失败


        【小程序直播】直播商品管理接口

        名称功能说明
        商品添加并提审调用此接口上传并提审需要直播的商品信息,审核通过后商品录入【小程序直播】商品库
        撤回商品审核调用此接口,可撤回直播商品的提审申请,消耗的提审次数不返还
        重新提交商品审核调用此接口可以对已撤回提审的商品再次发起提审申请
        删除商品调用此接口,可删除【小程序直播】商品库中的商品,删除后直播间上架的该商品也将被同步删除,不可恢复
        更新商品调用此接口可以更新商品信息,审核通过的商品仅允许更新价格类型与价格,审核中的商品不允许更新,未审核的商品允许更新所有字段, 只传入需要更新的字段
        获取商品状态调用此接口可获取商品的信息与审核状态
        获取商品列表调用此接口可获取商品列表

        一、简介

        直播商品管理接口,是小程序直播提供给开发者对直播商品进行批量操作的接口能力。

        开发者可以对商品批量进行添加、提审、删除以及更新等操作。

        接口仅支持对通过接口添加的商品进行操作,开发者在小程序管理后台添加的商品,不支持通过接口操作。

        开发者必须保存【商品ID】与【审核单ID】,如果丢失,则无法调用其他相关接口。

        二、接口文档

        1.商品添加并提审

        接口说明

        调用此接口上传并提审需要直播的商品信息,审核通过后商品录入【小程序直播】商品库

        注意:开发者必须保存【商品ID】与【审核单ID】,如果丢失,则无法调用其他相关接口

        调用频率

        调用额度:500次/一天

        请求方法

        POST

        请求URL

        https://api.weixin.qq.com/wxaapi/broadcast/goods/add?access_token=

        请求参数示例: json

        {        "goodsInfo": {                       "coverImgUrl": "ZuYVNKk9sMP1X4m7FXdcDCKra251KDZTjS502UTV7gwalgLZXcrOhG6oNYX6c7AR",                 "name":"TIT茶杯",               "priceType":1,            "price":99.5,         // "price2": 150.5, priceType为2或3时必填         "url":"pages/index/index"      }}

        请求参数含义

        参数类型必填说明
        coverImgUrlString填入mediaID(mediaID获取后,三天内有效);图片mediaID的获取,请参考以下文档: https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html;图片规则:图片尺寸最大300像素*300像素;
        nameString商品名称,最长14个汉字,1个汉字相当于2个字符
        priceTypeNumber价格类型,1:一口价(只需要传入price,price2不传) 2:价格区间(price字段为左边界,price2字段为右边界,price和price2必传) 3:显示折扣价(price字段为原价,price2字段为现价, price和price2必传)
        priceNumber数字,最多保留两位小数,单位元
        price2Number数字,最多保留两位小数,单位元
        urlString商品详情页的小程序路径,路径参数存在 url 的,该参数的值需要进行 encode 处理再填入

        正确返回示例

        {      "goodsId": 51,    "auditId": 525022786,    "errcode": 0 }

        返回参数含义

        参数说明
        goodsId商品ID
        auditId审核单ID

        2.撤回审核

        接口说明

        调用此接口,可撤回直播商品的提审申请,消耗的提审次数不返还

        调用频率

        调用额度:500次/一天

        请求方法

        POST

        请求URL

        https://api.weixin.qq.com/wxaapi/broadcast/goods/resetaudit?access_token=

        请求参数示例: json

        {        "auditId": 525022184,    "goodsId": 9}

        请求参数含义

        参数类型必填说明
        goodsIdNumber商品ID
        auditIdNumber审核单ID

        正确返回示例

        {      "errcode": 0 }

        3.重新提交审核

        接口说明

        调用此接口可以对已撤回提审的商品再次发起提审申请

        调用频率

        调用额度:500次/一天(与接口1共用500次限制)

        请求方法

        POST

        请求URL

        https://api.weixin.qq.com/wxaapi/broadcast/goods/audit?access_token=

        请求参数示例: json

        {        "goodsId": 9}

        请求参数含义

        参数类型必填说明
        goodsIdNumber商品ID

        正确返回示例

        {      "errcode": 0,    "auditId": 525022184}

        返回参数含义

        参数说明
        auditId审核单ID

        4.删除商品

        接口说明

        调用此接口,可删除【小程序直播】商品库中的商品,删除后直播间上架的该商品也将被同步删除,不可恢复;

        调用频率

        调用额度:1000次/一天

        请求方法

        POST

        请求URL

        https://api.weixin.qq.com/wxaapi/broadcast/goods/delete?access_token=

        请求参数示例: json

        {        "goodsId": 9}

        请求参数含义

        参数类型必填说明
        goodsIdNumber商品ID

        返回参数

        {       "errcode": 0,   }

        5.更新商品

        接口说明

        调用此接口可以更新商品信息,审核通过的商品仅允许更新价格类型与价格,审核中的商品不允许更新,未审核的商品允许更新所有字段, 只传入需要更新的字段。

        调用频率

        调用额度:1000次/一天

        请求方法

        POST

        请求URL

        https://api.weixin.qq.com/wxaapi/broadcast/goods/update?access_token=

        请求参数示例: json

        {        "goodsInfo": {                // 需要更新哪个字段就传入哪个字段,goodsId 必传                "coverImgUrl": "ZuYVNKk9sMP1X4m7FXdcDCKra251KDZTjS502UTV7gwalgLZXcrOhG6oNYX6c7AR",                "name":"TIT茶杯",                "priceType":1,        "price":99.5,        // "price2": 150.5, priceType为2或3时必填        "url": "pages/index/index",               "goodsId": 9         }}

        请求参数含义

        参数类型必填说明
        coverImgUrlString填入mediaID(mediaID获取后,三天内有效);图片mediaID的获取,请参考以下文档: https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html;图片规则:图片尺寸最大300像素*300像素;
        nameString商品名称,最长14个汉字,1个汉字相当于2个字符
        priceTypeNumber价格类型,1:一口价(只需要传入price,price2不传) 2:价格区间(price字段为左边界,price2字段为右边界,price和price2必传) 3:显示折扣价(price字段为原价,price2字段为现价, price和price2必传)
        priceNumber数字,最多保留两位小数,单位元
        price2Number数字,最多保留两位小数,单位元
        urlString商品详情页的小程序路径,路径参数存在 url 的,该参数的值需要进行 encode 处理再填入
        goodsIdNumber商品ID

        返回参数

        {       "errcode": 0,   }

        6.获取商品状态

        接口说明

        调用此接口可获取商品的信息与审核状态

        调用频率

        调用额度:1000次/一天

        请求方法

        POST

        请求URL

        https://api.weixin.qq.com/wxa/business/getgoodswarehouse?access_token=

        请求参数示例: json

        {​    "goods_ids": [1]}

        请求参数含义

        参数类型必填说明
        goods_idsArray<Number>商品ID

        返回参数

        {​    "errcode":0,​    "errmsg":"ok",​    "goods":​        [​            {​                "goods_id":9,​                "cover_img_url":"xxxx",​                "name":"xxxxx"​                "price":12300,​                "url":"xxxxxxx",​                "price_type":1,​                "price2":0,​                "audit_status":1,​                "third_party_tag":0​            }​        ],​    "total":0}

        返回参数含义

        参数说明
        goods_id商品ID
        name商品名称
        cover_img_url商品图片url
        url商品详情页的小程序路径
        priceType1:一口价,此时读price字段; 2:价格区间,此时price字段为左边界,price2字段为右边界; 3:折扣价,此时price字段为原价,price2字段为现价;
        price价格左区间,单位“元”
        price2价格右区间,单位“元”
        audit_status0:未审核,1:审核中,2:审核通过,3审核失败
        third_party_tag1、2:表示是为 API 添加商品,否则是直播控制台添加的商品
        total商品个数

        7.获取商品列表

        接口说明

        调用此接口可获取商品列表

        调用频率

        调用额度:10000次/一天

        请求方法

        GET

        请求URL

        https://api.weixin.qq.com/wxaapi/broadcast/goods/getapproved?access_token=[access_token]

        URL query 参数

        参数类型必填说明
        offsetNumber分页条数起点
        limitNumber分页大小,默认30,不超过100
        statusNumber商品状态,0:未审核。1:审核中,2:审核通过,3:审核驳回

        返回参数

        {​    "errcode":0,​    "total":68,​    "goods":​        [​            {​                "goodsId":9,​                "coverImgUrl":"xxxx",​                "name":"xxxxx"​                "price":12300,​                "url":"xxxxxxx",​                "priceType":1,​                "price2":0,​                "thirdPartyTag":0​            }​        ]}

        返回参数含义

        参数说明
        total商品数量
        goodsId商品ID
        coverImgUrl商品图片链接
        name商品名称
        price价格左区间,单位“元”
        price2价格右区间,单位“元”
        url商品小程序路径
        priceType1:一口价,此时读price字段; 2:价格区间,此时price字段为左边界,price2字段为右边界; 3:折扣价,此时price字段为原价,price2字段为现价;
        thirdPartyTag1、2:表示是为 API 添加商品,否则是直播控制台添加的商品

        附录:错误码

        -1:系统错误

        1003:商品id不存在

        47001:入参格式不符合规范

        200002:入参错误

        300001:禁止创建/更新商品(如:商品创建功能被封禁)

        300002:名称长度不符合规则

        300003:价格输入不合规(如:现价比原价大、传入价格非数字等)

        300004:商品名称存在违规违法内容

        300005:商品图片存在违规违法内容

        300006:图片上传失败(如:mediaID过期)

        300007:线上小程序版本不存在该链接

        300008:添加商品失败

        300009:商品审核撤回失败

        300010:商品审核状态不对(如:商品审核中)

        300011:操作非法(API不允许操作非API创建的商品)

        300012:没有提审额度(每天500次提审额度)

        300013:提审失败

        300014:审核中,无法删除(非零代表失败)

        300017:商品未提审

        300021:商品添加成功,审核失败


        其他能力

        1、 直播间小程序码

        说明:

        • 小程序引入直播组件后必须进行一次小程序发布上线,否则直播间的小程序码不生效,具体表现是用户扫码进入直播间会显示“页面不存在”。
        • 在 MP 小程序直播后台创建好直播间后,可以直接拿到直播间分享小程序码,无需额外开发

        如果商家在后台自己生成的直播间小程序码,需要做以下配置: 在跳转进入直播间的路径加上 type = 9 标识场景入口为小程序码: "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=9"。 若需要带上自定义参数则还需要加上 custom_params: "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=9&custom_params=encodeURIComponent(JSON.stringify(custom_params))"。

        2、 商家公众号文章添加小程序卡片

        说明:

        商家在公众号文章中添加跳转进入直播间的小程序卡片时,需要做以下配置: 在跳转进入直播间的路径加上 type = 10 标识场景入口为小程序卡片: "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=10"。 若需要带上自定义参数则还需要加上 custom_params: "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=10&custom_params=encodeURIComponent(JSON.stringify(custom_params))"。

        3、 商品详情页注意事项

        (1)添加返回按钮: 点击直播组件页面里的货架商品跳转到商家小程序的商品详情页面后,为了避免用户无法再返回直播间,商家需在小程序商品详情页面左上角加上返回按钮,通过wx.navigateBack返回到直播组件页面。

        (2)不建议使用wx.switchTab:若在商品详情页点击按钮(如购物车按钮等)通过wx.switchTab跳转到tabbar页,然后再点小窗回到直播间时会出现页面卡死问题(微信客户端7.0.15版本才修复)。此时可把页面改为非tabbar页并通过wx.navigateTo跳转,也可通过关闭小窗来解决该问题。

        (3)不建议使用wx.reLaunch:若在商品详情页及之后的页面元素上使用wx.reLaunch跳转,不仅会关闭小窗,而且无法返回到上一页,体验不好。

        4、 快速更新直播组件版本的方法

        商家小程序对应的管理员微信号收到【公众平台安全助手】下发的直播组件版本更新的服务通知后,可点击通知进行快速发布,移动端即可快速更新小程序内直播组件的新版本,无需修改代码或重新提交审核。

        服务通知如下图所示:

        直播组件页面

        5、 直播小窗

        版本限制:直播组件版本 1.1.4 及以上支持通过以下参数设置是否关闭小窗。

        close_picture_in_picture_mode:默认支持直播小窗,可通过close_picture_in_picture_mode=1关闭小窗功能,如 "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=直播房间号&close_picture_in_picture_mode=1"。

        6、 携带参数

        版本限制:直播组件版本 1.1.4 及以上支持携带以下参数,开发者可以根据这些参数建立用户、直播间、商品之间的映射关系。

        (1) shareTicket:分享直播间卡片到微信群,点击此卡片后可以在 App onShow 里获取该参数(默认不可获取该参数,可在跳转直播间页面路径上配置 open_share_ticket=1 打开 shareTicket,如 "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=直播房间号&open_share_ticket=1",但长按分享卡片时不能转发。)

        (2) room_id + openid + share_openid + custom_params :点击直播间里的货架商品跳转到商家小程序的商品详情页或点击直播间左上角首页icon跳转到商家小程序的首页时,可以在Page onLoad options里获取房间号、用户openid、分享者share_openid(如果是从分享卡片进入直播间再跳转到商详页才有该参数)、开发者携带的自定义参数custom_params


        仿原生乘车码

        业务方可通过接入仿原生乘车码行业模板,在业务方小程序中快速实现公共交通的线上扫码乘车功能,以及开通线路、乘车记录、帮助中心等相关页面。仿原生乘车码行业模板包括以下接口(在调用前需先完成小程序账号注册、微信支付商户号申请流程,并向 city_api@tencent.com 发送接入仿原生乘车码行业模板能力的申请邮件):

        API名称API描述
        仿原生跳转根据需求不同跳转不同的微信仿原生页面实现不同的功能需求。
        生码微信后台向业务方请求二维码源数据,微信前端可以根据源数据生成乘车码。
        支付回调微信后台向业务方请求二维码源数据,微信前端可以根据源数据生成乘车码。
        微信扣费用于接收业务方依据扫码接口获取到的信息对用户进行免密扣费。
        用户注册/签约微信后台向业主方发起用户注册。
        用户解约微信后台向业主方通知用户注销/解约。
        用户签约状态查询业主方查询用户签约状态接口。
        欠费支付微信后台向业主方通知用户支付成功(支付失败时无通知)。
        查询线路查询设置的公交/地铁线路
        设置线路设置公交/地铁线路
        查询欠费用户列表微信后台会定时(每天6点开始)获取所有欠费用户列表,并提供接口查询列表接口,此后如果有用户完成欠费缴纳会在收到成功支付通知时删除记录。

        仿原生跳转

        根据需求不同跳转不同的微信仿原生页面实现不同的功能需求。

        1、 请求参数

        参数名称类型必选备注
        path_typeintY需要跳转的页面 0 - 新用户首页/欢迎页(开通乘车码,包含“成功开通乘车码”
        1 - 乘车码页 2 - 已开通路线 3 - 个人中心 4 - 我的乘车记录 5 - 帮助 6 - 欠费记录

        注意:请求参数为json格式。

        2、 返回参数

        参数名称类型必选备注
        errcodeintY返回码
        errmsgstringY返回信息
        business_typestringY业务类型
        query_stringstringY调用仿原生小程序时使用的参数
        expire_atintY返回query_string的到期时间(uinx时间戳)

        3、 示例代码

        请求:

        https://api.weixin.qq.com/intp/transportcode/getbusinessview?access_token=ACCESSTOKEN

        请求参数:

        {"path_type":1}

        返回:

        {    "errcode":0,    "errmsg":"ok",    "business_type":"wxCity",    "query_string":"addr=pages%2Froute%2Fmain&amp;business_view_token=a52f6d30814a8d7d5717d004a0c38894",    "expire_at":1576838728}


        生码

        微信后台向业务方请求二维码源数据,前端可以根据源数据生成乘车码。

        1、 请求参数

        参数名称类型必选备注
        appidstringY小程序
        appidmch_idstringY支付商户号
        nonce_strstringY随机字符串
        encrypted_datastringY使用AESCBCPKCS7PADDING
        ivstringY用于解密的IV(base64后)
        signstringY1~5字段的签名

        encrypted_data解密后的数据

        参数名称类型必选备注
        openidstringY用户
        idcard_idstringY第三方用户id(有注册环节则有)
        user_public_keystringY用户公钥,16进制格式,共130字节

        2、 返回参数

        参数名称类型必选备注
        errcodeintY0为成功
        errmsgstringN错误信息
        nonce_strstringY原样带回
        encrypted_datastringY使用AESCBCPKCS7PADDING

        encrypted_data解密后的数据

        参数名称类型必选备注
        base64_svr_datastringY交通部乘车码标准1~15字段拼接的二进制流,base64后便于网络传输

        3、 示例代码

        请求:

        {"appid":"test","mch_id":"123456","nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

        encrypted_data解密后:

        {"openid":"1234","user_public_key":"123123","card_id":"2342343"}

        返回:

        {"errcode":0,"nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

        encrypted_data解密后的数据:

        {"base64_svr_data":"xxafdafd"}


        扫码支付

        (1)支付回调接口

        业务方调用微信扣费接口之后,接收扣费结果通知。

        1、 请求参数

        参数名称类型必选备注
        appidstringY小程序
        appidmch_idstringY支付商户号
        nonce_strstringY随机字符串
        encrypted_datastringY使用AESCBCPKCS7PADDING
        ivstringY用于解密的IV
        signstringY1~5字段的签名

        解密后的参数如下:

        参数名称类型必选备注
        openidstringY用户在小程序appid下的openid
        bank_typestringY支付类型
        total_feeintY支付总额,单位为分
        trade_statestringY支付状态:SUCCESS/FAIL
        trade_msgstringN支付失败时返回
        transaction_idstringY微信支付单号
        out_trade_nostringY乘车码业务方单号
        attachstringN扣费API的入参,原样带回
        time_endstringY支付完成时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010
        qrcodestringY二维码

        2、 返回参数

        参数名称类型必选备注
        errcodeintY0为成功
        errmsgstringN错误信息
        nonce_strstringY原样带回

        3、 示例代码

        {"appid":"test","mch_id":"123456","nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

        解密后数据:

        {"openid":"fafwefawef","bank_type":"CFT","total_fee":100,"trade_state":"SUCCESS",...}

        (2)微信扣费接口(微信API接口)

        用于接收业务方依据扫码接口获取到的信息对用户进行免密扣费。

        1、请求参数

        参数名称类型必选备注
        qrcodestringY乘车码数据,需要base64
        total_feeintY支付总额,分为单位(优惠后)
        original_feeintY支付总额,分为单位(优惠前)
        machine_ipstringN扫码机接入IP
        machine_latitudefloatN扫码机GPS纬度
        machine_longitudefloatN扫码机GPS经度
        bodystringY公交代扣/地铁代扣
        start_timestringY上车/乘车时间,如20091225091010
        end_timestringN下车时间,格式同上,适用于二次刷码的场景
        line_namestringY乘车线路
        trade_scenestringYMETRO/BUS
        start_qrcodestringN二次刷码时,传入首次刷码使用的二维码
        out_order_nostringN业务方自定义订单号,需要保证唯一
        attachstringN业务方自定义数据,对账单和查询接口会原样返回

        2、 返回参数

        参数名称类型必选备注
        errcodeint32Y返回码
        errmsgstringN返回信息

        3、 示例代码

        入参:

        {"qrcode":"afefawefwef",....}

        返回

        {"errcode":0,....}


        用户注册/签约(可选)

        微信后台向业主方发起用户注册。

        1、请求参数

        参数名称类型必选备注
        appidstringY小程序
        appidmch_idstringY支付商户号
        nonce_strstringY随机字符串
        encrypted_datastringY使用AESCBCPKCS7PADDING
        ivstringY用于解密的IV
        signstringY1~5字段的签名

        encrypted_data解密后的数据

        参数名称类型必选备注
        openidstringY用户id

        2、返回参数

        参数名称类型必选备注
        errcodeintY0为成功
        errmsgstringN错误信息
        nonce_strstringY原样带回
        encrypted_datastringY使用AESCBCPKCS7PADDING
        ivstringY用于解密的IV

        encrypted_data解密后的数据

        参数名称类型必选备注
        cardidstringY用户卡ID

        3、示例代码

        请求:

        {"appid":"test","mch_id":"123456","nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

        encrypted_data解密后为:

        {“openid”:”1234”}

        返回:

        {"errcode":0,"nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

        encrypted_data解密后的数据:

        {“card_id”:”xxafdafd”}


        用户解约(可选)

        微信后台向业主方通知用户注销/解约。

        1、请求参数

        参数名称类型必选备注
        appidstringY小程序
        mch_idstringY支付商户号
        nonce_strstringY随机字符串
        encrypted_datastringY使用AESCBCPKCS7PADDING
        ivstringY用于解密的IV(base64)
        signstringY1~5字段的签名

        encrypted_data解密后的数据

        参数名称类型必选备注
        openidstringY用户openid
        cardidstringN业主方的用户标识

        2、返回参数

        参数名称类型必选备注
        errcodeintY0为成功
        errmsgstringN错误信息
        nonce_strstringY原样带回

        3、 示例代码

        请求:

        {"appid":"test","mch_id":"123456","nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

        encrypted_data解密后为:

        {"openid":"1234","cardid":"1234"}

        返回:

        {"errcode":0,"nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}


        用户签约状态查询

        业主方查询用户签约状态接口。

        1、请求参数

        参数名称类型必选备注
        openidstringN用户openid(优先使用)
        cardidstringN业主方的用户标识,注册接口返回

        2、返回参数

        参数名称类型必选备注
        errcodeint32Y返回码
        errmsgstringN返回信息
        statusintY用户签约状态 0-已签约 1-未签约

        3、示例代码

        请求:

        {"openid":"afefawefwef","cardid":"123"}

        返回:

        {"errcode":0,"errmsg":"ok","status":0}


        欠费支付

        微信后台向业主方通知用户支付成功(支付失败时无通知)。

        1、请求参数

        参数名称类型必选备注
        appidstringY小程序appid
        mch_idstringY支付商户号
        nonce_strstringY随机字符串
        encrypted_datastringY使用AESCBCPKCS7PADDING
        ivstringY用于解密的IV(base64)
        signstringY1~5字段的签名

        encrypted_data解密后的数据

        参数名称类型必选备注
        out_user_idstringY业主后台对用户的标识,设置过注册回调接口时存在
        openidstringY用户openid
        bank_typestringY支付类型,采用字符串类型的银行标识
        total_feeintY支付费用
        transaction_idstringY微信支付单号
        time_endstringY格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010
        repay_nostringY欠费单号
        order_noarrayY与本欠费单号相关联的乘车码单号(存在一次支付多笔乘车欠费的情况),每一项的内容为string
        orderarrayY与本欠费单号相关联的乘车码单号的详细信息

        其中order的每一项内容如下:

        参数名称类型必选备注
        order_nostringY乘车码单号
        attachstringY免密代扣上传的附加信息
        base64_qrcodestringYbase64后的乘车码信息
        out_order_nostringY外部传的单号

        2、返回参数

        参数名称类型必选备注
        errcodeintY0为成功
        errmsgstringN错误信息
        nonce_strstringY原样带回

        3、示例

        请求:

        {"appid":"test","mch_id":"123456","nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

        encrypted_data解密后为:

        {    "out_user_id":"xxx",    "openid":"1234",    "bank_type":"LQT",    "total_fee":123,    "transaction_id":"12312312",    "time_end":"2020030319551111",    "repay_no":"2020202202020",    "order_no":[        "123",        "456"]}

        返回:

        {"errcode":0,"nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}


        查询线路接口

        查询设置的公交/地铁线路。

        1、请求参数

        参数名称类型必选备注
        typeintY类型 0-地铁 1-公交

        2、返回参数

        参数名称类型必选备注
        errcodeintY错误码
        errmsgstringY错误信息
        resultsobjectN线路信息

        其中results的内容如下:

        参数名称类型必选备注
        line_listawayY线路信息

        其中results.line_list的每一项内容如下:

        参数名称类型必选备注
        idintY线路的唯一id
        start_stationstringY起点站
        end_stationstringY终点站
        line_namestringY线路名称


        设置线路接口

        设置公交/地铁线路。

        1、请求参数

        参数名称类型必选备注
        typeintY类型 0-地铁 1-公交
        confobjectY设置的线路配置

        其中conf的内容如下:

        参数名称类型必选备注
        line_listawayY线路信息

        其中conf.line_list的每一项内容如下:

        参数名称类型必选备注
        idintY线路的唯一id
        start_stationstringY起点站
        end_stationstringY终点站
        line_namestringY线路名称

        2、返回参数

        参数名称类型必选备注
        errcodeintY错误码
        errmsgstringY错误信息


        查询欠费用户列表

        微信后台会定时(每天6点开始)获取所有欠费用户列表,并提供接口查询列表接口,此后如果有用户完成欠费缴纳会在收到成功支付通知时删除记录。

        1、请求参数

        参数名称类型必选备注
        start_openidstringN开始的openid,从头开始填空,start_openid不会包含在返回结果中
        limitintY最大返回数量(0,10000]

        2、返回参数

        参数名称类型必选备注
        errcodeintY错误码
        errmsgstringY错误信息
        listarrayN返回欠费用户列表

        其中list的每一项的内容如下:

        参数名称类型必选备注
        openidstringY用户openid
        feeintY欠费金额
        create_timeintY更新的时间
        out_user_idstringN用户在业主方的id,当设置了注册回调后才有


        safety-specifications

        接入微信城市服务,业务方需确保功能安全性。

        常见安全检查表

        XSS

        1. 输入校验:长度限制、值类型是否正确、是否包含特殊字符(如<>’”等)
        2. 输出编码:根据输出的位置进行相应的编码,如HTML编码、JavaScript编码、URL编码。
        3. 输出到HTML标签之间时,对这些数据进行HTML Entity编码
        4. 输出到HTML属性里时,特殊字符编码为&#xHH
        5. 输出到SCRIPT里时,对这些数据进行SCRIPT编码,除了阿拉伯数字和字母,对其他所有的字符进行编码,只要该字符的ASCII码小于256。编码后输出的格式为xHH
        6. 输出到Style属性里时,对这些数据进行CSS编码,除了阿拉伯数字和字母,对其他所有的字符进行编码,只要该字符的ASCII码小于256。编码后输出的格式为HH
        7. 输出到HTML URL里时,对这些数据进行URL编码,当需要往HTML页面中的URL里插入不可信数据的时候,需要对其进行URL编码

        SQL注入

        1. 最佳方式就是使用预编译语句,绑定变量
        2. 检查数据类型
        3. 使用安全函数,例如php的mysql_real_escape_string
        4. 从数据库自身来说,应使用最小权限原则,切记不要使用dba权限

        上传漏洞

        1. 在客户端和服务器端对用户上传的文件名和文件路径等项目分别进行严格的检查,尤其是服务端检测不能少
        2. 服务器端的检查最好使用白名单过滤的方法,比如只允许jpg文件上传等
        3. 上传目标路径尽量不在web目录下,如果在web目录下去掉该目录的可执行权限
        4. 慎用Fckeditor、ewebeditor等第三方上传组件,历史上曾出现多个漏洞

        Struts2

        历史上Struts2框架出过多个高危漏洞,这些漏洞足以黑掉一个网站,要尽量使用最新版本

        信息泄漏

        1. 线上机器删掉测试页面,例如test.html,phpinfo.php等
        2. 禁掉详细的错误提示
        3. 禁止显示调试信息
        4. 禁止将svn相关的文件更新到线上机器,例如.svn/entries

        登录安全

        1. 登录页面最好加入验证码
        2. 尽量使用https协议

        会话安全

        公众号开发中通常将openid作为用户身份标识,使用openid时要将openid设置到cookie中不要拼接到URL中例如http://www.qq.com/getuser?code=aaaaaa

        管理页面

        Tomcat、jboss、weblogic等管理页面可以做以下加个方面的安全策略

        使用白名单的方式限制可以登录的IP

        如果不使用这些管理界面直接删掉

        平行权限问题

        像订单等场景需要格外注意平行权限问题,例如order?Id=111,是否order?Id=112就可以看到其他的订单。对于这种情况的防御,可以加入校验参数,order?Id=111&sign=hash(字符串常量+id)

        支付金额问题

        1. 涉及到微支付的web应用一定要严格按照微信支付官方网站的文档设计
        2. 确定用户的支付金额与应付金额是否相等


        results-page

        接入微信城市服务,业务方需确保功能的闭环服务体验,需接入消息通路。点击此处查看城市服务消息通路说明

        调用方法

        1、接口调用请求

        请求方式:POST 请求地址:https://api.weixin.qq.com/cityservice/sendmsgdata?access_token=ACCESS_TOKEN

        (1)获取access_token方式请点击此处查看;获取openid方式请点击此处查看

        (2)通过小程序提供服务时,需使用小程序用户 openid ,并使用与小程序关联的、且申请了“消息通路”的公众号的 access_token

        2、以POST方式传入json格式的参数

        (1)模板申请成功后,将会分配biz_template_id,并根据模板推送渠道不同分别提供样式ID:result_page_style_id、deal_msg_style_id、card_style_id。

        (2)调用接口时,通过POST方式传入json格式的以下参数,所有参数的数据类型均为“字符串”,且字符集默认使用UTF-8。

        字段说明

        参数说明是否必填
        openid用户唯一标识必填
        biz_template_id城市服务分配给公众号的模板id必填
        result_page_style_id结果页样式id含结果页必填
        deal_msg_style_id办事记录样式id含办事记录必填
        card_style_id页卡样式id含页卡必填
        order_no订单号,同一订单号的办事记录会合并必填
        url跳转链接,用于服务通知、结果页、待办提醒含结果页必填
        data模板json数据,其中color字段只对服务通知有效必填

        参数示例

        {           "openid":"OPENID",           "biz_template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",           "result_page_style_id":"cUjfPSEtwasWQFsJ5PXo218PexBaHy5jg_peVDe4WkY",           "deal_msg_style_id":"cUjfPSEtwasWQFsJ5PXo24LeNjWbwMObXSHPNjVZ0uQ",           "card_style_id":"cUjfPSEtwasWQFsJ5PXo2z8LSM0Q6FH05DCerWEVkDs",           "order_no":"ORDER_NO",           "url":"http://weixin.qq.com/download",           "data":{                   "first": {                       "value":"恭喜你购买成功!",                       "color":"#173177"                   },                   "keynote1":{                       "value":"巧克力",                       "color":"#173177"                   },                   "keynote2": {                       "value":"39.8元",                       "color":"#173177"                   },                   "keynote3": {                       "value":"2014年9月22日",                       "color":"#173177"                   },                   "remark":{                       "value":"欢迎再次购买!",                       "color":"#173177"                   }           }}

        注:data为数组时用[ ]括起“data”字段内数据。

        3、返码说明

        在调用消息通路接口后,返回JSON数据包:

        返回结果返回码说明
        result_page_url结果页url需跳转至该url,替代原有的服务结果页面。如未传入result_page_style_id,则调用后result_page_url返回为空。
        errcode48001api未授权
        errcode400971.参数错误。2.或openid不来自有“消息通路”api权限的公众号
        errcode82020未关注公众号的用户,从未在城市服务访问过服务
        errcode82021未关注公众号的用户,未在近30天内通过城市服务访问服务
        errcode82022未关注公众号的用户,通过城市服务访问服务后,30天内被下发数超过10次(医疗行业超过20次)
        errcode82023未关注公众号的用户,1个小时内被下发次数超过5次
        errcode82024order_no异常,例如所有用户的业务订单号都用同一个
        errcode82025URL无效
        errcode820261.服务已下线。2.或服务在审核中且审核期超过了30天

        正常时的返回JSON数据包示例:

        {"errcode":0,"errmsg":"ok","result_page_url":"https://city.weixin.qq.com/static/resultpagenew.html?openid=ont-9vjAcIdSU-LgB7ubALAVJO9U&biz_template_id=ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY #wechat_redirect"}

        注:如未传入结果页样式ID(result_page_style_id),则result_page_url结果为空

        4、页面报错提示

        提示信息说明
        中文显示错误字符集未用utf8
        参数错误json参数错误
        非本人,页面打开失败非本人openid;或登录态获取失败
        请在微信内打开需在微信内打开页面
        系统错误其他错误


        auto-fill

        接入微信城市服务,业务方可以使用小程序auto-fill组件功能,获取用户首次填写过的表单的信息。需接入auto-fill组件,点击此处查看详细说明

        组件调用说明

        1、字段描述

        auto­-fill字段由两部分组成,(group.key)表示分组和具体字段,相同group的字段可以关联在一起,用户的一次选择可以完成全部的填写。另外,开发时,需要给input、textarea、picker指定auto­fill字段。

        字段定义及具体的group和key字段,详见详见下表。(申请权限时,可选择本表中的group_key,或key)

        group_keykey字段定义
        公共字段
        (可以和任意group_key组合)
        name姓名
        id_card_num身份证号
        phone手机号
        email邮箱
        基础信息
        base_info
        sex性别
        birthday生日
        nationality国籍
        驾驶证信息
        driver_licence_info
        licence_num驾驶证号
        licence_file_num驾驶证档案编号
        行驶证信息
        driver_licence_info
        licence_plate_num行驶证车牌号
        engine_num行驶证发动机号
        licence_hassis_num行驶证车架号
        地址
        address_info
        nationality国家
        address
        address_detail详细地址
        postcode邮编
        护照
        passport
        passport_num护照号
        validity护照有效期
        issue_at签发地
        first_name_zh名字(中文)
        last_name_zh姓氏(中文)
        first_name_en名字(英文)
        last_name_en姓氏(英文)
        birth_place户口出生地
        residence_place户口所在地
        港澳通行证
        hk_macau_passport
        passport_num港澳通行证号
        validity护照有效期
        issue_at签发地
        first_name_zh名字(中文)
        last_name_zh姓氏(中文)
        first_name_en名字(英文)
        last_name_en姓氏(英文)
        birth_place户口出生地
        residence_place户口所在地
        社保卡
        social_security
        card_num社保卡号

        调用字段填写表单时,公共字段使用,需调用对应group,如:base_info.name,base_info.phone;passport.name, passport.phone。其它group字段直接调用,如:base_info.email。

        2、form表单示例

        <form bindsubmit="submit">  <input class="weui-input" placeholder="姓名" auto-fill="address_info.name"  />  <input class="weui-input" placeholder="手机" auto-fill="address_info.phone" />  <input class="weui-input" placeholder="身份证" auto-fill="address_info.id_card_num" />  <button form-type="submit">submit</button></form>

        3、测试案例

        除以上文档,还可下载以下测试案例,测试试用。

        点击下载测试案例


        checkrealnameinfo

        接入微信城市服务,开发者小程序可以使用实名信息校验接口。主要实现的功能是,在用户同意情况下,通过微信城市服务去校验用户(或业务方)输入的实名信息,是否正确且与用户在“开通微信支付”时,预留的实名信息一致。此接口与接入城市服务的开放范围一致,需申请权限可点击此处查看详细说明

        接口文档说明

        1、业务流程说明

        1. 第一步:业务方小程序的界面,需要实现实名信息校验时,需根据接口文档提供的path跳转至微信城市服务提供的小程序授权页。
        2. 第二步:用户在微信授权页点击同意确认后,微信会回跳至业务方小程序,并带上code参数(code参数包含在返回的extraData)。
        3. 第三步:业务方页面获得code之后,需要通过后台调用微信提供的后台API,进行实名信息的校验。校验完成后,业务方再根据具体情况,完成自有的业务流程。

        2、获取code参数

        根据4.1描述的步骤,调用后台API校验实名信息时,需要先获取code参数。获取方式如下:

        1、请求方式:

        跳转至微信城市服务提供的appid和path appid:wx308bd2aeb83d3345 path:subPages/city/wxpay-auth/main

        2、应答方式:

        用户完成确认同意后,会跳回至业务方小程序,并在extraData字段中带上调用后台接口所需的code,即extraData中的code字段。 如需了解如何处理extraData字段,可以点击此处查看更多

        3、后台校验实名信息的API

        注:此后台API,与小程序API使用方式一致。如需了解小程序API使用方式,请点击此处查看详细说明

        1、请求方式:POST

        2、请求地址:

        https://api.weixin.qq.com/intp/realname/checkrealnameinfo?access_token=ACCESSTOKEN

        说明:此处的access_token获取方式,可点击此处参考详细说明

        3、请求格式:JSON

        4、请求参数:

        字段类型说明备注
        openidstring用户在业务方下的openid与申请权限时提供的业务方的小程序appid保持一致
        real_namestring姓名需要校验的姓名
        cred_idstring证件号需要校验的证件号
        cred_typestring默认为1,即身份证目前暂只支持身份证
        codestring回调获取的code通过小程序回跳获取的code参数

        5、返回字段:

        字段类型说明备注
        errcodeint0为接口调用成功错误码
        errmsgstring失败时的错误提示错误原因
        verify_openidstringV_OP_NA:用户暂未实名认证;V_OP_NM_MA:用户与姓名匹配;V_OP_NM_UM:用户与姓名不匹配。有多个结果时用分号”;”连接;
        verify_real_namestringverify_openid 为V_OP_NM_MA 时返回:V_NM_ID_MA:姓名与证件号匹配;V_NM_ID_UM:姓名与证件号不匹配。校验结果


        框架

        小程序开发框架的目标是通过尽可能简单、高效的方式让开发者可以在微信中开发具有原生APP体验的服务。

        框架提供了自己的视图层描述语言WXMLWXSS,以及基于JavaScript的逻辑层框架,并在视图层与逻辑层间提供了数据传输和事件系统,可以让开发者可以方便的聚焦于数据与逻辑上。


        响应的数据绑定

        框架的核心是一个响应的数据绑定系统。

        整个系统分为两块视图层(View)逻辑层(App Service)

        框架可以让数据与视图非常简单地保持同步。当做数据修改的时候,只需要在逻辑层修改数据,视图层就会做相应的更新。

        通过这个简单的例子来看:

        <!-- Thie 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,可以方便的调起微信提供的能力,如获取用户信息本地存储支付功能等。


        文件结构

        MINA程序包含一个描述整体程序的app和多个描述各自页面的page。

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

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

        一个MINA页面由四个文件组成,分别是:

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

        注意:为了方便开发者减少配置项,我们规定描述页面的这四个文件必须具有相同的路径与文件名。

        全局配置

        小程序根目录下的 app.json 文件用来对微信小程序进行全局配置。文件内容为一个 JSON 对象,有以下属性:

        配置项

        属性类型必填描述最低版本
        entryPagePathstring小程序默认启动首页
        pagesstring[]页面路径列表
        windowObject全局的默认窗口表现
        tabBarObject底部 tab 栏的表现
        networkTimeoutObject网络超时时间
        debugboolean是否开启 debug 模式,默认关闭
        functionalPagesboolean是否启用插件功能页,默认关闭2.1.0
        subpackagesObject[]分包结构配置1.7.3
        workersstringWorker 代码放置的目录1.9.90
        requiredBackgroundModesstring[]需要在后台使用的能力,如「音乐播放」
        pluginsObject使用到的插件1.9.6
        preloadRuleObject分包预下载规则2.3.0
        resizablebooleanPC 小程序是否支持用户任意改变窗口大小(包括最大化窗口);iPad 小程序是否支持屏幕旋转。默认关闭2.3.0
        usingComponentsObject全局自定义组件配置开发者工具 1.02.1810190
        permissionObject小程序接口权限相关设置微信客户端 7.0.0
        sitemapLocationstring指明 sitemap.json 的位置
        stylestring指定使用升级后的weui样式2.8.0
        useExtendedLibObject指定需要引用的扩展库2.2.1
        entranceDeclareObject微信消息用小程序打开微信客户端7.0.9
        darkmodeboolean小程序支持 DarkMode2.11.0
        themeLocationstring指明 theme.json 的位置,darkmode为true为必填开发者工具 1.03.2004271
        lazyCodeLoadingstring配置自定义组件代码按需注入2.11.1
        singlePageObject单页模式相关配置2.12.0

        entryPagePath

        指定小程序的默认启动路径(首页),常见情景是从微信聊天列表页下拉启动、小程序列表启动等。如果不填,将默认为 pages 列表的第一项。不支持带页面路径参数。

        {  "entryPagePath": "pages/index/index"}

        pages

        用于指定小程序由哪些页面组成,每一项都对应一个页面的 路径(含文件名) 信息。文件名不需要写文件后缀,框架会自动去寻找对应位置的 .json, .js, .wxml, .wxss 四个文件进行处理。

        未指定 entryPagePath 时,数组的第一项代表小程序的初始页面(首页)。

        小程序中新增/减少页面,都需要对 pages 数组进行修改。

        如开发目录为:

        ├── app.js├── app.json├── app.wxss├── pages│   │── index│   │   ├── index.wxml│   │   ├── index.js│   │   ├── index.json│   │   └── index.wxss│   └── logs│       ├── logs.wxml│       └── logs.js└── utils

        则需要在 app.json 中写

        {  "pages": ["pages/index/index", "pages/logs/logs"]}

        window

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

        属性类型默认值描述最低版本
        navigationBarBackgroundColorHexColor#000000导航栏背景颜色,如 #000000
        navigationBarTextStylestringwhite导航栏标题颜色,仅支持 black / white
        navigationBarTitleTextstring导航栏标题文字内容
        navigationStylestringdefault导航栏样式,仅支持以下值:
        default 默认样式
        custom 自定义导航栏,只保留右上角胶囊按钮。参见注 2。
        微信客户端 6.6.0
        backgroundColorHexColor#ffffff窗口的背景色
        backgroundTextStylestringdark下拉 loading 的样式,仅支持 dark / light
        backgroundColorTopstring#ffffff顶部窗口的背景色,仅 iOS 支持微信客户端 6.5.16
        backgroundColorBottomstring#ffffff底部窗口的背景色,仅 iOS 支持微信客户端 6.5.16
        enablePullDownRefreshbooleanfalse是否开启全局的下拉刷新。
        详见 Page.onPullDownRefresh
        onReachBottomDistancenumber50页面上拉触底事件触发时距页面底部距离,单位为 px。
        详见 Page.onReachBottom
        pageOrientationstringportrait屏幕旋转设置,支持 auto / portrait / landscape
        详见 响应显示区域变化
        2.4.0 (auto) / 2.5.0 (landscape)
        • 注 1:HexColor(十六进制颜色值),如"#ff00ff"
        • 注 2:关于navigationStyle客户端 7.0.0 以下版本,navigationStyle 只在 app.json 中生效。客户端 6.7.2 版本开始,navigationStyle: custom 对 web-view 组件无效开启 custom 后,低版本客户端需要做好兼容。开发者工具基础库版本切到 1.7.0(不代表最低版本,只供调试用)可方便切到旧视觉

        如:

        {  "window": {    "navigationBarBackgroundColor": "#ffffff",    "navigationBarTextStyle": "black",    "navigationBarTitleText": "微信接口功能演示",    "backgroundColor": "#eeeeee",    "backgroundTextStyle": "light"  }}

        tabBar

        如果小程序是一个多 tab 应用(客户端窗口的底部或顶部有 tab 栏可以切换页面),可以通过 tabBar 配置项指定 tab 栏的表现,以及 tab 切换时显示的对应页面。

        属性类型必填默认值描述最低版本
        colorHexColortab 上的文字默认颜色,仅支持十六进制颜色
        selectedColorHexColortab 上的文字选中时的颜色,仅支持十六进制颜色
        backgroundColorHexColortab 的背景色,仅支持十六进制颜色
        borderStylestringblacktabbar 上边框的颜色, 仅支持 black / white
        listArraytab 的列表,详见 list 属性说明,最少 2 个、最多 5 个 tab
        positionstringbottomtabBar 的位置,仅支持 bottom / top
        custombooleanfalse自定义 tabBar,见详情2.5.0

        其中 list 接受一个数组,只能配置最少 2 个、最多 5 个 tab。tab 按数组的顺序排序,每个项都是一个对象,其属性值如下:

        属性类型必填说明
        pagePathstring页面路径,必须在 pages 中先定义
        textstringtab 上按钮文字
        iconPathstring图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px,不支持网络图片。
        当 position 为 top 时,不显示 icon。
        selectedIconPathstring选中时的图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px,不支持网络图片。
        当 position 为 top 时,不显示 icon。

        networkTimeout

        各类网络请求的超时时间,单位均为毫秒。

        属性类型必填默认值说明
        requestnumber60000wx.request 的超时时间,单位:毫秒。
        connectSocketnumber60000wx.connectSocket 的超时时间,单位:毫秒。
        uploadFilenumber60000wx.uploadFile 的超时时间,单位:毫秒。
        downloadFilenumber60000wx.downloadFile 的超时时间,单位:毫秒。

        debug

        可以在开发者工具中开启 debug 模式,在开发者工具的控制台面板,调试信息以 info 的形式给出,其信息有 Page 的注册,页面路由,数据更新,事件触发等。可以帮助开发者快速定位一些常见的问题。

        functionalPages

        基础库 2.1.0 开始支持,低版本需做兼容处理。

        插件所有者小程序需要设置这一项来启用插件功能页。

        subpackages

        微信客户端 6.6.0 ,基础库 1.7.3 及以上版本支持

        启用分包加载时,声明项目分包结构。

        写成 subPackages 也支持。

        workers

        基础库 1.9.90 开始支持,低版本需做兼容处理。

        使用 Worker 处理多线程任务时,设置 Worker 代码放置的目录

        requiredBackgroundModes

        微信客户端 6.7.2 及以上版本支持

        申明需要后台运行的能力,类型为数组。目前支持以下项目:

        • audio: 后台音乐播放
        • location: 后台定位

        如:

        {  "pages": ["pages/index/index"],  "requiredBackgroundModes": ["audio", "location"]}

        注:在此处申明了后台运行的接口,开发版和体验版上可以直接生效,正式版还需通过审核。

        plugins

        基础库 1.9.6 开始支持,低版本需做兼容处理。

        声明小程序需要使用的插件。

        preloadRule

        基础库 2.3.0 开始支持,低版本需做兼容处理。

        声明分包预下载的规则。

        resizable

        基础库 2.3.0 开始支持,低版本需做兼容处理。

        在 iPad 上运行的小程序可以设置支持屏幕旋转。

        在 PC 上运行的小程序,用户可以按照任意比例拖动窗口大小,也可以在小程序菜单中最大化窗口

        usingComponents

        开发者工具 1.02.1810190 及以上版本支持

        在此处声明的自定义组件视为全局自定义组件,在小程序内的页面或自定义组件中可以直接使用而无需再声明。

        permission

        微信客户端 7.0.0 及以上版本支持

        小程序接口权限相关设置。字段类型为 Object,结构为:

        属性类型必填默认值描述
        scope.userLocationPermissionObject位置相关权限声明

        PermissionObject 结构

        属性类型必填默认值说明
        descstring小程序获取权限时展示的接口用途说明。最长 30 个字符

        如:

        {  "pages": ["pages/index/index"],  "permission": {    "scope.userLocation": {      "desc": "你的位置信息将用于小程序位置接口的效果展示" // 高速公路行驶持续后台定位    }  }}

        sitemapLocation

        指明 sitemap.json 的位置;默认为 'sitemap.json' 即在 app.json 同级目录下名字的 sitemap.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,}

        style

        基础库 2.8.0 开始支持,低版本需做兼容处理。

        微信客户端 7.0 开始,UI 界面进行了大改版。小程序也进行了基础组件的样式升级。app.json 中配置 "style": "v2"可表明启用新版的组件样式。

        本次改动涉及的组件有 button icon radio checkbox switch slider。可前往小程序示例进行体验。

        useExtendedLib

        基础库 2.2.1 开始支持,低版本需做兼容处理。
        最新的 nightly 版开发者工具开始支持,同时基础库从支持 npm 的版本(2.2.1)起支持

        指定需要引用的扩展库。目前支持以下项目:

        • kbone: 多端开发框架
        • weui: WeUI 组件库

        指定后,相当于引入了对应扩展库相关的最新版本的 npm 包,同时也不占用小程序的包体积。目前暂不支持在分包中引用。用法如下:

        {  "useExtendedLib": {    "kbone": true,    "weui": true  }}

        entranceDeclare

        微信客户端 7.0.9 及以上版本支持,iOS 暂不支持

        聊天位置消息用打车类小程序打开,详情参考。

        "entranceDeclare": {    "locationMessage": {        "path": "pages/index/index",        "query": "foo=bar"    }}

        darkmode

        开发者工具 1.03.2004271 及以上版本支持,基础库 2.11.0 及以上版本支持

        微信iOS客户端 7.0.12 版本、Android客户端 7.0.13 版本正式支持 DarkMode,可通过配置"darkmode": true表示当前小程序可适配 DarkMode,所有基础组件均会根据系统主题展示不同的默认样式,navigation bar 和 tab bar 也会根据开发者的配置自动切换。

        配置后,请根据DarkMode 适配指南自行完成基础样式以外的适配工作。

        {  "darkmode": true}

        themeLocation

        自定义 theme.json 的路径,当配置"darkmode":true时,当前配置文件为必填项。

        {  "themeLocation": "/path/to/theme.json"}

        lazyCodeLoading

        基础库 2.11.1 及以上版本支持,2.11.1 以下兼容但无优化效果

        通常情况下,在小程序启动期间,所有页面及自定义组件的代码都会进行注入,当前页面没有使用到的自定义组件和页面在注入后其实并没有被使用。

        自基础库版本 2.11.1 起,小程序支持有选择地注入必要的代码,以降低小程序的启动时间和运行时内存。

        {  "lazyCodeLoading": "requiredComponents"}

        当配置了这一项时,小程序仅注入当前页面需要的自定义组件和页面代码,在页面中必然不会用到的自定义组件不会被加载和初始化。

        注意:添加这项配置后,未使用到的代码文件将不被执行。

        singlePage

        基础库 2.11.3 及以上版本支持,目前分享到朋友圈 (Beta) 后打开会进入单页模式

        单页模式相关配置

        属性类型必填默认值描述
        navigationBarFitString默认自动调整,若原页面是自定义导航栏,则为 float,否则为 squeezed导航栏与页面的相交状态,值为 float 时表示导航栏浮在页面上,与页面相交;值为 squeezed 时表示页面被导航栏挤压,与页面不相交


        页面配置

        每一个小程序页面也可以使用 .json 文件来对本页面的窗口表现进行配置。页面中配置项在当前页面会覆盖 app.json 的 window 中相同的配置项。文件内容为一个 JSON 对象,有以下属性:

        配置项

        属性类型默认值描述最低版本
        navigationBarBackgroundColorHexColor#000000导航栏背景颜色,如 #000000
        navigationBarTextStylestringwhite导航栏标题颜色,仅支持 black / white
        navigationBarTitleTextstring导航栏标题文字内容
        navigationStylestringdefault导航栏样式,仅支持以下值:
        default 默认样式
        custom 自定义导航栏,只保留右上角胶囊按钮
        微信客户端 7.0.0
        backgroundColorHexColor#ffffff窗口的背景色
        backgroundTextStylestringdark下拉 loading 的样式,仅支持 dark / light
        backgroundColorTopstring#ffffff顶部窗口的背景色,仅 iOS 支持微信客户端 6.5.16
        backgroundColorBottomstring#ffffff底部窗口的背景色,仅 iOS 支持微信客户端 6.5.16
        enablePullDownRefreshbooleanfalse是否开启当前页面下拉刷新。
        详见 Page.onPullDownRefresh
        onReachBottomDistancenumber50页面上拉触底事件触发时距页面底部距离,单位为px。
        详见 Page.onReachBottom
        pageOrientationstringportrait屏幕旋转设置,支持 auto / portrait / landscape
        详见 响应显示区域变化
        2.4.0 (auto) / 2.5.0 (landscape)
        disableScrollbooleanfalse设置为 true 则页面整体不能上下滚动。
        只在页面配置中有效,无法在 app.json 中设置
        usingComponentsObject页面自定义组件配置1.6.3
        stylestringdefault启用新版的组件样式2.10.2
        singlePageObject单页模式相关配置2.12.0
        页面配置中只能设置 app.json 中 window 对应的配置项,以决定本页面的窗口表现,所以无需写 window 这个属性。

        singlePage

        基础库 2.11.3 及以上版本支持,目前分享到朋友圈 (Beta) 后打开会进入单页模式

        单页模式相关配置

        属性类型必填默认值描述
        navigationBarFitString默认自动调整,若原页面是自定义导航栏,则为 float,否则为 squeezed导航栏与页面的相交状态,值为 float 时表示导航栏浮在页面上,与页面相交;值为 squeezed 时表示页面被导航栏挤压,与页面不相交

        配置示例

        {  "navigationBarBackgroundColor": "#ffffff",  "navigationBarTextStyle": "black",  "navigationBarTitleText": "微信接口功能演示",  "backgroundColor": "#eeeeee",  "backgroundTextStyle": "light"}


        微信现已开放小程序内搜索,开发者可以通过 sitemap.json 配置,或者管理后台页面收录开关来配置其小程序页面是否允许微信索引。当开发者允许微信索引时,微信会通过爬虫的形式,为小程序的页面内容建立索引。当用户的搜索词条触发该索引时,小程序的页面将可能展示在搜索结果中。 爬虫访问小程序内页面时,会携带特定的 user-agent:mpcrawler 及场景值:1129。需要注意的是,若小程序爬虫发现的页面数据和真实用户的呈现不一致,那么该页面将不会进入索引中。

        sitemap 配置

        小程序根目录下的 sitemap.json 文件用于配置小程序及其页面是否允许被微信索引,文件内容为一个 JSON 对象,如果没有 sitemap.json ,则默认为所有页面都允许被索引;sitemap.json 有以下属性:

        配置项

        属性类型必填描述
        rulesObject[]索引规则列表

        rules

        rules 配置项指定了索引规则,每项规则为一个JSON对象,属性如下所示:

        属性类型必填默认值取值取值说明
        actionstring"allow""allow"、"disallow"命中该规则的页面是否能被索引
        pagestring"*"、页面的路径* 表示所有页面,不能作为通配符使用
        paramsstring[][]当 page 字段指定的页面在被本规则匹配时可能使用的页面参数名称的列表(不含参数值)
        matchingstring"inclusive"参考 matching 取值说明当 page 字段指定的页面在被本规则匹配时,此参数说明 params 匹配方式
        priorityNumber优先级,值越大则规则越早被匹配,否则默认从上到下匹配

        matching 取值说明

        说明
        exact当小程序页面的参数列表等于 params 时,规则命中
        inclusive当小程序页面的参数列表包含 params 时,规则命中
        exclusive当小程序页面的参数列表与 params 交集为空时,规则命中
        partial当小程序页面的参数列表与 params 交集不为空时,规则命中

        配置示例

        示例1

        {  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "exact"  }, {    "action": "disallow",    "page": "path/to/page"  }]}
        • path/to/page?a=1&b=2 => 优先索引
        • path/to/page => 不被索引
        • path/to/page?a=1 => 不被索引
        • path/to/page?a=1&b=2&c=3 => 不被索引
        • 其他页面都会被索引

        示例2

        {  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "inclusive"  }, {    "action": "disallow",    "page": "path/to/page"  }]}
        • path/to/page?a=1&b=2 => 优先索引
        • path/to/page?a=1&b=2&c=3 => 优先索引
        • path/to/page => 不被索引
        • path/to/page?a=1 => 不被索引
        • 其他页面都会被索引

        示例3

        {  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "exclusive"  }, {    "action": "disallow",    "page": "path/to/page"  }]}
        • path/to/page => 优先索引
        • path/to/page?c=3 => 优先索引
        • path/to/page?a=1 => 不被索引
        • path/to/page?a=1&b=2 => 不被索引
        • 其他页面都会被索引

        示例4

        {  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "partial"  }, {    "action": "disallow",    "page": "path/to/page"  }]}
        • path/to/page?a=1 => 优先索引
        • path/to/page?a=1&b=2 => 优先索引
        • path/to/page => 不被索引
        • path/to/page?c=3 => 不被索引
        • 其他页面都会被索引

        注:没有 sitemap.json 则默认所有页面都能被索引

        注:{"action": "allow", "page": "*"} 是优先级最低的默认规则,未显式指明 "disallow" 的都默认被索引


        App(Object object)

        注册小程序。接受一个 Object 参数,其指定小程序的生命周期回调等。

        App() 必须在 app.js 中调用,必须调用且只能调用一次。不然会出现无法预期的后果。

        参数

        Object object
        属性类型默认值必填说明最低版本
        onLaunchfunction生命周期回调——监听小程序初始化。
        onShowfunction生命周期回调——监听小程序启动或切前台。
        onHidefunction生命周期回调——监听小程序切后台。
        onErrorfunction错误监听函数。
        onPageNotFoundfunction页面不存在监听函数。1.9.90
        onUnhandledRejectionfunction未处理的 Promise 拒绝事件监听函数。2.10.0
        onThemeChangefunction监听系统主题变化2.11.0
        其他any开发者可以添加任意的函数或数据变量到 Object 参数中,用 this 可以访问
        关于小程序前后台的定义和小程序的运行机制,请参考运行机制章节。

        示例代码

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

        onLaunch(Object object)

        小程序初始化完成时触发,全局只触发一次。参数也可以使用 wx.getLaunchOptionsSync 获取。

        参数:与 wx.getLaunchOptionsSync 一致

        onShow(Object object)

        小程序启动,或从后台进入前台显示时触发。也可以使用 wx.onAppShow 绑定监听。

        参数:与 wx.onAppShow 一致

        onHide()

        小程序从前台进入后台时触发。也可以使用 wx.onAppHide 绑定监听。

        onError(String error)

        小程序发生脚本错误或 API 调用报错时触发。也可以使用 wx.onError 绑定监听。

        参数:与 wx.onError 一致

        onPageNotFound(Object object)

        基础库 1.9.90 开始支持,低版本需做兼容处理。

        小程序要打开的页面不存在时触发。也可以使用 wx.onPageNotFound 绑定监听。注意事项请参考 wx.onPageNotFound。

        参数:与 wx.onPageNotFound 一致

        示例代码:

        App({  onPageNotFound(res) {    wx.redirectTo({      url: 'pages/...'    }) // 如果是 tabbar 页面,请使用 wx.switchTab  }})

        onUnhandledRejection(Object object)

        基础库 2.10.0 开始支持,低版本需做兼容处理。

        小程序有未处理的 Promise 拒绝时触发。也可以使用 wx.onUnhandledRejection 绑定监听。注意事项请参考 wx.onUnhandledRejection。

        参数:与 wx.onUnhandledRejection 一致

        onThemeChange(Object object)

        基础库 2.11.0 开始支持,低版本需做兼容处理。

        系统切换主题时触发。也可以使用 wx.onThemeChange 绑定监听。

        参数:与 wx.onThemeChange 一致


        AppObject getApp(Object object)

        获取到小程序全局唯一的 App 实例。

        参数

        Object object
        属性类型默认值必填说明最低版本
        allowDefaultbooleanfalse在 App 未定义时返回默认实现。当App被调用时,默认实现中定义的属性会被覆盖合并到App中。一般用于独立分包2.2.4

        示例代码

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

        注意

        • 不要在定义于 App() 内的函数中,或调用 App 前调用 getApp() ,使用 this 就可以拿到 app 实例。
        • 通过 getApp() 获取实例之后,不要私自调用生命周期函数。


        Page(Object object)

        注册小程序中的一个页面。接受一个 Object 类型参数,其指定页面的初始数据、生命周期回调、事件处理函数等。

        参数

        Object object
        属性类型默认值必填说明
        dataObject页面的初始数据
        onLoadfunction生命周期回调—监听页面加载
        onShowfunction生命周期回调—监听页面显示
        onReadyfunction生命周期回调—监听页面初次渲染完成
        onHidefunction生命周期回调—监听页面隐藏
        onUnloadfunction生命周期回调—监听页面卸载
        onPullDownRefreshfunction监听用户下拉动作
        onReachBottomfunction页面上拉触底事件的处理函数
        onShareAppMessagefunction用户点击右上角转发
        onShareTimelinefunction用户点击右上角转发到朋友圈
        onAddToFavoritesfunction用户点击右上角收藏
        onPageScrollfunction页面滚动触发事件的处理函数
        onResizefunction页面尺寸改变时触发,详见 响应显示区域变化
        onTabItemTapfunction当前是 tab 页时,点击 tab 时触发
        其他any开发者可以添加任意的函数或数据到 Object 参数中,在页面的函数中用 this 可以访问

        示例代码

        //index.jsPage({  data: {    text: "This is page data."  },  onLoad: function(options) {    // Do some initialize when page load.  },  onShow: function() {    // Do something when page show.  },  onReady: function() {    // Do something when page ready.  },  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  },  onResize: function() {    // Do something when page resize  },  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

        data 是页面第一次渲染使用的初始数据。

        页面加载时,data 将会以JSON字符串的形式由逻辑层传至渲染层,因此data中的数据必须是可以转成JSON的类型:字符串,数字,布尔值,对象,数组。

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

        示例代码:

        在开发者工具中预览效果

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

        生命周期回调函数

        生命周期的触发以及页面的路由方式详见

        onLoad(Object query)

        页面加载时触发。一个页面只会调用一次,可以在 onLoad 的参数中获取打开当前页面路径中的参数。

        参数:

        名称类型说明
        queryObject打开当前页面路径中的参数

        onShow()

        页面显示/切入前台时触发。

        onReady()

        页面初次渲染完成时触发。一个页面只会调用一次,代表页面已经准备妥当,可以和视图层进行交互。

        注意:对界面内容进行设置的 API 如wx.setNavigationBarTitle,请在onReady之后进行。详见生命周期

        onHide()

        页面隐藏/切入后台时触发。 如 wx.navigateTo 或底部 tab 切换到其他页面,小程序切入后台等。

        onUnload()

        页面卸载时触发。如wx.redirectTo或wx.navigateBack到其他页面时。

        页面事件处理函数

        onPullDownRefresh()

        监听用户下拉刷新事件。

        • 需要在app.json的window选项中或页面配置中开启enablePullDownRefresh。
        • 可以通过wx.startPullDownRefresh触发下拉刷新,调用后触发下拉刷新动画,效果与用户手动下拉刷新一致。
        • 当处理完数据刷新后,wx.stopPullDownRefresh可以停止当前页面的下拉刷新。

        onReachBottom()

        监听用户上拉触底事件。

        • 可以在app.json的window选项中或页面配置中设置触发距离onReachBottomDistance。
        • 在触发距离内滑动期间,本事件只会被触发一次。

        onPageScroll(Object object)

        监听用户滑动页面事件。

        参数 Object object:

        属性类型说明
        scrollTopNumber页面在垂直方向已滚动的距离(单位px)

        注意:请只在需要的时候才在 page 中定义此方法,不要定义空方法。以减少不必要的事件派发对渲染层-逻辑层通信的影响。 注意:请避免在 onPageScroll 中过于频繁的执行 setData 等引起逻辑层-渲染层通信的操作。尤其是每次传输大量数据,会影响通信耗时。

        onAddToFavorites(Object object)

        本接口为 Beta 版本,安卓 7.0.15 版本起支持,暂只在安卓平台支持

        监听用户点击右上角菜单“收藏”按钮的行为,并自定义收藏内容。

        参数 Object object:

        参数类型说明
        webviewUrlString页面中包含web-view组件时,返回当前web-view的url

        此事件处理函数需要 return 一个 Object,用于自定义收藏内容:

        字段说明默认值
        title自定义标题页面标题或账号名称
        imageUrl自定义图片,显示图片长宽比为 1:1页面截图
        query自定义query字段当前页面的query

        示例代码

        Page({  onAddToFavorites(res) {    // webview 页面返回 webviewUrl    console.log('WebviewUrl: ', res.webviewUrl)    return {      title: '自定义标题',      imageUrl: 'http://demo.png',      query: 'name=xxx&age=xxx',    }  }})

        onShareAppMessage(Object object)

        监听用户点击页面内转发按钮(button 组件 open-type="share")或右上角菜单“转发”按钮的行为,并自定义转发内容。

        注意:只有定义了此事件处理函数,右上角菜单才会显示“转发”按钮

        参数 Object object:

        参数类型说明最低版本
        fromString转发事件来源。
        button:页面内转发按钮;
        menu:右上角转发菜单
        1.2.4
        targetObject如果 from 值是 button,则 target 是触发这次转发事件的 button,否则为 undefined1.2.4
        webViewUrlString页面中包含web-view组件时,返回当前web-view的url1.6.4

        此事件处理函数需要 return 一个 Object,用于自定义转发内容,返回内容如下:

        自定义转发内容 基础库 2.8.1 起,分享图支持云图片。

        字段说明默认值最低版本
        title转发标题当前小程序名称
        path转发路径当前页面 path ,必须是以 / 开头的完整路径
        imageUrl自定义图片路径,可以是本地文件路径、代码包文件路径或者网络图片路径。支持PNG及JPG。显示图片长宽比是 5:4。使用默认截图1.5.0

        示例代码

        在开发者工具中预览效果

        Page({  onShareAppMessage: function (res) {    if (res.from === 'button') {      // 来自页面内转发按钮      console.log(res.target)    }    return {      title: '自定义转发标题',      path: '/page/user?id=123'    }  }})

        onShareTimeline()

        基础库 2.11.3 开始支持,低版本需做兼容处理。
        本接口为 Beta 版本,暂只在 Android 平台支持,详见分享到朋友圈 (Beta)

        监听右上角菜单“分享到朋友圈”按钮的行为,并自定义发享内容。

        注意:只有定义了此事件处理函数,右上角菜单才会显示“分享到朋友圈”按钮

        自定义转发内容

        事件处理函数返回一个 Object,用于自定义分享内容,不支持自定义页面路径,返回内容如下:

        字段说明默认值最低版本
        title自定义标题,即朋友圈列表页上显示的标题当前小程序名称
        query自定义页面路径中携带的参数,如 path?a=1&b=2 的 “?” 后面部分当前页面路径携带的参数
        imageUrl自定义图片路径,可以是本地文件或者网络图片。支持 PNG 及 JPG,显示图片长宽比是 1:1。默认使用小程序 Logo

        onResize(Object object)

        基础库 2.4.0 开始支持,低版本需做兼容处理。

        小程序屏幕旋转时触发。详见 响应显示区域变化

        onTabItemTap(Object object)

        基础库 1.9.0 开始支持,低版本需做兼容处理。

        点击 tab 时触发

        Object 参数说明:

        参数类型说明最低版本
        indexString被点击tabItem的序号,从0开始1.9.0
        pagePathString被点击tabItem的页面路径1.9.0
        textString被点击tabItem的按钮文字1.9.0

        示例代码:

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

        组件事件处理函数

        Page 中还可以定义组件事件处理函数。在渲染层的组件中加入事件绑定,当事件被触发时,就会执行 Page 中定义的事件处理函数。

        示例代码:

        在开发者工具中预览效果

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

        Page.route

        基础库 1.2.0 开始支持,低版本需做兼容处理。

        到当前页面的路径,类型为String。

        Page({  onShow: function() {    console.log(this.route)  }})

        Page.prototype.setData(Object data, Function callback)

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

        参数说明

        字段类型必填描述最低版本
        dataObject这次要改变的数据
        callbackFunctionsetData引起的界面更新渲染完毕后的回调函数1.5.0

        Object 以 key: value 的形式表示,将 this.data 中的 key 对应的值改变成 value。

        其中 key 可以以数据路径的形式给出,支持改变数组中的某一项或对象的某个属性,如 array[2].message,a.b.c.d,并且不需要在 this.data 中预先定义。

        注意:

        1. 直接修改 this.data 而不调用 this.setData 是无法改变页面的状态的,还会造成数据不一致。
        2. 仅支持设置可 JSON 化的数据。
        3. 单次设置的数据不能超过1024kB,请尽量避免一次设置过多的数据。
        4. 请不要把 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.jsPage({  data: {    text: 'init data',    num: 0,    array: [{text: 'init data'}],    object: {      text: 'init data'    }  },  changeText: function() {    // this.data.text = 'changed data' // 不要直接修改 this.data    // 应该使用 setData    this.setData({      text: 'changed data'    })  },  changeNum: function() {    // 或者,可以修改 this.data 之后马上用 setData 设置一下修改了的字段    this.data.num = 1    this.setData({      num: this.data.num    })  },  changeItemInArray: function() {    // 对于对象或数组字段,可以直接修改一个其下的子字段,这样做通常比修改整个对象或数组更好    this.setData({      'array[0].text':'changed data'    })  },  changeItemInObject: function(){    this.setData({      'object.text': 'changed data'    });  },  addNewField: function() {    this.setData({      'newField.text': 'new data'    })  }})

        页面间通信

        基础库 2.7.3 开始支持,低版本需做兼容处理。

        如果一个页面由另一个页面通过 wx.navigateTo 打开,这两个页面间将建立一条数据通道:

        • 被打开的页面可以通过 this.getOpenerEventChannel() 方法来获得一个 EventChannel 对象;
        • wx.navigateTo 的 success 回调中也包含一个 EventChannel 对象。

        这两个 EventChannel 对象间可以使用 emit 和 on 方法相互发送、监听事件。


        PageObject[] getCurrentPages()

        获取当前页面栈。数组中第一个元素为首页,最后一个元素为当前页面。

        注意:

        • 不要尝试修改页面栈,会导致路由以及页面状态错误。
        • 不要在 App.onLaunch 的时候调用 getCurrentPages(),此时 page 还没有生成。


        Component(Object object)

        创建自定义组件,接受一个 Object 类型的参数。

        参数

        Object object

        定义段类型是否必填描述最低版本
        propertiesObject Map组件的对外属性,是属性名到属性设置的映射表
        dataObject组件的内部数据,和 properties 一同用于组件的模板渲染
        observersObject组件数据字段监听器,用于监听 properties 和 data 的变化,参见 数据监听器2.6.1
        methodsObject组件的方法,包括事件响应函数和任意的自定义方法,关于事件响应函数的使用,参见 组件间通信与事件
        behaviorsString Array类似于mixins和traits的组件间代码复用机制,参见 behaviors
        createdFunction组件生命周期函数-在组件实例刚刚被创建时执行,注意此时不能调用 setData )
        attachedFunction组件生命周期函数-在组件实例进入页面节点树时执行)
        readyFunction组件生命周期函数-在组件布局完成后执行)
        movedFunction组件生命周期函数-在组件实例被移动到节点树另一个位置时执行)
        detachedFunction组件生命周期函数-在组件实例被从页面节点树移除时执行)
        relationsObject组件间关系定义,参见 组件间关系
        externalClassesString Array组件接受的外部样式类,参见 外部样式类
        optionsObject Map一些选项(文档中介绍相关特性时会涉及具体的选项设置,这里暂不列举)
        lifetimesObject组件生命周期声明对象,参见 组件生命周期2.2.3
        pageLifetimesObject组件所在页面的生命周期声明对象,参见 组件生命周期2.2.3
        definitionFilterFunction定义段过滤器,用于自定义组件扩展,参见 自定义组件扩展2.2.3

        生成的组件实例可以在组件的方法、生命周期函数和属性 observer 中通过 this 访问。组件包含一些通用属性和方法。

        属性名类型描述
        isString组件的文件路径
        idString节点id
        datasetString节点dataset
        dataObject组件数据,包括内部数据和属性值
        propertiesObject组件数据,包括内部数据和属性值(与 data 一致)
        方法名参数描述最低版本
        setDataObject newData设置data并执行视图层渲染
        hasBehaviorObject behavior检查组件是否具有 behavior (检查时会递归检查被直接或间接引入的所有behavior)
        triggerEventString name, Object detail, Object options触发事件,参见 组件间通信与事件
        createSelectorQuery创建一个 SelectorQuery 对象,选择器选取范围为这个组件实例内
        createIntersectionObserver创建一个 IntersectionObserver 对象,选择器选取范围为这个组件实例内
        createMediaQueryObserver创建一个 MediaQueryObserver 对象2.11.1
        selectComponentString selector使用选择器选择组件实例节点,返回匹配到的第一个组件实例对象(会被 wx://component-export 影响)
        selectAllComponentsString selector使用选择器选择组件实例节点,返回匹配到的全部组件实例对象组成的数组(会被 wx://component-export 影响)
        selectOwnerComponent选取当前组件节点所在的组件实例(即组件的引用者),返回它的组件实例对象(会被 wx://component-export 影响)2.8.2
        getRelationNodesString relationKey获取这个关系所对应的所有关联节点,参见 组件间关系
        groupSetDataFunction callback立刻执行 callback ,其中的多个 setData 之间不会触发界面绘制(只有某些特殊场景中需要,如用于在不同组件同时 setData 时进行界面绘制同步)2.4.0
        getTabBar返回当前页面的 custom-tab-bar 的组件实例,详见自定义 tabBar2.6.2
        getPageId返回页面标识符(一个字符串),可以用来判断几个自定义组件实例是不是在同一个页面内2.7.1
        animateString selector, Array keyframes, Number duration, Function callback执行关键帧动画,详见动画2.9.0
        clearAnimationString selector, Object options, Function callback清除关键帧动画,详见动画2.9.0

        代码示例:

        在开发者工具中预览效果

        Component({  behaviors: [],  // 属性定义(详情参见下文)  properties: {    myProperty: { // 属性名      type: String,      value: ''    },    myProperty2: String // 简化的定义方式  },  data: {}, // 私有数据,可用于模板渲染  lifetimes: {    // 生命周期函数,可以为函数,或一个在methods段中定义的方法名    attached: function () { },    moved: function () { },    detached: function () { },  },  // 生命周期函数,可以为函数,或一个在methods段中定义的方法名  attached: function () { }, // 此处attached的声明会被lifetimes字段中的声明覆盖  ready: function() { },  pageLifetimes: {    // 组件所在页面的生命周期函数    show: function () { },    hide: function () { },    resize: function () { },  },  methods: {    onMyButtonTap: function(){      this.setData({        // 更新属性和数据的方法与更新页面数据的方法类似      })    },    // 内部方法建议以下划线开头    _myPrivateMethod: function(){      // 这里将 data.A[0].B 设为 'myPrivateData'      this.setData({        'A[0].B': 'myPrivateData'      })    },    _propertyChange: function(newVal, oldVal) {    }  }})

        注意:在 properties 定义段中,属性名采用驼峰写法(propertyName);在 wxml 中,指定属性值时则对应使用连字符写法(component-tag-name property-name="attr value"),应用于数据绑定时采用驼峰写法(attr="")。

        properties 定义

        定义段类型是否必填描述最低版本
        type属性的类型
        optionalTypesArray属性的类型(可以指定多个)2.6.5
        value属性的初始值
        observerFunction属性值变化时的回调函数

        属性值的改变情况可以使用 observer 来监听。目前,在新版本基础库中不推荐使用这个字段,而是使用 Component 构造器的 observers 字段代替,它更加强大且性能更好。

        代码示例:

        Component({  properties: {    min: {      type: Number,      value: 0    },    min: {      type: Number,      value: 0,      observer: function(newVal, oldVal) {        // 属性值变化时执行      }    },    lastLeaf: {      // 这个属性可以是 Number 、 String 、 Boolean 三种类型中的一种      type: Number,      optionalTypes: [String, Object],      value: 0    }  }})

        属性的类型可以为 String Number Boolean Object Array 其一,也可以为 null 表示不限制类型。

        多数情况下,属性最好指定一个确切的类型。这样,在 WXML 中以字面量指定属性值时,值可以获得一个确切的类型,如:

        <custom-comp min="1" max="5" />

        此时,由于自定义组件的对应属性被规定为 Number 类型, min 和 max 会被赋值为 1 和 5 ,而非 "1" 和 "5" ,即:

        this.data.min === 1 // truethis.data.max === 5 // true

        提示:

        • 使用 this.data 可以获取内部数据和属性值;但直接修改它不会将变更应用到界面上,应使用 setData 修改。
        • 生命周期函数无法在组件方法中通过 this 访问到。
        • 属性名应避免以 data 开头,即不要命名成 dataXyz 这样的形式,因为在 WXML 中, data-xyz="" 会被作为节点 dataset 来处理,而不是组件属性。
        • 在一个组件的定义和使用时,组件的属性名和 data 字段相互间都不能冲突(尽管它们位于不同的定义段中)。
        • 从基础库 2.0.9 开始,对象类型的属性和 data 字段中可以包含函数类型的子字段,即可以通过对象类型的属性字段来传递函数。低于这一版本的基础库不支持这一特性。
        • bug : 位于 slot 中的自定义组件没有触发 pageLifetimes 中声明的页面生命周期,此问题在 2.5.2 中修复。
        • bug : 对于 type 为 Object 或 Array 的属性,如果通过该组件自身的 this.setData 来改变属性值的一个子字段,则依旧会触发属性 observer ,且 observer 接收到的 newVal 是变化的那个子字段的值, oldVal 为空, changedPath 包含子字段的字段名相关信息;目前推荐使用 observers 定义段代替。

        Behavior(Object object)

        注册一个 behavior,接受一个 Object 类型的参数。

        参数

        Object object

        定义段类型是否必填描述最低版本
        propertiesObject Map同组件的属性
        dataObject同组件的数据
        methodsObject同自定义组件的方法
        behaviorsString Array引入其它的 behavior
        createdFunction生命周期函数
        attachedFunction生命周期函数
        readyFunction生命周期函数
        movedFunction生命周期函数
        detachedFunction生命周期函数

        代码示例:

        // my-behavior.jsmodule.exports = Behavior({  behaviors: [],  properties: {    myBehaviorProperty: {      type: String    }  },  data: {    myBehaviorData: {}  },  attached: function(){},  methods: {    myBehaviorMethod: function(){}  }})


        any require(string path)

        引入模块。返回模块通过 module.exports 或 exports 暴露的接口。

        参数

        名称类型说明
        pathstring需要引入模块文件相对于当前文件的相对路径,或npm模块名,或npm模块路径。不支持绝对路径

        示例代码

        // common.jsfunction sayHello(name) {  console.log(`Hello ${name} !`)}function sayGoodbye(name) {  console.log(`Goodbye ${name} !`)}module.exports.sayHello = sayHelloexports.sayGoodbye = sayGoodbye
        var common = require('common.js')Page({  helloMINA: function() {    common.sayHello('MINA')  },  goodbyeMINA: function() {    common.sayGoodbye('MINA')  }})

        Object module

        当前模块对象

        属性

        属性类型说明
        exportsObject模块向外暴露的对象,使用require引用该模块时可以获取

        示例代码

        // common.jsfunction sayHello(name) {  console.log(`Hello ${name} !`)}function sayGoodbye(name) {  console.log(`Goodbye ${name} !`)}module.exports.sayHello = sayHelloexports.sayGoodbye = sayGoodbye

        Object exports

        module.exports 的引用

        示例代码

        // common.jsfunction sayHello(name) {  console.log(`Hello ${name} !`)}function sayGoodbye(name) {  console.log(`Goodbye ${name} !`)}module.exports.sayHello = sayHelloexports.sayGoodbye = sayGoodbye


        Object wx

        小程序 API 全局对象,用于承载小程序能力相关 API。

        Object wx.env

        小程序环境变量对象

        String wx.env.USER_DATA_PATH

        文件系统中的用户目录路径


        console

        向调试面板中打印日志。console 是一个全局对象,可以直接访问。在微信客户端中,向 vConsole 中输出日志。

        方法:

        console.debug()

        向调试面板中打印 debug 日志

        参数

        any ...args

        日志内容,可以有任意多个。


        console.error()

        向调试面板中打印 error 日志

        参数

        any ...args

        日志内容,可以有任意多个。


        console.group(string label)

        在调试面板中创建一个新的分组。随后输出的内容都会被添加一个缩进,表示该内容属于当前分组。调用 console.groupEnd之后分组结束。

        参数

        string label

        分组标记,可选。

        注意

        仅在工具中有效,在 vConsole 中为空函数实现。


        console.groupEnd()

        结束由 console.group 创建的分组

        注意

        仅在工具中有效,在 vConsole 中为空函数实现。


        console.info()

        向调试面板中打印 info 日志

        参数

        any ...args

        日志内容,可以有任意多个。


        console.log()

        向调试面板中打印 log 日志

        参数

        any ...args

        日志内容,可以有任意多个


        console.warn()

        向调试面板中打印 warn 日志

        参数

        any ...args

        日志内容,可以有任意多个。


        number setTimeout(function callback, number delay, any rest)

        设定一个定时器。在定时到期以后执行注册的回调函数

        参数

        function callback

        回调函数

        number delay

        延迟的时间,函数的调用会在该延迟之后发生,单位 ms。

        any rest

        param1, param2, ..., paramN 等附加参数,它们会作为参数传递给回调函数。

        返回值

        number

        定时器的编号。这个值可以传递给 clearTimeout 来取消该定时。


        clearTimeout(number timeoutID)

        取消由 setTimeout 设置的定时器。

        参数

        number timeoutID

        要取消的定时器的 ID


        number setInterval(function callback, number delay, any rest)

        设定一个定时器。按照指定的周期(以毫秒计)来执行注册的回调函数

        参数

        function callback

        回调函数

        number delay

        执行回调函数之间的时间间隔,单位 ms。

        any rest

        param1, param2, ..., paramN 等附加参数,它们会作为参数传递给回调函数。

        返回值

        number

        定时器的编号。这个值可以传递给 clearInterval 来取消该定时。


        clearInterval(number intervalID)

        取消由 setInterval 设置的定时器。

        参数

        number intervalID

        要取消的定时器的 ID


        逻辑层(App Service)


        小程序开发框架的逻辑层是由JavaScript编写。

        逻辑层将数据进行处理后发送给视图层,同时接受视图层的事件反馈。在 JavaScript 的基础上,我们做了一些修改,以方便地开发小程序。

        • 增加 AppPage 方法,进行程序和页面的注册。
        • 提供丰富的 API,如扫一扫,支付等微信特有能力。
        • 每个页面有独立的作用域,并提供模块化能力。
        • 由于框架并非运行在浏览器中,所以 JavaScript 在 web 中一些能力都无法使用,如 document,window 等。
        • 开发者写的所有代码最终将会打包成一份 JavaScript,并在小程序启动的时候运行,直到小程序销毁。类似 ServiceWorker,所以逻辑层也称之为 App Service。

        App

        App()


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

        object参数说明:

        属性类型描述触发时机
        onLaunchFunction生命周期函数--监听小程序初始化当小程序初始化完成时,会触发 onLaunch(全局只触发一次)
        onShowFunction生命周期函数--监听小程序显示当小程序启动,或从后台进入前台显示,会触发 onShow
        onHideFunction生命周期函数--监听小程序隐藏当小程序从前台进入后台,会触发 onHide
        onErrorFunction错误监听函数当小程序发生脚本错误,或者 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 参数

        字段类型说明
        pathString打开小程序的路径
        queryObject打开小程序的query
        sceneNumber打开小程序的场景值
        shareTicketStringshareTicket,详见 获取更多转发信息
        referrerInfoObject当场景为由另一个小程序打开时,返回此字段
        referrerInfo.appIdString来源小程序的 appId
        referrerInfo.extraDataObject来源小程序传过来的数据

        场景值 详见

        以下场景支持返回 referrerInfo.appId:

        场景值场景appId 信息含义
        1020公众号 profile 页相关小程序列表返回来源公众号 appId
        1035公众号自定义菜单返回来源公众号 appId
        1036App 分享消息卡片返回来源应用 appId
        1037小程序打开小程序返回来源小程序 appId
        1038从另一个小程序返回返回来源小程序 appId
        1043公众号模板消息返回来源公众号 appId

        onPageNotFound

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

        当要打开的页面并不存在时,会回调这个监听器,并带上以下信息:

        字段类型说明
        pathString不存在页面的路径
        queryObject打开不存在页面的 query
        isEntryPageBoolean是否本次启动的首个页面(例如从分享等入口进来,首个页面是开发者配置的分享页面)

        开发者可以在 onPageNotFound 回调中进行重定向处理,但必须在回调中同步处理,异步处理(例如 setTimeout 异步执行)无效。

        示例代码:

        App({  onPageNotFound(res) {    wx.redirectTo({      url: 'pages/...'    })  }})

        注意:

        1. 微信开发者工具暂不支持 onPageNotFound 调试,请使用真机调试
        2. 如果开发者没有添加 onPageNotFound 监听,当跳转页面不存在时,将推入微信客户端原生的页面不存在提示页面
        3. 如果 onPageNotFound 回调中又重定向到另一个不存在的页面,将推入微信客户端原生的页面不存在提示页面,并且不在回调 onPageNotFound

        getApp()


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

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

        注意:

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

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

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

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

        场景值列表

        关于场景值的详细说明和获取方式请参考 指南-场景值

        场景值ID说明图例
        1000其他/
        1001发现栏小程序主入口,「最近使用」列表(基础库2.2.4版本起包含「我的小程序」列表)/
        1005微信首页顶部搜索框的搜索结果页查看
        1006发现栏小程序主入口搜索框的搜索结果页查看
        1007单人聊天会话中的小程序消息卡片查看
        1008群聊会话中的小程序消息卡片查看
        1010收藏夹查看
        1011扫描二维码查看
        1012长按图片识别二维码查看
        1013扫描手机相册中选取的二维码查看
        1014小程序模板消息查看
        1017前往小程序体验版的入口页查看
        1019微信钱包(微信客户端7.0.0版本改为支付入口)查看
        1020公众号 profile 页相关小程序列表(已废弃)查看
        1022聊天顶部置顶小程序入口(微信客户端6.6.1版本起废弃)/
        1023安卓系统桌面图标查看
        1024小程序 profile 页查看
        1025扫描一维码查看
        1026发现栏小程序主入口,「附近的小程序」列表查看
        1027微信首页顶部搜索框搜索结果页「使用过的小程序」列表查看
        1028我的卡包查看
        1029小程序中的卡券详情页查看
        1030自动化测试下打开小程序/
        1031长按图片识别一维码查看
        1032扫描手机相册中选取的一维码查看
        1034微信支付完成页查看
        1035公众号自定义菜单查看
        1036App 分享消息卡片查看
        1037小程序打开小程序查看
        1038从另一个小程序返回查看
        1039摇电视查看
        1042添加好友搜索框的搜索结果页查看
        1043公众号模板消息查看
        1044带 shareTicket 的小程序消息卡片 详情查看
        1045朋友圈广告查看
        1046朋友圈广告详情页查看
        1047扫描小程序码查看
        1048长按图片识别小程序码查看
        1049扫描手机相册中选取的小程序码查看
        1052卡券的适用门店列表查看
        1053搜一搜的结果页查看
        1054顶部搜索框小程序快捷入口(微信客户端版本6.7.4起废弃)/
        1056聊天顶部音乐播放器右上角菜单查看
        1057钱包中的银行卡详情页查看
        1058公众号文章查看
        1059体验版小程序绑定邀请页/
        1064微信首页连Wi-Fi状态栏查看
        1067公众号文章广告查看
        1068附近小程序列表广告(已废弃)/
        1069移动应用查看
        1071钱包中的银行卡列表页查看
        1072二维码收款页面查看
        1073客服消息列表下发的小程序消息卡片查看
        1074公众号会话下发的小程序消息卡片查看
        1077摇周边查看
        1078微信连Wi-Fi成功提示页查看
        1079微信游戏中心查看
        1081客服消息下发的文字链查看
        1082公众号会话下发的文字链查看
        1084朋友圈广告原生页查看
        1088会话中查看系统消息,打开小程序/
        1089微信聊天主界面下拉,「最近使用」栏(基础库2.2.4版本起包含「我的小程序」栏)查看
        1090长按小程序右上角菜单唤出最近使用历史查看
        1091公众号文章商品卡片查看
        1092城市服务入口查看
        1095小程序广告组件查看
        1096聊天记录,打开小程序查看
        1097微信支付签约原生页,打开小程序查看
        1099页面内嵌插件/
        1102公众号 profile 页服务预览查看
        1103发现栏小程序主入口,「我的小程序」列表(基础库2.2.4版本起废弃)/
        1104微信聊天主界面下拉,「我的小程序」栏(基础库2.2.4版本起废弃)/
        1106聊天主界面下拉,从顶部搜索结果页,打开小程序/
        1107订阅消息,打开小程序/
        1113安卓手机负一屏,打开小程序(三星)/
        1114安卓手机侧边栏,打开小程序(三星)/
        1124扫“一物一码”打开小程序/
        1125长按图片识别“一物一码”/
        1126扫描手机相册中选取的“一物一码”/
        1129微信爬虫访问 详情/
        1131浮窗打开小程序/
        1133硬件设备打开小程序 详情/
        1135小程序profile页其他小程序列表,打开小程序查看
        1146地理位置信息打开出行类小程序查看
        1148卡包-交通卡,打开小程序/
        1150扫一扫商品条码结果页打开小程序查看
        1153“识物”结果页打开小程序查看
        1154朋友圈内打开“单页模式”查看
        1155“单页模式”打开小程序查看
        1169发现栏小程序主入口,各个生活服务入口(例如快递服务、出行服务等)查看


        Page


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

        object 参数说明:

        属性类型描述
        dataObject页面的初始数据
        onLoadFunction生命周期函数--监听页面加载
        onReadyFunction生命周期函数--监听页面初次渲染完成
        onShowFunction生命周期函数--监听页面显示
        onHideFunction生命周期函数--监听页面隐藏
        onUnloadFunction生命周期函数--监听页面卸载
        onPullDownRefreshFunction页面相关事件处理函数--监听用户下拉动作
        onReachBottomFunction页面上拉触底事件的处理函数
        onShareAppMessageFunction用户点击右上角转发
        onPageScrollFunction页面滚动触发事件的处理函数
        其他Any开发者可以添加任意的函数或数据到 object 参数中,在页面的函数中用 this 可以访问

        示例代码:

        //index.jsPage({  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  },  // 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[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: 页面卸载

          • redirectTonavigateBack的时候调用。

        生命周期的调用以及页面的路由方式详见

        onLoad参数

        类型说明
        Object其他页面打开当前页面所调用的 query 参数

        页面相关事件处理函数


        • onPullDownRefresh: 下拉刷新

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

          • 监听用户下拉触底事件。
        • onPageScroll: 页面滚动

          • 监听用户滑动页面事件。
          • 参数为 Object,包含以下字段:
        字段类型说明
        scrollTopNumber页面在垂直方向已滚动的距离(单位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


        route 字段可以获取到当前页面的路径。

        Page.prototype.setData()


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

        setData() 参数格式


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

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

        注意:

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

        示例代码:

        <!--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.jsPage({  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 实例的生命周期。

        1488607970192659


        页面路由

        在小程序中所有页面的路由全部由框架进行管理。

        页面栈

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

        路由方式页面栈表现
        初始化新页面入栈
        打开新页面新页面入栈
        页面重定向当前页面出栈,新页面入栈
        页面返回页面不断出栈,直到目标返回页,新页面入栈
        Tab 切换页面全部出栈,只留下新的 Tab 页面
        重加载页面全部出栈,只留下新的页面

        getCurrentPages()

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

        Tip:不要尝试修改页面栈,会导致路由以及页面状态错误。

        路由方式

        对于路由的触发方式以及页面生命周期函数如下:

        路由方式触发时机路由前页面路由后页面
        初始化小程序打开的第一个页面 onLoad, onSHow
        打开新页面调用 API wx.navigateTo 或使用组件 <navigator open-type="navigateTo"/>onHideonLoad, onShow
        页面重定向调用 API wx.redirectTo 或使用组件 <navigator open-type="redirectTo"/>onUnloadonLoad, onShow
        页面返回调用 API wx.navigateBack 或使用组件<navigator open-type="navigateBack">或用户按左上角返回按钮onUnloadonShow
        Tab 切换调用 API wx.switchTab 或使用组件 <navigator open-type="switchTab"/> 或用户切换 Tab 各种情况请参考下表
        重启动调用 API wx.reLaunch 或使用组件 <navigator open-type="reLaunch"/>onUnloadonLoad, onShow

        Tab 切换对应的生命周期(以 A、B 页面为 Tabbar 页面,C 是从 A 页面打开的页面,D 页面是从 C 页面打开的页面为例):

        当前页面路由后页面触发的生命周期(按顺序)
        AANothing happend
        ABA.onHide(), B.onLoad(), B.onShow()
        AB(再次打开)A.onHide(), B.onShow()
        CAC.onUnload(), A.onShow()
        CBC.onUnload(), B.onLoad(), B.onShow()
        DBD.onUnload(), C.onUnload(), B.onLoad(), B.onShow()
        D(从转发进入)AD.onUnload(), A.onLoad(), A.onShow()
        D(从转发进入)BD.onUnload(), B.onLoad(), B.onShow()

        Tips:

        • navigateTo,redirectTo只能打开非 tabBar 页面。
        • switchTab 只能打开 tabBar 页面。
        • reLaunch 可以打开任意页面。
        • 页面底部的 tabBar 由页面决定,即只要是定义为 tabBar 的页面,底部都有 tabBar。
        • 调用页面路由带的参数可以在目标页面的onLoad中获取。

        文件作用域

        在JavaScript文件中声明的变量和函数只在该文件中有效;不同的文件中可以声明相同名字的变量和函数,不会互相影响。

        通过全局函数getApp()可以获取全局的应用实例,如果需要全局的数据可以在App()中设置,如:

        // app.jsApp({  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才能对外暴露接口。

        需要注意的是:

        • exportsmodule.exports的一个引用,因此在模块里边随意更改exports的指向会造成未知的错误。所以我们更推荐开发者采用module.exports来暴露模块接口,除非你已经清晰知道这两者的关系。
        • 小程序目前不支持直接引入node_modules,开发者需要使用到node_modules时候建议拷贝出相关的代码到小程序的目录中。

        // common.jsfunction sayHello(name) {  console.log('Hello ${name} !')}function sayGoodbye(name) {  console.log('Goodbye ${name} !')}module.exports.sayHello = sayHelloexports.sayGoodbye = sayGoodbye

        ​在需要使用这些模块的文件中,使用require(path)将公共代码引入。

        var common = require('common.js')Page({  helloMINA: function() {    common.sayHello('MINA')  }  goodbyeMINA: function() {    common.sayGoodbye('MINA')  }})

        Tips

        1. tip:require暂时不支持绝对路径


        小程序API

        小程序开发框架MINA提供丰富的微信原生API,可以方便的调起微信提供的能力,如获取用户信息本地存储支付功能等。

        详细介绍请参考微信小程序API文档

        视图层


        • MINA的视图层由WXML与WXSS编写。
        • 将逻辑层的数据反应成视图,同时将视图层的事件发送给逻辑层。
        • WXML(WeiXin Markup language)用于描述页面的结构。
        • WXSS(WeiXin Style Sheet)用于描述页面的样式。
        • 组件(Component)是视图的基本组成单元。

        WXML


        WXML(WeiXin Markup Language)是框架设计的一套标签语言,结合基础组件事件系统,可以构建出页面的结构。

        用以下一些简单的例子来看看WXML具有什么能力:

        数据绑定


        <!--wxml--><view> {{message}} </view>
        // page.jsPage({  data: {    message: 'Hello MINA!'  }})

        列表渲染


        <!--wxml--><view wx:for-items="{{array}}"> {{item}} </view>
        // page.jsPage({  data: {    array: [1, 2, 3, 4, 5]  }})

        条件渲染


        <!--wxml--><view wx:if="{{view == 'WEBVIEW'}}"> WEBVIEW </view><view wx:elif="{{view == 'APP'}}"> APP </view><view wx:else="{{view == 'MINA'}}"> MINA </view>
        // page.jsPage({  data: {    view: 'MINA'  }})

        模板


        <!--wxml--><template name="staffName">  <view>    FirstName: {{firstName}}, LastName: {{lastName}}  </view></template><template is="staffName" data="{{...staffA}}"></template><template is="staffName" data="{{...staffB}}"></template><template is="staffName" data="{{...staffC}}"></template>
        // page.jsPage({  data: {    staffA: {firstName: 'Hulk', lastName: 'Hu'},    staffB: {firstName: 'Shang', lastName: 'You'},    staffC: {firstName: 'Gideon', lastName: 'Lin'}  }})

        事件


        <view bindtap="add"> {{count}} </view>
        Page({  data: {    count: 1  },  add: function(e) {    this.setData({      count: this.data.count + 1    })  }})

        具体的能力以及使用方式在以下章节查看:

        数据绑定列表渲染条件渲染模板事件引用

        数据绑定

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

        简单绑定

        数据绑定使用"Mustache"语法(双大括号)将变量包起来,可以作用于:

        内容

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

        组件属性(需要在双引号之内)

        <view id="item-{{id}}"> </view>
        Page({  data: {    id: 0  }})

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

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

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

        true:boolean 类型的 true,代表真值。

        false: boolean 类型的 false,代表假值。

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

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


        运算

        可以在{{}}内进行简单的运算,支持的有如下几种方式:

        三元运算

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

        算数运算

        <view> {{a + b}} + {{c}} + d </view>
        Page({  data: {    a: 1,    b: 2,    c: 3  }})

        view中的内容为3 + 3 + d

        逻辑判断

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

        字符串运算

        <view>{{"hello" + name}}</view>
        Page({  data:{    name:"MINA"  }})

        数据路径运算

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

        组合

        也可以在Mustache内直接进行组合,构成新的对象或者数组。

        数组

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

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

        对象

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

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

        也可以用扩展运算符...来将一个对象展开

        <template is="objectCombine" data="{{...obj1, ...obj2, e: 5}}"></template>
        Page({  data: {    obj1: {      a: 1,      b: 2    },    obj2: {      c: 3,      d: 4    }  }})

        最终组合成的对象是{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'}

        注意:上述方式可以随意组合,但是如有存在变量名相同的情况,后边的会覆盖前面,如:

        <template is="objectCombine" data="{{...obj1, ...obj2, a, c: 6}}"></template>
        Page({  data: {    obj1: {      a: 1,      b: 2    },    obj2: {      b: 3,      c: 4    },    a: 5  }})

        最终组合成的对象是 {a: 5, b: 3, c: 6}

        注意: 花括号和引号之间如果有空格,将最终被解析成为字符串

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

        等同于

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

        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方法:

        20200629113357203

        20200629113319412

         这个注意了。wx:key还是要加上的,不然一直报这个提示错误

        20200629145733130



        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>

        wx:key


        如果列表中项目的位置会动态改变或者有新的项目添加到列表中,并且希望列表中的项目保持自己的特征和状态(如 <input/> 中的输入内容,<switch/> 的选中状态),需要使用 wx:key 来指定列表中项目的唯一的标识符。

        wx:key 的值以两种形式提供

        1. 字符串,代表在 for 循环的 array 中 item 的某个 property,该 property 的值需要是列表中唯一的字符串或数字,且不能动态改变。
        2. 保留关键字 *this 代表在 for 循环中的 item 本身,这种表示需要 item 本身是一个唯一的字符串或者数字,如:

        当数据改变触发渲染层重新渲染的时候,会校正带有 key 的组件,框架会确保他们被重新排序,而不是重新创建,以确保使组件保持自身的状态,并且提高列表渲染时的效率。

        如不提供 wx:key,会报一个 warning, 如果明确知道该列表是静态,或者不必关注其顺序,可以选择忽略。

        示例代码:

        <switch wx:for="{{objectArray}}" wx:key="unique" style="display: block;"> {{item.id}} </switch><button bindtap="switch"> Switch </button><button bindtap="addToFront"> Add to the front </button><switch wx:for="{{numberArray}}" wx:key="*this" style="display: block;"> {{item}} </switch><button bindtap="addNumberToFront"> Add to the front </button>
        Page({  data: {    objectArray: [      {id: 5, unique: 'unique_5'},      {id: 4, unique: 'unique_4'},      {id: 3, unique: 'unique_3'},      {id: 2, unique: 'unique_2'},      {id: 1, unique: 'unique_1'},      {id: 0, unique: 'unique_0'},    ],    numberArray: [1, 2, 3, 4]  },  switch: function(e) {    const length = this.data.objectArray.length    for (let i = 0; i < length; ++i) {      const x = Math.floor(Math.random() * length)      const y = Math.floor(Math.random() * length)      const temp = this.data.objectArray[x]      this.data.objectArray[x] = this.data.objectArray[y]      this.data.objectArray[y] = temp    }    this.setData({      objectArray: this.data.objectArray    })  },  addToFront: function(e) {    const length = this.data.objectArray.length    this.data.objectArray = [{id: length, unique: 'unique_' + length}].concat(this.data.objectArray)    this.setData({      objectArray: this.data.objectArray    })  },  addNumberToFront: function(e){    this.data.numberArray = [ this.data.numberArray.length + 1 ].concat(this.data.numberArray)    this.setData({      numberArray: this.data.numberArray    })  }})

        注意:

        wx:for 的值为字符串时,会将字符串解析成字符串数组

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

        等同于

        <view wx:for="{{['a','r','r','a','y']}}">  {{item}}</view>

        注意: 花括号和引号之间如果有空格,将最终被解析成为字符串

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

        等同于

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


        wx:if

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

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

        也可以用wx:elifwx:else来添加一个else块:

        <view wx:if="{{length > 5}}"> 1 </view><view wx:elif="{{length > 2}}"> 2 </view><view wx:else> 3 </view>

        block wx:if

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

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

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

        实例:

        wxml:使用view

        <!--index.wxml--><button bindtap="EventHandle">按钮</button><!-- wx:if --><view wx:if="{{boolean==true}}">    <view class="bg_black"></view></view> <view wx:elif="{{boolean==false}}">    <view class="bg_red"></view></view>

        wxss:

        /**index.wxss**/.bg_black {  height: 200rpx;  background: lightskyblue;}.bg_red {  height: 200rpx;  background: lightpink;}

        js:

        // index.js Page({  data: {    boolean:false  },   EventHandle: function(){    var bol = this.data.boolean;    this.setData({      boolean: !bol     })  } })

        运行:

        p


        wx:ifvshidden

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

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

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

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


        模板


        WXML提供模板(template),可以在模板中定义代码片段,然后在不同的地方调用。

        定义模板


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

        <!--  index: int  msg: string  time: string--><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'    }  }})

        is属性可以使用Mustache语法,来动态决定具体需要渲染哪个模板:

        <template name="odd">  <view> odd </view></template><template name="even">  <view> even </view></template><block wx:for="{{[1, 2, 3, 4, 5]}}">    <template is="{{item % 2 == 0 ? 'even' : 'odd'}}"/></block>

        模板的作用域

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

        什么是事件


        • 事件是视图层到逻辑层的通讯方式。
        • 事件可以将用户的行为反馈到逻辑层进行处理。
        • 事件可以绑定在组件上,当达到触发事件,就会执行逻辑层中对应的事件处理函数。
        • 事件对象可以携带额外信息,如id, dataset, touches。

        事件的使用方式


        • 在组件中绑定一个事件处理函数。

        bindtap,当用户点击该组件的时候会在该页面对应的Page中找到相应的事件处理函数。

        <view id="tapTest" data-hi="WeChat" bindtap="tapName"> Click me! </view>
        • 在相应的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,}],}

        事件详解

        事件分类

        事件分为冒泡事件和非冒泡事件

        1. 冒泡事件:当一个组件上的事件被触发后,该事件会向父节点传递。
        2. 非冒泡事件:当一个组件上的事件被触发后,该事件不会向父节点传递。

        WXML的冒泡事件列表:

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

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

        事件绑定


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

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

        bind事件绑定不会阻止冒泡事件向上冒泡,catch事件绑定可以阻止冒泡事件向上冒泡。

        如在下边这个例子中,点击inner view会先后触发handleTap3handleTap2(因为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>

        事件对象


        如无特殊说明,当组件触发事件时,逻辑层绑定该事件的处理函数会收到一个事件对象。

        BaseEvent基础事件对象属性列表:

        属性 类型 说明
        type String 事件类型
        timeStamp Integer 事件生成时的时间戳
        target Object 触发事件的组件的一些属性值集合
        currentTarget Object 当前组件的一些属性值集合

        CustomEvent 自定义事件对象属性列表(继承 BaseEvent):

        属性类型说明
        detailObject额外的信息

        TouchEvent 触摸事件对象属性列表(继承 BaseEvent):

        属性类型说明
        touchesArray触摸事件,当前停留在屏幕中的触摸点信息的数组
        changedTouchesArray触摸事件,当前变化的触摸点信息的数组

        特殊事件:<canvas/>中的触摸事件不可冒泡,所以没有 currentTarget。


        type

        通用事件类型

        timeStamp

        该页面打开到触发事件所经过的毫秒数。

        target

        触发事件的源组件。

        属性类型说明
        idString事件源组件的id
        tagNameString当前组件的类型
        datasetObject事件源组件上由data-开头的自定义属性组成的集合

        currentTarget

        事件绑定的当前组件。

        属性类型说明
        idString当前组件的id
        tagNameString当前组件的类型
        datasetObject当前组件上由data-开头的自定义属性组成的集合

        说明: target 和 currentTarget 可以参考上例中,点击 inner view 时,handleTap3 收到的事件对象 target 和 currentTarget 都是 inner,而 handleTap2 收到的事件对象 target 就是 inner,currentTarget 就是 middle。

        dataset

        在组件中可以定义数据,这些数据将会通过事件传递给 SERVICE。书写方式:以data-开头,多个单词由连字符-链接,不能有大写(大写会自动转成小写)如data-element-type,最终在 event.target.dataset 中会将连字符转成驼峰elementType

        示例:

        <view data-alpha-beta="1" data-alphaBeta="2" bindtap="bindViewTap"> DataSet Test </view>
        Page({  bindViewTap:function(event){    event.target.dataset.alphaBeta === 1 // - 会转为驼峰写法    event.target.dataset.alphabeta === 2 // 大写会转为小写  }})

        touches

        touches 是一个数组,每个元素为一个 Touch 对象(canvas 触摸事件中携带的 touches 是 CanvasTouch 数组)。 表示当前停留在屏幕上的触摸点。

        Touch 对象

        属性类型说明
        identifierNumber触摸点的标识符
        pageX, pageYNumber距离文档左上角的距离,文档的左上角为原点 ,横向为X轴,纵向为Y轴
        clientX, clientYNumber距离页面可显示区域(屏幕除去导航条)左上角距离,横向为X轴,纵向为Y轴

        CanvasTouch 对象

        属性类型说明特殊说明
        identifierNumber触摸点的标识符 
        x, yNumber距离 Canvas 左上角的距离,Canvas 的左上角为原点 ,横向为X轴,纵向为Y轴 

        changedTouches

        changedTouches 数据格式同 touches。表示有变化的触摸点,如从无变有(touchstart),位置变化(touchmove),从有变无(touchend、touchcancel)。

        detail

        自定义事件所携带的数据,如表单组件的提交事件会携带用户的输入,媒体的错误事件会携带错误信息,详见组件定义中各个事件的定义。

        点击事件的detail 带有的 x, y 同 pageX, pageY 代表距离文档左上角的距离。

        引用

        WXML提供两种文件引用方式importinclude

        import

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

        在item.wxml中定义了一个叫itemtemplate

        <!-- item.wxml --><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

        <!-- A.wxml --><template name="A">  <text> A template </text></template>
        <!-- B.wxml --><import src="a.wxml"/><template name="B">  <text> B template </text></template>
        <!-- C.wxml --><import src="b.wxml"/><template is="A"/>  <!-- Error! Can not use tempalte when not import A. --><template is="B"/>

        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>

        WXS

        WXS(WeiXin Script)是小程序的一套脚本语言,结合 WXML,可以构建出页面的结构。

        注意:

        1. wxs 不依赖于运行时的基础库版本,可以在所有版本的小程序中运行。
        2. wxs 与 javascript 是不同的语言,有自己的语法,并不和 javascript 一致。
        3. wxs 的运行环境和其他 javascript 代码是隔离的,wxs 中不能调用其他 javascript 文件中定义的函数,也不能调用小程序提供的API。
        4. wxs 函数不能作为组件的事件回调。
        5. 由于运行环境的差异,在 iOS 设备上小程序内的 wxs 会比 javascript 代码快 2 ~ 20 倍。在 android 设备上二者运行效率无差异。

        以下是一些使用 WXS 的简单示例:

        页面渲染

        <!--wxml--><wxs module="m1">var msg = "hello world";module.exports.message = msg;</wxs><view> {{m1.message}} </view>

        页面输出:

        hello world

        数据处理

        // page.jsPage({  data: {    array: [1, 2, 3, 4, 5, 1, 2, 3, 4]  }})
        <!--wxml--><!-- 下面的 getMax 函数,接受一个数组,且返回数组中最大的元素的值 --><wxs module="m1">var getMax = function(array) {  var max = undefined;  for (var i = 0; i < array.length; ++i) {    max = max === undefined ?       array[i] :       (max >= array[i] ? max : array[i]);  }  return max;}module.exports.getMax = getMax;</wxs><!-- 调用 wxs 里面的 getMax 函数,参数为 page.js 里面的 array --><view> {{m1.getMax(array)}} </view>

        页面输出:

        5

        WXS 模块

        WXS 代码可以编写在 wxml 文件中的<wxs> 标签内,或以 .wxs 为后缀名的文件内。

        模块

        每一个 .wxs 文件和 <wxs> 标签都是一个单独的模块。

        每个模块都有自己独立的作用域。即在一个模块里面定义的变量与函数,默认为私有的,对其他模块不可见。

        一个模块要想对外暴露其内部的私有变量与函数,只能通过 module.exports 实现。

        .wxs 文件

        在微信开发者工具里面,右键可以直接创建 .wxs 文件,在其中直接编写 WXS 脚本。

        示例代码:

        // /pages/comm.wxs

        var foo = "'hello world' from comm.wxs";var bar = function(d) { return d;}module.exports = { foo: foo, bar: bar};

        上述例子在 /pages/comm.wxs 的文件里面编写了 WXS 代码。该 .wxs 文件可以被其他的 .wxs 文件 或 WXML 中的 <wxs> 标签引用。

        module 对象

        每个 wxs 模块均有一个内置的 module 对象。

        属性

        • exports: 通过该属性,可以对外共享本模块的私有变量与函数。

        示例代码:

        // /pages/tools.wxs

        var foo = "'hello world' from tools.wxs";var bar = function (d) { return d;}module.exports = { FOO: foo, bar: bar,};module.exports.msg = "some msg";

        {{tools.msg}}

        {{tools.bar(tools.FOO)}}

        页面输出:

        some msg'hello world' from tools.wxs

        require 函数

        在.wxs模块中引用其他 wxs 文件模块,可以使用 require 函数。

        引用的时候,要注意如下几点:

        • 只能引用 .wxs 文件模块,且必须使用相对路径。
        • wxs 模块均为单例,wxs 模块在第一次被引用时,会自动初始化为单例对象。多个页面,多个地方,多次引用,使用的都是同一个 wxs 模块对象。
        • 如果一个 wxs 模块在定义之后,一直没有被引用,则该模块不会被解析与运行。

        示例代码:

        // /pages/tools.wxs

        var foo = "'hello world' from tools.wxs";var bar = function (d) { return d;}module.exports = { FOO: foo, bar: bar,};module.exports.msg = "some msg";

        // /pages/logic.wxs

        var tools = require("./tools.wxs");

        console.log(tools.FOO);console.log(tools.bar("logic.wxs"));console.log(tools.msg);

        控制台输出:

        'hello world' from tools.wxslogic.wxssome msg

        标签

        属性名类型默认值说明
        moduleString 当前<wxs>标签的模块名。必填字段。
        srcString 引用 .wxs 文件的相对路径。仅当本标签为单闭合标签标签的内容为空时有效。

        module 属性

        module 属性是当前<wxs>标签的模块名。在单个 wxml 文件内,建议其值唯一。有重复模块名则按照先后顺序覆盖(后者覆盖前者)。不同文件之间的 wxs 模块名不会相互覆盖。

        module 属性值的命名必须符合下面两个规则:

        • 首字符必须是:字母(a-zA-Z),下划线(_
        • 剩余字符可以是:字母(a-zA-Z),下划线(_), 数字(0-9)

        示例代码:

        <!--wxml--> 

        <wxs module="foo">

        var some_msg = "hello world";module.exports = { msg : some_msg,}

        </wxs>

        <view> {{foo.msg}} </view>

        页面输出:

        hello world

        上面例子声明了一个名字为 foo 的模块,将 some_msg 变量暴露出来,供当前页面使用。

        src 属性

        src 属性可以用来引用其他的 wxs 文件模块。

        引用的时候,要注意如下几点:

        • 只能引用 .wxs 文件模块,且必须使用相对路径。
        • wxs 模块均为单例,wxs 模块在第一次被引用时,会自动初始化为单例对象。多个页面,多个地方,多次引用,使用的都是同一个 wxs 模块对象。
        • 如果一个 wxs 模块在定义之后,一直没有被引用,则该模块不会被解析与运行。

        示例代码:

        // /pages/index/index.js

        Page({ data: { msg: "'hello world' from js", }})

        <!-- 也可以直接使用单标签闭合的写法

        -->

        {{some_comms.bar(some_comms.foo)}}

        {{some_comms.bar(msg)}}

        页面输出:

        'hello world' from comm.wxs'hello wrold' from js

        上述例子在文件 /page/index/index.wxml 中通过 标签引用了 /page/comm.wxs 模块。

        注意

        • <wxs>模块只能在定义模块的 WXML 文件中被访问到。使用<include> 或<import> 时, <wxs>模块不会被引入到对应的 WXML 文件中。
        • 标签中,只能使用定义该 的 WXML 文件中定义的 模块。


        概念

        • WXS 中的变量均为值的引用。
        • 没有声明的变量直接赋值使用,会被定义为全局变量。
        • 如果只声明变量而不赋值,则默认值为 undefined。
        • var表现与javascript一致,会有变量提升。
        var foo = 1;var bar = "hello world";var i; // i === undefined

        上面代码,分别声明了 foo、 bar、 i 三个变量。然后,foo 赋值为数值 1 ,bar 赋值为字符串 "hello wolrd"。

        变量名

        变量命名必须符合下面两个规则:

        • 首字符必须是:字母(a-zA-Z),下划线(_)
        • 剩余字符可以是:字母(a-zA-Z),下划线(_), 数字(0-9)

        保留标识符

        以下标识符不能作为变量名:

        delete void typeofnull undefined NaN Infinity varif else true falserequirethis function argumentsreturnforwhiledobreakcontinueswitchcasedefault

        WXS 主要有 3 种注释的方法。

        示例代码:

        <!-- wxml -->
        <wxs module="sample">
        // 方法一:单行注释
        /*
        方法二:多行注释
        */
        /*
        方法三:结尾注释。即从 /* 开始往后的所有 WXS 代码均被注释
        var a = 1;
        var b = 2;
        var c = "fake";
        </wxs>

        上述例子中,所有 WXS 代码均被注释掉了。

        方法三 和 方法二 的唯一区别是,没有 */ 结束符。


        示例:

        1.在文件中选中一行代码

        无标题

        2.然后再代码前面使用//,表示注释。

        5a5a00def4dca0396459dc5f58d96975f3c40d99

        3.另外我们还可以在代码的头部和尾部分别加上/*和*/,也是表示注释!a1780d1fceecd3d91333e0776799594305010899

        4.将模拟器打开。

        f385f2995943040137b80cf1d66b04d148290599

        5.在下面我们就发现内容是空白的,是因为我们的代码被注释掉了,就不起作用了

        edd84743040148fe9e044fd88fd149299b880299












        基本运算符

        示例代码:

        var a = 10, b = 20;// 加法运算console.log(30 === a + b);// 减法运算console.log(-10 === a - b);// 乘法运算console.log(200 === a * b);// 除法运算console.log(0.5 === a / b);// 取余运算console.log(10 === a % b);
        • 加法运算(+)也可以用作字符串的拼接。
        var a = '.w' , b = 'xs';// 字符串拼接console.log('.wxs' === a + b);

        一元运算符

        示例代码:

        var a = 10, b = 20;// 自增运算console.log(10 === a++);console.log(12 === ++a);// 自减运算console.log(12 === a--);console.log(10 === --a);// 正值运算console.log(10 === +a);// 负值运算console.log(0-10 === -a);// 否运算console.log(-11 === ~a);// 取反运算console.log(false === !a);// delete 运算console.log(true === delete a.fake);// void 运算console.log(undefined === void a);// typeof 运算console.log("number" === typeof a);

        位运算符

        示例代码:

        var a = 10, b = 20;// 左移运算console.log(80 === (a << 3));// 无符号右移运算console.log(2 === (a >> 2));// 带符号右移运算console.log(2 === (a >>> 2));// 与运算console.log(2 === (a & 3));// 异或运算console.log(9 === (a ^ 3));// 或运算console.log(11 === (a | 3));

        比较运算符

        示例代码:

        var a = 10, b = 20;// 小于console.log(true === (a < b));// 大于console.log(false === (a > b));// 小于等于console.log(true === (a <= b));// 大于等于console.log(false === (a >= b));

        等值运算符

        示例代码:

        var a = 10, b = 20;// 等号console.log(false === (a == b));// 非等号console.log(true === (a != b));// 全等号console.log(false === (a === b));// 非全等号console.log(true === (a !== b));

        赋值运算符

        示例代码:

        var a = 10;a = 10; a *= 10;console.log(100 === a);a = 10; a /= 5;console.log(2 === a);a = 10; a %= 7;console.log(3 === a);a = 10; a += 5;console.log(15 === a);a = 10; a -= 11;console.log(-1 === a);a = 10; a <<= 10;console.log(10240 === a);a = 10; a >>= 2;console.log(2 === a);a = 10; a >>>= 2;console.log(2 === a);a = 10; a &= 3;console.log(2 === a);a = 10; a ^= 3;console.log(9 === a);a = 10; a |= 3;console.log(11 === a);

        二元逻辑运算符

        示例代码:

        var a = 10, b = 20;// 逻辑与console.log(20 === (a && b));// 逻辑或console.log(10 === (a || b));

        其他运算符

        示例代码:

        var a = 10, b = 20;//条件运算符console.log(20 === (a >= 10 ? a + 10 : b + 10));//逗号运算符console.log(20 === (a, b));

        运算符优先级

        优先级运算符说明结合性
        20( ... )括号n/a
        19... . ...成员访问从左到右
        ... [ ... ]成员访问从左到右
        ... ( ... )函数调用从左到右
        17... ++后置递增n/a
        ... --后置递减n/a
        16! ...逻辑非从右到左
        ~ ...按位非从右到左
        + ...一元加法从右到左
        - ...一元减法从右到左
        ++ ...前置递增从右到左
        -- ...前置递减从右到左
        typeof ...typeof从右到左
        void ...void从右到左
        delete ...delete从右到左
        14... * ...乘法从左到右
        ... / ...除法从左到右
        ... % ...取模从左到右
        13... + ...加法从左到右
        ... - ...减法从左到右
        12... << ...按位左移从左到右
        ... >> ...按位右移从左到右
        ... >>> ...无符号右移从左到右
        11... < ...小于从左到右
        ... <= ...小于等于从左到右
        ... > ...大于从左到右
        ... >= ...大于等于从左到右
        10... == ...等号从左到右
        ... != ...非等号从左到右
        ... === ...全等号从左到右
        ... !== ...非全等号从左到右
        9... & ...按位与从左到右
        8... ^ ...按位异或从左到右
        7...  ...按位或从左到右
        6... && ...逻辑与从左到右
        5... || ...逻辑或从左到右
        4... ? ... : ...条件运算符从右到左
        3... = ...赋值从右到左
        ... += ...赋值从右到左
        ... -= ...赋值从右到左
        ... *= ...赋值从右到左
        ... /= ...赋值从右到左
        ... %= ...赋值从右到左
        ... <<= ...赋值从右到左
        ... >>= ...赋值从右到左
        ... >>>= ...赋值从右到左
        ... &= ...赋值从右到左
        ... ^= ...赋值从右到左
        ... |= ...赋值从右到左
        0... , ...逗号从左到右

        if 语句

        在 WXS 中,可以使用以下格式的 if 语句 :

        • if (expression) statement : 当 expression 为 truthy 时,执行 statement。
        • if (expression) statement1 else statement2 : 当 expression 为 truthy 时,执行 statement1。 否则,执行 statement2
        • if ... else if ... else statementN 通过该句型,可以在 statement1 ~ statementN 之间选其中一个执行。

        示例语法:

        // if ...if (表达式) 语句;if (表达式)   语句;if (表达式) {  代码块;}// if ... else if (表达式) 语句;else 语句;if (表达式)   语句;else   语句;if (表达式) {  代码块;} else {  代码块;}// if ... else if ... else ...if (表达式) {  代码块;} else if (表达式) {  代码块;} else if (表达式) {  代码块;} else {  代码块;}

        switch 语句

        示例语法:

        switch (表达式) {  case 变量:    语句;  case 数字:    语句;    break;  case 字符串:    语句;  default:    语句;}
        • default 分支可以省略不写。
        • case 关键词后面只能使用:变量,数字,字符串。

        示例代码:

        var exp = 10;switch ( exp ) {case "10":  console.log("string 10");  break;case 10:  console.log("number 10");  break;case exp:  console.log("var exp");  break;default:  console.log("default");}

        输出:

        number 10

        for 语句

        示例语法:

        for (语句; 语句; 语句)  语句;for (语句; 语句; 语句) {  代码块;}
        • 支持使用 break,continue 关键词。

        示例代码:

        for (var i = 0; i < 3; ++i) {  console.log(i);  if( i >= 1) break;}

        输出:

        01

        while 语句

        示例语法:

        while (表达式)  语句;while (表达式){  代码块;}do {  代码块;} while (表达式)
        • 当表达式为 true 时,循环执行语句或代码块。
        • 支持使用 break,continue 关键词。

        数据类型

        WXS 语言目前共有以下几种数据类型:

        • number : 数值
        • string :字符串
        • boolean:布尔值
        • object:对象
        • function:函数
        • array : 数组
        • date:日期
        • regexp:正则

        number

        语法

        number 包括两种数值:整数,小数。

        var a = 10;var PI = 3.141592653589793;

        属性

        • constructor:返回字符串 "Number"。

        方法

        • toString
        • toLocaleString
        • valueOf
        • toFixed
        • toExponential
        • toPrecision
        以上方法的具体使用请参考 ES5 标准。

        string

        语法

        string 有两种写法:

        'hello world';"hello world";

        属性

        • constructor:返回字符串 "String"。
        • length
        除constructor外属性的具体含义请参考 ES5 标准。

        方法

        • toString
        • valueOf
        • charAt
        • charCodeAt
        • concat
        • indexOf
        • lastIndexOf
        • localeCompare
        • match
        • replace
        • search
        • slice
        • split
        • substring
        • toLowerCase
        • toLocaleLowerCase
        • toUpperCase
        • toLocaleUpperCase
        • trim
        以上方法的具体使用请参考 ES5 标准。

        boolean

        语法

        布尔值只有两个特定的值:true 和 false。

        属性

        • constructor:返回字符串 "Boolean"。

        方法

        • toString
        • valueOf
        以上方法的具体使用请参考 ES5 标准。

        object

        语法

        object 是一种无序的键值对。使用方法如下所示:

        var o = {} //生成一个新的空对象//生成一个新的非空对象o = {  'string'  : 1,  //object 的 key 可以是字符串  const_var : 2,  //object 的 key 也可以是符合变量定义规则的标识符  func      : {}, //object 的 value 可以是任何类型};//对象属性的读操作console.log(1 === o['string']);console.log(2 === o.const_var);//对象属性的写操作o['string']++;o['string'] += 10;o.const_var++;o.const_var += 10;//对象属性的读操作console.log(12 === o['string']);console.log(13 === o.const_var);

        属性

        • constructor:返回字符串 "Object"。
        console.log("Object" === {k:"1",v:"2"}.constructor)

        方法

        • toString:返回字符串 "[object Object]"。

        function

        语法

        function 支持以下的定义方式:

        //方法 1function a (x) {  return x;}//方法 2var b = function (x) {   return x;}

        function 同时也支持以下的语法(匿名函数,闭包等):

        var a = function (x) {  return function () { return x;}}var b = a(100);console.log( 100 === b() );

        arguments

        function 里面可以使用 arguments 关键词。该关键词目前只支持以下的属性:

        • length: 传递给函数的参数个数。
        • [index]: 通过 index 下标可以遍历传递给函数的每个参数。

        示例代码:

        var a = function(){    console.log(3 === arguments.length);    console.log(100 === arguments[0]);    console.log(200 === arguments[1]);    console.log(300 === arguments[2]);};a(100,200,300);

        属性

        • constructor:返回字符串 "Function"。
        • length:返回函数的形参个数。

        方法

        • toString:返回字符串 "[function Function]"。

        示例代码:

        var func = function (a,b,c) { }console.log("Function" === func.constructor);console.log(3 === func.length);console.log("[function Function]" === func.toString());

        array

        语法

        array 支持以下的定义方式:

        var a = [];      //生成一个新的空数组a = [1,"2",{},function(){}];  //生成一个新的非空数组,数组元素可以是任何类型

        属性

        • constructor:返回字符串 "Array"。
        • length
        除constructor外属性的具体含义请参考 ES5 标准。

        方法

        • toString
        • concat
        • join
        • pop
        • push
        • reverse
        • shift
        • slice
        • sort
        • splice
        • unshift
        • indexOf
        • lastIndexOf
        • every
        • some
        • forEach
        • map
        • filter
        • reduce
        • reduceRight
        以上方法的具体使用请参考 ES5 标准。

        date

        语法

        生成 date 对象需要使用 getDate函数, 返回一个当前时间的对象。

        getDate()getDate(milliseconds)getDate(datestring)getDate(year, month[, date[, hours[, minutes[, seconds[, milliseconds]]]]])
        • 参数milliseconds: 从1970年1月1日00:00:00 UTC开始计算的毫秒数datestring: 日期字符串,其格式为:"month day, year hours:minutes:seconds"

        示例代码:

        var date = getDate(); //返回当前时间对象date = getDate(1500000000000);// Fri Jul 14 2017 10:40:00 GMT+0800 (中国标准时间)date = getDate('2017-7-14');// Fri Jul 14 2017 00:00:00 GMT+0800 (中国标准时间)date = getDate(2017, 6, 14, 10, 40, 0, 0);// Fri Jul 14 2017 10:40:00 GMT+0800 (中国标准时间)

        属性

        • constructor:返回字符串 “Date”。

        方法

        • parse
        • UTC
        • now
        • toString
        • toDateString
        • toTimeString
        • toLocaleString
        • toLocaleDateString
        • toLocaleTimeString
        • valueOf
        • getTime
        • getFullYear
        • getUTCFullYear
        • getMonth
        • getUTCMonth
        • getDate
        • getUTCDate
        • getDay
        • getUTCDay
        • getHours
        • getUTCHours
        • getMinutes
        • getUTCMinutes
        • getSeconds
        • getUTCSeconds
        • getMilliseconds
        • getUTCMilliseconds
        • getTimezoneOffset
        • setTime
        • setMilliseconds
        • setUTCMilliseconds
        • setSeconds
        • setUTCSeconds
        • setMinutes
        • setUTCMinutes
        • setHours
        • setUTCHours
        • setDate
        • setUTCDate
        • setMonth
        • setUTCMonth
        • setFullYear
        • setUTCFullYear
        • toUTCString
        • toISOString
        • toJSON
        以上方法的具体使用请参考 ES5 标准。

        regexp

        语法

        生成 regexp 对象需要使用 getRegExp函数。

        getRegExp(pattern[, flags])
        • 参数:pattern: 正则表达式的内容。flags:修饰符。该字段只能包含以下字符:g: globali: ignoreCasem: multiline。

        示例代码:

        var a = getRegExp("x", "img");console.log("x" === a.source);console.log(true === a.global);console.log(true === a.ignoreCase);console.log(true === a.multiline);

        属性

        • constructor:返回字符串 "RegExp"。
        • source
        • global
        • ignoreCase
        • multiline
        • lastIndex
        除constructor外属性的具体含义请参考 ES5 标准。

        方法

        • exec
        • test
        • toString
        以上方法的具体使用请参考 ES5 标准。

        数据类型判断

        constructor 属性

        数据类型的判断可以使用 constructor 属性。

        示例代码:

        var number = 10;console.log( "Number" === number.constructor );var string = "str";console.log( "String" === string.constructor );var boolean = true;console.log( "Boolean" === boolean.constructor );var object = {};console.log( "Object" === object.constructor );var func = function(){};console.log( "Function" === func.constructor );var array = [];console.log( "Array" === array.constructor );var date = getDate();console.log( "Date" === date.constructor );var regexp = getRegExp();console.log( "RegExp" === regexp.constructor );

        typeof

        使用 typeof 也可以区分部分数据类型。

        示例代码:

        var number = 10;var boolean = true;var object = {};var func = function(){};var array = [];var date = getDate();var regexp = getRegExp();console.log( 'number' === typeof number );console.log( 'boolean' === typeof boolean );console.log( 'object' === typeof object );console.log( 'function' === typeof func );console.log( 'object' === typeof array );console.log( 'object' === typeof date );console.log( 'object' === typeof regexp );console.log( 'undefined' === typeof undefined );console.log( 'object' === typeof null );


        console

        console.log 方法用于在 console 窗口输出信息。它可以接受多个参数,将它们的结果连接起来输出。

        Math

        属性

        • E
        • LN10
        • LN2
        • LOG2E
        • LOG10E
        • PI
        • SQRT1_2
        • SQRT2
        以上属性的具体使用请参考 ES5 标准。

        方法

        • abs
        • acos
        • asin
        • atan
        • atan2
        • ceil
        • cos
        • exp
        • floor
        • log
        • max
        • min
        • pow
        • random
        • round
        • sin
        • sqrt
        • tan
        以上方法的具体使用请参考 ES5 标准。

        JSON

        方法

        • stringify(object): 将 object 对象转换为 JSON 字符串,并返回该字符串。
        • parse(string): 将 JSON 字符串转化成对象,并返回该对象。

        示例代码:

        console.log(undefined === JSON.stringify());console.log(undefined === JSON.stringify(undefined));console.log("null"===JSON.stringify(null));console.log("111"===JSON.stringify(111));console.log('"111"'===JSON.stringify("111"));console.log("true"===JSON.stringify(true));console.log(undefined===JSON.stringify(function(){}));console.log(undefined===JSON.parse(JSON.stringify()));console.log(undefined===JSON.parse(JSON.stringify(undefined)));console.log(null===JSON.parse(JSON.stringify(null)));console.log(111===JSON.parse(JSON.stringify(111)));console.log("111"===JSON.parse(JSON.stringify("111")));console.log(true===JSON.parse(JSON.stringify(true)));console.log(undefined===JSON.parse(JSON.stringify(function(){})));

        Number

        属性

        • MAX_VALUE
        • MIN_VALUE
        • NEGATIVE_INFINITY
        • POSITIVE_INFINITY
        以上属性的具体使用请参考 ES5 标准。

        Date

        属性

        • parse
        • UTC
        • now
        以上属性的具体使用请参考 ES5 标准。

        Global

        属性

        • NaN
        • Infinity
        • undefined
        以上属性的具体使用请参考 ES5 标准。

        方法

        • parseInt
        • parseFloat
        • isNaN
        • isFinite
        • decodeURI
        • decodeURIComponent
        • encodeURI
        • encodeURIComponent
        以上方法的具体使用请参考 ES5 标准。


        WXSS

        WXSS(WeiXin Style Sheets)是一套样式语言,用于描述WXML的组件样式。

        WXSS用来决定WXML的组件应该怎么显示。

        为了适应广大的前端开发者,我们的WXSS具有CSS大部分特性。同时为了更适合开发微信小程序,我们对CSS进行了扩充以及修改。

        与css相比我们扩展的特性有:

        尺寸单位

        • 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"的组件
        element view 选择所有view组件
        element, element view checkbox 选择所有文档的view组件和所有的checkbox组件
        ::after view::after 在view组件后边插入内容
        ::before view::before 在view组件前边插入内容

        全局样式与局部样式

        定义在app.wxss中的样式为全局样式,作用于每一个页面。在page的wxss文件中定义的样式为局部样式,只作用在对应的页面,并会覆盖app.wxss中相同的选择器。


        基础组件


        框架为开发者提供了一系列基础组件,开发者可以通过组合这些基础组件进行快速开发。

        详细介绍请参考组件文档

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

        双向绑定语法

        在 WXML 中,普通的属性的绑定是单向的。例如:

        <input value="{{value}}" />

        如果使用 ​this.setData({ value: 'leaf' })​ 来更新 ​value​ ,​this.data.value​ 和输入框的中显示的值都会被更新为 leaf ;但如果用户修改了输入框里的值,却不会同时改变 ​this.data.value​ 。

        如果需要在用户输入的同时改变 ​this.data.value​ ,需要借助简易双向绑定机制。此时,可以在对应项目之前加入 ​model​: 前缀:

        <input model:value="{{value}}" />

        这样,如果输入框的值被改变了, ​this.data.value​ 也会同时改变。同时, WXML 中所有绑定了 ​value​ 的位置也会被一同更新, 数据监听器 也会被正常触发。

        用于双向绑定的表达式有如下限制:

        1. 只能是一个单一字段的绑定,如
        2. <input model:value="值为 {{value}}" /><input model:value="{{ a + b }}" />

          都是非法的;

        3. 目前,尚不能 data 路径,如

          <input model:value="{{ a.b }}" />

          这样的表达式目前暂不支持。

        在自定义组件中传递双向绑定

        双向绑定同样可以使用在自定义组件上。如下的自定义组件:

        // custom-component.jsComponent({  properties: {    myValue: String  }})
        <!-- custom-component.wxml --><input model:value="{{myValue}}" />

        这个自定义组件将自身的 ​myValue​ 属性双向绑定到了组件内输入框的 ​value​ 属性上。这样,如果页面这样使用这个组件:

        <custom-component model:my-value="{{pageValue}}" />

        当输入框的值变更时,自定义组件的 ​myValue​ 属性会同时变更,这样,页面的 ​this.data.pageValue​ 也会同时变更,页面 WXML 中所有绑定了 ​pageValue​ 的位置也会被一同更新。

        在自定义组件中触发双向绑定更新

        自定义组件还可以自己触发双向绑定更新,做法就是:使用 setData 设置自身的属性。例如:

        // custom-component.jsComponent({  properties: {    myValue: String  },  methods: {    update: function() {      // 更新 myValue      this.setData({        myValue: 'leaf'      })    }  }})

        如果页面这样使用这个组件:

        <custom-component model:my-value="{{pageValue}}" />

        当组件使用 ​setData​ 更新 ​myValue​ 时,页面的 ​this.data.pageValue​ 也会同时变更,页面 WXML 中所有绑定了 ​pageValue​ 的位置也会被一同更新。


        目前,我们提供了两种性能分析工具,和几个性能优化上的建议,开发者可以参考使用。

        1. 分析工具

        2. 优化建议

        微信 Andoid 6.5.10 开始,我们提供了 Trace 导出工具,开发者可以在开发者工具 Trace Panel 中使用该功能。

        使用方法

        1. PC 上需要先安装adb工具,可以参考一些主流教程进行安装,Mac 上可使用 brew 直接安装。
        2. 确定adb工具已成功安装后,在开发者工具上打开 Trace Panel,将 Android 手机通过 USB 连接上 PC,点击「Choose Devices」,此时手机上可能弹出连接授权框,请点击「允许」。
        3. 选择设备后,在手机上打开你需要调试的开发版小程序,通过右上角菜单,打开性能监控面板,重启小程序;
        4. 重启后,在小程序上进行操作,完成操作后,通过右上角菜单,导出 Trace 数据;
        5. 此时开发者工具 Trace Panel 上会自动拉取 Trace 文件,选择你要分析的 Trace 文件即可;

        可以通过adb devices命令确定设备是否已和 PC 建立起连接

        image

        性能面板

        从微信 6.5.8 开始,我们提供了性能面板让开发者了解小程序的性能。开发者可以在开发版小程序下打开性能面板,打开方法:进入开发版小程序,进入右上角更多按钮,点击「显示性能窗口」。

        image

        性能面板指标说明

        指标说明
        CPU小程序进程的 CPU 占用率,仅 Android 下提供
        内存小程序进程的内存占用(Total Pss),仅 Android 下提供
        启动耗时小程序启动总耗时
        下载耗时小程序包下载耗时,首次打开或资源包需更新时会进行下载
        页面切换耗时小程序页面切换的耗时
        帧率/FPS 
        首次渲染耗时页面次首次渲染的耗时
        再次渲染耗时页面再次渲染的耗时(通常由开发者的 setData 操作触发)
        数据缓存小程序通过 Storage 接口储存的缓存大小

        setData

        setData是小程序开发中使用最频繁的接口,也是最容易引发性能问题的接口。在介绍常见的错误用法前,先简单介绍一下setData背后的工作原理。

        工作原理

        小程序的视图层目前使用 WebView 作为渲染载体,而逻辑层是由独立的 JavascriptCore 作为运行环境。在架构上,WebView 和 JavascriptCore 都是独立的模块,并不具备数据直接共享的通道。当前,视图层和逻辑层的数据传输,实际上通过两边提供的evaluateJavascript所实现。即用户传输的数据,需要将其转换为字符串形式传递,同时把转换后的数据内容拼接成一份 JS 脚本,再通过执行 JS 脚本的形式传递到两边独立环境。

        evaluateJavascript的执行会受很多方面的影响,数据到达视图层并不是实时的。同一进程内的 WebView 实际上会共享一个 JS VM,如果 WebView 内 JS 线程正在执行渲染或其他逻辑,会影响 evaluateJavascript 脚本的实际执行时间,另外多个 WebView 也会抢占 JS VM 的执行权限;另外还有 JS 本身的编译执行耗时,都是影响数据传输速度的因素。

        常见的 setData 操作错误

        1. 频繁的去 setData

        在我们分析过的一些案例里,部分小程序会非常频繁(毫秒级)的去setData,其导致了两个后果:

        • Android 下用户在滑动时会感觉到卡顿,操作反馈延迟严重,因为 JS 线程一直在编译执行渲染,未能及时将用户操作事件传递到逻辑层,逻辑层亦无法及时将操作处理结果及时传递到视图层;
        • 渲染有出现延时,由于 WebView 的 JS 线程一直处于忙碌状态,逻辑层到页面层的通信耗时上升,视图层收到的数据消息时距离发出时间已经过去了几百毫秒,渲染的结果并不实时;

        2. 每次 setData 都传递大量新数据

        setData的底层实现可知,我们的数据传输实际是一次evaluateJavascript脚本过程,当数据量过大时会增加脚本的编译执行时间,占用 WebView JS 线程。

        3. 后台态页面进行 setData

        当页面进入后台态(用户不可见),不应该继续去进行setData,后台态页面的渲染用户是无法感受的,另外后台态页面去setData也会抢占前台页面的执行。

        图片资源

        目前图片资源的主要性能问题在于大图片和长列表图片上,这两种情况都有可能导致 iOS 客户端内存占用上升,从而触发系统回收小程序页面。

        图片对内存的影响

        在 iOS 上,小程序的页面是由多个 WKWebView 组成的,在系统内存紧张时,会回收掉一部分 WKWebView。从过去我们分析的案例来看,大图片和长列表图片的使用会引起 WKWebView 的回收。

        图片对页面切换的影响

        除了内存问题外,大图片也会造成页面切换的卡顿。我们分析过的案例中,有一部分小程序会在页面中引用大图片,在页面后退切换中会出现掉帧卡顿的情况。

        当前我们建议开发者尽量减少使用大图片资源。

        代码包大小的优化

        小程序一开始时代码包限制为 1MB,但我们收到了很多反馈说代码包大小不够用,经过评估后我们放开了这个限制,增加到 2MB 。代码包上限的增加对于开发者来说,能够实现更丰富的功能,但对于用户来说,也增加了下载流量和本地空间的占用。

        开发者在实现业务逻辑同时也有必要尽量减少代码包的大小,因为代码包大小直接影响到下载速度,从而影响用户的首次打开体验。除了代码自身的重构优化外,还可以从这两方面着手优化代码大小:

        控制代码包内图片资源

        小程序代码包经过编译后,会放在微信的 CDN 上供用户下载,CDN 开启了 GZIP 压缩,所以用户下载的是压缩后的 GZIP 包,其大小比代码包原体积会更小。 但我们分析数据发现,不同小程序之间的代码包压缩比差异也挺大的,部分可以达到 30%,而部分只有 80%,而造成这部分差异的一个原因,就是图片资源的使用。GZIP 对基于文本资源的压缩效果最好,在压缩较大文件时往往可高达 70%-80% 的压缩率,而如果对已经压缩的资源(例如大多数的图片格式)则效果甚微。

        及时清理没有使用到的代码和资源

        在日常开发的时候,我们可能引入了一些新的库文件,而过了一段时间后,由于各种原因又不再使用这个库了,我们常常会只是去掉了代码里的引用,而忘记删掉这类库文件了。目前小程序打包是会将工程下所有文件都打入代码包内,也就是说,这些没有被实际使用到的库文件和资源也会被打入到代码包里,从而影响到整体代码包的大小。

        基础库与客户端之间的关系

        小程序的能力需要微信客户端来支撑,每一个基础库都只能在对应的客户端版本上运行,高版本的基础库无法兼容低版本的微信客户端。

        关于基础库的兼容方法,可以查看「兼容处理」章节。

        基础库更新时机

        为了避免新版本的基础库给线上小程序带来未知的影响,微信客户端都是携带 上一个稳定版 的基础库发布的。

        在新版本客户端发布后,我们再通过后台灰度新版本基础库,灰度时长一般为 12 小时,在灰度结束后,用户设备上才会有新版本的基础库。

        以微信 6.5.8 为例,客户端在发布时携带的是 1.1.1 基础库(6.5.7 上已全量的稳定版)发布,在 6.5.8 发布后,我们再通过后台灰度 1.2.0 基础库。

        基础库版本分布

        iOS

        基础库版本用户占比
        1.4.01.88%
        1.3.080.74%
        1.2.60.00%
        1.2.57.29%
        1.2.40.00%
        1.2.30.00%
        1.2.20.00%
        1.2.10.00%
        1.2.00.00%
        1.1.16.75%
        1.1.00.00%
        1.0.13.34%
        1.0.00.00%

        (数据截止 2017-07-10)

        Android

        基础库版本用户占比
        1.4.03.20%
        1.3.051.24%
        1.2.60.00%
        1.2.537.03%
        1.2.40.58%
        1.2.30.00%
        1.2.20.02%
        1.2.10.00%
        1.2.00.00%
        1.1.14.33%
        1.1.00.00%
        1.0.12.05%
        1.0.01.55%

        (数据截止 2017-07-10)


        小程序的功能不断的增加,但是旧版本的微信客户端并不支持新功能,所以在使用这些新能力的时候需要做兼容。

        文档会在组件,API等页面描述中带上各个功能所支持的版本号。

        可以通过wx.getSystemInfo或者wx.getSystemInfoSync获取到小程序的基础库版本号。

        也可以通过wx.canIUse 详情 来判断是否可以在该基础库版本下直接使用对应的API或者组件

        兼容方式 - 接口

        对于新增的 API,可以用以下代码来判断是否支持用户的手机。

        if (wx.openBluetoothAdapter) {  wx.openBluetoothAdapter()} else {  // 如果希望用户在最新版本的客户端上体验您的小程序,可以这样子提示  wx.showModal({    title: '提示',    content: '当前微信版本过低,无法使用该功能,请升级到最新微信版本后重试。'  })}

        兼容方式 - 参数

        对于 API 的参数或者返回值有新增的参数,可以判断用以下代码判断。

        wx.showModal({  success: function(res) {    if (wx.canIUse('showModal.cancel')) {      console.log(res.cancel)    }  }})

        兼容方式 - 组件

        对于组件,新增的属性在旧版本上不会被处理,不过也不会报错。如果特殊场景需要对旧版本做一些降级处理,可以这样子做。

        Page({  data: {    canIUse: wx.canIUse('button.open-type.contact')  }})
        <button wx:if="{{canIUse}}" open-type="contact"> 客服消息 </button><contact-button wx:else></contact-button>

        运行机制

        • 小程序没有重启的概念
        • 当小程序进入后台,客户端会维持一段时间的运行状态,超过一定时间后(目前是5分钟)会被微信主动销毁
        • 置顶的小程序不会被微信主动销毁
        • 当收到系统内存告警也会进行小程序的销毁

        再次打开逻辑

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

        用户打开小程序的预期有以下两类场景:

        A. 打开首页: 场景值有 1001, 1019, 1022, 1023, 1038, 1056

        B. 打开小程序指定的某个页面: 场景值为除 A 以外的其他

        当再次打开一个小程序逻辑如下:

        上一次的场景当前打开的场景效果
        AA保留原来的状态
        BA清空原来的页面栈,打开首页(相当于执行 wx.reLaunch 到首页)
        A 或 BB清空原来的页面栈,打开指定页面(相当于执行 wx.reLaunch 到指定页)

        基础组件


        框架为开发者提供了一系列基础组件,开发者可以通过组合这些基础组件进行快速开发。

        什么是组件:

        • 组件是视图层的基本组成单元。
        • 组件自带一些功能与微信风格的样式。
        • 一个组件通常包括开始标签结束标签属性用来修饰这个组件,内容在两个标签之内。

          <tagname property="value">  Content goes here ...</tagename>

          注意:所有组件与属性都是小写,以连字符-连接

        属性类型


        类型 描述 注解
        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 组件的事件 详见事件

        特殊属性


        几乎所有组件都有各自定义的属性,可以对该组件的功能或样式进行修饰,请参考各个组件的定义。

        组件列表


        基础组件分为以下八大类:

        视图容器(View Container):

        组件名 说明
        view 视图容器
        scroll-view 可滚动视图容器
        swiper 可滑动的视图容器

        基础内容(Basic Content):

        组件名 说明
        icon 图标
        text 文字
        progress 进度条

        表单(Form):

        标签名 说明
        button 按钮
        form 表单
        input 输入框
        checkbox 多项选择器
        radio 单项选择器
        picker 列表选择器
        picker-view 内嵌列表选择器
        slider 滑动选择器
        switch 开关选择器
        label 标签

        导航(Navigation):

        组件名 说明
        navigator 应用内跳转

        多媒体(Media):

        组件名 说明
        audio 音频
        image 图片
        video 视频

        地图(Map):

        组件名 说明
        map 地图

        画布(Canvas):

        组件名 说明
        canvas 画布

        客服会话:

        组件名说明
        contact-button进入客服会话按钮

        view


        视图容器。

        属性类型默认值必填说明最低版本
        hover-classstringnone指定按下去的样式类。当 hover-class="none" 时,没有点击态效果1.0.0
        hover-stop-propagationbooleanfalse指定是否阻止本节点的祖先节点出现点击态1.5.0
        hover-start-timenumber50按住后多久出现点击态,单位毫秒1.0.0
        hover-stay-timenumber400手指松开后点击态保留时间,单位毫秒1.0.0

        示例:

        <view class="section">  <view class="section__title">flex-direction: row</view>  <view class="flex-wrp" style="flex-direction:row;">    <view class="flex-item bc_green">1</view>    <view class="flex-item bc_red">2</view>    <view class="flex-item bc_blue">3</view>  </view></view><view class="section">  <view class="section__title">flex-direction: column</view>  <view class="flex-wrp" style="height: 300px;flex-direction:column;">    <view class="flex-item bc_green">1</view>    <view class="flex-item bc_red">2</view>    <view class="flex-item bc_blue">3</view>  </view></view>

        view

        Bug & Tip

        1. tip: 如果需要使用滚动视图,请使用 scroll-view


        scroll-view


        可滚动视图区域。

        属性名类型默认值说明
        scroll-xBooleanfalse允许横向滚动
        scroll-yBooleanfalse允许纵向滚动
        upper-thresholdNumber50距顶部/左边多远时(单位px),触发 scrolltoupper 事件
        lower-thresholdNumber50距底部/右边多远时(单位px),触发 scrolltolower 事件
        scroll-topNumber 设置竖向滚动条位置
        scroll-leftNumber 设置横向滚动条位置
        scroll-into-viewString 值应为某子元素id(id不能以数字开头)。设置哪个方向可滚动,则在哪个方向滚动到该元素
        scroll-with-animationBooleanfalse在设置滚动条位置时使用动画过渡
        enable-back-to-topBooleanfalseiOS点击顶部状态栏、安卓双击标题栏时,滚动条返回顶部,只支持竖向
        bindscrolltoupperEventHandle 滚动到顶部/左边,会触发 scrolltoupper 事件
        bindscrolltolowerEventHandle 滚动到底部/右边,会触发 scrolltolower 事件
        bindscrollEventHandle 滚动时触发,event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}

        使用竖向滚动时,需要给<scroll-view/>一个固定高度,通过 WXSS 设置 height。

        示例代码:

        <view class="section">  <view class="section__title">vertical scroll</view>  <scroll-view scroll-y style="height: 200px;" bindscrolltoupper="upper" bindscrolltolower="lower" bindscroll="scroll" scroll-into-view="{{toView}}" scroll-top="{{scrollTop}}">    <view id="green" class="scroll-view-item bc_green"></view>    <view id="red"  class="scroll-view-item bc_red"></view>    <view id="yellow" class="scroll-view-item bc_yellow"></view>    <view id="blue" class="scroll-view-item bc_blue"></view>  </scroll-view>  <view class="btn-area">    <button size="mini" bindtap="tap">click me to scroll into view </button>    <button size="mini" bindtap="tapMove">click me to scroll</button>  </view></view><view class="section section_gap">  <view class="section__title">horizontal scroll</view>  <scroll-view class="scroll-view_H" scroll-x="true" style="width: 100%">    <view id="green" class="scroll-view-item_H bc_green"></view>    <view id="red"  class="scroll-view-item_H bc_red"></view>    <view id="yellow" class="scroll-view-item_H bc_yellow"></view>    <view id="blue" class="scroll-view-item_H bc_blue"></view>  </scroll-view></view>


        var order = ['red', 'yellow', 'blue', 'green', 'red']Page({  data: {    toView: 'red',    scrollTop: 100  },  upper: function(e) {    console.log(e)  },  lower: function(e) {    console.log(e)  },  scroll: function(e) {    console.log(e)  },  tap: function(e) {    for (var i = 0; i < order.length; ++i) {      if (order[i] === this.data.toView) {        this.setData({          toView: order[i + 1]        })        break      }    }  },  tapMove: function(e) {    this.setData({      scrollTop: this.data.scrollTop + 10    })  }})

        scroll-view

        Bug & Tip

        1. tip: 请勿在scroll-view中使用textareamapcanvasvideo组件
        2. tip: scroll-into-view的优先级高于scroll-top
        3. tip: 在滚动scroll-view时会阻止页面回弹,所以在scroll-view中滚动,是无法触发onPullDownRefresh
        4. tip: 若要使用下拉刷新,请使用页面的滚动,而不是scroll-view,这样也能通过点击顶部状态栏回到页面顶部


        swiper


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

        滑块视图容器。

        属性类型默认值必填说明最低版本
        indicator-dotsbooleanfalse是否显示面板指示点1.0.0
        indicator-colorcolorrgba(0, 0, 0, .3)指示点颜色1.1.0
        indicator-active-colorcolor#000000当前选中的指示点颜色1.1.0
        autoplaybooleanfalse是否自动切换1.0.0
        currentnumber0当前所在滑块的 index1.0.0
        intervalnumber5000自动切换时间间隔1.0.0
        durationnumber500滑动动画时长1.0.0
        circularbooleanfalse是否采用衔接滑动1.0.0
        verticalbooleanfalse滑动方向是否为纵向1.0.0
        previous-marginstring"0px"前边距,可用于露出前一项的一小部分,接受 px 和 rpx 值1.9.0
        next-marginstring"0px"后边距,可用于露出后一项的一小部分,接受 px 和 rpx 值1.9.0
        display-multiple-itemsnumber1同时显示的滑块数量1.9.0
        skip-hidden-item-layoutbooleanfalse是否跳过未显示的滑块布局,设为 true 可优化复杂情况下的滑动性能,但会丢失隐藏状态滑块的布局信息1.9.0
        easing-functionstring"default"指定 swiper 切换缓动动画类型2.6.5
        bindchangeeventhandlecurrent 改变时会触发 change 事件,event.detail = {current, source}1.0.0
        bindtransitioneventhandleswiper-item 的位置发生改变时会触发 transition 事件,event.detail = {dx: dx, dy: dy}2.4.3
        bindanimationfinisheventhandle动画结束时会触发 animationfinish 事件,event.detail 同上1.9.0

        easing-function 的合法值

        说明最低版本
        default默认缓动函数
        linear线性动画
        easeInCubic缓入动画
        easeOutCubic缓出动画
        easeInOutCubic缓入缓出动画


        从公共库v1.4.0开始,change事件返回detail中包含一个source字段,表示导致变更的原因,可能值如下:

        • autoplay自动播放导致swiper变化;
        • touch用户划动引起swiper变化;
        • 其他原因将用空字符串表示。

        注意:如果在 bindchange 的事件回调函数中使用 setData 改变 current 值,则有可能导致 setData 被不停地调用,因而通常情况下请在改变 current 值前检测 source 字段来判断是否是由于用户触摸引起。

        swiper-item

        基础库 1.0.0 开始支持,低版本需做兼容处理。

        仅可放置在<swiper/>组件中,宽高自动设置为100%。

        属性类型默认值必填说明最低版本
        item-idstring该 swiper-item 的标识符1.9.0

        示例代码:

        <swiper indicator-dots="{{indicatorDots}}"  autoplay="{{autoplay}}" interval="{{interval}}" duration="{{duration}}">  <block wx:for="{{imgUrls}}">    <swiper-item>      <image src="{{item}}" class="slide-image" width="355" height="150"/>    </swiper-item>  </block></swiper><button bindtap="changeIndicatorDots"> indicator-dots </button><button bindtap="changeAutoplay"> autoplay </button><slider bindchange="intervalChange" show-value min="500" max="2000"/> interval<slider bindchange="durationChange" show-value min="1000" max="10000"/> duration
        Page({  data: {    imgUrls: [      'http://img02.tooopen.com/images/20150928/tooopen_sy_143912755726.jpg',      'http://img06.tooopen.com/images/20160818/tooopen_sy_175866434296.jpg',      'http://img06.tooopen.com/images/20160818/tooopen_sy_175833047715.jpg'    ],    indicatorDots: false,    autoplay: false,    interval: 5000,    duration: 1000  },  changeIndicatorDots: function(e) {    this.setData({      indicatorDots: !this.data.indicatorDots    })  },  changeAutoplay: function(e) {    this.setData({      autoplay: !this.data.autoplay    })  },  intervalChange: function(e) {    this.setData({      interval: e.detail.value    })  },  durationChange: function(e) {    this.setData({      duration: e.detail.value    })  }})


        movable-area

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

        movable-view 的可移动区域

        注意:movable-area 必须设置width和height属性,不设置默认为10px

        movable-view

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

        可移动的视图容器,在页面中可以拖拽滑动

        属性名类型默认值说明
        directionStringnonemovable-view的移动方向,属性值有all、vertical、horizontal、none
        inertiaBooleanfalsemovable-view是否带有惯性
        out-of-boundsBooleanfalse超过可移动区域后,movable-view是否还可以移动
        xNumber 定义x轴方向的偏移,如果x的值不在可移动范围内,会自动移动到可移动范围;改变x的值会触发动画
        yNumber 定义y轴方向的偏移,如果y的值不在可移动范围内,会自动移动到可移动范围;改变y的值会触发动画
        dampingNumber20阻尼系数,用于控制x或y改变时的动画和过界回弹的动画,值越大移动越快
        frictionNumber2摩擦系数,用于控制惯性滑动的动画,值越大摩擦力越大,滑动越快停止;必须大于0,否则会被设置成默认值

        movable-view 必须设置width和height属性,不设置默认为10px

        movable-view 默认为绝对定位,top和left属性为0px

        当movable-view小于movable-area时,movable-view的移动范围是在movable-area内;当movable-view大于movable-area时,movable-view的移动范围必须包含movable-area(x轴方向和y轴方向分开考虑)

        注意:movable-view必须在<movable-area/>组件中,并且必须是直接子节点,否则不能移动。

        示例代码:

        <view class="section">  <view class="section__title">movable-view区域小于movable-area</view>  <movable-area style="height: 200px;width: 200px;background: red;">    <movable-view style="height: 50px; width: 50px; background: blue;" x="{{x}}" y="{{y}}" direction="all">    </movable-view>  </movable-area>  <view class="btn-area">    <button size="mini" bindtap="tap">click me to move to (30px, 30px)</button>  </view>  <view class="section__title">movable-view区域大于movable-area</view>  <movable-area style="height: 100px;width: 100px;background: red;" direction="all">    <movable-view style="height: 200px; width: 200px; background: blue;">    </movable-view>  </movable-area></view>
        Page({  data: {    x: 0,    y: 0  },  tap: function(e) {    this.setData({      x: 30,      y: 30    });  }})

        cover-view

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

        覆盖在原生组件之上的文本视图。

        可覆盖的原生组件包括 mapvideocanvascameralive-playerlive-pusher

        只支持嵌套 cover-view、cover-image,可在 cover-view 中使用 button。组件属性的长度单位默认为px,2.4.0起支持传入单位(rpx/px)。

        属性类型默认值必填说明最低版本
        scroll-topnumber/string设置顶部滚动偏移量,仅在设置了 overflow-y: scroll 成为滚动元素后生效2.1.0

        提示

        1. cover-viewcover-image的aria-role仅可设置为button,读屏模式下才可以点击,并朗读出“按钮”;为空时可以聚焦,但不可点击
        2. 基础库 2.2.4 起支持 touch 相关事件,也可使用 hover-class 设置点击态
        3. 基础库 2.1.0 起支持设置 scale rotate 的 css 样式,包括 transition 动画
        4. 基础库 1.9.90 起 cover-view 支持 overflow: scroll,但不支持动态更新 overflow
        5. 基础库 1.9.90 起最外层 cover-view 支持 position: fixed
        6. 基础库 1.9.0 起支持插在 view 等标签下。在此之前只可嵌套在原生组件map、video、canvas、camera内,避免嵌套在其他组件内。
        7. 基础库 1.6.0 起支持css transition动画,transition-property只支持transform (translateX, translateY)与opacity。
        8. 基础库 1.6.0 起支持css opacity。
        9. 事件模型遵循冒泡模型,但不会冒泡到原生组件。
        10. 文本建议都套上cover-view标签,避免排版错误。
        11. 只支持基本的定位、布局、文本样式。不支持设置单边的border、background-image、shadow、overflow: visible等。
        12. 建议子节点不要溢出父节点
        13. 支持使用 z-index 控制层级
        14. 默认设置的样式有:white-space: nowrap; line-height: 1.2; display: block;
        15. 自定义组件嵌套 cover-view 时,自定义组件的 slot 及其父节点暂不支持通过 wx:if 控制显隐,否则会导致 cover-view 不显示


        cover-image

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

        覆盖在原生组件之上的图片视图。可覆盖的原生组件同cover-view,支持嵌套在cover-view里。

        属性类型默认值必填说明最低版本
        srcstring图标路径,支持临时路径、网络地址(1.6.0起支持)、云文件ID(2.2.3起支持)。1.4.0
        bindloadeventhandle图片加载成功时触发2.1.0
        binderroreventhandle图片加载失败时触发2.1.0

        支持的格式

        格式iOSAndroid
        JPG
        PNG
        SVGxx
        WEBP
        GIF
        BASE64xx


        icon

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

        图标。组件属性的长度单位默认为px,2.4.0起支持传入单位(rpx/px)。

        属性名类型默认值说明
        typeString icon的类型,有效值:success, success_no_circle, info, warn, waiting, cancel, download, search, clear
        sizeNumber23icon的大小,单位px
        colorColor icon的颜色,同css的color

        示例:

        <view class="container">  <view class="icon-box">    <icon class="icon-box-img" type="success" size="93"></icon>    <view class="icon-box-ctn">      <view class="icon-box-title">成功</view>      <view class="icon-box-desc">用于表示操作顺利完成</view>    </view>  </view>  <view class="icon-box">    <icon class="icon-box-img" type="info" size="93"></icon>    <view class="icon-box-ctn">      <view class="icon-box-title">提示</view>      <view class="icon-box-desc">用于表示信息提示;也常用于缺乏条件的操作拦截,提示用户所需信息</view>    </view>  </view>  <view class="icon-box">    <icon class="icon-box-img" type="warn" size="93" color="#C9C9C9"></icon>    <view class="icon-box-ctn">      <view class="icon-box-title">普通警告</view>      <view class="icon-box-desc">用于表示操作后将引起一定后果的情况;也用于表示由于系统原因而造成的负向结果</view>    </view>  </view>  <view class="icon-box">    <icon class="icon-box-img" type="warn" size="93"></icon>    <view class="icon-box-ctn">      <view class="icon-box-title">强烈警告</view>      <view class="icon-box-desc">用于表示由于用户原因造成的负向结果;也用于表示操作后将引起不可挽回的严重后果的情况</view>    </view>  </view>  <view class="icon-box">    <icon class="icon-box-img" type="waiting" size="93"></icon>    <view class="icon-box-ctn">      <view class="icon-box-title">等待</view>      <view class="icon-box-desc">用于表示等待,告知用户结果需等待</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="success_no_circle" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">多选控件图标_已选择</view>      <view class="icon-box-desc">用于多选控件中,表示已选择该项目</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="circle" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">多选控件图标_未选择</view>      <view class="icon-box-desc">用于多选控件中,表示该项目可被选择,但还未选择</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="warn" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">错误提示</view>      <view class="icon-box-desc">用于在表单中表示出现错误</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="success" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">单选控件图标_已选择</view>      <view class="icon-box-desc">用于单选控件中,表示已选择该项目</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="download" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">下载</view>      <view class="icon-box-desc">用于表示可下载</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="info_circle" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">提示</view>      <view class="icon-box-desc">用于在表单中表示有信息提示</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="cancel" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">停止或关闭</view>      <view class="icon-box-desc">用于在表单中,表示关闭或停止</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="search" size="14"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">搜索</view>      <view class="icon-box-desc">用于搜索控件中,表示可搜索</view>    </view>  </view></view>
        Page({  data: {    iconSize: [20, 30, 40, 50, 60, 70],    iconColor: [      'red', 'orange', 'yellow', 'green', 'rgb(0,255,255)', 'blue', 'purple'    ],    iconType: [      'success', 'success_no_circle', 'info', 'warn', 'waiting', 'cancel', 'download', 'search', 'clear'    ]  }})

        icon




        text 

        文本。
        属性名类型默认值说明最低版本
        selectableBooleanfalse文本是否可选1.1.0
        spaceStringfalse显示连续空格1.4.0
        decodeBooleanfalse是否解码1.4.0

        space 有效值:

        说明
        ensp中文字符空格一半大小
        emsp中文字符空格大小
        nbsp根据字体设置的空格大小
        Tips
        • decode可以解析的有 &nbsp; &lt; &gt; &amp; &apos; &ensp; &emsp;
        • 各个操作系统的空格标准并不一致。
        • <text/> 组件内只支持 <text/> 嵌套。
        • 除了文本节点以外的其他节点都无法长按选中。

        示例:

        代码片段

        <view class="btn-area">  <view class="body-view">    <text>{{text}}</text>    <button bindtap="add">add line</button>    <button bindtap="remove">remove line</button>  </view></view>
        var initData = 'this is first line
        this is second line'var extraLine = [];Page({  data: {    text: initData  },  add: function(e) {    extraLine.push('other line')    this.setData({      text: initData + '
        ' + extraLine.join('
        ')    })  },  remove: function(e) {    if (extraLine.length > 0) {      extraLine.pop()      this.setData({        text: initData + '
        ' + extraLine.join('
        ')      })    }  }})




        # rich-text

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

        富文本。

        属性类型默认值必填说明最低版本
        nodesarray/string[]节点列表/HTML String1.4.0
        spacestring显示连续空格2.4.1

        space 的合法值

        说明最低版本
        ensp中文字符空格一半大小
        emsp中文字符空格大小
        nbsp根据字体设置的空格大小

        # nodes

        现支持两种节点,通过type来区分,分别是元素节点和文本节点,默认是元素节点,在富文本区域里显示的HTML节点 元素节点:type = node*

        属性说明类型必填备注
        name标签名string支持部分受信任的 HTML 节点
        attrs属性object支持部分受信任的属性,遵循 Pascal 命名法
        children子节点列表array结构和 nodes 一致

        文本节点:type = text*

        属性说明类型必填备注
        text文本string支持entities

        # 受信任的HTML节点及属性

        全局支持class和style属性,不支持id属性。

        节点属性
        a
        abbr
        address
        article
        aside
        b
        bdi
        bdodir
        big
        blockquote
        br
        caption
        center
        cite
        code
        colspan,width
        colgroupspan,width
        dd
        del
        div
        dl
        dt
        em
        fieldset
        font
        footer
        h1
        h2
        h3
        h4
        h5
        h6
        header
        hr
        i
        imgalt,src,height,width
        ins
        label
        legend
        li
        mark
        nav
        olstart,type
        p
        pre
        q
        rt
        ruby
        s
        section
        small
        span
        strong
        sub
        sup
        tablewidth
        tbody
        tdcolspan,height,rowspan,width
        tfoot
        thcolspan,height,rowspan,width
        thead
        trcolspan,height,rowspan,width
        tt
        u
        ul

        # Bug & Tip

        1. tip: nodes 不推荐使用 String 类型,性能会有所下降。
        2. tip: rich-text 组件内屏蔽所有节点的事件。
        3. tip: attrs 属性不支持 id ,支持 class 。
        4. tip: name 属性大小写不敏感。
        5. tip: 如果使用了不受信任的HTML节点,该节点及其所有子节点将会被移除。
        6. tip: img 标签仅支持网络图片。
        7. tip: 如果在自定义组件中使用 rich-text 组件,那么仅自定义组件的 wxss 样式对 rich-text 中的 class 生效。

        # 示例代码

        在开发者工具中预览效果

        JavaScript

        const htmlSnip =`<div class="div_class">  <h1>Title</h1>  <p class="p">    Life is&nbsp;<i>like</i>&nbsp;a box of    <b>&nbsp;chocolates</b>.  </p></div>`const nodeSnip =`Page({  data: {    nodes: [{      name: 'div',      attrs: {        class: 'div_class',        style: 'line-height: 60px; color: red;'      },      children: [{        type: 'text',        text: 'You never know what you're gonna get.'      }]    }]  }})`Page({  onShareAppMessage() {    return {      title: 'rich-text',      path: 'page/component/pages/rich-text/rich-text'    }  },  data: {    htmlSnip,    nodeSnip,    renderedByHtml: false,    renderedByNode: false,    nodes: [{      name: 'div',      attrs: {        class: 'div_class',        style: 'line-height: 60px; color: #1AAD19;'      },      children: [{        type: 'text',        text: 'You never know what you're gonna get.'      }]    }]  },  renderHtml() {    this.setData({      renderedByHtml: true    })  },  renderNode() {    this.setData({      renderedByNode: true    })  },  enterCode(e) {    console.log(e.detail.value)    this.setData({      htmlSnip: e.detail.value    })  }})

         WXML

        <view class="container">  <view class="page-body">    <view class="page-section">      <view class="page-section-title">通过HTML String渲染</view>      <view class="page-content">        <scroll-view scroll-y>{{htmlSnip}}</scroll-view>        <button style="margin: 30rpx 0" type="primary" bindtap="renderHtml">渲染HTML</button>        <block wx:if="{{renderedByHtml}}">          <rich-text nodes="{{htmlSnip}}"></rich-text>        </block>      </view>    </view>    <view class="page-section">      <view class="page-section-title">通过节点渲染</view>      <view class="page-content">        <scroll-view scroll-y>{{nodeSnip}}</scroll-view>        <button style="margin: 30rpx 0" type="primary" bindtap="renderNode">渲染Node</button>        <block wx:if="{{renderedByNode}}">          <rich-text nodes="{{nodes}}"></rich-text>        </block>      </view>    </view>  </view></view>


        progress

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

        进度条。组件属性的长度单位默认为px,2.4.0起支持传入单位(rpx/px)。

        属性类型默认值必填说明最低版本
        percentnumber百分比0~1001.0.0
        show-infobooleanfalse在进度条右侧显示百分比1.0.0
        border-radiusnumber/string0圆角大小2.3.1
        font-sizenumber/string16右侧百分比字体大小2.3.1
        stroke-widthnumber/string6进度条线的宽度1.0.0
        colorstring#09BB07进度条颜色(请使用activeColor)1.0.0
        activeColorstring#09BB07已选择的进度条的颜色1.0.0
        backgroundColorstring#EBEBEB未选择的进度条的颜色1.0.0
        activebooleanfalse进度条从左往右的动画1.0.0
        active-modestringbackwardsbackwards: 动画从头播;forwards:动画从上次结束点接着播1.7.0
        durationnumber30进度增加1%所需毫秒数2.8.2
        bindactiveendeventhandle动画完成事件2.4.1

        示例代码

        <view class="progress-box">  <progress percent="20" show-info stroke-width="3"/></view><view class="progress-box">  <progress percent="40" active stroke-width="3" />  <icon class="progress-cancel" type="cancel"></icon></view><view class="progress-box">  <progress percent="60" active stroke-width="3" /></view><view class="progress-box">  <progress percent="80" color="#10AEFF" active stroke-width="3" /></view>


        progress


        button

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

        按钮。

        属性类型默认值必填说明最低版本
        sizestringdefault按钮的大小1.0.0
        typestringdefault按钮的样式类型1.0.0
        plainbooleanfalse按钮是否镂空,背景色透明1.0.0
        disabledbooleanfalse是否禁用1.0.0
        loadingbooleanfalse名称前是否带 loading 图标1.0.0
        form-typestring用于 form 组件,点击分别会触发 form 组件的 submit/reset 事件1.0.0
        open-typestring微信开放能力1.1.0
        hover-classstringbutton-hover指定按钮按下去的样式类。当 hover-class="none" 时,没有点击态效果1.0.0
        hover-stop-propagationbooleanfalse指定是否阻止本节点的祖先节点出现点击态1.5.0
        hover-start-timenumber20按住后多久出现点击态,单位毫秒1.0.0
        hover-stay-timenumber70手指松开后点击态保留时间,单位毫秒1.0.0
        langstringen指定返回用户信息的语言,zh_CN 简体中文,zh_TW 繁体中文,en 英文。1.3.0
        session-fromstring会话来源,open-type="contact"时有效1.4.0
        send-message-titlestring当前标题会话内消息卡片标题,open-type="contact"时有效1.5.0
        send-message-pathstring当前分享路径会话内消息卡片点击跳转小程序路径,open-type="contact"时有效1.5.0
        send-message-imgstring截图会话内消息卡片图片,open-type="contact"时有效1.5.0
        app-parameterstring打开 APP 时,向 APP 传递的参数,open-type=launchApp时有效1.9.5
        show-message-cardbooleanfalse是否显示会话内消息卡片,设置此参数为 true,用户进入客服会话会在右下角显示"可能要发送的小程序"提示,用户点击后可以快速发送小程序消息,open-type="contact"时有效1.5.0
        bindgetuserinfoeventhandle用户点击该按钮时,会返回获取到的用户信息,回调的detail数据与wx.getUserInfo返回的一致,open-type="getUserInfo"时有效1.3.0
        bindcontacteventhandle客服消息回调,open-type="contact"时有效1.5.0
        bindgetphonenumbereventhandle获取用户手机号回调,open-type=getPhoneNumber时有效1.2.0
        binderroreventhandle当使用开放能力时,发生错误的回调,open-type=launchApp时有效1.9.5
        bindopensettingeventhandle在打开授权设置页后回调,open-type=openSetting时有效2.0.7
        bindlaunchappeventhandle打开 APP 成功的回调,open-type=launchApp时有效2.4.4

        size 的合法值

        说明最低版本
        default默认大小
        mini小尺寸

        type 的合法值

        说明最低版本
        primary绿色
        default白色
        warn红色

        form-type 的合法值

        说明最低版本
        submit提交表单
        reset重置表单

        open-type 的合法值

        说明最低版本
        contact打开客服会话,如果用户在会话中点击消息卡片后返回小程序,可以从 bindcontact 回调中获得具体信息,具体说明1.1.0
        share触发用户转发,使用前建议先阅读使用指引1.2.0
        getPhoneNumber获取用户手机号,可以从bindgetphonenumber回调中获取到用户信息,具体说明1.2.0
        getUserInfo获取用户信息,可以从bindgetuserinfo回调中获取到用户信息1.3.0
        launchApp打开APP,可以通过app-parameter属性设定向APP传的参数具体说明1.9.5
        openSetting打开授权设置页2.0.7
        feedback打开“意见反馈”页面,用户可提交反馈内容并上传日志,开发者可以登录小程序管理后台后进入左侧菜单“客服反馈”页面获取到反馈内容2.1.0

        lang 的合法值

        说明最低版本
        en英文
        zh_CN简体中文
        zh_TW繁体中文

        提示:

        1. button-hover 默认为{background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}
        2. bindgetphonenumber 从1.2.0 开始支持,但是在1.5.3以下版本中无法使用wx.canIUse进行检测,建议使用基础库版本进行判断。
        3. 在bindgetphonenumber 等返回加密信息的回调中调用 wx.login 登录,可能会刷新登录态。此时服务器使用 code 换取的 sessionKey 不是加密时使用的 sessionKey,导致解密失败。建议开发者提前进行 login;或者在回调中先使用 checkSession 进行登录态检查,避免 login 刷新登录态。
        4. 从 2.1.0 起,button 可作为原生组件的子节点嵌入,以便在原生组件上使用 open-type 的能力。
        5. 目前设置了 form-type 的 button 只会对当前组件中的 form 有效。因而,将 button 封装在自定义组件中,而 form 在自定义组件外,将会使这个 button 的 form-type 失效。

        示例代码:

        /** 修改button默认的点击态样式类**/.button-hover {  background-color: red;}/** 添加自定义button点击态样式类**/.other-button-hover {  background-color: blue;}
        WXML文件<button type="default" size="{{defaultSize}}" loading="{{loading}}" plain="{{plain}}"        disabled="{{disabled}}" bindtap="default" hover-class="other-button-hover"> default </button><button type="primary" size="{{primarySize}}" loading="{{loading}}" plain="{{plain}}"        disabled="{{disabled}}" bindtap="primary"> primary </button><button type="warn" size="{{warnSize}}" loading="{{loading}}" plain="{{plain}}"        disabled="{{disabled}}" bindtap="warn"> warn </button><button bindtap="setDisabled">点击设置以上按钮disabled属性</button><button bindtap="setPlain">点击设置以上按钮plain属性</button><button bindtap="setLoading">点击设置以上按钮loading属性</button><button open-type="contact">进入客服会话</button>
        JS文件var types = ['default', 'primary', 'warn']var pageObject = {  data: {    defaultSize: 'default',    primarySize: 'default',    warnSize: 'default',    disabled: false,    plain: false,    loading: false  },  setDisabled: function(e) {    this.setData({      disabled: !this.data.disabled    })  },  setPlain: function(e) {    this.setData({      plain: !this.data.plain    })  },  setLoading: function(e) {    this.setData({      loading: !this.data.loading    })  }}for (var i = 0; i < types.length; ++i) {  (function(type) {    pageObject[type] = function(e) {      var key = type + 'Size'      var changedData = {}      changedData[key] =        this.data[key] === 'default' ? 'mini' : 'default'      this.setData(changedData)    }  })(types[i])}Page(pageObject)




        微信小程序表单组件 checkbox

        checkbox-group

        多项选择器,内部由多个checkbox组成。

        属性名 类型 默认值 说明
        bindchange EventHandle   <checkbox-group/>中选中项发生改变是触发change事件,detail = {value:[选中的checkbox的value的数组]}

        checkbox

        多选项目。

        属性名 类型 默认值 说明
        value String   <checkbox/>标识,选中时触发<checkbox-group/>的change事件,并携带<checkbox/>的value
        disabled Boolean false 是否禁用
        checked Boolean false 当前是否选中,可用来设置默认选中
        color Color   checkbox的颜色,同css的color

        示例:

        <checkbox-group bindchange="checkboxChange">    <label class="checkbox" wx:for-items="{{items}}">        <checkbox value="{{item.name}}" checked="{{item.checked}}"/>{{item.value}}    </label></checkbox-group>
        Page({  data: {    items: [      {name: 'USA', value: '美国'},      {name: 'CHN', value: '中国', checked: 'true'},      {name: 'BRA', value: '巴西'},      {name: 'JPN', value: '日本'},      {name: 'ENG', value: '英国'},      {name: 'TUR', value: '法国'},    ]  },  checkboxChange: function(e) {    console.log('checkbox发生change事件,携带value值为:', e.detail.value)  }})

        checkbox

        微信小程序form

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

        表单。将组件内的用户输入的switch input checkbox slider radio picker 提交。

        当点击 form 表单中 form-type 为 submit 的 button 组件时,会将表单组件中的 value 值进行提交,需要在表单组件中加上 name 来作为 key。

        属性类型默认值必填说明最低版本
        report-submitbooleanfalse是否返回 formId 用于发送模板消息1.0.0
        report-submit-timeoutnumber0等待一段时间(毫秒数)以确认 formId 是否生效。如果未指定这个参数,formId 有很小的概率是无效的(如遇到网络失败的情况)。指定这个参数将可以检测 formId 是否有效,以这个参数的时间作为这项检测的超时时间。如果失败,将返回 requestFormId:fail 开头的 formId2.6.2
        bindsubmiteventhandle携带 form 中的数据触发 submit 事件,event.detail = {value : {'name': 'value'} , formId: ''}1.0.0
        bindreseteventhandle表单重置时会触发 reset 事件1.0.0

        示例代码:

        <form bindsubmit="formSubmit" bindreset="formReset">    <view class="section section_gap">        <view class="section__title">switch</view>        <switch name="switch"/>    </view>    <view class="section section_gap">        <view class="section__title">slider</view>        <slider name="slider" show-value ></slider>    </view>    <view class="section">        <view class="section__title">input</view>        <input name="input" placeholder="please input here" />    </view>    <view class="section section_gap">        <view class="section__title">radio</view>        <radio-group name="radio-group">            <label><radio value="radio1"/>radio1</label>            <label><radio value="radio2"/>radio2</label>        </radio-group>    </view>    <view class="section section_gap">        <view class="section__title">checkbox</view>        <checkbox-group name="checkbox">            <label><checkbox value="checkbox1"/>checkbox1</label>            <label><checkbox value="checkbox2"/>checkbox2</label>        </checkbox-group>    </view>    <view class="btn-area">        <button formType="submit">Submit</button>        <button formType="reset">Reset</button>    </view></form>
        Page({  formSubmit: function(e) {    console.log('form发生了submit事件,携带数据为:', e.detail.value)  },  formReset: function() {    console.log('form发生了reset事件')  }})

        form


        input

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

        输入框。该组件是原生组件,使用时请注意相关限制

        属性类型默认值必填说明最低版本
        valuestring输入框的初始内容1.0.0
        typestringtextinput 的类型1.0.0
        passwordbooleanfalse是否是密码类型1.0.0
        placeholderstring输入框为空时占位符1.0.0
        placeholder-stylestring指定 placeholder 的样式1.0.0
        placeholder-classstringinput-placeholder指定 placeholder 的样式类1.0.0
        disabledbooleanfalse是否禁用1.0.0
        maxlengthnumber140最大输入长度,设置为 -1 的时候不限制最大长度1.0.0
        cursor-spacingnumber0指定光标与键盘的距离,取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离1.0.0
        auto-focusbooleanfalse(即将废弃,请直接使用 focus )自动聚焦,拉起键盘1.0.0
        focusbooleanfalse获取焦点1.0.0
        confirm-typestringdone设置键盘右下角按钮的文字,仅在type='text'时生效1.1.0
        confirm-holdbooleanfalse点击键盘右下角按钮时是否保持键盘不收起1.1.0
        cursornumber指定focus时的光标位置1.5.0
        selection-startnumber-1光标起始位置,自动聚集时有效,需与selection-end搭配使用1.9.0
        selection-endnumber-1光标结束位置,自动聚集时有效,需与selection-start搭配使用1.9.0
        adjust-positionbooleantrue键盘弹起时,是否自动上推页面1.9.90
        hold-keyboardbooleanfalsefocus时,点击页面的时候不收起键盘2.8.2
        bindinputeventhandle键盘输入时触发,event.detail = {value, cursor, keyCode},keyCode 为键值,2.1.0 起支持,处理函数可以直接 return 一个字符串,将替换输入框的内容。1.0.0
        bindfocuseventhandle输入框聚焦时触发,event.detail = { value, height },height 为键盘高度,在基础库 1.9.90 起支持1.0.0
        bindblureventhandle输入框失去焦点时触发,event.detail = {value: value}1.0.0
        bindconfirmeventhandle点击完成按钮时触发,event.detail = {value: value}1.0.0
        bindkeyboardheightchangeeventhandle键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration}2.7.0

        type 的合法值

        说明最低版本
        text文本输入键盘
        number数字输入键盘
        idcard身份证输入键盘
        digit带小数点的数字键盘

        confirm-type 的合法值

        说明最低版本
        send右下角按钮为“发送”
        search右下角按钮为“搜索”
        next右下角按钮为“下一个”
        go右下角按钮为“前往”
        done右下角按钮为“完成”

        提示:

        1. confirm-type的最终表现与手机输入法本身的实现有关,部分安卓系统输入法和第三方输入法可能不支持或不完全支持
        2. input 组件是一个原生组件,字体是系统字体,所以无法设置 font-family
        3. 在 input 聚焦期间,避免使用 css 动画
        4. 对于将 input 封装在自定义组件中、而 form 在自定义组件外的情况, form 将不能获得这个自定义组件中 input 的值。此时需要使用自定义组件的 内置 behaviors wx://form-field
        5. 键盘高度发生变化,keyboardheightchange事件可能会多次触发,开发者对于相同的height值应该忽略掉
        6. 微信版本 6.3.30, focus 属性设置无效
        7. 微信版本 6.3.30, placeholder 在聚焦时出现重影问题

        示例代码:

        <view class="page-body">  <view class="page-section">    <view class="weui-cells__title">可以自动聚焦的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" auto-focus placeholder="将会获取焦点"/>      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">控制最大输入长度的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" maxlength="10" placeholder="最大输入长度为10" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">实时获取输入值:{{inputValue}}</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input"  maxlength="10" bindinput="bindKeyInput" placeholder="输入同步到view中"/>      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">控制输入的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input"  bindinput="bindReplaceInput" placeholder="连续的两个1会变成2" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">控制键盘的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input"  bindinput="bindHideKeyboard" placeholder="输入123自动收起键盘" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">数字输入的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" type="number" placeholder="这是一个数字输入框" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">密码输入的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" password type="text" placeholder="这是一个密码输入框" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">带小数点的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" type="digit" placeholder="带小数点的数字键盘"/>      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">身份证输入的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" type="idcard" placeholder="身份证输入键盘" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">控制占位符颜色的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" placeholder-style="color:#F76260" placeholder="占位符字体是红色的" />      </view>    </view>  </view></view>
        Page({  data: {    focus: false,    inputValue: ''  },  bindKeyInput: function (e) {    this.setData({      inputValue: e.detail.value    })  },  bindReplaceInput: function (e) {    var value = e.detail.value    var pos = e.detail.cursor    var left    if (pos !== -1) {      // 光标在中间      left = e.detail.value.slice(0, pos)      // 计算光标的位置      pos = left.replace(/11/g, '2').length    }    // 直接返回对象,可以对输入进行过滤处理,同时可以控制光标的位置    return {      value: value.replace(/11/g, '2'),      cursor: pos    }    // 或者直接返回字符串,光标在最后边    // return value.replace(/11/g,'2'),  },  bindHideKeyboard: function (e) {    if (e.detail.value === '123') {      // 收起键盘      wx.hideKeyboard()    }  }})

        1595573794(1)


        label

        用来改进表单组件的可用性,使用for属性找到对应的id,或者将控件放在该标签下,当点击时,就会触发对应的控件。

        for优先级高于内部控件,内部有多个控件的时候默认触发第一个控件。

        目前可以绑定的控件有:<button/>, <checkbox/>, <radio/>, <switch/>

        属性名 类型 说明
        for String 绑定控件的id

        示例代码:

        <view class="section section_gap"><view class="section__title">表单组件在label内</view><checkbox-group class="group" bindchange="checkboxChange">    <view class="label-1" wx:for-items="{{checkboxItems}}">        <label>            <checkbox hidden value="{{item.name}}" checked="{{item.checked}}"></checkbox>            <view class="label-1__icon">                <view class="label-1__icon-checked" style="opacity:{{item.checked ? 1: 0}}"></view>            </view>            <text class="label-1__text">{{item.value}}</text>        </label>    </view></checkbox-group></view><view class="section section_gap"><view class="section__title">label用for标识表单组件</view><radio-group class="group" bindchange="radioChange">    <view class="label-2" wx:for-items="{{radioItems}}">        <radio id="{{item.name}}" hidden value="{{item.name}}" checked="{{item.checked}}"></radio>        <view class="label-2__icon">            <view class="label-2__icon-checked" style="opacity:{{item.checked ? 1: 0}}"></view>        </view>        <label class="label-2__text" for="{{item.name}}"><text>{{item.name}}</text></label>    </view></radio-group></view>
        Page({  data: {    checkboxItems: [      {name: 'USA', value: '美国'},      {name: 'CHN', value: '中国', checked: 'true'},      {name: 'BRA', value: '巴西'},      {name: 'JPN', value: '日本', checked: 'true'},      {name: 'ENG', value: '英国'},      {name: 'TUR', value: '法国'},    ],    radioItems: [      {name: 'USA', value: '美国'},      {name: 'CHN', value: '中国', checked: 'true'},      {name: 'BRA', value: '巴西'},      {name: 'JPN', value: '日本'},      {name: 'ENG', value: '英国'},      {name: 'TUR', value: '法国'},    ],    hidden: false  },  checkboxChange: function(e) {    var checked = e.detail.value    var changed = {}    for (var i = 0; i < this.data.checkboxItems.length; i ++) {      if (checked.indexOf(this.data.checkboxItems[i].name) !== -1) {        changed['checkboxItems['+i+'].checked'] = true      } else {        changed['checkboxItems['+i+'].checked'] = false      }    }    this.setData(changed)  },  radioChange: function(e) {    var checked = e.detail.value    var changed = {}    for (var i = 0; i < this.data.radioItems.length; i ++) {      if (checked.indexOf(this.data.radioItems[i].name) !== -1) {        changed['radioItems['+i+'].checked'] = true      } else {        changed['radioItems['+i+'].checked'] = false      }    }    this.setData(changed)  }})
        .label-1, .label-2{    margin-bottom: 15px;}.label-1__text, .label-2__text {    display: inline-block;    vertical-align: middle;}.label-1__icon {    position: relative;    margin-right: 10px;    display: inline-block;    vertical-align: middle;    width: 18px;    height: 18px;    background: #fcfff4;}.label-1__icon-checked {    position: absolute;    top: 3px;    left: 3px;    width: 12px;    height: 12px;    background: #1aad19;}.label-2__icon {    position: relative;    display: inline-block;    vertical-align: middle;    margin-right: 10px;    width: 18px;    height: 18px;    background: #fcfff4;    border-radius: 50px;}.label-2__icon-checked {    position: absolute;    left: 3px;    top: 3px;    width: 12px;    height: 12px;    background: #1aad19;    border-radius: 50%;}.label-4_text{    text-align: center;    margin-top: 15px;}

        label

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

        从底部弹起的滚动选择器。

        属性类型默认值必填说明最低版本
        header-textstring选择器的标题,仅安卓可用2.11.0
        modestringselector选择器类型1.0.0
        disabledbooleanfalse是否禁用1.0.0
        bindcanceleventhandle取消选择时触发1.9.90

        mode 的合法值

        说明最低版本
        selector普通选择器
        multiSelector多列选择器
        time时间选择器
        date日期选择器
        region省市区选择器

        除了上述通用的属性,对于不同的mode,picker拥有不同的属性。

        普通选择器:mode = selector

        属性名类型默认值说明最低版本
        rangearray/object array[]mode 为 selector 或 multiSelector 时,range 有效
        range-keystring当 range 是一个 Object Array 时,通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
        valuenumber0表示选择了 range 中的第几个(下标从 0 开始)
        bindchangeeventhandlevalue 改变时触发 change 事件,event.detail = {value}

        多列选择器:mode = multiSelector

        属性名类型默认值说明最低版本
        rangearray/object array[]mode 为 selector 或 multiSelector 时,range 有效
        range-keystring当 range 是一个 Object Array 时,通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
        valuearray[]表示选择了 range 中的第几个(下标从 0 开始)
        bindchangeeventhandlevalue 改变时触发 change 事件,event.detail = {value}
        bindcolumnchangeeventhandle列改变时触发

        时间选择器:mode = time

        属性名类型默认值说明最低版本
        valuestring表示选中的时间,格式为"hh:mm"
        startstring表示有效时间范围的开始,字符串格式为"hh:mm"
        endstring表示有效时间范围的结束,字符串格式为"hh:mm"
        bindchangeeventhandlevalue 改变时触发 change 事件,event.detail = {value}

        日期选择器:mode = date

        属性名类型默认值说明最低版本
        valuestring当天表示选中的日期,格式为"YYYY-MM-DD"
        startstring表示有效日期范围的开始,字符串格式为"YYYY-MM-DD"
        endstring表示有效日期范围的结束,字符串格式为"YYYY-MM-DD"
        fieldsstringday有效值 year,month,day,表示选择器的粒度
        bindchangeeventhandlevalue 改变时触发 change 事件,event.detail = {value}

        fields 有效值:*

        说明
        year选择器粒度为年
        month选择器粒度为月份
        day选择器粒度为天

        省市区选择器:mode = region 1.4.0

        属性名类型默认值说明最低版本
        valuearray[]表示选中的省市区,默认选中每一列的第一个值
        custom-itemstring可为每一列的顶部添加一个自定义的项1.5.0
        bindchangeeventhandlevalue 改变时触发 change 事件,event.detail = {value, code, postcode},其中字段 code 是统计用区划代码,postcode 是邮政编码


        示例代码:

        <view class="section">    <view class="sectiontitle">普通选择器</view>    <picker bindchange="bindPickerChange" value="{{index}}" range="{{array}}">        <view class="picker">            当前选择: {{array[index]}}        </view>    </picker></view>    <view class="sectiontitle">多列选择器    <picker mode="multiSelector" bindchange="bindMultiPickerChange" bindcolumnchange="bindMultiPickerColumnChange" value="{{multiIndex}}">            当前选择: {{multiArray[0][multiIndex[0]]}},{{multiArray[1][multiIndex[1]]}},{{multiArray[2][multiIndex[2]]}}     <view class="section">    <view class="sectiontitle">时间选择器</view>    <picker mode="time" value="{{time}}" start="09:01" end="21:01" bindchange="bindTimeChange">        <view class="picker">            当前选择: {{time}}        </view>    </picker></view>

        <view class="section"> <view class="sectiontitle">日期选择器</view> <picker mode="date" value="{{date}}" start="2015-09-01" end="2017-09-01" bindchange="bindDateChange"> <view class="picker"> 当前选择: {{date}} </view> </picker></view>

        省市区选择器 当前选择: {{region[0]}},{{region[1]}},{{region[2]}}

        Page({  data: {    array: ['美国', '中国', '巴西', '日本'],    objectArray: [      {        id: 0,        name: '美国'      },      {        id: 1,        name: '中国'      },      {        id: 2,        name: '巴西'      },      {        id: 3,        name: '日本'      }    ],    index: 0,    multiArray: [['无脊柱动物', '脊柱动物'], ['扁性动物', '线形动物', '环节动物', '软体动物', '节肢动物'], ['猪肉绦虫', '吸血虫']],    objectMultiArray: [      [        {          id: 0,          name: '无脊柱动物'        },        {          id: 1,          name: '脊柱动物'        }      ], [        {          id: 0,          name: '扁性动物'        },        {          id: 1,          name: '线形动物'        },        {          id: 2,          name: '环节动物'        },        {          id: 3,          name: '软体动物'        },        {          id: 3,          name: '节肢动物'        }      ], [        {          id: 0,          name: '猪肉绦虫'        },        {          id: 1,          name: '吸血虫'        }      ]    ],    multiIndex: [0, 0, 0],    date: '2016-09-01',    time: '12:01',    region: ['广东省', '广州市', '海珠区']  },  bindPickerChange: function(e) {    console.log('picker发送选择改变,携带值为', e.detail.value)    this.setData({      index: e.detail.value    })  },  bindMultiPickerChange: function (e) {    console.log('picker发送选择改变,携带值为', e.detail.value)    this.setData({      multiIndex: e.detail.value    })  },  bindMultiPickerColumnChange: function (e) {    console.log('修改的列为', e.detail.column, ',值为', e.detail.value);    var data = {      multiArray: this.data.multiArray,      multiIndex: this.data.multiIndex    };    data.multiIndex[e.detail.column] = e.detail.value;    switch (e.detail.column) {      case 0:        switch (data.multiIndex[0]) {          case 0:            data.multiArray[1] = ['扁性动物', '线形动物', '环节动物', '软体动物', '节肢动物'];            data.multiArray[2] = ['猪肉绦虫', '吸血虫'];            break;          case 1:            data.multiArray[1] = ['鱼', '两栖动物', '爬行动物'];            data.multiArray[2] = ['鲫鱼', '带鱼'];            break;        }        data.multiIndex[1] = 0;        data.multiIndex[2] = 0;        break;      case 1:        switch (data.multiIndex[0]) {          case 0:            switch (data.multiIndex[1]) {              case 0:                data.multiArray[2] = ['猪肉绦虫', '吸血虫'];                break;              case 1:                data.multiArray[2] = ['蛔虫'];                break;              case 2:                data.multiArray[2] = ['蚂蚁', '蚂蟥'];                break;              case 3:                data.multiArray[2] = ['河蚌', '蜗牛', '蛞蝓'];                break;              case 4:                data.multiArray[2] = ['昆虫', '甲壳动物', '蛛形动物', '多足动物'];                break;            }            break;          case 1:            switch (data.multiIndex[1]) {              case 0:                data.multiArray[2] = ['鲫鱼', '带鱼'];                break;              case 1:                data.multiArray[2] = ['青蛙', '娃娃鱼'];                break;              case 2:                data.multiArray[2] = ['蜥蜴', '龟', '壁虎'];                break;            }            break;        }        data.multiIndex[2] = 0;        console.log(data.multiIndex);        break;    }    this.setData(data);  },  bindDateChange: function(e) {    console.log('picker发送选择改变,携带值为', e.detail.value)    this.setData({      date: e.detail.value    })  },  bindTimeChange: function(e) {    console.log('picker发送选择改变,携带值为', e.detail.value)    this.setData({      time: e.detail.value    })  },  bindRegionChange: function (e) {    console.log('picker发送选择改变,携带值为', e.detail.value)    this.setData({      region: e.detail.value    })  }})

        picker




        picker-view


        嵌入页面的滚动选择器

        属性名类型说明最低版本
        valueNumberArray数组中的数字依次表示 picker-view 内的 picker-view-colume 选择的第几项(下标从 0 开始),数字大于 picker-view-column 可选项长度时,选择最后一项。 
        indicator-styleString设置选择器中间选中框的样式 
        indicator-classString设置选择器中间选中框的类名1.1.0
        bindchangeEventHandle当滚动选择,value 改变时触发 change 事件,event.detail = {value: value};value为数组,表示 picker-view 内的 picker-view-column 当前选择的是第几项(下标从 0 开始) 

        注意:其中只可放置<picker-view-column/>组件,其他节点不会显示。

        picker-view-column

        仅可放置于<picker-view />中,其孩子节点的高度会自动设置成与picker-view的选中框的高度一致。

        示例代码:

        <view>  <view>{{year}}年{{month}}月{{day}}日</view>  <picker-view indicator-style="height: 50px;" style="width: 100%; height: 300px;" value="{{value}}" bindchange="bindChange">    <picker-view-column>      <view wx:for="{{years}}" style="line-height: 50px">{{item}}年</view>    </picker-view-column>    <picker-view-column>      <view wx:for="{{months}}" style="line-height: 50px">{{item}}月</view>    </picker-view-column>    <picker-view-column>      <view wx:for="{{days}}" style="line-height: 50px">{{item}}日</view>    </picker-view-column>  </picker-view></view>
        const date = new Date()const years = []const months = []const days = []for (let i = 1990; i <= date.getFullYear(); i++) {  years.push(i)}for (let i = 1 ; i <= 12; i++) {  months.push(i)}for (let i = 1 ; i <= 31; i++) {  days.push(i)}Page({  data: {    years: years,    year: date.getFullYear(),    months: months,    month: 2,    days: days,    day: 2,    year: date.getFullYear(),    value: [9999, 1, 1],  },  bindChange: function(e) {    const val = e.detail.value    this.setData({      year: this.data.years[val[0]],      month: this.data.months[val[1]],      day: this.data.days[val[2]]    })  }})

        picker_view

        微信小程序单选框radio

        radio-group

        单项选择器,内部由多个<radio/>组成。

        属性名 类型 默认值 说明
        bindchange EventHandle   <radio-group/>中的选中项发生变化时触发change事件,event.detail = {value: 选中项radio的value}

        radio


        ​ 单选项目

        属性名类型默认值说明
        valueString <radio/>标识。当该<radio/>选中时,<radio-group/> 的change 事件会携带<radio/>的value
        checkedBooleanfalse当前是否选中
        disabledBooleanfalse是否禁用
        colorColor radio的颜色,同css的color

        <radio-group class="radio-group" bindchange="radioChange">    <label class="radio" wx:for="{{items}}">        <radio value="{{item.name}}" checked="{{item.checked}}"/>{{item.value}}    </label></radio-group>
        Page({   data: {    items: [      {name: 'USA', value: '美国'},      {name: 'CHN', value: '中国', checked: 'true'},      {name: 'BRA', value: '巴西'},      {name: 'JPN', value: '日本'},      {name: 'ENG', value: '英国'},      {name: 'TUR', value: '法国'},    ]  },  radioChange: function(e) {    console.log('radio发生change事件,携带value值为:', e.detail.value)  }})

        radio

        slider

        滑动选择器。

        属性名类型默认值说明最低版本
        minNumber0最小值
        maxNumber100最大值
        stepNumber1步长,取值必须大于 0,并且可被(max - min)整除
        disabledBooleanfalse是否禁用
        valueNumber0当前取值
        colorColor#e9e9e9背景条的颜色(请使用 backgroundColor)
        selected-colorColor#1aad19已选择的颜色(请使用 activeColor)
        activeColorColor#1aad19已选择的颜色
        backgroundColorColor#e9e9e9背景条的颜色
        show-valueBooleanfalse是否显示当前 value
        bindchangeEventHandle完成一次拖动后触发的事件,event.detail = {value: value}
        bindchangingEventHandle拖动过程中触发的事件,event.detail = {value: value}1.7.0

        示例代码:

        <view class="section section_gap">    <text class="section__title">设置left/right icon</text>    <view class="body-view">        <slider bindchange="slider1change" left-icon="cancel" right-icon="success_no_circle"/>    </view></view><view class="section section_gap">    <text class="section__title">设置step</text>    <view class="body-view">        <slider bindchange="slider2change" step="5"/>    </view></view><view class="section section_gap">    <text class="section__title">显示当前value</text>    <view class="body-view">        <slider bindchange="slider3change" show-value/>    </view></view><view class="section section_gap">    <text class="section__title">设置最小/最大值</text>    <view class="body-view">        <slider bindchange="slider4change" min="50" max="200" show-value/>    </view></view>
        var pageData = {}for(var i = 1; i < 5; ++i) {  (function (index) {    pageData['slider' + index + 'change'] = function(e) {      console.log('slider' + 'index' + '发生 change 事件,携带值为', e.detail.value)    }  })(i);}Page(pageData)



        switch

        开关选择器。

        属性名类型默认值说明
        checkedBooleanfalse是否选中
        disabledBooleanfalse是否禁用
        typeStringswitch样式,有效值:switch, checkbox
        bindchangeEventHandle checked 改变时触发change事件,event.detail={ value}
        colorString #04BE02switch的颜色,同css的color
        <view class="body-view">    <switch checked bindchange="switch1Change"/>    <switch bindchange="switch2Change"/></view>
        page({  switch1Checked: function (e){    console.log('switch1 发生 change 事件,携带值为', e.detail.value)  },  switch2Change: function (e){    console.log('switch2 发生 change 事件,携带值为', e.detail.value)  }})

        switch


        textarea

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

        多行输入框。该组件是原生组件,使用时请注意相关限制。

        属性类型默认值必填说明最低版本
        valuestring输入框的内容1.0.0
        placeholderstring输入框为空时占位符1.0.0
        placeholder-stylestring指定 placeholder 的样式,目前仅支持color,font-size和font-weight1.0.0
        placeholder-classstringtextarea-placeholder指定 placeholder 的样式类1.0.0
        disabledbooleanfalse是否禁用1.0.0
        maxlengthnumber140最大输入长度,设置为 -1 的时候不限制最大长度1.0.0
        auto-focusbooleanfalse自动聚焦,拉起键盘。1.0.0
        focusbooleanfalse获取焦点1.0.0
        auto-heightbooleanfalse是否自动增高,设置auto-height时,style.height不生效1.0.0
        fixedbooleanfalse如果 textarea 是在一个 position:fixed 的区域,需要显示指定属性 fixed 为 true1.0.0
        cursor-spacingnumber0指定光标与键盘的距离。取textarea距离底部的距离和cursor-spacing指定的距离的最小值作为光标与键盘的距离1.0.0
        cursornumber-1指定focus时的光标位置1.5.0
        show-confirm-barbooleantrue是否显示键盘上方带有”完成“按钮那一栏1.6.0
        selection-startnumber-1光标起始位置,自动聚集时有效,需与selection-end搭配使用1.9.0
        selection-endnumber-1光标结束位置,自动聚集时有效,需与selection-start搭配使用1.9.0
        adjust-positionbooleantrue键盘弹起时,是否自动上推页面1.9.90
        hold-keyboardbooleanfalsefocus时,点击页面的时候不收起键盘2.8.2
        disable-default-paddingbooleanfalse是否去掉 iOS 下的默认内边距2.10.0
        confirm-typestringreturn设置键盘右下角按钮的文字2.13.0
        confirm-holdbooleanfalse点击键盘右下角按钮时是否保持键盘不收起2.16.0
        bindfocuseventhandle输入框聚焦时触发,event.detail = { value, height },height 为键盘高度,在基础库 1.9.90 起支持1.0.0
        bindblureventhandle输入框失去焦点时触发,event.detail = {value, cursor}1.0.0
        bindlinechangeeventhandle输入框行数变化时调用,event.detail = {height: 0, heightRpx: 0, lineCount: 0}1.0.0
        bindinputeventhandle当键盘输入时,触发 input 事件,event.detail = {value, cursor, keyCode},keyCode 为键值,目前工具还不支持返回keyCode参数。bindinput 处理函数的返回值并不会反映到 textarea 上1.0.0
        bindconfirmeventhandle点击完成时, 触发 confirm 事件,event.detail = {value: value}1.0.0
        bindkeyboardheightchangeeventhandle键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration}2.7.0


        confirm-type 的合法值

        说明最低版本
        send右下角按钮为“发送”
        search右下角按钮为“搜索”
        next右下角按钮为“下一个”
        go右下角按钮为“前往”
        done右下角按钮为“完成”
        return右下角按钮为“换行”

        Bug & Tip

        1. tip: textareablur 事件会晚于页面上的 tap 事件,如果需要在 button 的点击事件获取 textarea,可以使用 formbindsubmit
        2. tip: 不建议在多行文本上对用户的输入进行修改,所以 textareabindinput 处理函数并不会将返回值反映到 textarea 上。
        3. tip : 键盘高度发生变化,keyboardheightchange事件可能会多次触发,开发者对于相同的height值应该忽略掉
        4. bug: 微信版本 6.3.30textarea 在列表渲染时,新增加的 textarea 在自动聚焦时的位置计算错误。

        示例代码

        在开发者工具中预览效果

        <view class="section">  <textarea bindblur="bindTextAreaBlur" auto-height placeholder="自动变高" /></view><view class="section">  <textarea placeholder="placeholder颜色是红色的" placeholder-style="color:red;"  /></view><view class="section">  <textarea placeholder="这是一个可以自动聚焦的textarea" auto-focus /></view><view class="section">  <textarea placeholder="这个只有在按钮点击的时候才聚焦" focus="{{focus}}" />  <view class="btn-area">    <button bindtap="bindButtonTap">使得输入框获取焦点</button>  </view></view><view class="section">  <form bindsubmit="bindFormSubmit">    <textarea placeholder="form 中的 textarea" name="textarea"/>    <button form-type="submit"> 提交 </button>  </form></view>
        //textarea.jsPage({  data: {    height: 20,    focus: false  },  bindButtonTap: function() {    this.setData({      focus: true    })  },  bindTextAreaBlur: function(e) {    console.log(e.detail.value)  },  bindFormSubmit: function(e) {    console.log(e.detail.value.textarea)  }})

        editor

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

        富文本编辑器,可以对图片、文字进行编辑。

        编辑器导出内容支持带标签的 html和纯文本的 text,编辑器内部采用 delta 格式进行存储。

        通过setContents接口设置内容时,解析插入的 html 可能会由于一些非法标签导致解析错误,建议开发者在小程序内使用时通过 delta 进行插入。

        富文本组件内部引入了一些基本的样式使得内容可以正确的展示,开发时可以进行覆盖。需要注意的是,在其它组件或环境中使用富文本组件导出的html时,需要额外引入 这段样式,并维护<ql-container><ql-editor></ql-editor></ql-container>的结构。

        图片控件仅初始化时设置有效。

        相关 api:EditorContext

        属性类型默认值必填说明最低版本
        read-onlybooleanfalse设置编辑器为只读2.7.0
        placeholderstring提示信息2.7.0
        show-img-sizebooleanfalse点击图片时显示图片大小控件2.7.0
        show-img-toolbarbooleanfalse点击图片时显示工具栏控件2.7.0
        show-img-resizebooleanfalse点击图片时显示修改尺寸控件2.7.0
        bindreadyeventhandle编辑器初始化完成时触发2.7.0
        bindfocuseventhandle编辑器聚焦时触发,event.detail = {html, text, delta}2.7.0
        bindblureventhandle编辑器失去焦点时触发,detail = {html, text, delta}2.7.0
        bindinputeventhandle编辑器内容改变时触发,detail = {html, text, delta}2.7.0
        bindstatuschangeeventhandle通过 Context 方法改变编辑器内样式时触发,返回选区已设置的样式2.7.0

        编辑器内支持部分 HTML 标签和内联样式,不支持class和id

        支持的标签

        不满足的标签会被忽略,<div>会被转行为<p>储存。

        类型节点
        行内元素<span> <strong> <b> <ins> <em> <i> <u> <a> <del> <s> <sub> <sup> <img>
        块级元素<p> <h1> <h2> <h3> <h4> <h5> <h6> <hr> <ol> <ul> <li>

        支持的内联样式

        内联样式仅能设置在行内元素或块级元素上,不能同时设置。例如 font-size 归类为行内元素属性,在 p 标签上设置是无效的。

        类型样式
        块级样式text-align direction margin margin-top margin-left margin-right margin-bottom
        padding padding-top padding-left padding-right padding-bottom line-height text-indent
        行内样式font font-size font-style font-variant font-weight font-family
        letter-spacing text-decoration color background-color

        提示:

        1. 使用 catchtouchend 绑定事件则不会使编辑器失去焦点(2.8.3)
        2. 插入的 html 中事件绑定会被移除
        3. formats 中的 color 属性会统一以 hex 格式返回
        4. 粘贴时仅纯文本内容会被拷贝进编辑器
        5. 插入 html 到编辑器内时,编辑器会删除一些不必要的标签,以保证内容的统一。例如<p><span>xxx</span></p>会改写为<p>xxx</p>
        6. 编辑器聚焦时页面会被上推,系统行为以保证编辑区可见


        navigator

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

        页面链接。

        属性名类型默认值说明
        target
        Stringself在哪个目标上发生跳转,默认当前小程序,可选值self/miniProgram
        urlString 应用内的跳转链接
        open-typeStringnavigate跳转方式
        deltaNumber 当 open-type 为 'navigateBack' 时有效,表示回退的层数
        app-id
        String
         当target="miniProgram"时有效,要打开的小程序 appId
        path
        String
         当target="miniProgram"时有效,打开的页面路径,如果为空则打开首页
        extra-data
        Object
         当target="miniProgram"时有效,需要传递给目标小程序的数据,目标小程序可在 App.onLaunch()App.onShow() 中获取到这份数据。
        version
        version
        release当target="miniProgram"时有效,要打开的小程序版本,有效值 develop(开发版),trial(体验版),release(正式版),仅在当前小程序为开发版或体验版时此参数有效;如果当前小程序是正式版,则打开的小程序必定是正式版。
        hover-classStringnavigator-hover指定点击时的样式类,当hover-class="none"时,没有点击态效果
        hover-stop-propagation
        Boolean
        false
        指定是否阻止本节点的祖先节点出现点击态
        hover-start-timeNumber50按住后多久出现点击态,单位毫秒
        hover-stay-timeNumber600手指松开后点击态保留时间,单位毫秒
        bindsuccess
        String
        当target="miniProgram"时有效,跳转小程序成功
        bindfail
        String
        当target="miniProgram"时有效,跳转小程序失败
        bindcomplete
        String
        当target="miniProgram"时有效,跳转小程序完成


        open-type 有效值:

        说明最低版本
        navigate对应wx.navigateTo的功能 
        redirect对应wx.redirectTo的功能 
        switchTab对应wx.switchTab的功能 
        reLaunch对应wx.reLaunch的功能1.1.0
        navigateBack对应wx.navigateBack的功能1.1.0
        exit
        退出小程序,target="miniProgram"时生效
        2.1.0

        注:navigator-hover默认为{background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}, <navigator/>的子节点背景色应为透明色

        示例代码:

        /** wxss **//** 修改默认的navigator点击态 **/.navigator-hover {    color:blue;}/** 自定义其他点击态样式类 **/.other-navigator-hover {    color:red;}
        <!-- sample.wxml --><view class="btn-area">  <navigator url="/page/navigate/navigate?title=navigate" hover-class="navigator-hover">跳转到新页面</navigator>  <navigator url="../../redirect/redirect/redirect?title=redirect" open-type="redirect" hover-class="other-navigator-hover">在当前页打开</navigator>  <navigator url="/page/index/index" open-type="switchTab" hover-class="other-navigator-hover">切换 Tab</navigator></view>
        <!-- navigator.wxml --><view style="text-align:center"> {{title}} </view><view> 点击左上角返回回到之前页面 </view>
        <!-- redirect.wxml --><view style="text-align:center"> {{title}} </view><view> 点击左上角返回回到上级页面 </view>
        // redirect.js navigator.jsPage({  onLoad: function(options) {    this.setData({      title: options.title    })  }})


        functional-page-navigator

        基础库 2.9.0 开始支持,低版本需做兼容处理。

        页面导航条配置节点,用于指定导航栏的一些属性。只能是 page-meta 组件内的第一个节点,需要配合它一同使用。

        通过这个节点可以获得类似于调用 wx.setNavigationBarTitle wx.setNavigationBarColor 等接口调用的效果。

        属性类型默认值必填说明最低版本
        titlestring导航条标题2.9.0
        loadingbooleanfalse是否在导航条显示 loading 加载提示2.9.0
        front-colorstring导航条前景颜色值,包括按钮、标题、状态栏的颜色,仅支持 #ffffff 和 #0000002.9.0
        background-colorstring导航条背景颜色值,有效值为十六进制颜色2.9.0
        color-animation-durationnumber0改变导航栏颜色时的动画时长,默认为 0 (即没有动画效果)2.9.0
        color-animation-timing-funcnumber"linear"改变导航栏颜色时的动画方式,支持 linear 、 easeIn 、 easeOut 和 easeInOut2.9.0

        示例代码

        <page-meta>  <navigation-bar    title="{{nbTitle}}"    loading="{{nbLoading}}"    front-color="{{nbFrontColor}}"    background-color="{{nbBackgroundColor}}"    color-animation-duration="2000"    color-animation-timing-func="easeIn"  /></page-meta>
        Page({  data: {    nbFrontColor: '#000000',    nbBackgroundColor: '#ffffff',  },  onLoad() {    this.setData({      nbTitle: '新标题',      nbLoading: true,      nbFrontColor: '#ffffff',      nbBackgroundColor: '#000000',    })  }})


        audio


        音频。

        属性名类型默认值说明
        idString audio 组件的唯一标识符
        srcString 要播放音频的资源地址
        loopBooleanfalse是否循环播放
        controlsBooleantrue是否显示默认控件
        posterString 默认控件上的音频封面的图片资源地址,如果 controls 属性值为 false 则设置 poster 无效
        nameString未知音频默认控件上的音频名字,如果 controls 属性值为 false 则设置 name 无效
        authorString未知作者默认控件上的作者名字,如果 controls 属性值为 false 则设置 author 无效
        binderrorEventHandle 当发生错误时触发 error 事件,detail = {errMsg: MediaError.code}
        bindplayEventHandle 当开始/继续播放时触发play事件
        bindpauseEventHandle 当暂停播放时触发 pause 事件
        bindtimeupdateEventHandle 当播放进度改变时触发 timeupdate 事件,detail = {currentTime, duration}
        bindendedEventHandle 当播放到末尾时触发 ended 事件

        MediaError.code

        返回错误码描述
        MEDIA_ERR_ABORTED获取资源被用户禁止
        MEDIA_ERR_NETWORD网络错误
        MEDIA_ERR_DECODE解码错误
        MEDIA_ERR_SRC_NOT_SUPPOERTED不合适资源

        示例代码:

        <!-- audio.wxml --><audio poster="{{poster}}" name="{{name}}" author="{{author}}" src="{{src}}" id="myAudio" controls loop></audio><button type="primary" bindtap="audioPlay">播放</button><button type="primary" bindtap="audioPause">暂停</button><button type="primary" bindtap="audio14">设置当前播放时间为14秒</button><button type="primary" bindtap="audioStart">回到开头</button>
        // audio.jsPage({  onReady: function (e) {    // 使用 wx.createAudioContext 获取 audio 上下文 context    this.audioCtx = wx.createAudioContext('myAudio')  },  data: {    poster: 'http://y.gtimg.cn/music/photo_new/T002R300x300M000003rsKF44GyaSk.jpg?max_age=2592000',    name: '此时此刻',    author: '许巍',    src: 'http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E06DCBDC9AB7C49FD713D632D313AC4858BACB8DDD29067D3C601481D36E62053BF8DFEAF74C0A5CCFADD6471160CAF3E6A&fromtag=46',  },  audioPlay: function () {    this.audioCtx.play()  },  audioPause: function () {    this.audioCtx.pause()  },  audio14: function () {    this.audioCtx.seek(14)  },  audioStart: function () {    this.audioCtx.seek(0)  }})

        audio

        相关api:wx.createAudioContext

        微信小程序image


        图片。

        属性名 类型 默认值 说明
        src String   图片资源地址
        mode String 'scaleToFill' 图片裁剪、缩放的模式
        binderror HandleEvent   当错误发生时,发布到AppService的事件名,事件对象event.detail = { errMsg: 'something wrong' }
        bindload HandleEvent   当图片载入完毕时,发布到AppService的事件名,事件对象event.detail = {height:'图片高度px', width:'图片宽度px'
        }

        注:image组件默认宽度300px、高度225px

        mode 有效值:

        mode有13种模式,其中4种是缩放模式,9种是裁剪模式。

        模式说明
        缩放scaleToFill不保持纵横比缩放图片,使图片的宽高完全拉伸至填满 image 元素
        缩放aspectFit保持纵横比缩放图片,使图片的长边能完全显示出来。也就是说,可以完整地将图片显示出来。
        缩放aspectFill保持纵横比缩放图片,只保证图片的短边能完全显示出来。也就是说,图片通常只在水平或垂直方向是完整的,另一个方向将会发生截取。
        缩放widthFix宽度不变,高度自动变化,保持原图宽高比不变
        裁剪top不缩放图片,只显示图片的顶部区域
        裁剪bottom不缩放图片,只显示图片的底部区域
        裁剪center不缩放图片,只显示图片的中间区域
        裁剪left不缩放图片,只显示图片的左边区域
        裁剪right不缩放图片,只显示图片的右边区域
        裁剪top left不缩放图片,只显示图片的左上边区域
        裁剪top right不缩放图片,只显示图片的右上边区域
        裁剪bottom left不缩放图片,只显示图片的左下边区域
        裁剪bottom right不缩放图片,只显示图片的右下边区域


        示例:

        <view class="page">  <view class="page__hd">    <text class="page__title">image</text>    <text class="page__desc">图片</text>  </view>  <view class="page__bd">    <view class="section section_gap" wx:for="{{array}}" wx:for-item="item">      <view class="section__title">{{item.text}}</view>      <view class="section__ctn">        <image style="width: 200px; height: 200px; background-color: #eeeeee;" mode="{{item.mode}}" src="{{src}}"></image>      </view>    </view>  </view></view>
        Page({  data: {    array: [{      mode: 'scaleToFill',      text: 'scaleToFill:不保持纵横比缩放图片,使图片完全适应'    }, {      mode: 'aspectFit',      text: 'aspectFit:保持纵横比缩放图片,使图片的长边能完全显示出来'    }, {      mode: 'aspectFill',      text: 'aspectFill:保持纵横比缩放图片,只保证图片的短边能完全显示出来'    }, {      mode: 'top',      text: 'top:不缩放图片,只显示图片的顶部区域'    }, {      mode: 'bottom',      text: 'bottom:不缩放图片,只显示图片的底部区域'    }, {      mode: 'center',      text: 'center:不缩放图片,只显示图片的中间区域'    }, {      mode: 'left',      text: 'left:不缩放图片,只显示图片的左边区域'    }, {      mode: 'right',      text: 'right:不缩放图片,只显示图片的右边边区域'    }, {      mode: 'top left',      text: 'top left:不缩放图片,只显示图片的左上边区域'    }, {      mode: 'top right',      text: 'top right:不缩放图片,只显示图片的右上边区域'    }, {      mode: 'bottom left',      text: 'bottom left:不缩放图片,只显示图片的左下边区域'    }, {      mode: 'bottom right',      text: 'bottom right:不缩放图片,只显示图片的右下边区域'    }],    src: '../../resources/cat.jpg'  },  imageError: function(e) {    console.log('image3发生error事件,携带值为', e.detail.errMsg)  }})

        原图

        image

        scaleToFill

        不保持纵横比缩放图片,使图片完全适应

        image

        aspectFit

        保持纵横比缩放图片,使图片的长边能完全显示出来

        image

        aspectFill

        保持纵横比缩放图片,只保证图片的短边能完全显示出来

        image

        top

        不缩放图片,只显示图片的顶部区域

        image

        bottom

        不缩放图片,只显示图片的底部区域

        image

        center

        不缩放图片,只显示图片的中间区域

        image

        left

        不缩放图片,只显示图片的左边区域

        image

        right

        不缩放图片,只显示图片的右边边区域

        image

        top left

        不缩放图片,只显示图片的左上边区域

        image

        top right

        不缩放图片,只显示图片的右上边区域

        image

        bottom left

        不缩放图片,只显示图片的左下边区域

        image

        bottom right

        不缩放图片,只显示图片的右下边区域

        image

        video

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

        视频(v2.4.0 起支持同层渲染)。相关api:wx.createVideoContext

        属性类型默认值必填说明最低版本
        srcstring要播放视频的资源地址,支持网络路径、本地临时路径、云文件ID(2.3.0)1.0.0
        durationnumber指定视频时长1.1.0
        controlsbooleantrue是否显示默认播放控件(播放/暂停按钮、播放进度、时间)1.0.0
        danmu-listArray.<object>弹幕列表1.0.0
        danmu-btnbooleanfalse是否显示弹幕按钮,只在初始化时有效,不能动态变更1.0.0
        enable-danmubooleanfalse是否展示弹幕,只在初始化时有效,不能动态变更1.0.0
        autoplaybooleanfalse是否自动播放1.0.0
        loopbooleanfalse是否循环播放1.4.0
        mutedbooleanfalse是否静音播放1.4.0
        initial-timenumber0指定视频初始播放位置1.6.0
        page-gesturebooleanfalse在非全屏模式下,是否开启亮度与音量调节手势(废弃,见 vslide-gesture)1.6.0
        directionnumber设置全屏时视频的方向,不指定则根据宽高比自动判断1.7.0
        show-progressbooleantrue若不设置,宽度大于240时才会显示1.9.0
        show-fullscreen-btnbooleantrue是否显示全屏按钮1.9.0
        show-play-btnbooleantrue是否显示视频底部控制栏的播放按钮1.9.0
        show-center-play-btnbooleantrue是否显示视频中间的播放按钮1.9.0
        enable-progress-gesturebooleantrue是否开启控制进度的手势1.9.0
        object-fitstringcontain当视频大小与 video 容器大小不一致时,视频的表现形式1.0.0
        posterstring视频封面的图片网络资源地址或云文件ID(2.3.0)。若 controls 属性值为 false 则设置 poster 无效1.0.0
        show-mute-btnbooleanfalse是否显示静音按钮2.4.0
        titlestring视频的标题,全屏时在顶部展示2.4.0
        play-btn-positionstringbottom播放按钮的位置2.4.0
        enable-play-gesturebooleanfalse是否开启播放手势,即双击切换播放/暂停2.4.0
        auto-pause-if-navigatebooleantrue当跳转到本小程序的其他页面时,是否自动暂停本页面的视频播放2.5.0
        auto-pause-if-open-nativebooleantrue当跳转到其它微信原生页面时,是否自动暂停本页面的视频2.5.0
        vslide-gesturebooleanfalse在非全屏模式下,是否开启亮度与音量调节手势(同 page-gesture)2.6.2
        vslide-gesture-in-fullscreenbooleantrue在全屏模式下,是否开启亮度与音量调节手势2.6.2
        ad-unit-idstring视频前贴广告单元ID,更多详情可参考开放能力视频前贴广告2.8.1
        poster-for-crawlerstring用于给搜索等场景作为视频封面展示,建议使用无播放 icon 的视频封面图,只支持网络地址
        show-casting-buttonbooleanfalse显示投屏按钮。只安卓且同层渲染下生效,支持 DLNA 协议2.10.2
        picture-in-picture-modestring/Array设置小窗模式: push, pop,空字符串或通过数组形式设置多种模式(如: ["push", "pop"])2.11.0
        picture-in-picture-show-progressbooleanfalse是否在小窗模式下显示播放进度2.11.0
        enable-auto-rotationbooleanfalse是否开启手机横屏时自动全屏,当系统设置开启自动旋转时生效2.11.0
        show-screen-lock-buttonbooleanfalse是否显示锁屏按钮,仅在全屏时显示,锁屏后控制栏的操作2.11.0
        bindplayeventhandle当开始/继续播放时触发play事件1.0.0
        bindpauseeventhandle当暂停播放时触发 pause 事件1.0.0
        bindendedeventhandle当播放到末尾时触发 ended 事件1.0.0
        bindtimeupdateeventhandle播放进度变化时触发,event.detail = {currentTime, duration} 。触发频率 250ms 一次1.0.0
        bindfullscreenchangeeventhandle视频进入和退出全屏时触发,event.detail = {fullScreen, direction},direction 有效值为 vertical 或 horizontal1.4.0
        bindwaitingeventhandle视频出现缓冲时触发1.7.0
        binderroreventhandle视频播放出错时触发1.7.0
        bindprogresseventhandle加载进度变化时触发,只支持一段加载。event.detail = {buffered},百分比2.4.0
        bindloadedmetadataeventhandle视频元数据加载完成时触发。event.detail = {width, height, duration}2.7.0
        bindcontrolstoggleeventhandle切换 controls 显示隐藏时触发。event.detail = {show}2.9.5
        bindenterpictureinpictureeventhandler播放器进入小窗2.11.0
        bindleavepictureinpictureeventhandler播放器退出小窗2.11.0
        bindseekcompleteeventhandlerseek 完成时触发2.12.0

        direction 的合法值

        说明最低版本
        0正常竖向
        90屏幕逆时针90度
        -90屏幕顺时针90度

        object-fit 的合法值

        说明最低版本
        contain包含
        fill填充
        cover覆盖

        play-btn-position 的合法值

        说明最低版本
        bottomcontrols bar上
        center视频中间

        picture-in-picture-mode 的合法值

        说明最低版本
        []取消小窗
        push路由 push 时触发小窗
        pop路由 pop 时触发小窗

        提示

        1. tip:`video 默认宽度 300px、高度 225px,可通过 wxss 设置宽高。
        2. tip:从 2.4.0 起 video 支持同层渲染。

        支持的格式

        格式iOSAndroid
        mp4
        movx
        m4vx
        3gp
        avix
        m3u8
        webmx

        支持的编码格式

        格式iOSAndroid
        H.264
        HEVC
        MPEG-4
        VP9x

        小窗特性说明

        video 小窗支持以下三种触发模式(在组件上设置 picture-in-picture-mode 属性):

        1. push 模式,即从当前页跳转至下一页时出现小窗(页面栈push)
        2. pop 模式,即离开当前页面时触发(页面栈pop)
        3. 以上两种路由行为均触发小窗

        此外,小窗还支持以下特性:

        • 小窗容器尺寸会根据原组件尺寸自动判断
        • 点击小窗,用户会被导航回小窗对应的播放器页面
        • 小窗出现后,用户可点击小窗右上角的关闭按钮或调用 context.exitPictureInPicture() 接口关闭小窗

        当播放器进入小窗模式后,播放器所在页面处于 hide 状态(触发 onHide 生命周期),该页面不会被销毁。当小窗被关闭时,播放器所在页面会被 unload (触发 onUnload 生命周期)。

        示例代码

        video标签认宽度300px、高度225px,设置宽高需要通过wxss设置width和height。

        示例代码: 

        <view class="section tc">  <video src="{{src}}"   controls ></video>  <view class="btn-area">    <button bindtap="bindButtonTap">获取视频</button>  </view></view><view class="section tc">  <video id="myVideo" src="http://wxsnsdy.tc.qq.com/105/20210/snsdyvideodownload?filekey=30280201010421301f0201690402534804102ca905ce620b1241b726bc41dcff44e00204012882540400&bizid=1023&hy=SH&fileparam=302c020101042530230204136ffd93020457e3c4ff02024ef202031e8d7f02030f42400204045a320a0201000400" rel="external nofollow"  danmu-list="{{danmuList}}" enable-danmu danmu-btn controls></video>  <view class="btn-area">    <button bindtap="bindButtonTap">获取视频</button>    <input bindblur="bindInputBlur"/>    <button bindtap="bindSendDanmu">发送弹幕</button>  </view></view>
        function getRandomColor () {  let rgb = []  for (let i = 0 ; i < 3; ++i){    let color = Math.floor(Math.random() * 256).toString(16)    color = color.length == 1 ? '0' + color : color    rgb.push(color)  }  return '#' + rgb.join('')}Page({  onReady: function (res) {    this.videoContext = wx.createVideoContext('myVideo')  },  inputValue: '',    data: {        src: '',    danmuList: [      {        text: '第 1s 出现的弹幕',        color: '#ff0000',        time: 1      },      {        text: '第 3s 出现的弹幕',        color: '#ff00ff',        time: 3    }]    },  bindInputBlur: function(e) {    this.inputValue = e.detail.value  },  bindButtonTap: function() {    var that = this    wx.chooseVideo({      sourceType: ['album', 'camera'],      maxDuration: 60,      camera: ['front','back'],      success: function(res) {        that.setData({          src: res.tempFilePath        })      }    })  },  bindSendDanmu: function () {    this.videoContext.sendDanmu({      text: this.inputValue,      color: getRandomColor()    })  }})

        video

        相关api:wx.createVideoContext

        Bug & Tip

        1. tip:video组件是由客户端创建的原生组件,它的层级是最高的。
        2. tip: 请勿在scroll-view中使用video组件。
        3. tip:css动画对video组件无效。


        camera


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

        系统相机。

        需要用户授权 scope.camera

        属性名类型默认值说明
        device-positionStringback前置或后置,值为front, back
        flashStringauto闪光灯,值为auto, on, off
        bindstopEventHandle摄像头在非正常终止时触发,如退出后台等情况
        binderrorEventHandle用户不允许使用摄像头时触发

        相关api:wx.createCameraContext

        Bug & Tip
        1. tip: camera 组件是由客户端创建的原生组件,它的层级是最高的,不能通过 z-index 控制层级。可使用 cover-view cover-image覆盖在上面。
        2. tip: 同一页面只能插入一个 camera 组件。
        3. tip: 请勿在 scroll-view、swiper、picker-view、movable-view 中使用 camera 组件。

        示例:

        <!-- camera.wxml --><camera device-position="back" flash="off" binderror="error" style="width: 100%; height: 300px;"></camera><button type="primary" bindtap="takePhoto">拍照</button><view>预览</view><image mode="widthFix" src="{{src}}"></image>
        // camera.jsPage({    takePhoto() {        const ctx = wx.createCameraContext()        ctx.takePhoto({            quality: 'high',            success: (res) => {                this.setData({                    src: res.tempImagePath                })            }        })    },    error(e) {        console.log(e.detail)    }})

        live-pusher

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

        实时音视频录制(v2.9.1 起支持同层渲染)。需要用户授权 scope.camera、scope.record。

        暂只针对国内主体如下类目的小程序开放,需要先通过类目审核,再在小程序管理后台,「开发」-「接口设置」中自助开通该组件权限。

        一级类目/主体类型二级类目小程序内容场景
        社交直播涉及娱乐性质,如明星直播、生活趣事直播、宠物直播等。选择该类目后首次提交代码审核,需经当地互联网主管机关审核确认,预计审核时长7天左右
        教育在线视频课程网课、在线培训、讲座等教育类直播
        医疗互联网医院,公立医疗机构,私立医疗机构问诊、大型健康讲座等直播
        金融银行、信托、公募基金、私募基金、证券/期货、证券、期货投资咨询、保险、征信业务、新三板信息服务平台、股票信息服务平台(港股/美股)、消费金融金融产品视频客服理赔、金融产品推广直播等
        汽车汽车预售服务汽车预售、推广直播
        政府主体帐号/政府相关工作推广直播、领导讲话直播等
        工具视频客服不涉及以上几类内容的一对一视频客服服务,如企业售后一对一视频服务等
        IT科技多方通信为多方提供电话会议/视频会议等服务

        相关api:wx.createLivePusherContext

        属性类型默认值必填说明最低版本
        urlstring推流地址。目前仅支持 rtmp 格式1.7.0
        modestringRTCSD(标清), HD(高清), FHD(超清), RTC(实时通话)1.7.0
        autopushbooleanfalse自动推流1.7.0
        mutedbooleanfalse是否静音。即将废弃,可用 enable-mic 替代1.7.0
        enable-camerabooleantrue开启摄像头1.7.0
        auto-focusbooleantrue自动聚集1.7.0
        orientationstringvertical画面方向1.7.0
        beautynumber0美颜,取值范围 0-9 ,0 表示关闭1.7.0
        whitenessnumber0美白,取值范围 0-9 ,0 表示关闭1.7.0
        aspectstring9:16宽高比,可选值有 3:49:161.7.0
        min-bitratenumber200最小码率1.7.0
        max-bitratenumber1000最大码率1.7.0
        audio-qualitystringhigh高音质(48KHz)或低音质(16KHz),值为highlow1.7.0
        waiting-imagestring进入后台时推流的等待画面1.7.0
        waiting-image-hashstring等待画面资源的MD5值1.7.0
        zoombooleanfalse调整焦距2.1.0
        device-positionstringfront前置或后置,值为frontback2.3.0
        background-mutebooleanfalse进入后台时是否静音(已废弃,默认退后台静音)1.7.0
        mirrorbooleanfalse设置推流画面是否镜像,产生的效果在 live-player 反应到2.7.0
        remote-mirrorbooleanfalse同 mirror 属性,后续 mirror 将废弃2.10.0
        local-mirrorstringauto控制本地预览画面是否镜像2.10.0
        audio-reverb-typenumber0音频混响类型2.10.0
        enable-micbooleantrue开启或关闭麦克风2.10.0
        enable-agcbooleanfalse是否开启音频自动增益2.10.0
        enable-ansbooleanfalse是否开启音频噪声抑制2.10.0
        audio-volume-typestringauto音量类型2.10.0
        video-widthnumber360上推的视频流的分辨率宽度2.10.0
        video-heightnumber640上推的视频流的分辨率高度2.10.0
        beauty-stylestringsmooth设置美颜类型2.12.0
        filterstringstandard设置色彩滤镜2.12.0
        bindstatechangeeventhandle状态变化事件,detail = {code}1.7.0
        bindnetstatuseventhandle网络状态通知,detail = {info}1.9.0
        binderroreventhandle渲染错误事件,detail = {errMsg, errCode}1.7.4
        bindbgmstarteventhandle背景音开始播放时触发2.4.0
        bindbgmprogresseventhandle背景音进度变化时触发,detail = {progress, duration}2.4.0
        bindbgmcompleteeventhandle背景音播放完成时触发2.4.0
        bindaudiovolumenotifyeventhandle返回麦克风采集的音量大小2.12.0

        orientation 的合法值

        说明最低版本
        vertical竖直
        horizontal水平

        local-mirror 的合法值

        说明最低版本
        auto前置摄像头镜像,后置摄像头不镜像
        enable前后置摄像头均镜像
        disable前后置摄像头均不镜像

        audio-reverb-type 的合法值

        说明最低版本
        0关闭
        1KTV
        2小房间
        3大会堂
        4低沉
        5洪亮
        6金属声
        7磁性

        audio-volume-type 的合法值

        说明最低版本
        auto自动
        media媒体音量
        voicecall通话音量

        beauty-style 的合法值

        说明最低版本
        smooth光滑美颜
        nature自然美颜

        filter 的合法值

        说明最低版本
        standard标准
        pink粉嫩
        nostalgia怀旧
        blues蓝调
        romantic浪漫
        cool清凉
        fresher清新
        solor日系
        aestheticism唯美
        whitening美白
        cerisered樱红

        注意:

        1. tip:开发者工具上暂不支持。
        2. tip:live-pusher 默认宽度为100%、无默认高度,请通过wxss设置宽高。
        3. tip:waiting-image 属性在 2.3.0 起完整支持网络路径、临时文件和包内路径。
        4. tip:请注意原生组件使用限制。
        5. tip: 相关介绍和原理可参考此文章

        错误码(errCode)

        代码说明
        10001用户禁止使用摄像头
        10002用户禁止使用录音
        10003背景音资源(BGM)加载失败
        10004等待画面资源(waiting-image)加载失败

        状态码(code)

        代码说明
        1001已经连接推流服务器
        1002已经与服务器握手完毕,开始推流
        1003打开摄像头成功
        1004录屏启动成功
        1005推流动态调整分辨率
        1006推流动态调整码率
        1007首帧画面采集完成
        1008编码器启动
        -1301打开摄像头失败
        -1302打开麦克风失败
        -1303视频编码失败
        -1304音频编码失败
        -1305不支持的视频分辨率
        -1306不支持的音频采样率
        -1307网络断连,且经多次重连抢救无效,更多重试请自行重启推流
        -1308开始录屏失败,可能是被用户拒绝
        -1309录屏失败,不支持的Android系统版本,需要5.0以上的系统
        -1310录屏被其他应用打断了
        -1311Android Mic打开成功,但是录不到音频数据
        -1312录屏动态切横竖屏失败
        1101网络状况不佳:上行带宽太小,上传数据受阻
        1102网络断连, 已启动自动重连
        1103硬编码启动失败,采用软编码
        1104视频编码失败
        1105新美颜软编码启动失败,采用老的软编码
        1106新美颜软编码启动失败,采用老的软编码
        3001RTMP -DNS解析失败
        3002RTMP服务器连接失败
        3003RTMP服务器握手失败
        3004RTMP服务器主动断开,请检查推流地址的合法性或防盗链有效期
        3005RTMP 读/写失败

        网络状态数据(info)

        键名说明
        videoBitrate当前视频编/码器输出的比特率,单位 kbps
        audioBitrate当前音频编/码器输出的比特率,单位 kbps
        videoFPS当前视频帧率
        videoGOP当前视频 GOP,也就是每两个关键帧(I帧)间隔时长,单位 s
        netSpeed当前的发送/接收速度
        netJitter网络抖动情况,抖动越大,网络越不稳定
        videoWidth视频画面的宽度
        videoHeight视频画面的高度


        live-player

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

        实时音视频播放(v2.9.1 起支持同层渲染)。

        暂只针对国内主体如下类目的小程序开放,需要先通过类目审核,再在小程序管理后台,「开发」-「接口设置」中自助开通该组件权限。

        一级类目/主体类型二级类目小程序内容场景
        社交直播涉及娱乐性质,如明星直播、生活趣事直播、宠物直播等。选择该类目后首次提交代码审核,需经当地互联网主管机关审核确认,预计审核时长 7 天左右
        教育在线视频课程网课、在线培训、讲座等教育类直播
        医疗互联网医院,公立医疗机构,私立医疗机构问诊、大型健康讲座等直播
        金融银行、信托、公募基金、私募基金、证券/期货、证券、期货投资咨询、保险、征信业务、新三板信息服务平台、股票信息服务平台(港股/美股)、消费金融金融产品视频客服理赔、金融产品推广直播等
        汽车汽车预售服务汽车预售、推广直播
        政府主体帐号/政府相关工作推广直播、领导讲话直播等
        工具视频客服不涉及以上几类内容的一对一视频客服服务,如企业售后一对一视频服务等
        IT科技多方通信为多方提供电话会议/视频会议等服务
        属性类型默认值必填说明最低版本
        srcstring音视频地址。目前仅支持 flvrtmp 格式1.7.0
        modestringlive模式1.7.0
        autoplaybooleanfalse自动播放1.7.0
        mutedbooleanfalse是否静音1.7.0
        orientationstringvertical画面方向1.7.0
        object-fitstringcontain填充模式,可选值有 containfillCrop1.7.0
        background-mutebooleanfalse进入后台时是否静音(已废弃,默认退后台静音)1.7.0
        min-cachenumber1最小缓冲区,单位s(RTC 模式推荐 0.2s)1.7.0
        max-cachenumber3最大缓冲区,单位s(RTC 模式推荐 0.8s)。缓冲区用来抵抗网络波动,缓冲数据越多,网络抗性越好,但时延越大。1.7.0
        sound-modestringspeaker声音输出方式1.9.90
        auto-pause-if-navigatebooleantrue当跳转到本小程序的其他页面时,是否自动暂停本页面的实时音视频播放2.5.0
        auto-pause-if-open-nativebooleantrue当跳转到其它微信原生页面时,是否自动暂停本页面的实时音视频播放2.5.0
        picture-in-picture-modestring/Array设置小窗模式: push, pop,空字符串或通过数组形式设置多种模式(如: ["push", "pop"])2.10.3
        bindstatechangeeventhandle播放状态变化事件,detail = {code}1.7.0
        bindfullscreenchangeeventhandle全屏变化事件,detail = {direction, fullScreen}1.7.0
        bindnetstatuseventhandle网络状态通知,detail = {info}1.9.0
        bindaudiovolumenotifyeventhandler播放音量大小通知,detail = {}2.10.0
        bindenterpictureinpictureeventhandler播放器进入小窗2.11.0
        bindleavepictureinpictureeventhandler播放器退出小窗2.11.0

        mode 的合法值

        说明最低版本
        live直播
        RTC实时通话,该模式时延更低

        orientation 的合法值

        说明最低版本
        vertical竖直
        horizontal水平

        object-fit 的合法值

        说明最低版本
        contain图像长边填满屏幕,短边区域会被填充⿊⾊
        fillCrop图像铺满屏幕,超出显示区域的部分将被截掉

        sound-mode 的合法值

        说明最低版本
        speaker扬声器
        ear听筒

        picture-in-picture-mode 的合法值

        说明最低版本
        []取消小窗
        push路由 push 时触发小窗
        pop路由 pop 时触发小窗

        状态码

        代码说明
        2001已经连接服务器
        2002已经连接 RTMP 服务器,开始拉流
        2003网络接收到首个视频数据包(IDR)
        2004视频播放开始
        2005视频播放进度
        2006视频播放结束
        2007视频播放Loading
        2008解码器启动
        2009视频分辨率改变
        -2301网络断连,且经多次重连抢救无效,更多重试请自行重启播放
        -2302获取加速拉流地址失败
        2101当前视频帧解码失败
        2102当前音频帧解码失败
        2103网络断连, 已启动自动重连
        2104网络来包不稳:可能是下行带宽不足,或由于主播端出流不均匀
        2105当前视频播放出现卡顿
        2106硬解启动失败,采用软解
        2107当前视频帧不连续,可能丢帧
        2108当前流硬解第一个I帧失败,SDK自动切软解
        3001RTMP -DNS解析失败
        3002RTMP服务器连接失败
        3003RTMP服务器握手失败
        3005RTMP 读/写失败,之后会发起网络重试

        网络状态数据

        键名说明
        videoBitrate当前视频编/码器输出的比特率,单位 kbps
        audioBitrate当前音频编/码器输出的比特率,单位 kbps
        videoFPS当前视频帧率
        videoGOP当前视频 GOP,也就是每两个关键帧(I帧)间隔时长,单位 s
        netSpeed当前的发送/接收速度
        netJitter网络抖动情况,为 0 时表示没有任何抖动,值越大表明网络抖动越大,网络越不稳定
        videoWidth视频画面的宽度
        videoHeight视频画面的高度

        小窗特性说明

        live-player 小窗支持以下三种触发模式(在组件上设置 picture-in-picture-mode 属性):

        1. push 模式,即从当前页跳转至下一页时出现小窗(页面栈push)
        2. pop 模式,即离开当前页面时触发(页面栈pop)
        3. 以上两种路由行为均触发小窗

        此外,小窗还支持以下特性:

        • 小窗容器尺寸会根据原组件尺寸自动判断
        • 点击小窗,用户会被导航回小窗对应的播放器页面
        • 小窗出现后,用户可点击小窗右上角的关闭按钮或调用 context.exitPictureInPicture() 接口关闭小窗

        当播放器进入小窗模式后,播放器所在页面处于 hide 状态(触发 onHide 生命周期),该页面不会被销毁。当小窗被关闭时,播放器所在页面会被 unload (触发 onUnload 生命周期)。

        提示:

        1. live-player 默认宽度300px、高度225px,可通过wxss设置宽高。
        2. 开发者工具上暂不支持。

        示例代码

        <live-player src="https://domain/pull_stream" rel="external nofollow"  mode="RTC" autoplay bindstatechange="statechange" binderror="error" style="width: 300px; height: 225px;" />
        Page({  statechange(e) {    console.log('live-player code:', e.detail.code)  },  error(e) {    console.error('live-player error:', e.detail.errMsg)  }})


        voip-room

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

        多人音视频对话。需用户授权 scope.camera、scope.record。相关接口: wx.joinVoIPChat

        暂只针对国内主体如下类目的小程序开放,需要先通过类目审核,再在小程序管理后台,「开发」-「接口设置」中自助开通该组件权限。

        一级类目/主体类型二级类目小程序内容场景
        教育在线视频课程网课、在线培训、讲座等教育类直播
        医疗互联网医院,公立医院问诊、大型健康讲座等直播
        医疗私立医疗机构/
        金融银行、信托、基金、证券/期货、证券、期货投资咨询、保险、征信业务、新三板信息服务平台、股票信息服务平台(港股/美股)、消费金融金融产品视频客服理赔、金融产品推广直播等
        汽车汽车预售服务汽车预售、推广直播
        政府主体帐号/政府相关工作推广直播、领导讲话直播等
        IT 科技多方通信在线会议
        IT 科技硬件设备智能硬件

        开通该组件权限后,开发者可在 joinVoIPChat 成功后,获取房间成员的 openid,传递给 voip-room 组件,以显示成员画面。

        属性类型默认值必填说明最低版本
        openidstring进入房间用户的 openid2.11.0
        modestringcamera对话窗口类型,自身传入 camera,其它用户传入 video2.11.0
        device-positionstringfront仅在 mode 为 camera 时有效,前置或后置,值为frontback2.11.0
        binderroreventhandle创建对话窗口失败时触发2.11.0

        Bug & Tip

        1. tip:开发者工具上暂不支持
        2. tip:请注意原生组件使用限制

        示例代码

        <block wx:for="{{openIdList}}" wx:key="*this">  <voip-room    openid="{{item}}"    mode="{{selfOpenId === item ? 'camera' : 'video'}}">  </voip-room></block>


        基础库 1.0.0 开始支持,低版本需做兼容处理。

        地图(v2.7.0 起支持同层渲染)。相关api wx.createMapContext

        个性化地图能力可在小程序后台“开发-开发者工具-腾讯位置服务”申请开通。 小程序内地图组件应使用同一 subkey,可通过 layer-style(地图官网设置的样式 style 编号)属性选择不同的底图风格。 组件属性的长度单位默认为px,2.4.0起支持传入单位(rpx/px)。

        示例小程序

        属性类型默认值必填说明最低版本
        longitudenumber中心经度1.0.0
        latitudenumber中心纬度1.0.0
        scalenumber16缩放级别,取值范围为3-201.0.0
        markersArray.<marker>标记点1.0.0
        coversArray.<cover>即将移除,请使用 markers1.0.0
        polylineArray.<polyline>路线1.0.0
        circlesArray.<circle>1.0.0
        controlsArray.<control>控件(即将废弃,建议使用 cover-view 代替)1.0.0
        include-pointsArray.<point>缩放视野以包含所有给定的坐标点1.0.0
        show-locationbooleanfalse显示带有方向的当前定位点1.0.0
        polygonsArray.<polygon>多边形2.3.0
        subkeystring个性化地图使用的key2.3.0
        layer-stylenumber1个性化地图配置的 style,不支持动态修改
        rotatenumber0旋转角度,范围 0 ~ 360, 地图正北和设备 y 轴角度的夹角2.5.0
        skewnumber0倾斜角度,范围 0 ~ 40 , 关于 z 轴的倾角2.5.0
        enable-3Dbooleanfalse展示3D楼块(工具暂不支持)2.3.0
        show-compassbooleanfalse显示指南针2.3.0
        show-scalebooleanfalse显示比例尺,工具暂不支持2.8.0
        enable-overlookingbooleanfalse开启俯视2.3.0
        enable-zoombooleantrue是否支持缩放2.3.0
        enable-scrollbooleantrue是否支持拖动2.3.0
        enable-rotatebooleanfalse是否支持旋转2.3.0
        enable-satellitebooleanfalse是否开启卫星图2.7.0
        enable-trafficbooleanfalse是否开启实时路况2.7.0
        settingobject配置项2.8.2
        bindtapeventhandle点击地图时触发,2.9.0起返回经纬度信息1.0.0
        bindmarkertapeventhandle点击标记点时触发,e.detail = {markerId}1.0.0
        bindlabeltapeventhandle点击label时触发,e.detail = {markerId}2.9.0
        bindcontroltapeventhandle点击控件时触发,e.detail = {controlId}1.0.0
        bindcallouttapeventhandle点击标记点对应的气泡时触发e.detail = {markerId}1.2.0
        bindupdatedeventhandle在地图渲染更新完成时触发1.6.0
        bindregionchangeeventhandle视野发生变化时触发,2.3.0
        bindpoitapeventhandle点击地图poi点时触发,e.detail = {name, longitude, latitude}2.3.0

        regionchange 返回值

        视野改变时,regionchange 会触发两次,返回的 type 值分别为 begin / end。

        2.8.0起 begin 阶段返回 causedBy,有效值为 gesture(手势触发) & update(接口触发)

        2.3.0起 end 阶段返回 causedBy,有效值为 drag(拖动导致)、scale(缩放导致)、update(调用更新接口导致) rotate、skew仅在 end 阶段返回

        e = {  causedBy,  type,  detail: {    rotate,    skew  }}

        setting

        提供 setting 对象统一设置地图配置。同时对于一些动画属性如 rotate 和 skew,通过 setData 分开设置时无法同时生效,需通过 settting 统一修改。

        // 默认值const setting = {  skew: 0,  rotate: 0,  showLocation: false,  showScale: false,  subKey: '',  layerStyle: -1,  enableZoom: true,  enableScroll: true,  enableRotate: false,  showCompass: false,  enable3D: false,  enableOverlooking: false,  enableSatellite: false,  enableTraffic: false,}this.setData({  // 仅设置的属性会生效,其它的不受影响  setting: {    enable3D: true,    enableTraffic: true  }})

        marker

        标记点用于在地图上显示标记的位置

        属性说明类型必填备注最低版本
        id标记点 idnumbermarker 点击事件回调会返回此 id。建议为每个 marker 设置上 number 类型 id,保证更新 marker 时有更好的性能。
        latitude纬度number浮点数,范围 -90 ~ 90
        longitude经度number浮点数,范围 -180 ~ 180
        title标注点名string点击时显示,callout存在时将被忽略
        zIndex显示层级number2.3.0
        iconPath显示的图标string项目目录下的图片路径,支持网络路径、本地路径、代码包路径(2.3.0)
        rotate旋转角度number顺时针旋转的角度,范围 0 ~ 360,默认为 0
        alpha标注的透明度number默认 1,无透明,范围 0 ~ 1
        width标注图标宽度number/string默认为图片实际宽度
        height标注图标高度number/string默认为图片实际高度
        callout自定义标记点上方的气泡窗口Object支持的属性见下表,可识别换行符。1.2.0
        label为标记点旁边增加标签Object支持的属性见下表,可识别换行符。1.2.0
        anchor经纬度在标注图标的锚点,默认底边中点Object{x, y},x 表示横向(0-1),y 表示竖向(0-1)。{x: .5, y: 1} 表示底边中点1.2.0
        aria-label无障碍访问,(属性)元素的额外描述string2.5.0

        marker 上的气泡 callout

        属性说明类型最低版本
        content文本string1.2.0
        color文本颜色string1.2.0
        fontSize文字大小number1.2.0
        borderRadius边框圆角number1.2.0
        borderWidth边框宽度number2.3.0
        borderColor边框颜色string2.3.0
        bgColor背景色string1.2.0
        padding文本边缘留白number1.2.0
        display'BYCLICK':点击显示; 'ALWAYS':常显string1.2.0
        textAlign文本对齐方式。有效值: left, right, centerstring1.6.0
        anchorX横向偏移量,向右为正数number2.11.0
        anchorY纵向偏移量,向下为正数number2.11.0

        marker 上的气泡 label

        属性说明类型最低版本
        content文本string1.2.0
        color文本颜色string1.2.0
        fontSize文字大小number1.2.0
        xlabel的坐标(废弃)number1.2.0
        ylabel的坐标(废弃)number1.2.0
        anchorXlabel的坐标,原点是 marker 对应的经纬度number2.1.0
        anchorYlabel的坐标,原点是 marker 对应的经纬度number2.1.0
        borderWidth边框宽度number1.6.0
        borderColor边框颜色string1.6.0
        borderRadius边框圆角number1.6.0
        bgColor背景色string1.6.0
        padding文本边缘留白number1.6.0
        textAlign文本对齐方式。有效值: left, right, centerstring1.6.0

        polyline

        指定一系列坐标点,从数组第一项连线至最后一项

        属性说明类型必填备注最低版本
        points经纬度数组array[{latitude: 0, longitude: 0}]
        color线的颜色string十六进制
        width线的宽度number
        dottedLine是否虚线boolean默认 false
        arrowLine带箭头的线boolean默认 false,开发者工具暂不支持该属性1.2.0
        arrowIconPath更换箭头图标string在 arrowLine 为 true 时生效1.6.0
        borderColor线的边框颜色string1.2.0
        borderWidth线的厚度number1.2.0

        polygon

        指定一系列坐标点,根据 points 坐标数据生成闭合多边形

        属性说明类型必填备注最低版本
        points经纬度数组array[{latitude: 0, longitude: 0}]2.3.0
        strokeWidth描边的宽度number2.3.0
        strokeColor描边的颜色string十六进制2.3.0
        fillColor填充颜色string十六进制
        zIndex设置多边形Z轴数值number2.3.0

        circle

        在地图上显示圆

        属性说明类型必填备注
        latitude纬度number浮点数,范围 -90 ~ 90
        longitude经度number浮点数,范围 -180 ~ 180
        color描边的颜色string十六进制
        fillColor填充颜色string十六进制
        radius半径number
        strokeWidth描边的宽度number

        control

        在地图上显示控件,控件不随着地图移动。即将废弃,请使用 cover-view

        属性说明类型必填备注
        id控件idnumber在控件点击事件回调会返回此id
        position控件在地图的位置object控件相对地图位置
        iconPath显示的图标string项目目录下的图片路径,支持本地路径、代码包路径
        clickable是否可点击boolean默认不可点击

        position

        属性说明类型必填备注
        left距离地图的左边界多远number默认为0
        top距离地图的上边界多远number默认为0
        width控件宽度number默认为图片宽度
        height控件高度number默认为图片高度

        bindregionchange 返回值

        属性说明类型备注
        type视野变化开始、结束时触发string视野变化开始为begin,结束为end
        causedBy导致视野变化的原因string拖动地图导致(drag)、缩放导致(scale)、调用接口导致(update)

        Bug & Tip

        1. tip:个性化地图暂不支持工具中调试。请先使用微信客户端进行测试。
        2. tip:地图中的颜色值color/borderColor/bgColor等需使用6位(8位)十六进制表示,8位时后两位表示alpha值,如:#000000AA
        3. tip:地图组件的经纬度必填, 如果不填经纬度则默认值是北京的经纬度。
        4. tip: map 组件使用的经纬度是火星坐标系,调用 wx.getLocation 接口需要指定 type 为 gcj02
        5. tip:从 2.8.0 起 map 支持同层渲染,更多请参考原生组件使用限制
        6. tip:请注意原生组件使用限制

        比例尺

        scale34567891011
        比例1000km500km200km100km50km50km20km10km5km
        scale121314151617181920
        比例2km1km500m200m100m50m50m20m10m

        示例代码

        在开发者工具中预览效果

        <!-- map.wxml --><map id="map" longitude="113.324520" latitude="23.099994" scale="14" controls="{{controls}}" bindcontroltap="controltap" markers="{{markers}}" bindmarkertap="markertap" polyline="{{polyline}}" bindregionchange="regionchange" show-location style="width: 100%; height: 300px;"></map>
        // map.jsPage({  data: {    markers: [{      iconPath: "/resources/others.png",      id: 0,      latitude: 23.099994,      longitude: 113.324520,      width: 50,      height: 50    }],    polyline: [{      points: [{        longitude: 113.3245211,        latitude: 23.10229      }, {        longitude: 113.324520,        latitude: 23.21229      }],      color:"#FF0000DD",      width: 2,      dottedLine: true    }],    controls: [{      id: 1,      iconPath: '/resources/location.png',      position: {        left: 0,        top: 300 - 50,        width: 50,        height: 50      },      clickable: true    }]  },  regionchange(e) {    console.log(e.type)  },  markertap(e) {    console.log(e.detail.markerId)  },  controltap(e) {    console.log(e.detail.controlId)  }})


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

        画布。2.9.0 起支持一套新 Canvas 2D 接口(需指定 type 属性),同时支持同层渲染,原有接口不再维护。相关api:获取 canvas 实例

        属性类型默认值必填说明最低版本
        typestring指定 canvas 类型,支持 2d (2.9.0) 和 webgl (2.7.0)2.7.0
        canvas-idstringcanvas 组件的唯一标识符,若指定了 type 则无需再指定该属性1.0.0
        disable-scrollbooleanfalse当在 canvas 中移动时且有绑定手势事件时,禁止屏幕滚动以及下拉刷新1.0.0
        bindtouchstarteventhandle手指触摸动作开始1.0.0
        bindtouchmoveeventhandle手指触摸后移动1.0.0
        bindtouchendeventhandle手指触摸动作结束1.0.0
        bindtouchcanceleventhandle手指触摸动作被打断,如来电提醒,弹窗1.0.0
        bindlongtapeventhandle手指长按 500ms 之后触发,触发了长按事件后进行移动不会触发屏幕的滚动1.0.0
        binderroreventhandle当发生错误时触发 error 事件,detail = {errMsg}1.0.0

        Bug & Tip

        1. tip:canvas 标签默认宽度300px、高度150px
        2. tip:同一页面中的 canvas-id 不可重复,如果使用一个已经出现过的 canvas-id,该 canvas 标签对应的画布将被隐藏并不再正常工作
        3. tip:请注意原生组件使用限制
        4. tip:开发者工具中默认关闭了 GPU 硬件加速,可在开发者工具的设置中开启“硬件加速”提高 WebGL 的渲染性能
        5. tip: WebGL 支持通过 getContext('webgl', { alpha: true }) 获取透明背景的画布
        6. tip: Canvas 2D(新接口)需要显式设置画布宽高 (默认为 300x150)
        7. bug: 避免设置过大的宽高,在安卓下会有crash的问题

        Canvas 2D 示例代码

        在开发者工具中预览效果

          <!-- canvas.wxml -->  <canvas type="2d" id="myCanvas"></canvas>
        // canvas.jsPage({  onReady() {    const query = wx.createSelectorQuery()    query.select('#myCanvas')      .fields({ node: true, size: true })      .exec((res) => {        const canvas = res[0].node        const ctx = canvas.getContext('2d')        const dpr = wx.getSystemInfoSync().pixelRatio        canvas.width = res[0].width * dpr        canvas.height = res[0].height * dpr        ctx.scale(dpr, dpr)        ctx.fillRect(0, 0, 100, 100)      })  }})

        WebGL 示例代码

        在开发者工具中预览效果

          <!-- canvas.wxml -->  <canvas type="webgl" id="myCanvas"></canvas>
        // canvas.jsPage({  onReady() {    const query = wx.createSelectorQuery()    query.select('#myCanvas').node().exec((res) => {      const canvas = res[0].node      const gl = canvas.getContext('webgl')      gl.clearColor(1, 0, 1, 1)      gl.clear(gl.COLOR_BUFFER_BIT)    })  }})

        示例代码(旧的接口)

        在开发者工具中预览效果 下载

        <!-- canvas.wxml --><canvas style="width: 300px; height: 200px;" canvas-id="firstCanvas"></canvas><!-- 当使用绝对定位时,文档流后边的 canvas 的显示层级高于前边的 canvas --><canvas style="width: 400px; height: 500px;" canvas-id="secondCanvas"></canvas><!-- 因为 canvas-id 与前一个 canvas 重复,该 canvas 不会显示,并会发送一个错误事件到 AppService --><canvas style="width: 400px; height: 500px;" canvas-id="secondCanvas" binderror="canvasIdErrorCallback"></canvas>
        Page({  canvasIdErrorCallback: function (e) {    console.error(e.detail.errMsg)  },  onReady: function (e) {    // 使用 wx.createContext 获取绘图上下文 context    var context = wx.createCanvasContext('firstCanvas')    context.setStrokeStyle("#00ff00")    context.setLineWidth(5)    context.rect(0, 0, 200, 200)    context.stroke()    context.setStrokeStyle("#ff0000")    context.setLineWidth(2)    context.moveTo(160, 100)    context.arc(100, 100, 60, 0, 2 * Math.PI, true)    context.moveTo(140, 100)    context.arc(100, 100, 40, 0, Math.PI, false)    context.moveTo(85, 80)    context.arc(80, 80, 5, 0, 2 * Math.PI, true)    context.moveTo(125, 80)    context.arc(120, 80, 5, 0, 2 * Math.PI, true)    context.stroke()    context.draw()  }})




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

        用于展示微信开放的数据。

        属性类型默认值必填说明最低版本
        typestring开放数据类型1.4.0
        open-gidstring当 type="groupName" 时生效, 群 id1.4.0
        langstringen当 type="user*" 时生效,以哪种语言展示 userInfo1.4.0
        default-textstring数据为空时的默认文案2.8.1
        default-avatarstring用户头像为空时的默认图片,支持相对路径和网络图片路径2.8.1
        binderroreventhandle群名称或用户信息为空时触发2.8.1

        type 的合法值

        说明最低版本
        groupName拉取群名称1.4.0
        userNickName用户昵称1.9.90
        userAvatarUrl用户头像1.9.90
        userGender用户性别1.9.90
        userCity用户所在城市1.9.90
        userProvince用户所在省份1.9.90
        userCountry用户所在国家1.9.90
        userLanguage用户的语言1.9.90

        lang 的合法值

        说明最低版本
        en英文
        zh_CN简体中文
        zh_TW繁体中文

        Bug & Tip

        1. tip:只有当前用户在此群内才能拉取到群名称
        2. tip:关于 open-gid 的获取请使用 wx.getShareInfo

        示例代码

        <open-data type="groupName" open-gid="xxxxxx"></open-data><open-data type="userAvatarUrl"></open-data><open-data type="userGender" lang="zh_CN"></open-data>


        web-view

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

        web-view 组件是一个可以用来承载网页的容器,会自动铺满整个小程序页面。个人类型与海外类型的小程序暂不支持使用。

        属性名类型默认值说明
        srcStringnonewebview 指向网页的链接。需登录小程序管理后台配置域名白名单。

        示例代码:

        <!-- wxml --><!-- 指向微信公众平台首页的web-view --><web-view src="https://mp.weixin.qq.com/" rel="external nofollow" ></web-view>

        相关接口 1

        <web-view/>网页中可使用JSSDK 1.3.0提供的接口返回小程序页面。 支持的接口有:

        接口名说明最低版本
        wx.miniProgram.navigateTo参数与小程序接口一致1.6.4
        wx.miniProgram.navigateBack参数与小程序接口一致1.6.4
        wx.miniProgram.switchTab参数与小程序接口一致1.6.5
        wx.miniProgram.reLaunch参数与小程序接口一致1.6.5
        wx.miniProgram.redirectTo参数与小程序接口一致1.6.5

        示例代码:

        <!-- html --><script type="text/javascript" src="https://res.wx.qq.com/open/js/jweixin-1.3.0.js" rel="external nofollow" ></script>// javascriptwx.miniProgram.navigateTo({url: '/path/to/page'})

        相关接口 2

        <web-view/>网页中仅支持以下JSSDK接口:

        接口模块接口说明具体接口
        判断客户端是否支持jscheckJSApi
        图像接口拍照或上传chooseImage
        预览图片previewImage
        上传图片uploadImage
        下载图片downloadImage
        获取本地图片getLocalImgData
        音频接口开始录音startRecord
        停止录音stopRecord
        监听录音自动停止onVoiceRecordEnd
        播放语音playVoice
        暂停播放pauseVoice
        停止播放stopVoice
        监听语音播放完毕onVoicePlayEnd
        上传接口uploadVoice
        下载接口downloadVoice
        智能接口识别音频translateVoice
        设备信息获取网络状态getNetworkType
        地理位置使用内置地图getLocation
        获取地理位置openLocation
        摇一摇周边开启ibeaconstartSearchBeacons
        关闭ibeaconstopSearchBeacons
        监听ibeacononSearchBeacons
        微信扫一扫调起微信扫一扫scanQRCode
        微信卡券拉取使用卡券列表chooseCard
        批量添加卡券接口addCard
        查看微信卡包的卡券openCard
        长按识别小程序圆形码
        相关接口 3

        用户分享时可获取当前<web-view/>的URL,即在onShareAppMessage回调中返回webViewUrl参数。

        示例代码:

        Page({  onShareAppMessage(options) {    console.log(options.webViewUrl)  }})
        相关接口 4

        在网页内可通过window.__wxjs_environment变量判断是否在小程序环境。

        示例代码:

        // web-view下的页面内wx.ready(function() {    console.log(window.__wxjs_environment === 'miniprogram') // true})

        Bug & Tip

        1. 网页内iframe的域名也需要配置到域名白名单。
        2. 开发者工具上,可以在 <web-view/> 组件上通过右键 - 调试,打开 <web-view/> 组件的调试。
        3. 每个页面只能有一个<web-view/>,<web-view/>会自动铺满整个页面,并覆盖其他组件。
        4. <web-view/>网页与小程序之间不支持除JSSDK提供的接口之外的通信。
        5. 在iOS中,若存在JSSDK接口调用无响应的情况,可在<web-view/>的src后面加个#wechat_redirect解决。

        ad

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

        Banner 广告。

        属性类型默认值必填说明最低版本
        unit-idstring广告单元id,可在小程序管理后台的流量主模块新建1.9.94
        ad-intervalsnumber广告自动刷新的间隔时间,单位为秒,参数值必须大于等于30(该参数不传入时 Banner 广告不会自动刷新)2.3.1
        bindloadeventhandle广告加载成功的回调2.2.1
        binderroreventhandle广告加载失败的回调,event.detail = {errCode: 1002}2.2.1
        bindcloseeventhandle广告关闭的回调2.6.5

        错误码信息与解决方案表

        错误码是通过binderror回调获取到的错误信息。

        代码异常情况理由解决方案
        1000后端错误调用失败该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
        1001参数错误使用方法错误可以前往developers.weixin.qq.com确认具体教程(小程序和小游戏分别有各自的教程,可以在顶部选项中,“设计”一栏的右侧进行切换。
        1002广告单元无效可能是拼写错误、或者误用了其他APP的广告ID请重新前往mp.weixin.qq.com确认广告位ID。
        1003内部错误该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
        1004无适合的广告广告不是每一次都会出现,这次没有出现可能是由于该用户不适合浏览广告属于正常情况,且开发者需要针对这种情况做形态上的兼容。
        1005广告组件审核中你的广告正在被审核,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
        1006广告组件被驳回你的广告审核失败,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
        1007广告组件被驳回你的广告能力已经被封禁,封禁期间无法展现广告请前往mp.weixin.qq.com确认小程序广告封禁状态。
        1008广告单元已关闭该广告位的广告能力已经被关闭请前往mp.weixin.qq.com重新打开对应广告位的展现。

        提示:

        1. 在无广告展示时,ad 标签不会占用高度
        2. ad 组件不支持触发 bindtap 等触摸相关事件
        3. 目前可以给 ad 标签设置 wxss 样式调整广告宽度,以使广告与页面更融洽,但请遵循小程序流量主应用规范
        4. 监听到error回调后,开发者可以针对性的处理,比如隐藏广告组件的父容器,以保证用户体验,但不要移除广告组件,否则将无法收到bindload的回调。


        official-account

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

        公众号关注组件。当用户扫小程序码打开小程序时,开发者可在小程序内配置公众号关注组件,方便用户快捷关注公众号,可嵌套在原生组件内。

        Tips

        1. 使用组件前,需前往小程序后台,在“设置”->“关注公众号”中设置要展示的公众号。注:设置的公众号需与小程序主体一致。
        2. 在一个小程序的生命周期内,只有从以下场景进入小程序,才具有展示引导关注公众号组件的能力:当小程序从扫小程序码场景(场景值1047,场景值1124)打开时当小程序从聊天顶部场景(场景值1089)中的「最近使用」内打开时,若小程序之前未被销毁,则该组件保持上一次打开小程序时的状态当从其他小程序返回小程序(场景值1038)时,若小程序之前未被销毁,则该组件保持上一次打开小程序时的状态
        3. 为便于开发者调试,基础库 2.7.3 版本起开发版小程序增加以下场景展示公众号组件:开发版小程序从扫二维码(场景值 1011)打开 — 体验版小程序打开
        4. 组件限定最小宽度为300px,高度为定值84px。
        5. 每个页面只能配置一个该组件。
        属性名类型说明
        bindloadEventHandle组件加载成功时触发
        binderrorEventHandle组件加载失败时触发

        detail 对象

        属性名类型说明
        statusNumber状态码
        errMsgString错误信息
        status 有效值
        说明
        -2网络错误
        -1数据解析错误
        0加载成功
        1小程序关注公众号功能被封禁
        2关联公众号被封禁
        3关联关系解除或未选中关联公众号
        4未开启关注公众号功能
        5场景值错误
        6重复创建

        示例代码

        <official-account></official-account>


        ad-custom

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

        原生模板 广告。

        属性类型默认值必填说明最低版本
        unit-idstring广告单元id,可在小程序管理后台的流量主模块新建2.10.4
        ad-intervalsnumber广告自动刷新的间隔时间,单位为秒,参数值必须大于等于30(该参数不传入时 模板 广告不会自动刷新)2.10.4
        bindloadeventhandle广告加载成功的回调2.10.4
        binderroreventhandle广告加载失败的回调,event.detail = {errCode: 1002}2.10.4

        错误码信息与解决方案表

        错误码是通过binderror回调获取到的错误信息。

        代码异常情况理由解决方案
        1000后端错误调用失败该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
        1001参数错误使用方法错误可以前往developers.weixin.qq.com确认具体教程(小程序和小游戏分别有各自的教程,可以在顶部选项中,“设计”一栏的右侧进行切换。
        1002广告单元无效可能是拼写错误、或者误用了其他APP的广告ID请重新前往mp.weixin.qq.com确认广告位ID。
        1003内部错误该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
        1004无适合的广告广告不是每一次都会出现,这次没有出现可能是由于该用户不适合浏览广告属于正常情况,且开发者需要针对这种情况做形态上的兼容。
        1005广告组件审核中你的广告正在被审核,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
        1006广告组件被驳回你的广告审核失败,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
        1007广告组件被驳回你的广告能力已经被封禁,封禁期间无法展现广告请前往mp.weixin.qq.com确认小程序广告封禁状态。
        1008广告单元已关闭该广告位的广告能力已经被关闭请前往mp.weixin.qq.com重新打开对应广告位的展现。

        Bug & Tip

        1. tip:在无广告展示时,ad-custom 标签不会占用高度
        2. tip:ad-custom 组件不支持触发 bindtap 等触摸相关事件
        3. tip:目前可以给 ad-custom 标签设置 wxss 样式调整广告宽度,以使广告与页面更融洽,但请遵循小程序流量主应用规范
        4. tip:监听到error回调后,开发者可以针对性的处理,比如隐藏广告组件的父容器,以保证用户体验,但不要移除广告组件,否则将无法收到bindload的回调
        5. tip:不同模板涉及一些不同的使用场景,具体方式请参考模板编辑器


        contact-button


        客服会话按钮,用于在页面上显示一个客服会话按钮,用户点击该按钮后会进入客服会话。

        属性名类型默认值说明
        sizeNumber18会话按钮大小,有效值 18-27,单位:px
        typeStringdefault-dark会话按钮的样式类型
        session-fromString 用户从该按钮进入会话时,开发者将收到带上本参数的事件推送。本参数可用于区分用户进入客服会话的来源。

        type 有效值:

        说明
        default-dark 
        default-light 

        示例代码

        <contact-button   type="default-light"   size="20"  session-from="weapp"></contact-button>

        相关api:详见客服消息接口文档

        相关组件:button 组件通过设置 open-type="contact" 亦可进入客服会话

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

        页面属性配置节点,用于指定页面的一些属性、监听页面事件。只能是页面内的第一个节点。可以配合 navigation-bar 组件一同使用。

        通过这个节点可以获得类似于调用 wx.setBackgroundTextStyle wx.setBackgroundColor 等接口调用的效果。

        属性类型默认值必填说明最低版本
        background-text-stylestring下拉背景字体、loading 图的样式,仅支持 dark 和 light2.9.0
        background-colorstring窗口的背景色,必须为十六进制颜色值2.9.0
        background-color-topstring顶部窗口的背景色,必须为十六进制颜色值,仅 iOS 支持2.9.0
        background-color-bottomstring底部窗口的背景色,必须为十六进制颜色值,仅 iOS 支持2.9.0
        scroll-topstring""滚动位置,可以使用 px 或者 rpx 为单位,在被设置时,页面会滚动到对应位置2.9.0
        scroll-durationnumber300滚动动画时长2.9.0
        page-stylestring""页面根节点样式,页面根节点是所有页面节点的祖先节点,相当于 HTML 中的 body 节点2.9.0
        body-font-sizestring""页面 page 的字体大小,可以设置为 system ,表示使用当前用户设置的微信字体大小2.11.0
        root-font-sizestring""页面的根字体大小,页面中的所有 rem 单位,将使用这个字体大小作为参考值,即 1rem 等于这个字体大小;自小程序版本 2.11.0 起,也可以设置为 system2.9.0
        bindresizeeventhandle页面尺寸变化时会触发 resize 事件, event.detail = { size: { windowWidth, windowHeight } }2.9.0
        bindscrolleventhandle页面滚动时会触发 scroll 事件, event.detail = { scrollTop }2.9.0
        bindscrolldoneeventhandle如果通过改变 scroll-top 属性来使页面滚动,页面滚动结束后会触发 scrolldone 事件2.9.0

        示例代码

        <page-meta  background-text-style="{{bgTextStyle}}"  background-color="{{bgColor}}"  background-color-top="{{bgColorTop}}"  background-color-bottom="{{bgColorBottom}}"  scroll-top="{{scrollTop}}"  page-style="color: green"  root-font-size="16px">  <navigation-bar    title="{{nbTitle}}"    loading="{{nbLoading}}"    front-color="{{nbFrontColor}}"    background-color="{{nbBackgroundColor}}"  /></page-meta>
        Page({  data: {    bgTextStyle: 'dark',    scrollTop: '200rpx',    bgColor: '#ff0000',    bgColorTop: '#00ff00',    bgColorBottom: '#0000ff',    nbTitle: '标题',    nbLoading: false,    nbFrontColor: '#000000',    nbBackgroundColor: '#ffffff',  },})


        native-component

        原生组件

        小程序中的部分组件是由客户端创建的原生组件,这些组件有:

        • camera
        • canvas
        • input(仅在focus时表现为原生组件)
        • live-player
        • live-pusher
        • map
        • textarea
        • video

        原生组件的使用限制

        由于原生组件脱离在 WebView 渲染流程外,因此在使用时有以下限制:

        • 原生组件的层级是最高的,所以页面中的其他组件无论设置 z-index 为多少,都无法盖在原生组件上。后插入的原生组件可以覆盖之前的原生组件。
        • 原生组件还无法在 picker-view 中使用。基础库 2.4.4 以下版本,原生组件不支持在 scroll-view、swiper、movable-view 中使用。
        • 部分CSS样式无法应用于原生组件,例如:无法对原生组件设置 CSS 动画无法定义原生组件为 position: fixed不能在父级节点使用 overflow: hidden 来裁剪原生组件的显示区域
        • 原生组件的事件监听不能使用 bind:eventname 的写法,只支持 bindeventname。原生组件也不支持 catch 和 capture 的事件绑定方式。
        • 原生组件会遮挡 vConsole 弹出的调试面板。 在工具上,原生组件是用web组件模拟的,因此很多情况并不能很好的还原真机的表现,建议开发者在使用到原生组件时尽量在真机上进行调试。*

        cover-view 与 cover-image

        为了解决原生组件层级最高的限制。小程序专门提供了 cover-view 和 cover-image 组件,可以覆盖在部分原生组件上面。这两个组件也是原生组件,但是使用限制与其他原生组件有所不同。

        原生组件同层渲染

        同层渲染是为了解决原生组件的层级问题,在支持同层渲染后,原生组件与其它组件可以随意叠加,有关层级的限制将不再存在。但需要注意的是,组件内部仍由原生渲染,样式一般还是对原生组件内部无效。当前 video, map, live-player, live-pusher, canvas(2d) 组件已支持同层渲染。

        原生组件相对层级

        为了可以调整原生组件之间的相对层级位置,小程序在 v2.7.0 及以上版本支持在样式中声明 z-index 来指定原生组件的层级。该 z-index 仅调整原生组件之间的层级顺序,其层级仍高于其他非原生组件。


        aria-component

        无障碍访问

        为了更好地满足视障人士对于小程序的访问需求,基础库自2.7.1起,支持部分ARIA标签。

        无障碍特性在读屏模式下可以访问,iOS可通过设置->通用->辅助功能->旁白打开。

        以 view 组件为例,开发者可以增加aria-role和aria-label属性。 其中aria-role表示组件的角色,当设置为'img'时,读屏模式下聚焦后系统会朗读出'图像'。设置为'button'时,聚焦后后系统朗读出'按钮'。 aria-label表示组件附带的额外信息,聚焦后系统会自动朗读出来。

        小程序已经内置了一些无障碍的特性,对于非原生组件,开发者可以添加以下无障碍标签。

        aria-hiddenaria-rolearia-labelaria-checkedaria-disabled
        aria-describedbyaria-expandedaria-haspopuparia-selectedaria-required
        aria-orientationaria-valueminaria-valuemaxaria-valuenowaria-readonly
        aria-multiselectablearia-controlstabindexaria-labelledbyria-orientation
        aia-multiselectablearia-labelledby

        示例代码

        <view aria-role="button"  aria-label="提交表单">提交</view>

        提示:

        1. 安卓和iOS读屏模式下设置aria-role后朗读的内容不同系统之间会有差异
        2. 可设置的aria-role可参看 Using Aria中的Widget Roles,部分role的设置在移动端可能无效。


        aria-component

        无障碍访问

        为了更好地满足视障人士对于小程序的访问需求,基础库自2.7.1起,支持部分ARIA标签。

        无障碍特性在读屏模式下可以访问,iOS可通过设置->通用->辅助功能->旁白打开。

        以 view 组件为例,开发者可以增加aria-role和aria-label属性。 其中aria-role表示组件的角色,当设置为'img'时,读屏模式下聚焦后系统会朗读出'图像'。设置为'button'时,聚焦后后系统朗读出'按钮'。 aria-label表示组件附带的额外信息,聚焦后系统会自动朗读出来。

        小程序已经内置了一些无障碍的特性,对于非原生组件,开发者可以添加以下无障碍标签。

        aria-hiddenaria-rolearia-labelaria-checkedaria-disabled
        aria-describedbyaria-expandedaria-haspopuparia-selectedaria-required
        aria-orientationaria-valueminaria-valuemaxaria-valuenowaria-readonly
        aria-multiselectablearia-controlstabindexaria-labelledbyria-orientation
        aia-multiselectablearia-labelledby

        示例代码

        <view aria-role="button"  aria-label="提交表单">提交</view>

        提示:

        1. 安卓和iOS读屏模式下设置aria-role后朗读的内容不同系统之间会有差异
        2. 可设置的aria-role可参看 Using Aria中的Widget Roles,部分role的设置在移动端可能无效。


        API

        框架提供丰富的微信原生API,可以方便的调起微信提供的能力,如获取用户信息,本地存储,支付功能等。

        说明:

        • wx.on开头的API是监听某个事件发生的API接口,接受一个CALLBACK函数作为参数。当该事件触发时,会调用CALLBACK函数。
        • 如未特殊约定,其他API接口都接受一个OBJECT作为参数。
        • OBJECT中可以指定success,fail,complete来接收接口调用结果。
        参数名类型必填说明
        successFunction接口调用成功的回调函数
        failFunction接口调用失败的回调函数
        completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

        API列表:

        网络API列表:

        API说明
        wx.request发起网络请求
        wx.uploadFile上传文件
        wx.downloadFile下载文件
        wx.connectSocket创建WebSocket连接
        wx.onSocketOpen监听WebSocket打开
        wx.onSocketError监听WebSocket错误
        wx.sendSocketMessage发送WebSocket消息
        wx.onSocketMessage接受WebSocket消息
        wx.closeSocket关闭WebSocket连接
        wx.onSocketClose监听WebSocket关闭

        媒体API列表:

        API说明
        wx.chooseImage从相册选择图片,或者拍照
        wx.previewImage预览图片
        wx.startRecord开始录音
        wx.stopRecord结束录音
        wx.playVoice播放语音
        wx.pauseVoice暂停播放语音
        wx.stopVoice结束播放语音
        wx.getBackgroundAudioPlayerState获取音乐播放状态
        wx.playBackgroundAudio播放音乐
        wx.pauseBackgroundAudio暂停播放音乐
        wx.seekBackgroundAudio控制音乐播放进度
        wx.stopBackgroundAudio停止播放音乐
        wx.onBackgroundAudioPlay监听音乐开始播放
        wx.onBackgroundAudioPause监听音乐暂停
        wx.onBackgroundAudioStop监听音乐结束
        wx.chooseVideo从相册选择视频,或者拍摄

        文件 API 列表:

        API说明
        wx.saveFile保存文件
        wx.getSavedFileList获取已保存的文件列表
        wx.getSavedFileInfo获取已保存的文件信息
        wx.removeSavedFile删除已保存的文件信息
        wx.openDocument打开文件

        数据 API 列表:

        API说明
        wx.getStorage获取本地数据缓存
        wx.getStorageSync获取本地数据缓存
        wx.setStorage设置本地数据缓存
        wx.setStorageSync设置本地数据缓存
        wx.getStorageInfo获取本地缓存的相关信息
        wx.getStorageInfoSync获取本地缓存的相关信息
        wx.removeStorage删除本地缓存内容
        wx.removeStorageSync删除本地缓存内容
        wx.clearStorage清理本地数据缓存
        wx.clearStorageSync清理本地数据缓存

        位置 API 列表:

        API说明
        wx.getLocation获取当前位置
        wx.chooseLocation打开地图选择位置
        wx.openLocation打开内置地图
        wx.createMapContext地图组件控制

        设备 API 列表:

        API说明
        wx.getNetworkType获取网络类型
        wx.onNetworkStatusChange监听网络状态变化
        wx.getSystemInfo获取系统信息
        wx.getSystemInfoSync获取系统信息
        wx.onAccelerometerChange监听加速度数据
        wx.startAccelerometer开始监听加速度数据
        wx.stopAccelerometer停止监听加速度数据
        wx.onCompassChange监听罗盘数据
        wx.startCompass开始监听罗盘数据
        wx.stopCompass停止监听罗盘数据
        wx.setClipboardData设置剪贴板内容
        wx.getClipboardData获取剪贴板内容
        wx.makePhoneCall拨打电话
        wx.scanCode扫码

        界面 API 列表:

        API说明
        wx.showToast显示提示框
        wx.showLoading显示加载提示框
        wx.hideToast隐藏提示框
        wx.hideLoading隐藏提示框
        wx.showModal显示模态弹窗
        wx.showActionSheet显示菜单列表
        wx.setNavigationBarTitle设置当前页面标题
        wx.showNavigationBarLoading显示导航条加载动画
        wx.hideNavigationBarLoading隐藏导航条加载动画
        wx.navigateTo新窗口打开页面
        wx.redirectTo原窗口打开页面
        wx.switchTab切换到 tabbar 页面
        wx.navigateBack退回上一个页面
        wx.createAnimation动画
        wx.createCanvasContext创建绘图上下文
        wx.drawCanvas绘图
        wx.stopPullDownRefresh停止下拉刷新动画

        WXML节点信息 API 列表:

        API说明
        wx.createSelectorQuery创建查询请求
        selectorQuery.select根据选择器选择单个节点
        selectorQuery.selectAll根据选择器选择全部节点
        selectorQuery.selectViewport选择显示区域
        nodesRef.boundingClientRect获取布局位置和尺寸
        nodesRef.scrollOffset获取滚动位置
        nodesRef.fields获取任意字段
        selectorQuery.exec执行查询请求

        开放接口:

        API说明
        wx.login登录
        wx.getUserInfo获取用户信息
        wx.chooseAddress获取用户收货地址
        wx.requestPayment发起微信支付
        wx.addCard添加卡券
        wx.openCard打开卡券

        每个微信小程序需要事先设置一个通讯域名,小程序可以跟指定的域名与进行网络通信。包括普通 HTTPS 请求(wx.request)、 WebSocket 通信(wx.connectSocket)、上传文件(wx.uploadFile)和下载文件(wx.downloadFile)。

        网络API列表:

        API说明
        wx.request发起网络请求
        wx.uploadFile上传文件
        wx.downloadFile下载文件
        wx.connectSocket创建 WebSocket 连接
        wx.onSocketOpen监听 WebSocket 打开
        wx.onSocketError监听 WebSocket 错误
        wx.sendSocketMessage发送 WebSocket 消息
        wx.onSocketMessage接受 WebSocket 消息
        wx.closeSocket关闭 WebSocket 连接
        wx.onSocketClose监听 WebSocket 关闭

        Tip

        1. tip: 网络请求的 referer 是不可以设置的,格式固定为https://servicewechat.com/{appid}/{version}/page-frame.html,其中{appid}为小程序的 appid,{version}为小程序的版本号,版本号为 0 表示为开发版。
        2. tip: 小程序进入后台运行后(非置顶聊天),如果 5s 内网络请求没有结束,会回调错误信息 "fail interrupted";在回到前台之前,网络请求接口调用都会无法调用。

        RequestTask wx.request(Object object)

        发起 HTTPS 网络请求。使用前请注意阅读相关说明。

        参数

        Object object

        属性类型默认值必填说明最低版本
        urlstring开发者服务器接口地址
        datastring/object/ArrayBuffer请求的参数
        headerObject设置请求的 header,header 中不能设置 Referer。
        content-type 默认为 application/json
        timeoutnumber超时时间,单位为毫秒2.10.0
        methodstringGETHTTP 请求方法
        dataTypestringjson返回的数据格式
        responseTypestringtext响应的数据类型1.7.0
        enableHttp2booleanfalse开启 http22.10.4
        enableQuicbooleanfalse开启 quic2.10.4
        enableCachebooleanfalse开启 cache2.10.4
        successfunction接口调用成功的回调函数
        failfunction接口调用失败的回调函数
        completefunction接口调用结束的回调函数(调用成功、失败都会执行)

        object.method 的合法值

        说明最低版本
        OPTIONSHTTP 请求 OPTIONS
        GETHTTP 请求 GET
        HEADHTTP 请求 HEAD
        POSTHTTP 请求 POST
        PUTHTTP 请求 PUT
        DELETEHTTP 请求 DELETE
        TRACEHTTP 请求 TRACE
        CONNECTHTTP 请求 CONNECT

        object.dataType 的合法值

        说明最低版本
        json返回的数据为 JSON,返回后会对返回的数据进行一次 JSON.parse
        其他不对返回的内容进行 JSON.parse

        object.responseType 的合法值

        说明最低版本
        text响应的数据为文本
        arraybuffer响应的数据为 ArrayBuffer

        object.success 回调函数

        参数
        Object res
        属性类型说明最低版本
        datastring/Object/Arraybuffer开发者服务器返回的数据
        statusCodenumber开发者服务器返回的 HTTP 状态码
        headerObject开发者服务器返回的 HTTP Response Header1.2.0
        cookiesArray.<string>开发者服务器返回的 cookies,格式为字符串数组2.10.0
        profileObject网络请求过程中一些调试信息2.10.4

        res.profile 的结构

        属性类型说明
        redirectStartnumber第一个 HTTP 重定向发生时的时间。有跳转且是同域名内的重定向才算,否则值为 0
        redirectEndnumber最后一个 HTTP 重定向完成时的时间。有跳转且是同域名内部的重定向才算,否则值为 0
        fetchStartnumber组件准备好使用 HTTP 请求抓取资源的时间,这发生在检查本地缓存之前
        domainLookupStartnumberDNS 域名查询开始的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等
        domainLookupEndnumberDNS 域名查询完成的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等
        connectStartnumberHTTP(TCP) 开始建立连接的时间,如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接开始的时间
        connectEndnumberHTTP(TCP) 完成建立连接的时间(完成握手),如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接完成的时间。注意这里握手结束,包括安全连接建立完成、SOCKS 授权通过
        SSLconnectionStartnumberSSL建立连接的时间,如果不是安全连接,则值为 0
        SSLconnectionEndnumberSSL建立完成的时间,如果不是安全连接,则值为 0
        requestStartnumberHTTP请求读取真实文档开始的时间(完成建立连接),包括从本地读取缓存。连接错误重连时,这里显示的也是新建立连接的时间
        requestEndnumberHTTP请求读取真实文档结束的时间
        responseStartnumberHTTP 开始接收响应的时间(获取到第一个字节),包括从本地读取缓存
        responseEndnumberHTTP 响应全部接收完成的时间(获取到最后一个字节),包括从本地读取缓存
        rttnumber当次请求连接过程中实时 rtt
        estimate_nettypestring评估的网络状态 slow 2g/2g/3g/4g
        httpRttEstimatenumber协议层根据多个请求评估当前网络的 rtt(仅供参考)
        transportRttEstimatenumber传输层根据多个请求评估的当前网络的 rtt(仅供参考)
        downstreamThroughputKbpsEstimatenumber评估当前网络下载的kbps
        throughputKbpsnumber当前网络的实际下载kbps
        peerIPstring当前请求的IP
        portnumber当前请求的端口
        socketReusedboolean是否复用连接
        sendBytesCountnumber发送的字节数
        receivedBytedCountnumber收到字节数

        返回值

        RequestTask

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

        请求任务对象

        data 参数说明

        最终发送给服务器的数据是 String 类型,如果传入的 data 不是 String 类型,会被转换成 String 。转换规则如下:

        • 对于 GET 方法的数据,会将数据转换成 query string(encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...)
        • 对于 POST 方法且 header['content-type'] 为 application/json 的数据,会对数据进行 JSON 序列化
        • 对于 POST 方法且 header['content-type'] 为 application/x-www-form-urlencoded 的数据,会将数据转换成 query string (encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...)

        示例代码

        wx.request({  url: 'test.php', //仅为示例,并非真实的接口地址  data: {    x: '',    y: ''  },  header: {    'content-type': 'application/json' // 默认值  },  success (res) {    console.log(res.data)  }})

        RequestTask

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

        网络请求任务对象

        方法

        RequestTask.abort()

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

        中断请求任务


        RequestTask.offHeadersReceived(function callback)

        基础库 2.1.0 开始支持,低版本需做兼容处理。

        取消监听 HTTP Response Header 事件

        参数

        function callback

        HTTP Response Header 事件的回调函数


        RequestTask.onHeadersReceived(function callback)

        基础库 2.1.0 开始支持,低版本需做兼容处理。

        监听 HTTP Response Header 事件。会比请求完成事件更早

        参数

        function callback

        HTTP Response Header 事件的回调函数

        参数

        Object res
        属性类型说明
        headerObject开发者服务器返回的 HTTP Response Header


        示例代码

        const requestTask = wx.request({  url: 'test.php', //仅为示例,并非真实的接口地址  data: {    x: '' ,    y: ''  },  header: {    'content-type': 'application/json'  },  success (res) {    console.log(res.data)  }})requestTask.abort() // 取消请求任务


        wx.uploadFile(OBJECT)


        将本地资源上传到开发者服务器。如页面通过 wx.chooseImage 等接口获取到一个本地资源的临时文件路径后,可通过此接口将本地资源上传到指定服务器。客户端发起一个HTTPS POST请求,其中Content-Typemultipart/form-data

        OBJECT参数说明:

        参数类型必填说明
        urlString开发者服务器url
        filePathString要上传文件资源的路径
        nameString文件对应的key , 开发者在服务器端通过这个key可以获取到文件二进制内容
        headerObjectHTTP 请求 Header,header中不能设置Referer
        formDataObjectHTTP 请求中其他额外的form data
        successFunction接口调用成功的回调函数
        failFunction接口调用失败的回调函数
        completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

        success返回参数说明:

        参数类型说明
        dataString开发者服务器返回的数据
        statusCodeNumberHTTP状态码

        示例代码:

        wx.chooseImage({  success:function(res){    var tempFilePaths = res.tempFilePaths    wx.uploadFile({      url: 'http://example.weixin.qq.com/upload', //仅为示例,非真实的接口地址      filePath: tempFilePaths[0],      name:"file",      formData:{        "user":"test"      }      success: function(res){        var data = res.data        //do something      }    })  }})

        返回值:

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

        返回一个uploadTask对象,通过uploadTask,可监听上传进度变化事件,以及取消上传任务。

        uploadTask

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

        一个可以监听上传进度变化事件,以及取消上传任务的对象

        方法:

        UploadTask.abort()

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

        中断上传任务


        UploadTask.offHeadersReceived(function callback)

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

        取消监听 HTTP Response Header 事件

        参数

        function callback

        HTTP Response Header 事件的回调函数


        UploadTask.offProgressUpdate(function callback)

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

        取消监听上传进度变化事件

        参数

        function callback

        上传进度变化事件的回调函数


        UploadTask.onHeadersReceived(function callback)

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

        监听 HTTP Response Header 事件。会比请求完成事件更早

        参数

        function callback

        HTTP Response Header 事件的回调函数

        参数

        Object res
        属性类型说明
        headerObject开发者服务器返回的 HTTP Response Header


        UploadTask.onProgressUpdate(function callback)

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

        监听上传进度变化事件

        参数

        function callback

        上传进度变化事件的回调函数

        参数

        Object res
        属性类型说明
        progressnumber上传进度百分比
        totalBytesSentnumber已经上传的数据长度,单位 Bytes
        totalBytesExpectedToSendnumber预期需要上传的数据总长度,单位 Bytes


        示例代码:

        const uploadTask = wx.uploadFile({    url: 'http://example.weixin.qq.com/upload', //仅为示例,非真实的接口地址    filePath: tempFilePaths[0],    name: 'file',    formData:{        'user': 'test'    },    success: function(res){        var data = res.data        //do something    }})uploadTask.onProgressUpdate((res) => {    console.log('上传进度', res.progress)    console.log('已经上传的数据长度', res.totalBytesSent)    console.log('预期需要上传的数据总长度', res.totalBytesExpectedToSend)})uploadTask.abort() // 取消上传任务

        Bug & Tip

        1. tip: 最大并发限制是 10 个
        2. tip: 默认超时时间和最大超时时间都是 60s


        wx.downloadFile(OBJECT)

        下载文件资源到本地。客户端直接发起一个HTTP GET请求,返回文件的本地临时路径。

        参数

        Object object

        属性类型默认值必填说明最低版本
        urlstring下载资源的 url
        headerObjectHTTP 请求的 Header,Header 中不能设置 Referer
        timeoutnumber超时时间,单位为毫秒2.10.0
        filePathstring指定文件下载后存储的路径 (本地路径)1.8.0
        successfunction接口调用成功的回调函数
        failfunction接口调用失败的回调函数
        completefunction接口调用结束的回调函数(调用成功、失败都会执行)

        object.success 回调函数

        参数
        Object res
        属性类型说明最低版本
        tempFilePathstring临时文件路径 (本地路径)。没传入 filePath 指定文件存储路径时会返回,下载后的文件会存储到一个临时文件
        filePathstring用户文件路径 (本地路径)。传入 filePath 时会返回,跟传入的 filePath 一致
        statusCodenumber开发者服务器返回的 HTTP 状态码
        profileObject网络请求过程中一些调试信息2.10.4

        res.profile 的结构

        属性类型说明
        redirectStartnumber第一个 HTTP 重定向发生时的时间。有跳转且是同域名内的重定向才算,否则值为 0
        redirectEndnumber最后一个 HTTP 重定向完成时的时间。有跳转且是同域名内部的重定向才算,否则值为 0
        fetchStartnumber组件准备好使用 HTTP 请求抓取资源的时间,这发生在检查本地缓存之前
        domainLookupStartnumberDNS 域名查询开始的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等
        domainLookupEndnumberDNS 域名查询完成的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等
        connectStartnumberHTTP(TCP) 开始建立连接的时间,如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接开始的时间
        connectEndnumberHTTP(TCP) 完成建立连接的时间(完成握手),如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接完成的时间。注意这里握手结束,包括安全连接建立完成、SOCKS 授权通过
        SSLconnectionStartnumberSSL建立连接的时间,如果不是安全连接,则值为 0
        SSLconnectionEndnumberSSL建立完成的时间,如果不是安全连接,则值为 0
        requestStartnumberHTTP请求读取真实文档开始的时间(完成建立连接),包括从本地读取缓存。连接错误重连时,这里显示的也是新建立连接的时间
        requestEndnumberHTTP请求读取真实文档结束的时间
        responseStartnumberHTTP 开始接收响应的时间(获取到第一个字节),包括从本地读取缓存
        responseEndnumberHTTP 响应全部接收完成的时间(获取到最后一个字节),包括从本地读取缓存
        rttnumber当次请求连接过程中实时 rtt
        estimate_nettypestring评估的网络状态 slow 2g/2g/3g/4g
        httpRttEstimatenumber协议层根据多个请求评估当前网络的 rtt(仅供参考)
        transportRttEstimatenumber传输层根据多个请求评估的当前网络的 rtt(仅供参考)
        downstreamThroughputKbpsEstimatenumber评估当前网络下载的kbps
        throughputKbpsnumber当前网络的实际下载kbps
        peerIPstring当前请求的IP
        portnumber当前请求的端口
        socketReusedboolean是否复用连接
        sendBytesCountnumber发送的字节数
        receivedBytedCountnumber收到字节数

        返回值

        DownloadTask

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

        一个可以监听下载进度变化事件和取消下载的对象


        示例代码:

        wx.downloadFile({  url: 'https://example.com/audio/123', //仅为示例,并非真实的资源  success (res) {    // 只要服务器有响应数据,就会把响应内容写入文件并进入 success 回调,业务需要自行判断是否下载到了想要的内容    if (res.statusCode === 200) {      wx.playVoice({        filePath: res.tempFilePath      })    }  }})



        DownloadTask

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

        一个可以监听下载进度变化事件,以及取消下载任务的对象

        方法:

        DownloadTask.abort()

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

        中断下载任务


        DownloadTask.offHeadersReceived(function callback)

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

        取消监听 HTTP Response Header 事件

        参数

        function callback

        HTTP Response Header 事件的回调函数


        DownloadTask.offProgressUpdate(function callback)

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

        取消监听下载进度变化事件

        参数

        function callback

        下载进度变化事件的回调函数

          DownloadTask.onHeadersReceived(function callback)

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

          监听 HTTP Response Header 事件。会比请求完成事件更早

          参数

          function callback

          HTTP Response Header 事件的回调函数

          参数

          Object res
          属性类型说明
          headerObject开发者服务器返回的 HTTP Response Header

          DownloadTask.onProgressUpdate(function callback)

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

          监听下载进度变化事件

          参数

          function callback

          下载进度变化事件的回调函数

          参数

          Object res
          属性类型说明
          progressnumber下载进度百分比
          totalBytesWrittennumber已经下载的数据长度,单位 Bytes
          totalBytesExpectedToWritenumber预期需要下载的数据总长度,单位 Bytes


          wx.connectSocket(OBJECT)


          创建一个 WebSocket 连接;一个微信小程序同时只能有一个 WebSocket 连接,如果当前已存在一个 WebSocket 连接,会自动关闭该连接,并重新创建一个 WebSocket 连接。

          OBJECT参数说明:

          参数类型必填说明最低版本
          urlString开发者服务器接口地址,必须是 wss 协议,且域名必须是后台配置的合法域名 
          dataObject请求的数据 
          headerObjectHTTP Header , header 中不能设置 Referer 
          methodString默认是GET,有效值: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT 
          protocolsStringArray子协议数组1.4.0
          successFunction接口调用成功的回调函数 
          failFunction接口调用失败的回调函数 
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行) 

          示例代码:
          wx.connectSocket({    url: 'test.php',  data:{    x: '',    y: ''  },  header:{     'content-type': 'application/json'  },  protocols: ['protocol1'],  method:"GET"})

          wx.onSocketOpen(CALLBACK)


          监听WebSocket连接打开事件。

          示例代码:

          wx.connectSocket({  url: 'test.php'})wx.onSocketOpen(function(res) {  console.log('WebSocket连接已打开!')})

          wx.onSocketError(CALLBACK)


          监听WebSocket错误。

          示例代码:

          wx.connectSocket({  url: 'test.php'})wx.onSocketOpen(function(res){  console.log('WebSocket连接已打开!')})wx.onSocketError(function(res){  console.log('WebSocket连接打开失败,请检查!')})

          wx.sendSocketMessage(OBJECT)


          通过 WebSocket 连接发送数据,需要先 wx.connectSocket,并在 wx.onSocketOpen 回调之后才能发送。

          OBJECT参数说明:

          参数类型必填说明
          dataString/ArrayBuffer需要发送的内容
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          var socketOpen = falsevar socketMsgQueue = []wx.connectSocket({  url: 'test.php'})wx.onSocketOpen(function(res) {  socketOpen = true  for (var i = 0; i < socketMsgQueue.length; i++){     sendSocketMessage(socketMsgQueue[i])  }  socketMsgQueue = []})function sendSocketMessage(msg) {  if (socketOpen) {    wx.sendSocketMessage({      data:msg    })  } else {     socketMsgQueue.push(msg)  }}

          wx.onSocketMessage(CALLBACK)


          监听WebSocket接受到服务器的消息事件。

          CALLBACK返回参数:

          参数类型说明
          dataString/ArrayBuffer服务器返回的消息

          示例代码:

          wx.connectSocket({  url: 'test.php'})wx.onSocketMessage(function(res) {  console.log('收到服务器内容:' + res.data)})

          wx.closeSocket(OBJECT)


          关闭WebSocket连接。

          参数类型必填说明最低版本
          codeNumber一个数字值表示关闭连接的状态号,表示连接被关闭的原因。如果这个参数没有被指定,默认的取值是1000 (表示正常连接关闭)1.4.0
          reasonString一个可读的字符串,表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本(不是字符)1.4.0
          successFunction接口调用成功的回调函数 
          failFunction接口调用失败的回调函数 
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行) 

          wx.onSocketClose(CALLBACK)


          监听WebSocket关闭。

          wx.connectSocket({  url: 'test.php'})//注意这里有时序问题,//如果 wx.connectSocket 还没回调 wx.onSocketOpen,而先调用 wx.closeSocket,那么就做不到关闭 WebSocket 的目的。//必须在 WebSocket 打开期间调用 wx.closeSocket 才能关闭。wx.onSocketOpen(function() {  wx.closeSocket()})wx.onSocketClose(function(res) {  console.log('WebSocket 已关闭!')})

          返回值:

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

          返回一个 SocketTask。

          Bug & Tip

          1. tip: createSocket 链接默认和最大超时时间都是 60s
          2. tip: 网络请求的 referer 是不可以设置的,格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中{appid}为小程序的 appid,{version}为小程序的版本号,版本号为 0 表示为开发版。

          SocketTask

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

          WebSocket 任务,可通过 wx.connectSocket() 接口创建返回。

          方法

          SocketTask.send(OBJECT)

          通过 WebSocket 连接发送数据。

          OBJECT参数说明:

          参数类型必填说明
          dataString/ArrayBuffer需要发送的内容
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)
          SocketTask.close(OBJECT)

          关闭 WebSocket 连接。

          OBJECT参数说明:

          参数类型必填说明
          codeNumber一个数字值表示关闭连接的状态号,表示连接被关闭的原因。如果这个参数没有被指定,默认的取值是1000 (表示正常连接关闭)
          reasonString一个可读的字符串,表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本(不是字符)
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)
          SocketTask.onOpen(CALLBACK)

          监听 WebSocket 连接打开事件。

          SocketTask.onClose(CALLBACK)

          监听 WebSocket 连接关闭事件。

          SocketTask.onError(CALLBACK)

          监听 WebSocket 错误。

          CALLBACK返回参数:

          参数类型说明
          errMsgString错误信息
          SocketTask.onMessage(CALLBACK)

          监听WebSocket接受到服务器的消息事件。

          CALLBACK返回参数:

          参数类型说明
          dataString/ArrayBuffer服务器返回的消息

          wx.stopLocalServiceDiscovery(Object object)

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

          停止搜索 mDNS 服务

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          task not found在当前没有处在搜索服务中的情况下调用 stopLocalServiceDiscovery

          wx.startLocalServiceDiscovery(Object object)

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

          开始搜索局域网下的 mDNS 服务。搜索的结果会通过 wx.onLocalService* 事件返回。

          参数

          Object object

          属性类型默认值必填说明
          serviceTypestring要搜索的服务类型
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          invalid paramserviceType 为空
          scan task already exist在当前 startLocalServiceDiscovery 发起的搜索未停止的情况下,再次调用 startLocalServiceDiscovery

          示例代码

              wx.startLocalServiceDiscovery({      // 当前手机所连的局域网下有一个 _http._tcp. 类型的服务      serviceType: '_http._tcp.',      success: console.log,      fail: console.log    })

          注意

          1. wx.startLocalServiceDiscovery 是一个消耗性能的行为,开始 30 秒后会自动 stop 并执行 wx.onLocalServiceDiscoveryStop 注册的回调函数。
          2. 在调用 wx.startLocalServiceDiscovery 后,在这次搜索行为停止后才能发起下次 wx.startLocalServiceDiscovery。停止本次搜索行为的操作包括调用 wx.stopLocalServiceDiscovery 和 30 秒后系统自动 stop 本次搜索。

          wx.onLocalServiceResolveFail(function callback)

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

          监听 mDNS 服务解析失败的事件

          参数

          function callback

          mDNS 服务解析失败的事件的回调函数

          参数

          Object res
          属性类型说明
          serviceTypestring服务的类型
          serviceNamestring服务的名称

          wx.onLocalServiceLost(function callback)

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

          监听 mDNS 服务离开的事件

          参数

          function callback

          mDNS 服务离开的事件的回调函数

          参数

          Object res
          属性类型说明
          serviceTypestring服务的类型
          serviceNamestring服务的名称

          wx.onLocalServiceFound(function callback)

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

          监听 mDNS 服务发现的事件

          参数

          function callback

          mDNS 服务发现的事件的回调函数

          参数

          Object res
          属性类型说明
          serviceTypestring服务的类型
          serviceNamestring服务的名称
          ipstring服务的 ip 地址
          portnumber服务的端口

          wx.onLocalServiceDiscoveryStop(function callback)

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

          监听 mDNS 服务停止搜索的事件

          参数

          function callback

          mDNS 服务停止搜索的事件的回调函数


          wx.offLocalServiceResolveFail(function callback)

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

          取消监听 mDNS 服务解析失败的事件

          参数

          function callback

          mDNS 服务解析失败的事件的回调函数


          wx.offLocalServiceLost(function callback)

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

          取消监听 mDNS 服务离开的事件

          参数

          function callback

          mDNS 服务离开的事件的回调函数


          wx.offLocalServiceFound(function callback)

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

          取消监听 mDNS 服务发现的事件

          参数

          function callback

          mDNS 服务发现的事件的回调函数


          wx.offLocalServiceDiscoveryStop(function callback)

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

          取消监听 mDNS 服务停止搜索的事件

          参数

          function callback

          mDNS 服务停止搜索的事件的回调函数


          UDPSocket wx.createUDPSocket()

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

          创建一个 UDP Socket 实例。使用前请注意阅读相关说明。

          返回值

          UDPSocket

          一个 UDP Socket 实例


          UDPSocket

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

          一个 UDP Socket 实例,默认使用 IPv4 协议。

          方法:

          number UDPSocket.bind(number port)

          绑定一个系统随机分配的可用端口,或绑定一个指定的端口号

          参数

          number port

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

          指定要绑定的端口号,不传则返回系统随机分配的可用端口

          返回值

          number

          绑定成功的端口号

          示例代码

          const udp = wx.createUDPSocket()const port = udp.bind()


          UDPSocket.close()

          关闭 UDP Socket 实例,相当于销毁。 在关闭之后,UDP Socket 实例不能再发送消息,每次调用 UDPSocket.send 将会触发错误事件,并且 message 事件回调函数也不会再也执行。在 UDPSocket 实例被创建后将被 Native 强引用,保证其不被 GC。在 UDPSocket.close 后将解除对其的强引用,让 UDPSocket 实例遵从 GC。


          UDPSocket.offClose(function callback)

          取消监听关闭事件

          参数

          function callback

          关闭事件的回调函数


          UDPSocket.offError(function callback)

          取消监听错误事件

          参数

          function callback

          错误事件的回调函数


          UDPSocket.offListening(function callback)

          取消监听开始监听数据包消息的事件

          参数

          function callback

          开始监听数据包消息的事件的回调函数


          UDPSocket.offMessage(function callback)

          取消监听收到消息的事件

          参数

          function callback

          收到消息的事件的回调函数


          UDPSocket.onClose(function callback)

          监听关闭事件

          参数

          function callback

          关闭事件的回调函数


          UDPSocket.onError(function callback)

          监听错误事件

          参数

          function callback

          错误事件的回调函数

          参数

          Object res
          属性类型说明
          errMsgstring错误信息


          UDPSocket.onListening(function callback)

          监听开始监听数据包消息的事件

          参数

          function callback

          开始监听数据包消息的事件的回调函数


          UDPSocket.onMessage(function callback)

          监听收到消息的事件

          参数

          function callback

          收到消息的事件的回调函数

          参数

          Object res
          属性类型说明
          messageArrayBuffer收到的消息
          remoteInfoObject消息来源的结构化信息

          remoteInfo 的结构

          属性类型说明
          addressstring发送消息的 socket 的地址
          familystring使用的协议族,为 IPv4 或者 IPv6
          portnumber端口号
          sizenumbermessage 的大小,单位:字节


          UDPSocket.send(Object object)

          向指定的 IP 和 port 发送消息

          参数

          Object object

          属性类型默认值必填说明
          addressstring要发消息的地址。在基础库 2.9.3 及之前版本可以是一个和本机同网段的 IP 地址,也可以是在安全域名列表内的域名地址;在基础库 2.9.4 及之后版本,可以是任意 IP 和域名
          portnumber要发送消息的端口号
          messagestring/ArrayBuffer要发送的数据
          offsetnumber0发送数据的偏移量,仅当 message 为 ArrayBuffer 类型时有效
          lengthnumbermessage.byteLength发送数据的长度,仅当 message 为 ArrayBuffer 类型时有效

          示例代码

            const udp = wx.createUDPSocket()  udp.bind()  udp.send({    address: '192.168.193.2',    port: 8848,    message: 'hello, how are you'  })


          MapContext wx.createMapContext(string mapId, Object this)

          创建 map 上下文 MapContext 对象。

          参数

          string mapId

          map 组件的 id

          Object this

          在自定义组件下,当前组件实例的this,以操作组件内 map 组件

          返回值

          MapContext


          MapContext 实例,可通过 wx.createMapContext 获取。

          MapContext 通过 id 跟一个 map 组件绑定,操作对应的 map 组件。

          方法

          MapContext.getCenterLocation()

          获取当前地图中心的经纬度。返回的是 gcj02 坐标系,可以用于 wx.openLocation()

          MapContext.moveToLocation(Object object)

          将地图中心移置当前定位点,此时需设置地图组件 show-locationtrue2.8.0 起支持将地图中心移动到指定位置。

          MapContext.translateMarker(Object object)

          平移marker,带动画

          MapContext.includePoints(Object object)

          缩放视野展示所有经纬度

          MapContext.getRegion()

          获取当前地图的视野范围

          MapContext.getRotate()

          获取当前地图的旋转角

          MapContext.getSkew()

          获取当前地图的倾斜角

          MapContext.getScale()

          获取当前地图的缩放级别

          MapContext.setCenterOffset(Object object)

          设置地图中心点偏移,向后向下为增长,屏幕比例范围(0.25~0.75),默认偏移为[0.5, 0.5]

          MapContext.removeCustomLayer(Object object)

          移除个性化图层。

          MapContext.addCustomLayer(Object object)

          添加个性化图层。

          示例代码

          <!-- map.wxml --><map id="myMap" show-location /><button type="primary" bindtap="getCenterLocation">获取位置</button><button type="primary" bindtap="moveToLocation">移动位置</button><button type="primary" bindtap="translateMarker">移动标注</button><button type="primary" bindtap="includePoints">缩放视野展示所有经纬度</button>
          // map.jsPage({  onReady: function (e) {    // 使用 wx.createMapContext 获取 map 上下文    this.mapCtx = wx.createMapContext('myMap')  },  getCenterLocation: function () {    this.mapCtx.getCenterLocation({      success: function(res){        console.log(res.longitude)        console.log(res.latitude)      }    })  },  moveToLocation: function () {    this.mapCtx.moveToLocation()  },  translateMarker: function() {    this.mapCtx.translateMarker({      markerId: 0,      autoRotate: true,      duration: 1000,      destination: {        latitude:23.10229,        longitude:113.3345211,      },      animationEnd() {        console.log('animation end')      }    })  },  includePoints: function() {    this.mapCtx.includePoints({      padding: [10],      points: [{        latitude:23.10229,        longitude:113.3345211,      }, {        latitude:23.00229,        longitude:113.3345211,      }]    })  }})


          wx.saveImageToPhotosAlbum(Object object)

          基础库 1.2.0 开始支持,低版本需做兼容处理
          调用前需要 用户授权 scope.writePhotosAlbum

          保存图片到系统相册。

          参数

          Object object

          属性类型默认值必填说明
          filePathstring图片文件路径,可以是临时文件路径或永久文件路径 (本地路径) ,不支持网络路径
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.saveImageToPhotosAlbum({  success(res) { }})


          wx.previewMedia(Object object)

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

          预览图片和视频。

          参数

          Object object

          属性类型默认值必填说明
          sourcesArray.<Object>需要预览的资源列表
          currentcurrent0当前显示的资源序号
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.sources 的结构

          属性类型默认值必填说明
          urlString图片或视频的地址
          typeStringimage资源的类型,默认为图片
          posterstring视频的封面图片

          type 的合法值

          说明最低版本
          image图片
          video视频




          wx.previewImage(Object object)

          在新页面中全屏预览图片。预览的过程中用户可以进行保存图片、发送给朋友等操作。

          参数

          Object object

          属性类型默认值必填说明
          urlsArray.<string>需要预览的图片链接列表。2.2.3 起支持云文件ID。
          currentstringurls 的第一张当前显示图片的链接
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.previewImage({  current: '', // 当前显示图片的http链接  urls: [] // 需要预览的图片http链接列表})


          wx.getImageInfo(Object object)

          获取图片信息。网络图片需先配置download域名才能生效。

          参数

          Object object

          属性类型默认值必填说明
          srcstring图片的路径,支持网络路径、本地路径、代码包路径
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明最低版本
          widthnumber图片原始宽度,单位px。不考虑旋转。
          heightnumber图片原始高度,单位px。不考虑旋转。
          pathstring图片的本地路径
          orientationstring拍照时设备方向1.9.90
          typestring图片格式1.9.90

          res.orientation 的合法值

          说明最低版本
          up默认方向(手机横持拍照),对应 Exif 中的 1。或无 orientation 信息。
          up-mirrored同 up,但镜像翻转,对应 Exif 中的 2
          down旋转180度,对应 Exif 中的 3
          down-mirrored同 down,但镜像翻转,对应 Exif 中的 4
          left-mirrored同 left,但镜像翻转,对应 Exif 中的 5
          right顺时针旋转90度,对应 Exif 中的 6
          right-mirrored同 right,但镜像翻转,对应 Exif 中的 7
          left逆时针旋转90度,对应 Exif 中的 8

          示例代码

          wx.getImageInfo({  src: 'images/a.jpg',  success (res) {    console.log(res.width)    console.log(res.height)  }})wx.chooseImage({  success (res) {    wx.getImageInfo({      src: res.tempFilePaths[0],      success (res) {        console.log(res.width)        console.log(res.height)      }    })  }})


          wx.compressImage(Object object)

          基础库 2.4.0 开始支持,低版本需做兼容处理。

          压缩图片接口,可选压缩质量

          参数

          Object object

          属性类型默认值必填说明
          srcstring图片路径,图片的路径,支持本地路径、代码包路径
          qualitynumber80压缩质量,范围0~100,数值越小,质量越低,压缩率越高(仅对jpg有效)。
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          tempFilePathstring压缩后图片的临时文件路径 (本地路径)

          示例代码

          wx.compressImage({  src: '', // 图片路径  quality: 80 // 压缩质量})


          wx.chooseMessageFile(Object object)

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

          从客户端会话选择文件。

          参数

          Object object

          属性类型默认值必填说明最低版本
          countnumber最多可以选择的文件个数,可以 0~100
          typestring'all'所选的文件的类型
          extensionArray.<string>根据文件拓展名过滤,仅 type==file 时有效。每一项都不能是空字符串。默认不过滤。2.6.0
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.type 的合法值

          说明最低版本
          all从所有文件选择
          video只能选择视频文件
          image只能选择图片文件
          file可以选择除了图片和视频之外的其它的文件

          object.success 回调函数

          参数
          Object res
          属性类型说明
          tempFilesArray.<Object>返回选择的文件的本地临时文件对象数组

          res.tempFiles 的结构

          属性类型说明
          pathstring本地临时文件路径 (本地路径)
          sizenumber本地临时文件大小,单位 B
          namestring选择的文件名称
          typestring选择的文件类型
          timenumber选择的文件的会话发送时间,Unix时间戳,工具暂不支持此属性

          type 的合法值

          说明最低版本
          video选择了视频文件
          image选择了图片文件
          file选择了除图片和视频的文件
          wx.chooseMessageFile({  count: 10,  type: 'image',  success (res) {    // tempFilePath可以作为img标签的src属性显示图片    const tempFilePaths = res.tempFiles  }})


          wx.chooseImage(Object object)

          从本地相册选择图片或使用相机拍照。

          参数

          Object object

          属性类型默认值必填说明
          countnumber9最多可以选择的图片张数
          sizeTypeArray.<string>['original', 'compressed']所选的图片的尺寸
          sourceTypeArray.<string>['album', 'camera']选择图片的来源
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.sizeType 的合法值

          说明最低版本
          original原图
          compressed压缩图

          object.sourceType 的合法值

          说明最低版本
          album从相册选图
          camera使用相机

          object.success 回调函数

          参数
          Object res
          属性类型说明最低版本
          tempFilePathsArray.<string>图片的本地临时文件路径列表 (本地路径)
          tempFilesArray.<Object>图片的本地临时文件列表1.2.0

          res.tempFiles 的结构

          属性类型说明
          pathstring本地临时文件路径 (本地路径)
          sizenumber本地临时文件大小,单位 B
          wx.chooseImage({  count: 1,  sizeType: ['original', 'compressed'],  sourceType: ['album', 'camera'],  success (res) {    // tempFilePath可以作为img标签的src属性显示图片    const tempFilePaths = res.tempFilePaths  }})


          wx.saveVideoToPhotosAlbum(Object object)

          基础库 1.2.0 开始支持,低版本需做兼容处理
          调用前需要 用户授权 scope.writePhotosAlbum

          保存视频到系统相册。支持mp4视频格式。

          参数

          Object object

          属性类型默认值必填说明
          filePathstring视频文件路径,可以是临时文件路径也可以是永久文件路径 (本地路径)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.saveVideoToPhotosAlbum({  filePath: 'wxfile://xxx',  success (res) {    console.log(res.errMsg)  }})


          wx.openVideoEditor(Object object)

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

          打开视频编辑器

          参数

          Object object

          属性类型默认值必填说明
          filePathstring视频源的路径,只支持本地路径
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          durationnumber剪辑后生成的视频文件的时长,单位毫秒(ms)
          sizenumber剪辑后生成的视频文件大小,单位字节数(byte)
          tempFilePathstring编辑后生成的视频文件的临时路径
          tempThumbPathstring编辑后生成的缩略图文件的临时路径


          wx.getVideoInfo(Object object)

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

          获取视频详细信息。

          参数

          Object object

          属性类型默认值必填说明
          srcstring视频文件路径,可以是临时文件路径也可以是永久文件路径
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          orientationstring画面方向
          typestring视频格式
          durationnumber视频长度
          sizenumber视频大小,单位 kB
          heightnumber视频的长,单位 px
          widthnumber视频的宽,单位 px
          fpsnumber视频帧率
          bitratenumber视频码率,单位 kbps

          res.orientation 的合法值

          说明最低版本
          up默认
          down180度旋转
          left逆时针旋转90度
          right顺时针旋转90度
          up-mirrored同up,但水平翻转
          down-mirrored同down,但水平翻转
          left-mirrored同left,但垂直翻转
          right-mirrored同right,但垂直翻转




          VideoContext wx.createVideoContext(string id, Object this)

          创建 video 上下文 VideoContext 对象。

          参数

          string id

          video 组件的 id

          Object this

          在自定义组件下,当前组件实例的this,以操作组件内 video 组件

          返回值

          VideoContext


          wx.compressVideo(Object object)

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

          压缩视频接口。开发者可指定压缩质量 quality 进行压缩。当需要更精细的控制时,可指定 bitrate、fps、和 resolution,当 quality 传入时,这三个参数将被忽略。原视频的相关信息可通过 getVideoInfo 获取。

          参数

          Object object

          属性类型默认值必填说明
          srcstring视频文件路径,可以是临时文件路径也可以是永久文件路径
          qualitystring压缩质量
          bitratenumber码率,单位 kbps
          fpsnumber帧率
          resolutionnumber相对于原视频的分辨率比例,取值范围(0, 1]
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.quality 的合法值

          说明最低版本
          low
          medium
          high

          object.success 回调函数

          参数
          Object res
          属性类型说明
          tempFilePathstring压缩后的临时文件地址
          sizestring压缩后的大小,单位 kB


          wx.chooseVideo(Object object)

          拍摄视频或从手机相册中选视频。

          参数

          Object object

          属性类型默认值必填说明最低版本
          sourceTypeArray.<string>['album', 'camera']视频选择的来源
          compressedbooleantrue是否压缩所选择的视频文件1.6.0
          maxDurationnumber60拍摄视频最长拍摄时间,单位秒
          camerastring'back'默认拉起的是前置或者后置摄像头。部分 Android 手机下由于系统 ROM 不支持无法生效
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.sourceType 的合法值

          说明最低版本
          album从相册选择视频
          camera使用相机拍摄视频

          object.camera 的合法值

          说明最低版本
          back默认拉起后置摄像头
          front默认拉起前置摄像头

          object.success 回调函数

          参数
          Object res
          属性类型说明
          tempFilePathstring选定视频的临时文件路径 (本地路径)
          durationnumber选定视频的时间长度
          sizenumber选定视频的数据量大小
          heightnumber返回选定视频的高度
          widthnumber返回选定视频的宽度

          示例代码

          wx.chooseVideo({  sourceType: ['album','camera'],  maxDuration: 60,  camera: 'back',  success(res) {    console.log(res.tempFilePath)  }})


          wx.chooseMedia(Object object)

          基础库 2.10.0 开始支持,低版本需做兼容处理。

          拍摄或从手机相册中选择图片或视频。

          参数

          Object object

          属性类型默认值必填说明
          countnumber9最多可以选择的文件个数
          mediaTypeArray.<string>['image', 'video']文件类型
          sourceTypeArray.<string>['album', 'camera']图片和视频选择的来源
          maxDurationnumber10拍摄视频最长拍摄时间,单位秒。时间范围为 3s 至 30s 之间
          sizeTypeArray.<string>['original', 'compressed']仅对 mediaType 为 image 时有效,是否压缩所选文件
          camerastring'back'仅在 sourceType 为 camera 时生效,使用前置或后置摄像头
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.mediaType 的合法值

          说明最低版本
          image只能拍摄图片或从相册选择图片
          video只能拍摄视频或从相册选择视频

          object.sourceType 的合法值

          说明最低版本
          album从相册选择
          camera使用相机拍摄

          object.camera 的合法值

          说明最低版本
          back使用后置摄像头
          front使用前置摄像头

          object.success 回调函数

          参数
          Object res
          属性类型说明
          tempFilesArray.<Object>本地临时文件列表
          typestring文件类型,有效值有 image 、video

          res.tempFiles 的结构

          属性类型说明
          tempFilePathstring本地临时文件路径 (本地路径)
          sizenumber本地临时文件大小,单位 B
          durationnumber视频的时间长度
          heightnumber视频的高度
          widthnumber视频的宽度
          thumbTempFilePathstring视频缩略图临时文件路径

          示例代码

          wx.chooseMedia({  count: 9,  mediaType: ['image','video'],  sourceType: ['album', 'camera'],  maxDuration: 30,  camera: 'back',  success(res) {    console.log(res.tempFiles.tempFilePath)    console.log(res.tempFiles.size)  }})


          VideoContext

          VideoContext 实例,可通过 wx.createVideoContext 获取。

          VideoContext 通过 id 跟一个 video 组件绑定,操作对应的 video 组件。

          方法:

          VideoContext.exitFullScreen()

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

          退出全屏

          VideoContext.exitPictureInPicture(Object object)

          退出小窗,该方法可在任意页面调用

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          VideoContext.hideStatusBar()

          基础库 2.1.0 开始支持,低版本需做兼容处理。

          隐藏状态栏,仅在iOS全屏下有效

          VideoContext.pause()

          暂停视频

          VideoContext.play()

          播放视频

          VideoContext.playbackRate(number rate)

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

          设置倍速播放

          参数

          number rate

          倍率,支持 0.5/0.8/1.0/1.25/1.5,2.6.3 起支持 2.0 倍速

          VideoContext.requestFullScreen(Object object)

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

          进入全屏。若有自定义内容需在全屏时展示,需将内容节点放置到 video 节点内。

          参数

          Object object

          属性类型默认值必填说明最低版本
          directionnumber设置全屏时视频的方向,不指定则根据宽高比自动判断。1.7.0

          object.direction 的合法值

          说明最低版本
          0正常竖向
          90屏幕逆时针90度
          -90屏幕顺时针90度

          VideoContext.seek(number position)

          跳转到指定位置

          参数

          number position

          跳转到的位置,单位 s

          VideoContext.sendDanmu(Object data)

          发送弹幕

          参数

          Object data

          弹幕内容

          属性类型默认值必填说明
          textstring弹幕文字
          colorstring弹幕颜色

          VideoContext.showStatusBar()

          基础库 2.1.0 开始支持,低版本需做兼容处理。

          显示状态栏,仅在iOS全屏下有效

          VideoContext.stop()

          基础库 1.7.0 开始支持,低版本需做兼容处理。

          停止视频

          示例代码

          在开发者工具中预览效果

          <view class="section tc">  <video id="myVideo" src="http://wxsnsdy.tc.qq.com/105/20210/snsdyvideodownload?filekey=30280201010421301f0201690402534804102ca905ce620b1241b726bc41dcff44e00204012882540400&bizid=1023&hy=SH&fileparam=302c020101042530230204136ffd93020457e3c4ff02024ef202031e8d7f02030f42400204045a320a0201000400" rel="external nofollow"  enable-danmu danmu-btn controls></video>  <view class="btn-area">    <input bindblur="bindInputBlur"/>    <button bindtap="bindSendDanmu">发送弹幕</button>  </view></view>

          function getRandomColor () {  let rgb = []  for (let i = 0 ; i < 3; ++i) {    let color = Math.floor(Math.random() * 256).toString(16)    color = color.length == 1 ? '0' + color : color    rgb.push(color)  }  return '#' + rgb.join('')}Page({  onReady (res) {    this.videoContext = wx.createVideoContext('myVideo')  },  inputValue: '',  bindInputBlur (e) {    this.inputValue = e.detail.value  },  bindSendDanmu () {    this.videoContext.sendDanmu({      text: this.inputValue,      color: getRandomColor()    })  }})


          wx.stopVoice(Object object)

          从基础库 1.6.0 开始,本接口停止维护,请使用 wx.createInnerAudioContext 代替

          结束播放语音。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.startRecord({  success (res) {    const tempFilePath = res.tempFilePath    wx.playVoice({      filePath: tempFilePath,    })    setTimeout(() => { wx.stopVoice() }, 5000)  }})


          wx.setInnerAudioOption(Object object)

          基础库 2.3.0 开始支持,低版本需做兼容处理。

          设置 InnerAudioContext 的播放选项。设置之后对当前小程序全局生效。

          参数

          Object object

          属性类型默认值必填说明
          mixWithOtherbooleantrue是否与其他音频混播,设置为 true 之后,不会终止其他应用或微信内的音乐
          obeyMuteSwitchbooleantrue(仅在 iOS 生效)是否遵循静音开关,设置为 false 之后,即使是在静音模式下,也能播放声音
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          相关回答


          wx.playVoice(Object object)

          从基础库 1.6.0 开始,本接口停止维护,请使用 wx.createInnerAudioContext 代替

          开始播放语音。同时只允许一个语音文件正在播放,如果前一个语音文件还没播放完,将中断前一个语音播放。

          参数

          Object object

          属性类型默认值必填说明最低版本
          filePathstring需要播放的语音文件的文件路径 (本地路径)
          durationnumber60指定录音时长,到达指定的录音时长后会自动停止录音,单位:秒1.6.0
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.startRecord({  success (res) {    const tempFilePath = res.tempFilePath    wx.playVoice({      filePath: tempFilePath,      complete () { }    })  }})


          wx.pauseVoice(Object object)

          从基础库 1.6.0 开始,本接口停止维护,请使用 wx.createInnerAudioContext 代替

          暂停正在播放的语音。再次调用 wx.playVoice 播放同一个文件时,会从暂停处开始播放。如果想从头开始播放,需要先调用 wx.stopVoice。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.startRecord({  success (res) {    const tempFilePath = res.tempFilePath    wx.playVoice({      filePath: tempFilePath    })    setTimeout(() => { wx.pauseVoice() }, 5000)  }})


          wx.getAvailableAudioSources(Object object)

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

          获取当前支持的音频输入源

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          audioSourcesArray.<string>支持的音频输入源列表,可在 RecorderManager.start() 接口中使用。返回值定义参考 https://developer.android.com/reference/kotlin/android/media/MediaRecorder.AudioSource

          res.audioSources 的合法值

          说明最低版本
          auto自动设置,默认使用手机麦克风,插上耳麦后自动切换使用耳机麦克风,所有平台适用
          buildInMic手机麦克风,仅限 iOS
          headsetMic耳机麦克风,仅限 iOS
          mic麦克风(没插耳麦时是手机麦克风,插耳麦时是耳机麦克风),仅限 Android
          camcorder同 mic,适用于录制音视频内容,仅限 Android
          voice_communication同 mic,适用于实时沟通,仅限 Android
          voice_recognition同 mic,适用于语音识别,仅限 Android




          InnerAudioContext wx.createInnerAudioContext()

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

          创建内部 audio 上下文 InnerAudioContext 对象。

          返回值

          InnerAudioContext


          AudioContext wx.createAudioContext(string id, Object this)

          从基础库 1.6.0 开始,本接口停止维护,请使用 wx.createInnerAudioContext 代替

          创建 audio 上下文 AudioContext 对象。

          参数

          string id

          audio 组件的 id

          Object this

          在自定义组件下,当前组件实例的this,以操作组件内 audio 组件

          返回值

          AudioContext


          InnerAudioContext

          InnerAudioContext 实例,可通过 wx.createInnerAudioContext 接口获取实例。



          属性


          string src

          音频资源的地址,用于直接播放。2.2.3 开始支持云文件ID


          number startTime

          开始播放的位置(单位:s),默认为 0


          boolean autoplay

          是否自动开始播放,默认为 false


          boolean loop

          是否循环播放,默认为 false


          boolean obeyMuteSwitch

          是否遵循系统静音开关,默认为 true。当此参数为 false 时,即使用户打开了静音开关,也能继续发出声音。从 2.3.0 版本开始此参数不生效,使用 wx.setInnerAudioOption 接口统一设置。


          number volume

          音量。范围 0~1。默认为 1


          number playbackRate

          播放速度。范围 0.5-2.0,默认为 1。(Android 需要 6 及以上版本)


          number duration

          当前音频的长度(单位 s)。只有在当前有合法的 src 时返回(只读)


          number currentTime

          当前音频的播放位置(单位 s)。只有在当前有合法的 src 时返回,时间保留小数点后 6 位(只读)


          boolean paused

          当前是是否暂停或停止状态(只读)


          number buffered

          音频缓冲的时间点,仅保证当前播放时间点到此时间点内容已缓冲(只读)



          方法:

          InnerAudioContext.destroy()

          销毁当前实例


          InnerAudioContext.offCanplay(function callback)

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

          取消监听音频进入可以播放状态的事件

          参数

          function callback

          音频进入可以播放状态的事件的回调函数



          InnerAudioContext.offEnded(function callback)

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

          取消监听音频自然播放至结束的事件

          参数

          function callback

          音频自然播放至结束的事件的回调函数


          InnerAudioContext.offError(function callback)

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

          取消监听音频播放错误事件

          参数

          function callback

          音频播放错误事件的回调函数


          InnerAudioContext.offPause(function callback)

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

          取消监听音频暂停事件

          参数

          function callback

          音频暂停事件的回调函数


          InnerAudioContext.offPlay(function callback)

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

          取消监听音频播放事件

          参数

          function callback

          音频播放事件的回调函数


          InnerAudioContext.offSeeked(function callback)

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

          取消监听音频完成跳转操作的事件

          参数

          function callback

          音频完成跳转操作的事件的回调函数


          InnerAudioContext.offSeeking(function callback)

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

          取消监听音频进行跳转操作的事件

          参数

          function callback

          音频进行跳转操作的事件的回调函数


          InnerAudioContext.offStop(function callback)

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

          取消监听音频停止事件

          参数

          function callback

          音频停止事件的回调函数


          InnerAudioContext.offTimeUpdate(function callback)

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

          取消监听音频播放进度更新事件

          参数

          function callback

          音频播放进度更新事件的回调函数


          InnerAudioContext.offWaiting(function callback)

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

          取消监听音频加载中事件

          参数

          function callback

          音频加载中事件的回调函数


          InnerAudioContext.onCanplay(function callback)

          监听音频进入可以播放状态的事件。但不保证后面可以流畅播放

          参数

          function callback

          音频进入可以播放状态的事件的回调函数


          InnerAudioContext.onEnded(function callback)

          监听音频自然播放至结束的事件

          参数

          function callback

          音频自然播放至结束的事件的回调函数


          InnerAudioContext.onError(function callback)

          监听音频播放错误事件

          参数

          function callback

          音频播放错误事件的回调函数

          参数

          Object res
          属性类型说明
          errMsgstring
          errCodenumber

          errCode 的合法值

          说明最低版本
          10001系统错误
          10002网络错误
          10003文件错误
          10004格式错误
          -1未知错误


          InnerAudioContext.onPause(function callback)

          监听音频暂停事件

          参数

          function callback

          音频暂停事件的回调函数


          InnerAudioContext.onPlay(function callback)

          监听音频播放事件

          参数

          function callback

          音频播放事件的回调函数


          InnerAudioContext.onSeeked(function callback)

          监听音频完成跳转操作的事件

          参数

          function callback

          音频完成跳转操作的事件的回调函数


          InnerAudioContext.onSeeking(function callback)

          监听音频进行跳转操作的事件

          参数

          function callback

          音频进行跳转操作的事件的回调函数


          InnerAudioContext.onStop(function callback)

          监听音频停止事件

          参数

          function callback

          音频停止事件的回调函数


          InnerAudioContext.onTimeUpdate(function callback)

          监听音频播放进度更新事件

          参数

          function callback

          音频播放进度更新事件的回调函数


          InnerAudioContext.onWaiting(function callback)

          监听音频加载中事件。当音频因为数据不足,需要停下来加载时会触发

          参数

          function callback

          音频加载中事件的回调函数


          InnerAudioContext.pause()

          暂停。暂停后的音频再播放会从暂停处开始播放



          InnerAudioContext.play()

          播放


          InnerAudioContext.seek(number position)

          跳转到指定位置

          参数

          number position

          跳转的时间,单位 s。精确到小数点后 3 位,即支持 ms 级别精确度


          InnerAudioContext.stop()

          停止。停止后的音频再播放会从头开始播放。



          支持格式

          格式iOSAndroid
          flacx
          m4a
          oggx
          apex
          amrx
          wmax
          wav
          mp3
          mp4x
          aac
          aiffx
          cafx

          示例代码:

          const innerAudioContext = wx.createInnerAudioContext()innerAudioContext.autoplay = trueinnerAudioContext.src = 'http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E061FF02C31F716658E5C81F5594D561F2E88B854E81CAAB7806D5E4F103E55D33C16F3FAC506D1AB172DE8600B37E43FAD&fromtag=46'innerAudioContext.onPlay(() => {  console.log('开始播放')})innerAudioContext.onError((res) => {  console.log(res.errMsg)  console.log(res.errCode)})


          AudioContext

          AudioContext 实例,可通过 wx.createAudioContext 获取。

          AudioContext 通过 id 跟一个 audio 组件绑定,操作对应的 audio 组件。


          方法:

          AudioContext.pause()

          暂停音频。


          AudioContext.play()

          播放音频。


          AudioContext.seek(number position)

          跳转到指定位置。

          参数

          number position

          跳转位置,单位 s


          AudioContext.setSrc(string src)

          设置音频地址

          参数

          string src

          音频地址


          示例代码:

          <!-- audio.wxml --><audio  src="{{src}}" id="myAudio" ></audio><button type="primary" bindtap="audioPlay">播放</button><button type="primary" bindtap="audioPause">暂停</button><button type="primary" bindtap="audio14">设置当前播放时间为14秒</button><button type="primary" bindtap="audioStart">回到开头</button>
          // audio.jsPage({  onReady (e) {    // 使用 wx.createAudioContext 获取 audio 上下文 context    this.audioCtx = wx.createAudioContext('myAudio')    this.audioCtx.setSrc('http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E06DCBDC9AB7C49FD713D632D313AC4858BACB8DDD29067D3C601481D36E62053BF8DFEAF74C0A5CCFADD6471160CAF3E6A&fromtag=46')    this.audioCtx.play()  },  data: {    src: ''  },  audioPlay () {    this.audioCtx.play()  },  audioPause () {    this.audioCtx.pause()  },  audio14 () {    this.audioCtx.seek(14)  },  audioStart () {    this.audioCtx.seek(0)  }})


          wx.stopBackgroundAudio(Object object)

          从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

          停止播放音乐。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.stopBackgroundAudio()


          wx.seekBackgroundAudio(Object object)

          从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

          控制音乐播放进度。

          参数

          Object object

          属性类型默认值必填说明
          positionnumber音乐位置,单位:秒
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.seekBackgroundAudio({  position: 30})


          wx.playBackgroundAudio(Object object)

          从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

          使用后台播放器播放音乐。对于微信客户端来说,只能同时有一个后台音乐在播放。当用户离开小程序后,音乐将暂停播放;当用户在其他小程序占用了音乐播放器,原有小程序内的音乐将停止播放。

          参数

          Object object

          属性类型默认值必填说明
          dataUrlstring音乐链接,目前支持的格式有 m4a, aac, mp3, wav
          titlestring音乐标题
          coverImgUrlstring封面URL
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.playBackgroundAudio({  dataUrl: '',  title: '',  coverImgUrl: ''})


          wx.pauseBackgroundAudio(Object object)

          从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

          暂停播放音乐。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.pauseBackgroundAudio()


          wx.onBackgroundAudioStop(function callback)

          从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

          监听音乐停止事件。

          参数

          function callback

          音乐停止事件的回调函数


          wx.onBackgroundAudioPlay(function callback)

          从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

          监听音乐播放事件。

          参数

          function callback

          音乐播放事件的回调函数


          wx.onBackgroundAudioPause(function callback)

          从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

          监听音乐暂停事件。

          参数

          function callback

          音乐暂停事件的回调函数


          wx.getBackgroundAudioPlayerState(Object object)

          从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

          获取后台音乐播放状态。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          durationnumber选定音频的长度(单位:s),只有在音乐播放中时返回
          currentPositionnumber选定音频的播放位置(单位:s),只有在音乐播放中时返回
          statusnumber播放状态
          downloadPercentnumber音频的下载进度百分比,只有在音乐播放中时返回
          dataUrlstring歌曲数据链接,只有在音乐播放中时返回

          res.status 的合法值

          说明最低版本
          0暂停中
          1播放中
          2没有音乐播放

          示例代码

          wx.getBackgroundAudioPlayerState({  success (res) {    const status = res.status    const dataUrl = res.dataUrl    const currentPosition = res.currentPosition    const duration = res.duration    const downloadPercent = res.downloadPercent  }})


          BackgroundAudioManager wx.getBackgroundAudioManager()

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

          获取全局唯一的背景音频管理器。 小程序切入后台,如果音频处于播放状态,可以继续播放。但是后台状态不能通过调用API操纵音频的播放状态。

          从微信客户端6.7.2版本开始,若需要在小程序切后台后继续播放音频,需要在 app.json 中配置 requiredBackgroundModes 属性。开发版和体验版上可以直接生效,正式版还需通过审核。

          返回值

          BackgroundAudioManager


          BackgroundAudioManager

          BackgroundAudioManager 实例,可通过 wx.getBackgroundAudioManager 获取。

          属性

          string src

          音频的数据源(2.2.3 开始支持云文件ID)。默认为空字符串,当设置了新的 src 时,会自动开始播放,目前支持的格式有 m4a, aac, mp3, wav。


          number startTime

          音频开始播放的位置(单位:s)。


          string title

          音频标题,用于原生音频播放器音频标题(必填)。原生音频播放器中的分享功能,分享出去的卡片标题,也将使用该值。


          string epname

          专辑名,原生音频播放器中的分享功能,分享出去的卡片简介,也将使用该值。


          string singer

          歌手名,原生音频播放器中的分享功能,分享出去的卡片简介,也将使用该值。


          string coverImgUrl

          封面图 URL,用于做原生音频播放器背景图。原生音频播放器中的分享功能,分享出去的卡片配图及背景也将使用该图。


          string webUrl

          页面链接,原生音频播放器中的分享功能,分享出去的卡片简介,也将使用该值。


          string protocol

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

          音频协议。默认值为 'http',设置 'hls' 可以支持播放 HLS 协议的直播音频。


          number playbackRate

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

          播放速度。范围 0.5-2.0,默认为 1。(Android 需要 6 及以上版本)


          number duration

          当前音频的长度(单位:s),只有在有合法 src 时返回。(只读)


          number currentTime

          当前音频的播放位置(单位:s),只有在有合法 src 时返回。(只读)


          boolean paused

          当前是否暂停或停止。(只读)


          number buffered

          音频已缓冲的时间,仅保证当前播放时间点到此时间点内容已缓冲。(只读)



          方法:

          BackgroundAudioManager.onCanplay(function callback)

          监听背景音频进入可播放状态事件。 但不保证后面可以流畅播放

          参数

          function callback

          背景音频进入可播放状态事件的回调函数


          BackgroundAudioManager.onEnded(function callback)

          监听背景音频自然播放结束事件

          参数

          function callback

          背景音频自然播放结束事件的回调函数


          BackgroundAudioManager.onError(function callback)

          监听背景音频播放错误事件

          参数

          function callback

          背景音频播放错误事件的回调函数


          BackgroundAudioManager.onNext(function callback)

          监听用户在系统音乐播放面板点击下一曲事件(仅iOS)

          参数

          function callback

          用户在系统音乐播放面板点击下一曲事件的回调函数


          BackgroundAudioManager.onPause(function callback)

          监听背景音频暂停事件

          参数

          function callback

          背景音频暂停事件的回调函数


          BackgroundAudioManager.onPlay(function callback)

          监听背景音频播放事件

          参数

          function callback

          背景音频播放事件的回调函数


          BackgroundAudioManager.onPrev(function callback)

          监听用户在系统音乐播放面板点击上一曲事件(仅iOS)

          参数

          function callback

          用户在系统音乐播放面板点击上一曲事件的回调函数


          BackgroundAudioManager.onSeeked(function callback)

          监听背景音频完成跳转操作事件

          参数

          function callback

          背景音频完成跳转操作事件的回调函数


          BackgroundAudioManager.onSeeking(function callback)

          监听背景音频开始跳转操作事件

          参数

          function callback

          背景音频开始跳转操作事件的回调函数


          BackgroundAudioManager.onStop(function callback)

          监听背景音频停止事件

          参数

          function callback

          背景音频停止事件的回调函数


          BackgroundAudioManager.onTimeUpdate(function callback)

          监听背景音频播放进度更新事件,只有小程序在前台时会回调。

          参数

          function callback

          背景音频播放进度更新事件的回调函数


          BackgroundAudioManager.onWaiting(function callback)

          监听音频加载中事件。当音频因为数据不足,需要停下来加载时会触发

          参数

          function callback

          音频加载中事件的回调函数



          BackgroundAudioManager.pause()

          暂停音乐

          错误

          错误码错误信息说明
          10001系统错误
          10002网络错误
          10003文件错误
          10004格式错误
          -1未知错误



          BackgroundAudioManager.play()

          播放音乐

          错误

          错误码错误信息说明
          10001系统错误
          10002网络错误
          10003文件错误
          10004格式错误
          -1未知错误



          BackgroundAudioManager.seek(number currentTime)

          跳转到指定位置

          参数

          number currentTime

          跳转的位置,单位 s。精确到小数点后 3 位,即支持 ms 级别精确度

          错误

          错误码错误信息说明
          10001系统错误
          10002网络错误
          10003文件错误
          10004格式错误
          -1未知错误



          BackgroundAudioManager.stop()

          停止音乐

          错误

          错误码错误信息说明
          10001系统错误
          10002网络错误
          10003文件错误
          10004格式错误
          -1未知错误

          示例代码

          const backgroundAudioManager = wx.getBackgroundAudioManager()backgroundAudioManager.title = '此时此刻'backgroundAudioManager.epname = '此时此刻'backgroundAudioManager.singer = '许巍'backgroundAudioManager.coverImgUrl = 'http://y.gtimg.cn/music/photo_new/T002R300x300M000003rsKF44GyaSk.jpg?max_age=2592000'// 设置了 src 之后会自动播放backgroundAudioManager.src = 'http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E061FF02C31F716658E5C81F5594D561F2E88B854E81CAAB7806D5E4F103E55D33C16F3FAC506D1AB172DE8600B37E43FAD&fromtag=46'


          LivePusherContext wx.createLivePusherContext()

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

          创建 live-pusher 上下文 LivePusherContext 对象。

          返回值

          LivePusherContext


          LivePlayerContext wx.createLivePlayerContext(string id, Object this)

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

          创建 live-player 上下文 LivePlayerContext 对象。

          参数

          string id

          live-player 组件的 id

          Object this

          在自定义组件下,当前组件实例的this,以操作组件内 live-player 组件

          返回值

          LivePlayerContext


          LivePlayerContext

          LivePlayerContext 实例,可通过 wx.createLivePlayerContext 获取。

          LivePlayerContext 通过 id 跟一个 live-player 组件绑定,操作对应的 live-player 组件。



          方法:

          LivePlayerContext.exitFullScreen(Object object)

          退出全屏

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePlayerContext.exitPictureInPicture(Object object)

          退出小窗,该方法可在任意页面调用

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePlayerContext.mute(Object object)

          静音

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePlayerContext.pause(Object object)

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

          暂停

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePlayerContext.play(Object object)

          播放

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePlayerContext.requestFullScreen(Object object)

          进入全屏

          参数

          Object object

          属性类型默认值必填说明
          directionnumber0设置全屏时的方向
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.direction 的合法值

          说明最低版本
          0正常竖向
          90屏幕逆时针90度
          -90屏幕顺时针90度


          LivePlayerContext.resume(Object object)

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

          恢复

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePlayerContext.snapshot(string quality)

          基础库 2.7.1 开始支持,低版本需做兼容处理。

          截图

          参数

          string quality

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

          图片的质量,默认原图。有效值为 raw、compressed


          LivePlayerContext.stop(Object object)

          停止

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext 实例,可通过 wx.createLivePusherContext 获取。

          LivePusherContext 与页面内唯一的 live-pusher 组件绑定,操作对应的 live-pusher 组件。



          方法:


          LivePusherContext.pause(Object object)

          暂停推流

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.pauseBGM(Object object)

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

          暂停背景音

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.playBGM(Object object)

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

          播放背景音

          参数

          Object object

          属性类型默认值必填说明
          urlstring加入背景混音的资源地址
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.resume(Object object)

          恢复推流

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.resumeBGM(Object object)

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

          恢复背景音

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.setBGMVolume(Object object)

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

          设置背景音音量

          参数

          Object object

          属性类型默认值必填说明
          volumestring音量大小,范围是 0-1
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.setMICVolume(Object object)

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

          设置麦克风音量

          参数

          Object object

          属性类型默认值必填说明
          volumenumber音量大小,范围是 0.0-1.0
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.snapshot(string quality)

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

          快照

          参数

          string quality

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

          图片的质量,默认原图。有效值为 raw、compressed


          LivePusherContext.start(Object object)

          开始推流,同时开启摄像头预览

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.startPreview(Object object)

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

          开启摄像头预览

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.stop(Object object)

          停止推流,同时停止摄像头预览

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.stopBGM(Object object)

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

          停止背景音

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.stopPreview(Object object)

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

          关闭摄像头预览

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.switchCamera(Object object)

          切换前后摄像头

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          LivePusherContext.toggleTorch(Object object)

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

          切换手电筒

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          wx.startRecord(Object object)

          调用前需要 用户授权 scope.record
          从基础库 1.6.0 开始,本接口停止维护,请使用 wx.getRecorderManager 代替

          开始录音。当主动调用 wx.stopRecord,或者录音超过1分钟时自动结束录音。当用户离开小程序时,此接口无法调用。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          tempFilePathstring录音文件的临时路径 (本地路径)

          示例代码

          wx.startRecord({  success (res) {    const tempFilePath = res.tempFilePath  }})setTimeout(function () {  wx.stopRecord() // 结束录音}, 10000)


          wx.stopRecord(Object object)

          从基础库 1.6.0 开始,本接口停止维护,请使用 wx.getRecorderManager 代替

          停止录音。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.startRecord({  success (res) {    const tempFilePath = res.tempFilePath  }})setTimeout(function () {  wx.stopRecord() // 结束录音}, 10000)


          RecorderManager wx.getRecorderManager()

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

          获取全局唯一的录音管理器 RecorderManager

          返回值

          RecorderManager


          RecorderManager

          全局唯一的录音管理器


          方法:

          RecorderManager.onError(function callback)

          监听录音错误事件

          参数

          function callback

          录音错误事件的回调函数

          参数

          Object res
          属性类型说明
          errMsgstring错误信息


          RecorderManager.onFrameRecorded(function callback)

          监听已录制完指定帧大小的文件事件。如果设置了 frameSize,则会回调此事件。

          参数

          function callback

          已录制完指定帧大小的文件事件的兼容处理

          参数

          Object res
          属性类型说明
          frameBufferArrayBuffer录音分片数据
          isLastFrameboolean当前帧是否正常录音结束前的最后一帧


          RecorderManager.onInterruptionBegin(function callback)

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

          监听录音因为受到系统占用而被中断开始事件。以下场景会触发此事件:微信语音聊天、微信视频聊天。此事件触发后,录音会被暂停。pause 事件在此事件后触发

          参数

          function callback

          录音因为受到系统占用而被中断开始事件的回调函数


          RecorderManager.onInterruptionEnd(function callback)

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

          监听录音中断结束事件。在收到 interruptionBegin 事件之后,小程序内所有录音会暂停,收到此事件之后才可再次录音成功。

          参数

          function callback

          录音中断结束事件的回调函数


          RecorderManager.onPause(function callback)

          监听录音暂停事件

          参数

          function callback

          录音暂停事件的回调函数


          RecorderManager.onResume(function callback)

          监听录音继续事件

          参数

          function callback

          录音继续事件的回调函数


          RecorderManager.onStart(function callback)

          监听录音开始事件

          参数

          function callback

          录音开始事件的回调函数


          RecorderManager.onStop(function callback)

          监听录音结束事件

          参数

          function callback

          录音结束事件的回调函数

          参数

          Object res
          属性类型说明
          tempFilePathstring录音文件的临时路径 (本地路径)
          durationnumber录音总时长,单位:ms
          fileSizenumber录音文件大小,单位:Byte


          RecorderManager.pause()

          暂停录音


          RecorderManager.resume()

          继续录音


          RecorderManager.start(Object object)

          开始录音

          参数

          Object object

          属性类型默认值必填说明最低版本
          durationnumber60000录音的时长,单位 ms,最大值 600000(10 分钟)
          sampleRatenumber8000采样率
          numberOfChannelsnumber2录音通道数
          encodeBitRatenumber48000编码码率,有效值见下表格
          formatstringaac音频格式
          frameSizenumber指定帧大小,单位 KB。传入 frameSize 后,每录制指定帧大小的内容后,会回调录制的文件内容,不指定则不会回调。暂仅支持 mp3 格式。
          audioSourcestringauto指定录音的音频输入源,可通过 wx.getAvailableAudioSources() 获取当前可用的音频源2.1.0

          object.sampleRate 的合法值

          说明最低版本
          80008000 采样率
          1102511025 采样率
          1200012000 采样率
          1600016000 采样率
          2205022050 采样率
          2400024000 采样率
          3200032000 采样率
          4410044100 采样率
          4800048000 采样率

          object.numberOfChannels 的合法值

          说明最低版本
          11 个通道
          22 个通道

          object.format 的合法值

          说明最低版本
          mp3mp3 格式
          aacaac 格式
          wavwav 格式
          PCMpcm 格式

          object.audioSource 的合法值

          说明最低版本
          auto自动设置,默认使用手机麦克风,插上耳麦后自动切换使用耳机麦克风,所有平台适用
          buildInMic手机麦克风,仅限 iOS
          headsetMic耳机麦克风,仅限 iOS
          mic麦克风(没插耳麦时是手机麦克风,插耳麦时是耳机麦克风),仅限 Android
          camcorder同 mic,适用于录制音视频内容,仅限 Android
          voice_communication同 mic,适用于实时沟通,仅限 Android
          voice_recognition同 mic,适用于语音识别,仅限 Android

          采样率与编码码率限制

          每种采样率有对应的编码码率范围有效值,设置不合法的采样率或编码码率会导致录音失败,具体对应关系如下表。

          采样率编码码率
          800016000 ~ 48000
          1102516000 ~ 48000
          1200024000 ~ 64000
          1600024000 ~ 96000
          2205032000 ~ 128000
          2400032000 ~ 128000
          3200048000 ~ 192000
          4410064000 ~ 320000
          4800064000 ~ 320000


          RecorderManager.stop()

          停止录音



          示例代码

          const recorderManager = wx.getRecorderManager()recorderManager.onStart(() => {  console.log('recorder start')})recorderManager.onPause(() => {  console.log('recorder pause')})recorderManager.onStop((res) => {  console.log('recorder stop', res)  const { tempFilePath } = res})recorderManager.onFrameRecorded((res) => {  const { frameBuffer } = res  console.log('frameBuffer.byteLength', frameBuffer.byteLength)})const options = {  duration: 10000,  sampleRate: 44100,  numberOfChannels: 1,  encodeBitRate: 192000,  format: 'aac',  frameSize: 50}recorderManager.start(options)


          CameraContext wx.createCameraContext()

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

          创建 camera 上下文 CameraContext 对象。

          返回值

          CameraContext


          CameraContext

          CameraContext 实例,可通过 wx.createCameraContext 获取。

          CameraContext 与页面内唯一的 camera 组件绑定,操作对应的 camera 组件。



          方法:

          CameraFrameListener CameraContext.onCameraFrame(function callback)

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

          获取 Camera 实时帧数据

          参数

          function callback

          回调函数

          参数

          Object res
          属性类型说明
          widthnumber图像数据矩形的宽度
          heightnumber图像数据矩形的高度
          dataArrayBuffer图像像素点数据,一维数组,每四项表示一个像素点的 rgba

          返回值

          CameraFrameListener

          注: 使用该接口需同时在 camera 组件属性中指定 frame-size。

          示例代码

          const context = wx.createCameraContext()const listener = context.onCameraFrame((frame) => {  console.log(frame.data instanceof ArrayBuffer, frame.width, frame.height)})listener.start()


          CameraContext.setZoom(Object object)

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

          设置缩放级别

          参数

          Object object

          属性类型默认值必填说明
          zoomnumber缩放级别,范围[1, maxZoom]。zoom 可取小数,精确到小数后一位。maxZoom 可在 bindinitdone 返回值中获取。
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          zoomnumber实际设置的缩放级别。由于系统限制,某些机型可能无法设置成指定值,会改用最接近的可设值。


          CameraContext.startRecord(Object object)

          开始录像

          参数

          Object object

          属性类型默认值必填说明
          timeoutCallbackfunction超过30s或页面 onHide 时会结束录像
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.timeoutCallback 回调函数

          参数
          Object res
          属性类型说明
          tempThumbPathstring封面图片文件的临时路径 (本地路径)
          tempVideoPathstring视频的文件的临时路径 (本地路径)


          CameraContext.stopRecord(Object object)

          结束录像

          参数

          Object object

          属性类型默认值必填说明
          compressedbooleanfalse启动视频压缩,压缩效果同chooseVideo
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          tempThumbPathstring封面图片文件的临时路径 (本地路径)
          tempVideoPathstring视频的文件的临时路径 (本地路径)


          CameraContext.takePhoto(Object object)

          拍摄照片

          参数

          Object object

          属性类型默认值必填说明
          qualitystringnormal成像质量
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.quality 的合法值

          说明最低版本
          high高质量
          normal普通质量
          low低质量

          object.success 回调函数

          参数
          Object res
          属性类型说明
          tempImagePathstring照片文件的临时路径 (本地路径),安卓是jpg图片格式,ios是png


          CameraFrameListener

          CameraContext.onCameraFrame() 返回的监听器。


          方法:

          CameraFrameListener.start(Object object)

          开始监听帧数据

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          CameraFrameListener.stop(Object object)

          停止监听帧数据

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          EditorContext 实例,可通过 wx.createSelectorQuery 获取。

          EditorContext 通过 id 跟一个 editor 组件绑定,操作对应的 editor 组件。

          方法:

          EditorContext.blur(Object object)

          基础库 2.8.3 开始支持,低版本需做兼容处理。

          编辑器失焦,同时收起键盘。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.clear(Object object)

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          清空编辑器内容

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.format(string name, string value)

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          修改样式

          参数

          string name

          属性

          string value

          支持设置的样式列表

          namevalueverson
          bold2.7.0
          italic2.7.0
          underline2.7.0
          strike2.7.0
          ins2.7.0
          scriptsub / super2.7.0
          headerH1 / H2 / h3 / H4 / h5 / H62.7.0
          alignleft / center / right / justify2.7.0
          directionrtl2.7.0
          indent-1 / +12.7.0
          listordered / bullet / check2.7.0
          colorhex color2.7.0
          backgroundColorhex color2.7.0
          margin/marginTop/marginBottom/marginLeft/marginRightcss style2.7.0
          padding/paddingTop/paddingBottom/paddingLeft/paddingRightcss style2.7.0
          font/fontSize/fontStyle/fontVariant/fontWeight/fontFamilycss style2.7.0
          lineHeightcss style2.7.0
          letterSpacingcss style2.7.0
          textDecorationcss style2.7.0
          textIndentcss style2.8.0
          wordWrapcss style2.10.2
          wordBreakcss style2.10.2
          whiteSpacecss style2.10.2

          对已经应用样式的选区设置会取消样式。css style 表示 css 中规定的允许值。


          EditorContext.getContents(Object object)

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          获取编辑器内容

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          htmlstring带标签的HTML内容
          textstring纯文本内容
          deltaObject表示内容的delta对象


          EditorContext.getSelectionText(Object object)

          基础库 2.10.2 开始支持,低版本需做兼容处理。

          获取编辑器已选区域内的纯文本内容。当编辑器失焦或未选中一段区间时,返回内容为空。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          textstring纯文本内容


          EditorContext.insertDivider(Object object)

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          插入分割线

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.insertImage(Object object)

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          插入图片。

          地址为临时文件时,获取的编辑器html格式内容中 <img> 标签增加属性 data-local,delta 格式内容中图片 attributes 属性增加 data-local 字段,该值为传入的临时文件地址。

          开发者可选择在提交阶段上传图片到服务器,获取到网络地址后进行替换。替换时对于html内容应替换掉 <img> 的 src 值,对于 delta 内容应替换掉 insert { image: abc } 值。

          参数

          Object object

          属性类型默认值必填说明
          srcstring图片地址,仅支持 http(s)、base64、云图片(2.8.0)、临时文件(2.8.3)。
          altstring图像无法显示时的替代文本
          widthstring图片宽度(pixels/百分比)
          heightstring图片高度 (pixels/百分比)
          extClassstring添加到图片 img 标签上的类名
          dataObjectdata 被序列化为 name=value;name1=value2 的格式挂在属性 data-custom 上
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          this.editorCtx.insertImage({  src: 'xx',  width: '100px',  height: '50px',  extClass: className})


          EditorContext.insertText(Object object)

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          覆盖当前选区,设置一段文本

          参数

          Object object

          属性类型默认值必填说明
          textstring文本内容
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.redo(Object object)

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          恢复

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.removeFormat(Object object)

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          清除当前选区的样式

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.scrollIntoView()

          基础库 2.8.3 开始支持,低版本需做兼容处理。

          使得编辑器光标处滚动到窗口可视区域内。


          EditorContext.setContents(Object object)

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          初始化编辑器内容,html和delta同时存在时仅delta生效

          参数

          Object object

          属性类型默认值必填说明
          htmlstring带标签的HTML内容
          deltaObject表示内容的delta对象
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.undo(Object object)

          基础库 2.7.0 开始支持,低版本需做兼容处理。

          撤销

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext

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

          EditorContext 实例,可通过 wx.createSelectorQuery 获取。

          EditorContext 通过 id 跟一个 editor 组件绑定,操作对应的 editor 组件。



          方法:

          EditorContext.blur(Object object)

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

          编辑器失焦,同时收起键盘。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.clear(Object object)

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

          清空编辑器内容

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.format(string name, string value)

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

          修改样式

          参数

          string name

          属性

          string value

          支持设置的样式列表

          namevalueverson
          bold2.7.0
          italic2.7.0
          underline2.7.0
          strike2.7.0
          ins2.7.0
          scriptsub / super2.7.0
          headerH1 / H2 / h3 / H4 / h5 / H62.7.0
          alignleft / center / right / justify2.7.0
          directionrtl2.7.0
          indent-1 / +12.7.0
          listordered / bullet / check2.7.0
          colorhex color2.7.0
          backgroundColorhex color2.7.0
          margin/marginTop/marginBottom/marginLeft/marginRightcss style2.7.0
          padding/paddingTop/paddingBottom/paddingLeft/paddingRightcss style2.7.0
          font/fontSize/fontStyle/fontVariant/fontWeight/fontFamilycss style2.7.0
          lineHeightcss style2.7.0
          letterSpacingcss style2.7.0
          textDecorationcss style2.7.0
          textIndentcss style2.8.0
          wordWrapcss style2.10.2
          wordBreakcss style2.10.2
          whiteSpacecss style2.10.2

          对已经应用样式的选区设置会取消样式。css style 表示 css 中规定的允许值。


          EditorContext.getContents(Object object)

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

          获取编辑器内容

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          htmlstring带标签的HTML内容
          textstring纯文本内容
          deltaObject表示内容的delta对象


          EditorContext.getSelectionText(Object object)

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

          获取编辑器已选区域内的纯文本内容。当编辑器失焦或未选中一段区间时,返回内容为空。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          textstring纯文本内容


          EditorContext.insertDivider(Object object)

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

          插入分割线

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.insertImage(Object object)

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

          插入图片。

          地址为临时文件时,获取的编辑器html格式内容中 <img> 标签增加属性 data-local,delta 格式内容中图片 attributes 属性增加 data-local 字段,该值为传入的临时文件地址。

          开发者可选择在提交阶段上传图片到服务器,获取到网络地址后进行替换。替换时对于html内容应替换掉 <img> 的 src 值,对于 delta 内容应替换掉 insert { image: abc } 值。

          参数

          Object object

          属性类型默认值必填说明
          srcstring图片地址,仅支持 http(s)、base64、云图片(2.8.0)、临时文件(2.8.3)。
          altstring图像无法显示时的替代文本
          widthstring图片宽度(pixels/百分比)
          heightstring图片高度 (pixels/百分比)
          extClassstring添加到图片 img 标签上的类名
          dataObjectdata 被序列化为 name=value;name1=value2 的格式挂在属性 data-custom 上
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          this.editorCtx.insertImage({  src: 'xx',  width: '100px',  height: '50px',  extClass: className})


          EditorContext.insertText(Object object)

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

          覆盖当前选区,设置一段文本

          参数

          Object object

          属性类型默认值必填说明
          textstring文本内容
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.redo(Object object)

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

          恢复

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.removeFormat(Object object)

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

          清除当前选区的样式

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.scrollIntoView()

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

          使得编辑器光标处滚动到窗口可视区域内。

          EditorContext.setContents(Object object)

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

          初始化编辑器内容,html和delta同时存在时仅delta生效

          参数

          Object object

          属性类型默认值必填说明
          htmlstring带标签的HTML内容
          deltaObject表示内容的delta对象
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          EditorContext.undo(Object object)

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

          撤销

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          MediaContainer wx.createMediaContainer()

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

          创建音视频处理容器,最终可将容器中的轨道合成一个视频

          返回值

          MediaContainer


          MediaContainer

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

          可通过 wx.createMediaContainer 创建。

          MediaContainer 音视频处理容器,可以进行音频混音等操作



          方法:

          MediaContainer.addTrack(MediaTrack track)

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

          将音频或视频轨道添加到容器

          参数

          MediaTrack track

          要添加的音频或视频轨道


          MediaContainer.destroy()

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

          将容器销毁,释放资源


          MediaContainer.export()

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

          将容器内的轨道合并并导出视频文件


          MediaContainer.extractDataSource(Object object)

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

          将传入的视频源分离轨道。不会自动将轨道添加到待合成的容器里。

          参数

          Object object

          属性类型默认值必填说明
          sourcestring视频源地址,只支持本地文件


          MediaContainer.removeTrack(MediaTrack track)

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

          将音频或视频轨道从容器中移除

          参数

          MediaTrack track

          要移除的音频或视频轨道



          MediaTrack

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

          可通过 MediaContainer.extractDataSource 返回。

          MediaTrack 音频或视频轨道,可以对轨道进行一些操作

          属性

          string kind

          轨道类型,只读

          kind 的合法值

          说明最低版本
          audio音频轨道
          video视频轨道

          number duration

          轨道长度,只读

          number volume

          音量,音频轨道下有效,可写


          wx.updateVoIPChatMuteConfig(Object object)

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

          更新实时语音静音设置

          参数

          Object object

          属性类型默认值必填说明
          muteConfigObject静音设置
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.muteConfig 的结构

          属性类型默认值必填说明
          muteMicrophoneBooleanfalse是否静音麦克风
          muteEarphoneBooleanfalse是否静音耳机


          wx.onVoIPChatSpeakersChanged(function callback)

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

          监听实时语音通话成员通话状态变化事件。有成员开始/停止说话时触发回调

          参数

          function callback

          实时语音通话成员通话状态变化事件的回调函数

          参数

          Object res
          属性类型说明
          openIdListArray.<String>还在实时语音通话中的成员 openId 名单
          errCodeNumber错误码
          errMsgString调用结果(错误原因)


          wx.onVoIPChatMembersChanged(function callback)

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

          监听实时语音通话成员在线状态变化事件。有成员加入/退出通话时触发回调

          参数

          function callback

          实时语音通话成员在线状态变化事件的回调函数

          参数

          Object res
          属性类型说明
          openIdListArray.<String>还在实时语音通话中的成员 openId 名单
          errCodeNumber错误码
          errMsgString调用结果


          wx.onVoIPChatInterrupted(function callback)

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

          监听被动断开实时语音通话事件。包括小游戏切入后端时断开

          参数

          function callback

          被动断开实时语音通话事件的回调函数

          参数

          Object res
          属性类型说明
          errCodeNumber错误码
          errMsgString调用结果(错误原因)


          wx.onOnVoIPVideoMembersChanged(function callback)

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

          监听实时语音通话成员视频状态变化事件。

          参数

          function callback

          实时语音通话成员视频状态变化事件的回调函数

          参数

          Object res
          属性类型说明
          openIdListArray.<String>开启视频的成员名单
          errCodeNumber错误码
          errMsgString调用结果


          wx.offVoIPChatMembersChanged(function callback)

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

          取消监听实时语音通话成员在线状态变化事件。

          参数

          function callback

          实时语音通话成员在线状态变化事件的回调函数


          wx.offVoIPChatInterrupted(function callback)

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

          取消监听被动断开实时语音通话事件。

          参数

          function callback

          被动断开实时语音通话事件的回调函数


          wx.offOnVoIPVideoMembersChanged(function callback)

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

          取消监听实时语音通话成员视频状态变化事件

          参数

          function callback

          实时语音通话成员视频状态变化事件的回调函数


          wx.joinVoIPChat(Object object)

          基础库 2.7.0 开始支持,低版本需做兼容处理
          调用前需要 用户授权 scope.record

          加入 (创建) 实时语音通话,更多信息可见 实时语音指南

          参数

          Object object

          属性类型默认值必填说明
          roomTypeStringvoice房间类型
          signatureString签名,用于验证小游戏的身份
          nonceStrString验证所需的随机字符串
          timeStampNumber验证所需的时间戳
          groupIdString小游戏内此房间/群聊的 ID。同一时刻传入相同 groupId 的用户会进入到同个实时语音房间。
          muteConfigObject静音设置
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.roomType 的合法值

          说明最低版本
          voice音频房间,用于语音通话
          video视频房间,结合 voip-room 组件可显示成员画面

          object.muteConfig 的结构

          属性类型默认值必填说明
          muteMicrophoneBooleanfalse是否静音麦克风
          muteEarphoneBooleanfalse是否静音耳机

          object.success 回调函数

          参数
          Object res
          属性类型说明
          openIdListArray.<String>在此通话中的成员 openId 名单
          errCodeNumber错误码
          errMsgString调用结果

          错误

          错误码错误信息说明
          -1当前已在房间内
          -2录音设备被占用,可能是当前正在使用微信内语音通话或系统通话
          -3加入会话期间退出(可能是用户主动退出,或者退后台、来电等原因),因此加入失败
          -1000系统错误


          wx.exitVoIPChat(Object object)

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

          退出(销毁)实时语音通话

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          MediaRecorder wx.createMediaRecorder(Object canvas, Object options)

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

          创建 WebGL 画面录制器,可逐帧录制在 WebGL 上渲染的画面并导出视频文件

          参数

          Object canvas

          WebGL 对象,通过 SelectorQuery 获取到的 node 对象

          Object options

          属性类型默认值必填说明
          durationnumber600指定录制的时长(s),到达自动停止。最大 7200,最小 5
          videoBitsPerSecondnumber1000视频比特率(kbps),最小值 600,最大值 3000
          gopnumber12视频关键帧间隔
          fpsnumber24视频 fps

          返回值

          MediaRecorder


          MediaRecorder

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

          可通过 wx.createMediaRecorder 创建。

          MediaRecorder WebGL 画面录制器,可以进行录制相关操作,在结束录制时导出视频文件



          方法:

          MediaRecorder.destroy()

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

          销毁录制器


          MediaRecorder.off(string eventName, function callback)

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

          取消监听录制事件。当对应事件触发时,该回调函数不再执行。

          参数

          string eventName

          事件名

          function callback

          事件触发时执行的回调函数


          MediaRecorder.on(string eventName, function callback)

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

          注册监听录制事件的回调函数。当对应事件触发时,回调函数会被执行。

          参数

          string eventName

          事件名

          eventName 的合法值

          说明最低版本
          start录制开始事件。
          stop录制结束事件。返回 {tempFilePath, duration, fileSize}

          function callback

          事件触发时执行的回调函数


          MediaRecorder.pause()

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

          暂停录制


          MediaRecorder.requestFrame(function callback)

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

          请求下一帧录制,在 callback 里完成一帧渲染后开始录制当前帧

          参数

          function callback


          MediaRecorder.resume()

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

          恢复录制


          MediaRecorder.start()

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

          开始录制


          MediaRecorder.stop()

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

          结束录制


          VideoDecoder wx.createVideoDecoder()

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

          创建视频解码器,可逐帧获取解码后的数据

          返回值

          VideoDecoder


          VideoDecoder

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

          可通过 wx.createVideoDecoder 创建。

          VideoDecoder 视频解码器,可以进行视频解码相关操作,逐帧获取解码数据



          方法:

          Object VideoDecoder.getFrameData()

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

          获取下一帧的解码数据

          返回值

          Object

          视频帧数据,若取不到则返回 null。当缓冲区为空的时候可能暂停取不到数据。

          属性类型说明
          widthnumber帧数据宽度
          heightnumber帧数据高度
          dataArrayBuffer帧数据
          pkPtsnumber帧原始 pts
          pkDtsnumber帧原始 dts


          VideoDecoder.off(string eventName, function callback)

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

          取消监听录制事件。当对应事件触发时,该回调函数不再执行

          参数

          string eventName

          事件名

          function callback

          事件触发时执行的回调函数


          VideoDecoder.on(string eventName, function callback)

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

          注册监听录制事件的回调函数。当对应事件触发时,回调函数会被执行

          参数

          string eventName

          事件名

          eventName 的合法值

          说明最低版本
          start开始事件。返回 {width, height}
          stop结束事件。
          seekseek 完成事件。
          bufferchange缓冲区变化事件。
          ended解码结束事件。

          function callback

          事件触发时执行的回调函数


          VideoDecoder.remove()

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

          移除解码器


          VideoDecoder.seek(number position)

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

          跳到某个时间点解码

          参数

          number position

          跳转的解码位置,单位 ms


          VideoDecoder.start(Object object)

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

          开始解码

          参数

          Object object

          属性类型默认值必填说明
          sourcestring需要解码的视频源文件,只支持本地路径
          modenumber1解码模式。0:按 pts 解码;1:以最快速度解码


          VideoDecoder.stop()

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

          停止解码


          wx.saveFileToDisk(Object object)

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

          保存文件系统的文件到用户磁盘,仅在 PC 端支持

          参数

          Object object

          属性类型默认值必填说明
          filePathstring待保存文件路径
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          wx.saveFile(Object object)

          保存文件到本地。注意:saveFile 会把临时文件移动,因此调用成功后传入的 tempFilePath 将不可用

          参数

          Object object

          属性类型默认值必填说明
          tempFilePathstring需要保存的文件的临时路径 (本地路径)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          savedFilePathnumber存储后的文件路径 (本地路径)

          示例代码

          wx.chooseImage({  success: function(res) {    const tempFilePaths = res.tempFilePaths    wx.saveFile({      tempFilePath: tempFilePaths[0],      success (res) {        const savedFilePath = res.savedFilePath      }    })  }})

          注意

          本地文件存储的大小限制为 10M


          wx.removeSavedFile(Object object)

          删除本地缓存文件

          参数

          Object object

          属性类型默认值必填说明
          filePathstring需要删除的文件路径 (本地路径)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.getSavedFileList({ success (res) {   if (res.fileList.length > 0){     wx.removeSavedFile({       filePath: res.fileList[0].filePath,       complete (res) {         console.log(res)       }     })   } }})


          wx.openDocument(Object object)

          删除本地缓存文件。微信客户端 7.0.12 版本前默认显示右上角菜单按钮,之后的版本默认不显示,需主动传入 showMenu。

          参数

          Object object

          属性类型默认值必填说明最低版本
          filePathstring文件路径 (本地路径) ,可通过 downloadFile 获得
          showMenubooleanfalse是否显示右上角菜单2.11.0
          fileTypestring文件类型,指定文件类型打开文件1.4.0
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fileType 的合法值

          说明最低版本
          docdoc 格式
          docxdocx 格式
          xlsxls 格式
          xlsxxlsx 格式
          pptppt 格式
          pptxpptx 格式
          pdfpdf 格式

          示例代码

          wx.downloadFile({  // 示例 url,并非真实存在  url: 'http://example.com/somefile.pdf',  success: function (res) {    const filePath = res.tempFilePath    wx.openDocument({      filePath: filePath,      success: function (res) {        console.log('打开文档成功')      }    })  }})


          wx.getSavedFileList(Object object)

          获取该小程序下已保存的本地缓存文件列表

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          fileListArray.<Object>文件数组,每一项是一个 FileItem

          res.fileList 的结构

          属性类型说明
          filePathstring文件路径 (本地路径)
          sizenumber本地文件大小,以字节为单位
          createTimenumber文件保存时的时间戳,从1970/01/01 08:00:00 到当前时间的秒数

          示例代码

          wx.getSavedFileList({  success (res) {    console.log(res.fileList)  }})


          wx.getSavedFileInfo(Object object)

          获取本地文件的文件信息。此接口只能用于获取已保存到本地的文件,若需要获取临时文件信息,请使用 wx.getFileInfo() 接口。

          参数

          Object object

          属性类型默认值必填说明
          filePathstring文件路径 (本地路径)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          sizenumber文件大小,单位 B
          createTimenumber文件保存时的时间戳,从1970/01/01 08:00:00 到该时刻的秒数

          示例代码

          wx.getSavedFileList({  success (res) {    console.log(res.fileList)  }})


          FileSystemManager wx.getFileSystemManager()

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

          获取全局唯一的文件管理器

          返回值

          FileSystemManager

          文件管理器


          wx.getFileInfo(Object object)

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

          获取文件信息

          参数

          Object object

          属性类型默认值必填说明
          filePathstring本地文件路径 (本地路径)
          digestAlgorithmstring'md5'计算文件摘要的算法
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.digestAlgorithm 的合法值

          说明最低版本
          md5md5 算法
          sha1sha1 算法

          object.success 回调函数

          参数
          Object res
          属性类型说明
          sizenumber文件大小,以字节为单位
          digeststring按照传入的 digestAlgorithm 计算得出的的文件摘要

          示例代码

          wx.getFileInfo({  success (res) {    console.log(res.size)    console.log(res.digest)  }})


          FileSystemManager

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

          文件管理器


          方法:

          FileSystemManager.access(Object object)

          判断文件/目录是否存在

          参数

          Object object

          属性类型默认值必填说明
          pathstring要判断是否存在的文件/目录路径 (本地路径)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail no such file or directory ${path}文件/目录不存在



          FileSystemManager.accessSync(string path)

          FileSystemManager.access 的同步版本

          参数

          string path

          要判断是否存在的文件/目录路径 (本地路径)

          错误

          错误码错误信息说明
          fail no such file or directory ${path}文件/目录不存在


          FileSystemManager.appendFile(Object object)

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

          在文件结尾追加内容

          参数

          Object object

          属性类型默认值必填说明
          filePathstring要追加内容的文件路径 (本地路径)
          datastring/ArrayBuffer要追加的文本或二进制数据
          encodingstringutf8指定写入文件的字符编码
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.encoding 的合法值

          说明最低版本
          ascii
          base64
          binary
          hex
          ucs2以小端序读取
          ucs-2以小端序读取
          utf16le以小端序读取
          utf-16le以小端序读取
          utf-8
          utf8
          latin1

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail no such file or directory, open ${filePath}指定的 filePath 文件不存在
          fail illegal operation on a directory, open "${filePath}"指定的 filePath 是一个已经存在的目录
          fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
          fail sdcard not mounted指定的 filePath 是一个已经存在的目录


          FileSystemManager.appendFileSync(string filePath, string|ArrayBuffer data, string encoding)

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

          FileSystemManager.appendFile 的同步版本

          参数

          string filePath

          要追加内容的文件路径 (本地路径)

          string|ArrayBuffer data

          要追加的文本或二进制数据

          string encoding

          指定写入文件的字符编码

          encoding 的合法值

          说明最低版本
          ascii
          base64
          binary
          hex
          ucs2以小端序读取
          ucs-2以小端序读取
          utf16le以小端序读取
          utf-16le以小端序读取
          utf-8
          utf8
          latin1

          错误

          错误码错误信息说明
          fail no such file or directory, open ${filePath}指定的 filePath 文件不存在
          fail illegal operation on a directory, open "${filePath}"指定的 filePath 是一个已经存在的目录
          fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
          fail sdcard not mounted指定的 filePath 是一个已经存在的目录


          FileSystemManager.copyFile(Object object)

          复制文件

          参数

          Object object

          属性类型默认值必填说明
          srcPathstring源文件路径,支持本地路径
          destPathstring目标文件路径,支持本地路径
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail permission denied, copyFile ${srcPath} -> ${destPath}指定目标文件路径没有写权限
          fail no such file or directory, copyFile ${srcPath} -> ${destPath}源文件不存在,或目标文件路径的上层目录不存在
          fail the maximum size of the file storage limit is exceeded存储空间不足


          FileSystemManager.copyFileSync(string srcPath, string destPath)

          FileSystemManager.copyFile 的同步版本

          参数

          string srcPath

          源文件路径,支持本地路径

          string destPath

          目标文件路径,支持本地路径

          错误

          错误码错误信息说明
          fail permission denied, copyFile ${srcPath} -> ${destPath}指定目标文件路径没有写权限
          fail no such file or directory, copyFile ${srcPath} -> ${destPath}源文件不存在,或目标文件路径的上层目录不存在
          fail the maximum size of the file storage limit is exceeded存储空间不足


          FileSystemManager.getFileInfo(Object object)

          获取该小程序下的 本地临时文件 或 本地缓存文件 信息

          参数

          Object object

          属性类型默认值必填说明
          filePathstring要读取的文件路径 (本地路径)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          sizenumber文件大小,以字节为单位

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail file not exist指定的 filePath 找不到文件


          FileSystemManager.getSavedFileList(Object object)

          获取该小程序下已保存的本地缓存文件列表

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          fileListArray.<Object>文件数组

          res.fileList 的结构

          属性类型说明
          filePathstring文件路径 (本地路径)
          sizenumber本地文件大小,以字节为单位
          createTimenumber文件保存时的时间戳,从1970/01/01 08:00:00 到当前时间的秒数


          FileSystemManager.mkdir(Object object)

          创建目录

          参数

          Object object

          属性类型默认值必填说明最低版本
          dirPathstring创建的目录路径 (本地路径)
          recursivebooleanfalse是否在递归创建该目录的上级目录后再创建该目录。如果对应的上级目录已经存在,则不创建该上级目录。如 dirPath 为 a/b/c/d 且 recursive 为 true,将创建 a 目录,再在 a 目录下创建 b 目录,以此类推直至创建 a/b/c 目录下的 d 目录。2.3.0
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail no such file or directory ${dirPath}上级目录不存在
          fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
          fail file already exists ${dirPath}有同名文件或目录


          FileSystemManager.mkdirSync(string dirPath, boolean recursive)

          FileSystemManager.mkdir 的同步版本

          参数

          string dirPath

          创建的目录路径 (本地路径)

          boolean recursive

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

          是否在递归创建该目录的上级目录后再创建该目录。如果对应的上级目录已经存在,则不创建该上级目录。如 dirPath 为 a/b/c/d 且 recursive 为 true,将创建 a 目录,再在 a 目录下创建 b 目录,以此类推直至创建 a/b/c 目录下的 d 目录。

          错误

          错误码错误信息说明
          fail no such file or directory ${dirPath}上级目录不存在
          fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
          fail file already exists ${dirPath}有同名文件或目录


          FileSystemManager.readdir(Object object)

          读取目录内文件列表

          参数

          Object object

          属性类型默认值必填说明
          dirPathstring要读取的目录路径 (本地路径)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          filesArray.<string>指定目录下的文件名数组。

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail no such file or directory ${dirPath}目录不存在
          fail not a directory ${dirPath}dirPath 不是目录
          fail permission denied, open ${dirPath}指定的 filePath 路径没有读权限


          Array.<string> FileSystemManager.readdirSync(string dirPath)

          FileSystemManager.readdir 的同步版本

          参数

          string dirPath

          要读取的目录路径 (本地路径)

          返回值

          Array.<string> files

          指定目录下的文件名数组。

          错误

          错误码错误信息说明
          fail no such file or directory ${dirPath}目录不存在
          fail not a directory ${dirPath}dirPath 不是目录
          fail permission denied, open ${dirPath}指定的 filePath 路径没有读权限


          FileSystemManager.readFile(Object object)

          读取本地文件内容

          参数

          Object object

          属性类型默认值必填说明最低版本
          filePathstring要读取的文件的路径 (本地路径)
          encodingstring指定读取文件的字符编码,如果不传 encoding,则以 ArrayBuffer 格式读取文件的二进制内容
          positionstring从文件指定位置开始读,如果不指定,则从文件头开始读。读取的范围应该是左闭右开区间 [position, position+length)。有效范围:[0, fileLength - 1]。单位:byte2.10.0
          lengthstring指定文件的长度,如果不指定,则读到文件末尾。有效范围:[1, fileLength]。单位:byte2.10.0
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.encoding 的合法值

          说明最低版本
          ascii
          base64
          binary
          hex
          ucs2以小端序读取
          ucs-2以小端序读取
          utf16le以小端序读取
          utf-16le以小端序读取
          utf-8
          utf8
          latin1

          object.success 回调函数

          参数
          Object res
          属性类型说明
          datastring/ArrayBuffer文件内容

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail no such file or directory, open ${filePath}指定的 filePath 所在目录不存在
          fail permission denied, open ${dirPath}指定的 filePath 路径没有读权限


          string|ArrayBuffer FileSystemManager.readFileSync(string filePath, string encoding, string position, string length)

          FileSystemManager.readFile 的同步版本

          参数

          string filePath

          要读取的文件的路径 (本地路径)

          string encoding

          指定读取文件的字符编码,如果不传 encoding,则以 ArrayBuffer 格式读取文件的二进制内容

          encoding 的合法值

          说明最低版本
          ascii
          base64
          binary
          hex
          ucs2以小端序读取
          ucs-2以小端序读取
          utf16le以小端序读取
          utf-16le以小端序读取
          utf-8
          utf8
          latin1

          string position

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

          从文件指定位置开始读,如果不指定,则从文件头开始读。读取的范围应该是左闭右开区间 [position, position+length)。有效范围:[0, fileLength - 1]。单位:byte

          string length

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

          指定文件的长度,如果不指定,则读到文件末尾。有效范围:[1, fileLength]。单位:byte

          返回值

          string|ArrayBuffer data

          文件内容

          错误

          错误码错误信息说明
          fail no such file or directory, open ${filePath}指定的 filePath 所在目录不存在
          fail permission denied, open ${dirPath}指定的 filePath 路径没有读权限


          FileSystemManager.removeSavedFile(Object object)

          删除该小程序下已保存的本地缓存文件

          参数

          Object object

          属性类型默认值必填说明
          filePathstring需要删除的文件路径 (本地路径)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail file not exist指定的 tempFilePath 找不到文件


          FileSystemManager.rename(Object object)

          重命名文件。可以把文件从 oldPath 移动到 newPath

          参数

          Object object

          属性类型默认值必填说明
          oldPathstring源文件路径,支持本地路径
          newPathstring新文件路径,支持本地路径
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail permission denied, rename ${oldPath} -> ${newPath}指定源文件或目标文件没有写权限
          fail no such file or directory, rename ${oldPath} -> ${newPath}源文件不存在,或目标文件路径的上层目录不存在


          FileSystemManager.renameSync(string oldPath, string newPath)

          FileSystemManager.rename 的同步版本

          参数

          string oldPath

          源文件路径,支持本地路径

          string newPath

          新文件路径,支持本地路径

          错误

          错误码错误信息说明
          fail permission denied, rename ${oldPath} -> ${newPath}指定源文件或目标文件没有写权限
          fail no such file or directory, rename ${oldPath} -> ${newPath}源文件不存在,或目标文件路径的上层目录不存在


          FileSystemManager.rmdir(Object object)

          删除目录

          参数

          Object object

          属性类型默认值必填说明最低版本
          dirPathstring要删除的目录路径 (本地路径)
          recursivebooleanfalse是否递归删除目录。如果为 true,则删除该目录和该目录下的所有子目录以及文件。2.3.0
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail no such file or directory ${dirPath}目录不存在
          fail directory not empty目录不为空
          fail permission denied, open ${dirPath}指定的 dirPath 路径没有写权限


          FileSystemManager.rmdirSync(string dirPath, boolean recursive)

          FileSystemManager.rmdir 的同步版本

          参数

          string dirPath

          要删除的目录路径 (本地路径)

          boolean recursive

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

          是否递归删除目录。如果为 true,则删除该目录和该目录下的所有子目录以及文件。

          错误

          错误码错误信息说明
          fail no such file or directory ${dirPath}目录不存在
          fail directory not empty目录不为空
          fail permission denied, open ${dirPath}指定的 dirPath 路径没有写权限


          FileSystemManager.saveFile(Object object)

          保存临时文件到本地。此接口会移动临时文件,因此调用成功后,tempFilePath 将不可用。

          参数

          Object object

          属性类型默认值必填说明
          tempFilePathstring临时存储文件路径 (本地路径)
          filePathstring要存储的文件路径 (本地路径)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          savedFilePathstring存储后的文件路径 (本地路径)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail tempFilePath file not exist指定的 tempFilePath 找不到文件
          fail permission denied, open "${filePath}"指定的 filePath 路径没有写权限
          fail no such file or directory "${dirPath}"上级目录不存在
          fail the maximum size of the file storage limit is exceeded存储空间不足


          string FileSystemManager.saveFileSync(string tempFilePath, string filePath)

          FileSystemManager.saveFile 的同步版本

          参数

          string tempFilePath

          临时存储文件路径 (本地路径)

          string filePath

          要存储的文件路径 (本地路径)

          返回值

          string savedFilePath

          存储后的文件路径 (本地路径)

          错误

          错误码错误信息说明
          fail tempFilePath file not exist指定的 tempFilePath 找不到文件
          fail permission denied, open "${filePath}"指定的 filePath 路径没有写权限
          fail no such file or directory "${dirPath}"上级目录不存在
          fail the maximum size of the file storage limit is exceeded存储空间不足


          FileSystemManager.stat(Object object)

          获取文件 Stats 对象

          参数

          Object object

          属性类型默认值必填说明最低版本
          pathstring文件/目录路径 (本地路径)
          recursivebooleanfalse是否递归获取目录下的每个文件的 Stats 信息2.3.0
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          statsStats/Object当 recursive 为 false 时,res.stats 是一个 Stats 对象。当 recursive 为 true 且 path 是一个目录的路径时,res.stats 是一个 Object,key 以 path 为根路径的相对路径,value 是该路径对应的 Stats 对象。

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail permission denied, open ${path}指定的 path 路径没有读权限
          fail no such file or directory ${path}文件不存在

          示例代码

          recursive 为 false 时

          let fs = wx.getFileSystemManager()fs.stat({  path: `${wx.env.USER_DATA_PATH}/testDir`,  success: res => {    console.log(res.stats.isDirectory())  }})

          recursive 为 true 时

          fs.stat({  path: `${wx.env.USER_DATA_PATH}/testDir`,  recursive: true,  success: res => {    Object.keys(res.stats).forEach(path => {      let stats = res.stats[path]      console.log(path, stats.isDirectory())    })  }})


          Stats|Object FileSystemManager.statSync(string path, boolean recursive)

          FileSystemManager.stat 的同步版本

          参数

          string path

          文件/目录路径 (本地路径)

          boolean recursive

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

          是否递归获取目录下的每个文件的 Stats 信息

          返回值

          Stats|Object stats

          当 recursive 为 false 时,res.stats 是一个 Stats 对象。当 recursive 为 true 且 path 是一个目录的路径时,res.stats 是一个 Object,key 以 path 为根路径的相对路径,value 是该路径对应的 Stats 对象。

          错误

          错误码错误信息说明
          fail permission denied, open ${path}指定的 path 路径没有读权限
          fail no such file or directory ${path}文件不存在

          示例代码

          recursive 为 false 时

          let fs = wx.getFileSystemManager()fs.stat({  path: `${wx.env.USER_DATA_PATH}/testDir`,  success: res => {    console.log(res.stats.isDirectory())  }})

          recursive 为 true 时

          fs.stat({  path: `${wx.env.USER_DATA_PATH}/testDir`,  recursive: true,  success: res => {    Object.keys(res.stats).forEach(path => {      let stats = res.stats[path]      console.log(path, stats.isDirectory())    })  }})


          FileSystemManager.unlink(Object object)

          删除文件

          参数

          Object object

          属性类型默认值必填说明
          filePathstring要删除的文件路径 (本地路径)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值


          说明最低版本
          fail permission denied, open ${path}指定的 path 路径没有读权限
          fail no such file or directory ${path}文件不存在
          fail operation not permitted, unlink ${filePath}传入的 filePath 是一个目录


          FileSystemManager.unlinkSync(string filePath)

          FileSystemManager.unlink 的同步版本

          参数

          string filePath

          要删除的文件路径 (本地路径)

          错误

          错误码错误信息说明
          fail permission denied, open ${path}指定的 path 路径没有读权限
          fail no such file or directory ${path}文件不存在
          fail operation not permitted, unlink ${filePath}传入的 filePath 是一个目录


          FileSystemManager.unzip(Object object)

          解压文件

          参数

          Object object

          属性类型默认值必填说明
          zipFilePathstring源文件路径,支持本地路径, 只可以是 zip 压缩文件
          targetPathstring目标目录路径, 支持本地路径
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail permission denied, unzip ${zipFilePath} -> ${destPath}指定目标文件路径没有写权限
          fail no such file or directory, unzip ${zipFilePath} -> "${destPath}源文件不存在,或目标文件路径的上层目录不存在


          FileSystemManager.writeFile(Object object)

          写文件

          参数

          Object object

          属性类型默认值必填说明
          filePathstring要写入的文件路径 (本地路径)
          datastring/ArrayBuffer要写入的文本或二进制数据
          encodingstringutf8指定写入文件的字符编码
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.encoding 的合法值

          说明最低版本
          ascii
          base64
          binary
          hex
          ucs2以小端序读取
          ucs-2以小端序读取
          utf16le以小端序读取
          utf-16le以小端序读取
          utf-8
          utf8
          latin1

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgstring错误信息

          res.errMsg 的合法值

          说明最低版本
          fail no such file or directory, open ${filePath}指定的 filePath 所在目录不存在
          fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
          fail the maximum size of the file storage limit is exceeded存储空间不足


          FileSystemManager.writeFileSync(string filePath, string|ArrayBuffer data, string encoding)

          FileSystemManager.writeFile 的同步版本

          参数

          string filePath

          要写入的文件路径 (本地路径)

          string|ArrayBuffer data

          要写入的文本或二进制数据

          string encoding

          指定写入文件的字符编码

          encoding 的合法值

          说明最低版本
          ascii
          base64
          binary
          hex
          ucs2以小端序读取
          ucs-2以小端序读取
          utf16le以小端序读取
          utf-16le以小端序读取
          utf-8
          utf8
          latin1

          错误

          错误码错误信息说明
          fail no such file or directory, open ${filePath}指定的 filePath 所在目录不存在
          fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
          fail the maximum size of the file storage limit is exceeded存储空间不足




          Stats

          描述文件状态的对象


          属性

          属性说明
          string mode文件的类型和存取的权限,对应 POSIX stat.st_mode
          number size文件大小,单位:B,对应 POSIX stat.st_size
          number lastAccessedTime文件最近一次被存取或被执行的时间,UNIX 时间戳,对应 POSIX stat.st_atime
          number lastModifiedTime文件最后一次被修改的时间,UNIX 时间戳,对应 POSIX stat.st_mtime

          方法:

          boolean Stats.isDirectory()

          判断当前文件是否一个目录

          返回值

          boolean

          表示当前文件是否一个目录

          boolean Stats.isFile()

          判断当前文件是否一个普通文件

          返回值

          boolean

          表示当前文件是否一个普通文件


          每个微信小程序都可以有自己的本地缓存,可以通过wx.setStorage(wx.setStorageSync)、wx.getStorage(wx.getStorageSync)、wx.clearStorage(wx.clearStorageSync)可以对本地缓存进行设置、获取和清理。同一个微信用户,同一个小程序 storage 上限为 10MB。localStorage 以用户维度隔离,同一台设备上,A 用户无法读取到 B 用户的数据。

          注意: localStorage是永久存储的,但是我们不建议将关键信息全部存在localStorage,以防用户换设备的情况。

          wx.setStorage(OBJECT)


          将数据存储在本地缓存中指定的key中,会覆盖掉原来该key对应的内容,这是一个异步接口。

          OBJECT参数说明:

          参数类型必填说明
          keyString本地缓存中的指定的 key
          dataObject/String需要存储的内容
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

          wx.setStorage({  key:"key"  data:"value"})

          wx.setStorageSync(KEY,DATA)


          ​将data存储在本地缓存中指定的key中,会覆盖掉原来该key对应的内容,这是一个同步接口。

          参数说明:

          参数类型必填说明
          keyString本地缓存中的指定的key
          dataObject/String需要存储的内容

          示例代码

          try {   wx.setStorageSync("key","value")} catch (e) {}

          wx.getStorage(OBJECT)


          从本地缓存中异步获取指定key对应的内容。

          OBJECT参数说明:

          参数类型必填说明
          keyString本地缓存中的指定的 key
          successFunction接口调用的回调函数,res = {data: key对应的内容}
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数类型说明
          dataStringkey对应的内容

          示例代码:

          wx.getStorage({  key:'key',  success: function(res){      console.log(res.data)  } })

          wx.getStorageSync(KEY)


          ​从本地缓存中同步获取指定key对应的内容。

          参数说明:

          参数类型必填说明
          keyString本地缓存中的指定的key

          示例代码:

          try {  var value = wx.getStorageSync('key')  if (value) {      // Do something with return value  }} catch (e) {  // Do something when catch error}

          wx.getStorageInfo(OBJECT)

          异步获取当前storage的相关信息

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用的回调函数,详见返回参数说明
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数类型说明
          keysString Array当前storage中所有的key
          currentSizeNumber当前占用的空间大小, 单位kb
          limitSizeNumber限制的空间大小,单位kb

          示例代码:

          wx.getStorageInfo({  success: function(res) {    console.log(res.keys)    console.log(res.currentSize)    console.log(res.limitSize)  }})

          wx.getStorageInfoSync

          同步获取当前storage的相关信息

          示例代码:

          try {  var res = wx.getStorageInfoSync()  console.log(res.keys)  console.log(res.currentSize)  console.log(res.limitSize)} catch (e) {  // Do something when catch error}

          wx.removeStorage(OBJECT)

          从本地缓存中异步移除指定 key 。

          OBJECT参数说明:

          参数类型必填说明
          keyString本地缓存中的指定的 key
          successFunction接口调用的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.removeStorage({  key: 'key',  success: function(res) {    console.log(res.data)  } })

          wx.removeStorageSync(KEY)

          从本地缓存中同步移除指定 key 。

          参数说明:

          参数类型必填说明
          keyString本地缓存中的指定的 key

          示例代码:

          try {  wx.removeStorageSync('key')} catch (e) {  // Do something when catch error}

          wx.clearStorage()


          ​清理本地数据缓存。

          示例代码:

          wx.clearStorage()

          wx.clearStorageSync()


          同步清理本地数据缓存

          示例代码:

          try {    wx.clearStorageSync()} catch(e) {  // Do something when catch error}

          Bug & Tip

          1. tip: 本地数据存储的大小限制为 10MB


          wx.getLocation(OBJECT)

          获取当前的地理位置、速度。当用户离开小程序后,此接口无法调用;当用户点击“显示在聊天顶部”时,此接口可继续调用。

          OBJECT参数说明:

          参数 类型 必填 说明
          type String 默认为"wgs84"返回gps坐标,"gcj02"返回可用于wx.openLocation的坐标
          success Function 接口调用成功的回调函数,返回内容详见返回参数说明。
          fail Function 接口调用失败的回调函数
          complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数说明最低版本
          latitude纬度,浮点数,范围为-90~90,负数表示南纬 
          longitude经度,浮点数,范围为-180~180,负数表示西经 
          speed速度,浮点数,单位m/s 
          accuracy位置的精确度 
          altitude高度,单位 m1.2.0
          verticalAccuracy垂直精度,单位 m(Android 无法获取,返回 0)1.2.0
          horizontalAccuracy水平精度,单位 m1.2.0

          示例代码:

          wx.getLocation({  type: 'wgs84',  success: function(res) {    var latitude = res.latitude    var longitude = res.longitude    var speed = res.speed    var accuracy = res.accuracy  }})


          wx.chooseLocation(OBJECT)


          打开地图选择位置。

          需要用户授权 scope.userLocation

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数,返回内容详见返回参数说明。
          cancelFunction用户取消时调用
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数说明
          name位置名称
          address详细地址
          latitude纬度,浮点数,范围为-90~90,负数表示南纬
          longitude经度,浮点数,范围为-180~180,负数表示西经



          wx.getLocation(OBJECT)


          获取当前的地理位置、速度。当用户离开小程序后,此接口无法调用;当用户点击“显示在聊天顶部”时,此接口可继续调用。

          OBJECT参数说明:

          参数类型必填说明
          typeString默认为 wgs84 返回 gps 坐标,gcj02 返回可用于wx.openLocation的坐标
          successFunction接口调用成功的回调函数,返回内容详见返回参数说明。
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数说明最低版本
          latitude纬度,浮点数,范围为-90~90,负数表示南纬
          longitude经度,浮点数,范围为-180~180,负数表示西经
          speed速度,浮点数,单位m/s
          accuracy位置的精确度
          altitude高度,单位 m1.2.0
          verticalAccuracy垂直精度,单位 m(Android 无法获取,返回 0)1.2.0
          horizontalAccuracy水平精度,单位 m1.2.0

          示例代码:

          wx.getLocation({  type: 'wgs84',  success: function(res) {    var latitude = res.latitude    var longitude = res.longitude    var speed = res.speed    var accuracy = res.accuracy  }})

          wx.chooseLocation(OBJECT)


          打开地图选择位置。

          需要用户授权 scope.userLocation

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数,返回内容详见返回参数说明。
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数说明
          name位置名称
          address详细地址
          latitude纬度,浮点数,范围为-90~90,负数表示南纬
          longitude经度,浮点数,范围为-180~180,负数表示西经

          wx.openLocation(OBJECT)


          ​使用微信内置地图查看位置。

          需要用户授权 scope.userLocation

          OBJECT参数说明:

          参数类型必填说明
          latitudeFloat纬度,范围为-90~90,负数表示南纬
          longitudeFloat经度,范围为-180~180,负数表示西经
          scaleINT缩放比例,范围5~18,默认为18
          nameString位置名
          addressString地址的详细说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.getLocation({  type: 'gcj02', //返回可以用于wx.openLocation的经纬度  success: function(res) {    var latitude = res.latitude    var longitude = res.longitude    wx.openLocation({      latitude: latitude,      longitude: longitude,      scale: 28    })  }})

          Bug & Tip

          1. bug: iOS 6.3.30 type 参数不生效,只会返回 wgs84 类型的坐标信息


          wx.createMapContext(mapId)


          创建并返回 map 上下文 mapContext 对象。在自定义组件下,第二个参数传入组件实例this,以操作组件内 <map/> 组件


          mapContext

          mapContext通过 mapId 跟一个<map/>组件绑定,通过它可以操作对应的<map/>组件。

          mapContext 对象的方法列表

          方法参数说明最低版本
          getCenterLocationOBJECT获取当前地图中心的经纬度,返回的是 gcj02 坐标系,可以用于 wx.openLocation 
          moveToLocation将地图中心移动到当前定位点,需要配合map组件的show-location使用 
          translateMarkerOBJECT平移marker,带动画1.2.0
          includePointsOBJECT缩放视野展示所有经纬度1.2.0
          getRegionOBJECT获取当前地图的视野范围1.4.0
          getScaleOBJECT获取当前地图的缩放级别1.4.0

          getCenterLocation 的 OBJECT 参数列表

          参数类型必填说明
          successFunction接口调用成功的回调函数 ,res = { longitude: "经度", latitude: "纬度"}
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          translateMarker 的 OBJECT 参数列表

          参数类型必填说明
          markerIdNumber指定marker
          destinationObject指定marker移动到的目标点
          autoRotateBoolean移动过程中是否自动旋转marker
          rotateNumbermarker的旋转角度
          durationNumber动画持续时长,默认值1000ms,平移与旋转分别计算
          animationEndFunction动画结束回调函数
          failFunction接口调用失败的回调函数

          includePoints 的 OBJECT 参数列表

          参数类型必填说明
          pointsArray要显示在可视区域内的坐标点列表,[{latitude, longitude}]
          paddingArray坐标点形成的矩形边缘到地图边缘的距离,单位像素。格式为[上,右,下,左],安卓上只能识别数组第一项,上下左右的padding一致。开发者工具暂不支持padding参数。

          getRegion 的 OBJECT 参数列表

          参数类型必填说明
          successFunction接口调用成功的回调函数,res = {southwest, northeast},西南角与东北角的经纬度
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          getScale 的 OBJECT 参数列表

          参数类型必填说明
          successFunction接口调用成功的回调函数,res = {scale}
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)


          示例代码:

          <!-- map.wxml --><map id="myMap" show-location /><button type="primary" bindtap="getCenterLocation">获取位置</button><button type="primary" bindtap="moveToLocation">移动位置</button><button type="primary" bindtap="translateMarker">移动标注</button><button type="primary" bindtap="includePoints">缩放视野展示所有经纬度</button>
          // map.jsPage({  onReady: function (e) {    // 使用 wx.createMapContext 获取 map 上下文    this.mapCtx = wx.createMapContext('myMap')  },  getCenterLocation: function () {    this.mapCtx.getCenterLocation({      success: function(res){        console.log(res.longitude)        console.log(res.latitude)      }    })  },  moveToLocation: function () {    this.mapCtx.moveToLocation()  },  translateMarker: function() {    this.mapCtx.translateMarker({      markerId: 0,      autoRotate: true,      duration: 1000,      destination: {        latitude:23.10229,        longitude:113.3345211,      },      animationEnd() {        console.log('animation end')      }    })  },  includePoints: function() {    this.mapCtx.includePoints({      padding: [10],      points: [{        latitude:23.10229,        longitude:113.3345211,      }, {        latitude:23.00229,        longitude:113.3345211,      }]    })  }})


          wx.onLocationChange(function callback)

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

          监听实时地理位置变化事件,需结合 wx.startLocationUpdateBackground、wx.startLocationUpdate使用。

          参数

          function callback

          实时地理位置变化事件的回调函数

          参数

          Object res
          属性类型说明最低版本
          latitudenumber纬度,范围为 -90~90,负数表示南纬
          longitudenumber经度,范围为 -180~180,负数表示西经
          speednumber速度,单位 m/s
          accuracynumber位置的精确度
          altitudenumber高度,单位 m1.2.0
          verticalAccuracynumber垂直精度,单位 m(Android 无法获取,返回 0)1.2.0
          horizontalAccuracynumber水平精度,单位 m1.2.0

          示例代码

           const _locationChangeFn = function(res) {  console.log('location change', res) } wx.onLocationChange(_locationChangeFn) wx.offLocationChange(_locationChangeFn)

          wx.offLocationChange(function callback)

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

          取消监听实时地理位置变化事件

          参数

          function callback

          实时地理位置变化事件的回调函数


          微信小程序API设备概览

          wx.getSystemInfo(OBJECT)


          获取系统信息。

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success回调参数说明:

          属性说明
          model手机型号
          pixelRatio设备像素比
          windowWidth窗口宽度
          windowHeight窗口高度
          language微信设置的语言
          version微信版本号
          system操作系统版本
          platform客户端平台

          示例代码:

          wx.getSystemInfo({  success: function(res) {    console.log(res.model)    console.log(res.pixelRatio)    console.log(res.windowWidth)    console.log(res.windowHeight)    console.log(res.language)    console.log(res.version)    console.log(res.platform)  }})

          wx.getSystemInfoSync()


          获取系统信息同步接口

          示例代码:

          try {  var res = wx.getSystemInfoSync()  console.log(res.model)  console.log(res.pixelRatio)  console.log(res.windowWidth)  console.log(res.windowHeight)  console.log(res.language)  console.log(res.version)  console.log(res.platform)} catch (e) {  // Do something when catch error}

          wx.getSystemInfo(OBJECT)

          获取系统信息。

          OBJECT参数说明:

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

          success回调参数说明:

          参数 说明 最低版本
          model 手机型号  
          pixelRatio 设备像素比  
          screenWidth 屏幕宽度 1.1.0
          screenHeight 屏幕高度 1.1.0
          windowWidth 可使用窗口宽度  
          windowHeight 可使用窗口高度  
          language 微信设置的语言  
          version 微信版本号  
          system 操作系统版本  
          platform 客户端平台  
          fontSizeSetting 用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准,单位:px 1.5.0
          SDKVersion 客户端基础库版本 1.1.0


          示例代码:

          wx.getSystemInfo({
          success: function(res) {
          console.log(res.model)
          console.log(res.pixelRatio)
          console.log(res.windowWidth)
          console.log(res.windowHeight)
          console.log(res.language)
          console.log(res.version)
          console.log(res.platform)

          }
          })

          wx.getSystemInfoSync()

          获取系统信息同步接口

          同步返回参数说明:

          参数 说明 最低版本
          model 手机型号  
          pixelRatio 设备像素比  
          screenWidth 屏幕宽度 1.1.0
          screenHeight 屏幕高度 1.1.0
          windowWidth 可使用窗口宽度  
          windowHeight 可使用窗口高度  
          language 微信设置的语言  
          version 微信版本号  
          system 操作系统版本  
          platform 客户端平台  
          SDKVersion 客户端基础库版本 1.1.0

          示例代码:

          try {
          var res = wx.getSystemInfoSync()
          console.log(res.model)
          console.log(res.pixelRatio)
          console.log(res.windowWidth)
          console.log(res.windowHeight)
          console.log(res.language)
          console.log(res.version)
          console.log(res.platform)
          } catch (e) {
          // Do something when catch error
          }

          wx.canIUse(String)

          判断小程序的API,回调,参数,组件等是否在当前版本可用。

          String参数说明: 使用${API}.${method}.${param}.${options}或者${component}.${attribute}.${option}方式来调用,例如:

          • ${API}代表 API 名字
          • ${method}代表调用方式,有效值为returnsuccessobjectcallback
          • ${param}代表参数或者返回值
          • ${options}代表参数的可选值
          • ${component}代表组件名字
          • ${attribute}代表组件属性
          • ${option}代表组件属性的可选值

          例子:

          wx.canIUse('openBluetoothAdapter')wx.canIUse('getSystemInfoSync.return.screenWidth')
          wx.canIUse('getSystemInfo.success.screenWidth')
          wx.canIUse('showToast.object.image')
          wx.canIUse('onCompassChange.callback.direction')
          wx.canIUse('request.object.method.GET')
          wx.canIUse('contact-button')
          wx.canIUse('text.selectable')
          wx.canIUse('button.open-type.contact')


          wx.getNetworkType(OBJECT)

          获取网络类型。

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功,返回网络类型 networkType
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数说明
          networkType网络类型
          wx.getNetworkType({  success: function(res) {    // 返回网络类型, 有效值:    // wifi/2g/3g/4g/unknown(Android下不常见的网络类型)/none(无网络)    var networkType = res.networkType  }})

          wx.onNetworkStatusChange(CALLBACK)

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

          监听网络状态变化。

          CALLBACK返回参数:

          参数类型说明
          isConnectedBoolean当前是否有网络连接
          networkTypeString网络类型

          networkType 有效值:

          说明
          wifiwifi 网络
          2g2g 网络
          3g3g 网络
          4g4g 网络
          none无网络
          unknownAndroid下不常见的网络类型

          示例代码:

          wx.onNetworkStatusChange(function(res) {  console.log(res.isConnected)  console.log(res.networkType)})

          wx.offNetworkStatusChange(function callback)

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

          取消监听网络状态变化事件,参数为空,则取消所有的事件监听。

          参数

          function callback

          网络状态变化事件的回调函数

          wx.onAccelerometerChange(CALLBACK)


          监听重力感应数据,频率:5次/秒,接口调用后会自动开始监听,可使用wx.stopAccelerometer停止监听。

          CALLBACK返回参数:

          参数类型说明
          xNumberX 轴
          yNumberY 轴
          zNumberZ 轴

          示例代码:

          wx.onAccelerometerChange(function(res) {  console.log(res.x)  console.log(res.y)  console.log(res.z)})

          wx.startAccelerometer(OBJECT)

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

          微信客户端 6.5.6 版本开始支持

          开始监听加速度数据。

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.startAccelerometer()

          wx.stopAccelerometer(OBJECT)

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

          微信客户端 6.5.6 版本开始支持

          停止监听加速度数据。

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.stopAccelerometer()

          wx.offAccelerometerChange(function callback)


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

          取消监听加速度数据事件,参数为空,则取消所有的事件监听。

          参数

          function callback

          加速度数据事件的回调函数


          wx.onCompassChange(CALLBACK)

          监听罗盘数据,频率:5次/秒,接口调用后会自动开始监听,可使用wx.stopCompass停止监听。

          CALLBACK返回参数:

          参数类型说明
          directionNumber面对的方向度数

          示例代码:

          wx.onCompassChange(function (res) {  console.log(res.direction)})

          wx.startCompass(OBJECT)

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

          开始监听罗盘数据。

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.startCompass()

          wx.stopCompass(OBJECT)

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

          停止监听罗盘数据。

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.stopCompass()

          wx.offCompassChange(function callback)


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

          取消监听罗盘数据变化事件,参数为空,则取消所有的事件监听。

          参数

          function callback

          罗盘数据变化事件的回调函数


          wx.makePhoneCall(OBJECT)


          OBJECT参数说明:

          参数类型必填说明
          phoneNumberString需要拨打的电话号码
          successFunction接口调用成功的回调
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.makePhoneCall({  phoneNumber: '1340000' //仅为示例,并非真实的电话号码})

          wx.scanCode(Object object)

          调起客户端扫码界面进行扫码

          参数

          Object object

          属性类型默认值必填说明最低版本
          onlyFromCamerabooleanfalse是否只能从相机扫码,不允许从相册选择图片1.2.0
          scanTypeArray.<string>['barCode', 'qrCode']扫码类型1.7.0
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.scanType 的合法值

          说明最低版本
          barCode一维码
          qrCode二维码
          datamatrixData Matrix 码
          pdf417PDF417 条码

          object.success 回调函数

          参数
          Object res
          属性类型说明
          resultstring所扫码的内容
          scanTypestring所扫码的类型
          charSetstring所扫码的字符集
          pathstring当所扫的码为当前小程序二维码时,会返回此字段,内容为二维码携带的 path
          rawDatastring原始数据,base64编码

          res.scanType 的合法值

          说明最低版本
          QR_CODE二维码
          AZTEC一维码
          CODABAR一维码
          CODE_39一维码
          CODE_93一维码
          CODE_128一维码
          DATA_MATRIX二维码
          EAN_8一维码
          EAN_13一维码
          ITF一维码
          MAXICODE一维码
          PDF_417二维码
          RSS_14一维码
          RSS_EXPANDED一维码
          UPC_A一维码
          UPC_E一维码
          UPC_EAN_EXTENSION一维码
          WX_CODE二维码
          CODE_25一维码

          示例代码

          // 允许从相机和相册扫码wx.scanCode({  success (res) {    console.log(res)  }})// 只允许从相机扫码wx.scanCode({  onlyFromCamera: true,  success (res) {    console.log(res)  }})


          wx.setClipboardData(OBJECT)

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

          设置系统剪贴板的内容。

          OBJECT参数说明:

          参数类型必填说明
          dataString需要设置的内容
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.setClipboardData({  data: 'data',  success: function(res) {    wx.getClipboardData({      success: function(res) {        console.log(res.data) // data      }    })  }})

          wx.getClipboardData(OBJECT)

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

          获取系统剪贴板内容

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数类型说明
          dataString剪贴板的内容

          示例代码:

          wx.getClipboardData({  success: function(res){    console.log(res.data)  }})

          蓝牙适配器接口


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

          iOS 微信客户端 6.5.6 版本开始支持,Android 客户端暂不支持

          wx.openBluetoothAdapter(OBJECT)

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

          初始化蓝牙适配器

          OBJECT参数说明:

          参数类型必填说明
          successFunction成功则返回成功初始化信息
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.openBluetoothAdapter({  success: function (res) {    console.log(res)  }})

          Bug & Tip

          1. tip: 由于系统的问题,目前仅在 mac 版的开发工具上支持蓝牙调试
          2. tip: 基础库版本 1.1.0 开始支持,低版本需做兼容处理

          wx.closeBluetoothAdapter(OBJECT)

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

          关闭蓝牙模块。调用该方法将断开所有已建立的链接并释放系统资源

          OBJECT参数说明:

          参数类型必填说明
          successFunction成功则返回成功关闭模块信息
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.closeBluetoothAdapter({  success: function (res) {    console.log(res)  }})

          wx.getBluetoothAdapterState(OBJECT)

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

          获取本机蓝牙适配器状态

          OBJECT参数说明:

          参数类型必填说明
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          discoveringBoolean是否正在搜索设备
          availableBoolean蓝牙适配器是否可用
          errMsgString成功:ok,错误:详细信息

          示例代码:

          wx.getBluetoothAdapterState({  success: function (res) {    console.log(res)  }})

          wx.onBluetoothAdapterStateChange(CALLBACK)

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

          监听蓝牙适配器状态变化事件

          CALLBACK参数说明:

          参数类型说明
          availableboolean蓝牙适配器是否可用
          discoveringboolean蓝牙适配器是否处于搜索状态

          示例代码:

          wx.onBluetoothAdapterStateChange(function(res) {  console.log(`adapterState changed, now is`, res)})

          wx.startBluetoothDevicesDiscovery(OBJECT)

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

          开始搜寻附近的蓝牙外围设备。注意,该操作比较耗费系统资源,请在搜索并连接到设备后调用 stop 方法停止搜索。

          OBJECT参数说明:

          参数类型必填说明
          servicesArray蓝牙设备主 service 的 uuid 列表
          allowDuplicatesKeyboolean是否允许重复上报同一设备, 如果允许重复上报,则onDeviceFound 方法会多次上报同一设备,但是 RSSI 值会有不同
          intervalinteger上报设备的间隔,默认为0,意思是找到新设备立即上报,否则根据传入的间隔上报
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          services参数说明:某些蓝牙设备会广播自己的主 service 的 uuid。如果这里传入该数组,那么根据该 uuid 列表,只搜索有这个主服务的设备。

          success返回参数:

          参数类型说明
          errMsgstring成功:ok,错误:详细信息
          isDiscoveringboolean当前蓝牙适配器是否处于搜索状态

          示例代码:

          // 以微信硬件平台的蓝牙智能灯为例,主服务的 UUID 是 FEE7。传入这个参数,只搜索主服务 UUID 为 FEE7 的设备wx.startBluetoothDevicesDiscovery({  services: ['FEE7'],  success: function (res) {    console.log(res)  }})

          wx.stopBluetoothDevicesDiscovery(OBJECT)

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

          停止搜寻附近的蓝牙外围设备。请在确保找到需要连接的设备后调用该方法停止搜索。

          OBJECT参数说明:

          参数类型必填说明
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          errMsgstring成功:ok,错误:详细信息

          adapterState

          蓝牙适配器状态信息

          参数类型说明
          discoveringboolean是否正在搜索设备
          availableboolean蓝牙适配器是否可用

          示例代码:

          wx.stopBluetoothDevicesDiscovery({  success: function (res) {    console.log(res)  }})

          wx.getBluetoothDevices(OBJECT)

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

          获取所有已发现的蓝牙设备,包括已经和本机处于连接状态的设备

          OBJECT参数说明:

          参数类型必填说明
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          devicesArrayuuid 对应的的已连接设备列表
          errMsgstring成功:ok,错误:详细信息

          device 对象

          蓝牙设备信息

          参数类型说明
          namestring蓝牙设备名称,某些设备可能没有
          deviceIdstring用于区分设备的 id
          RSSIint当前蓝牙设备的信号强度
          advertisDataArrayBuffer当前蓝牙设备的广播内容(注意:vConsole 无法打印出 ArrayBuffer 类型数据)

          示例代码:

          wx.getBluetoothDevices({  success: function (res) {    console.log(res)  }})

          Bug & Tip

          1. tip: Mac系统可能无法获取advertisDataRSSI,请使用真机调试
          2. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址,iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

          wx.getConnectedBluetoothDevices(OBJECT)

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

          根据 uuid 获取处于已连接状态的设备

          OBJECT参数说明:

          参数类型必填说明
          servicesArray蓝牙设备主 service 的 uuid 列表
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          devicesArray搜索到的设备列表
          errMsgstring成功:ok,错误:详细信息

          device对象

          蓝牙设备信息

          参数类型说明
          namestring蓝牙设备名称,某些设备可能没有
          deviceIdstring用于区分设备的 id

          示例代码:

          wx.getConnectedBluetoothDevices({  success: function (res) {    console.log(res)  }})

          Bug & Tip

          1. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址,iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

          wx.onBluetoothDeviceFound(CALLBACK)

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

          监听寻找到新设备的事件

          CALLBACK参数说明:

          参数类型说明
          devicesArray新搜索到的设备列表

          device对象

          参数类型说明
          deviceIdstring蓝牙设备 id,参考 device 对象
          namestring蓝牙设备名称,参考 device 对象
          RSSIint当前蓝牙设备的信号强度
          advertisDataArrayBuffer当前蓝牙设备的广播内容(注意:vConsole 无法打印出 ArrayBuffer 类型数据)

          示例代码:

          wx.onBluetoothDeviceFound(function(devices) {  console.log('new device list has founded')  console.dir(devices)})

          Bug & Tip

          1. tip: Mac系统可能无法获取advertisDataRSSI,请使用真机调试
          2. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址,iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

          低功耗蓝牙接口

          wx.createBLEConnection(OBJECT)

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

          连接低功耗蓝牙设备

          OBJECT参数说明:

          参数类型必填说明
          deviceIdstring蓝牙设备 id,参考 getDevices 接口
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          errMsgstring成功:ok,错误:详细信息

          示例代码:

          wx.createBLEConnection({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  success: function (res) {    console.log(res)  }})

          wx.closeBLEConnection(OBJECT)

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

          断开与低功耗蓝牙设备的连接

          OBJECT参数说明:

          参数类型必填说明
          deviceIdstring蓝牙设备 id,参考 getDevices 接口
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          errMsgstring成功:ok,错误:详细信息

          示例代码:

          wx.closeBLEConnection({  success: function (res) {    console.log(res)  }})

          wx.getBLEDeviceServices(OBJECT)

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

          获取蓝牙设备所有 service(服务)

          OBJECT参数说明:

          参数类型必填说明
          deviceIdstring蓝牙设备 id,参考 getDevices 接口
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          servicesarray设备服务列表
          errMsgstring成功:ok,错误:详细信息

          service对象

          蓝牙设备service(服务)信息

          参数类型说明
          uuidstring蓝牙设备服务的 uuid
          isPrimaryboolean该服务是否为主服务

          示例代码:

          wx.getBLEDeviceServices({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  success: function (res) {    console.log('device services:', res.services)  }})

          wx.getBLEDeviceCharacteristics(OBJECT)

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

          获取蓝牙设备所有 characteristic(特征值)

          OBJECT参数说明:

          参数类型必填说明
          deviceIdstring蓝牙设备 id,参考 device 对象
          serviceIdstring蓝牙服务 uuid
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          characteristicsarray设备特征值列表
          errMsgstring成功:ok,错误:详细信息

          characteristic对象

          蓝牙设备characteristic(特征值)信息

          参数类型说明
          uuidstring蓝牙设备特征值的 uuid
          propertiesobject该特征值支持的操作类型

          properties对象

          参数类型说明
          readboolean该特征值是否支持 read 操作
          writeboolean该特征值是否支持 write 操作
          notifyboolean该特征值是否支持 notify 操作
          indicateboolean该特征值是否支持 indicate 操作

          示例代码:

          wx.getBLEDeviceCharacteristics({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,  success: function (res) {    console.log('device getBLEDeviceCharacteristics:', res.characteristics)  }})

          wx.readBLECharacteristicValue(OBJECT)

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

          读取低功耗蓝牙设备的特征值的二进制数据值。注意:必须设备的特征值支持read才可以成功调用,具体参照 characteristic 的 properties 属性

          OBJECT参数说明:

          参数类型必填说明
          deviceIdstring蓝牙设备 id,参考 device 对象
          serviceIdstring蓝牙特征值对应服务的 uuid
          characteristicIdstring蓝牙特征值的 uuid
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          characteristicobject设备特征值信息
          errMsgstring成功:ok,错误:详细信息

          characteristic对象

          蓝牙设备characteristic(特征值)信息

          参数类型说明
          characteristicIdstring蓝牙设备特征值的 uuid
          serviceIdobject蓝牙设备特征值对应服务的 uuid
          valueArrayBuffer蓝牙设备特征值对应的二进制值(注意:vConsole 无法打印出 ArrayBuffer 类型数据)

          示例代码:

          // 必须在这里的回调才能获取wx.onBLECharacteristicValueChange(function(characteristic) {  console.log('characteristic value comed:', characteristic)})wx.readBLECharacteristicValue({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取  characteristicId: characteristicId,  success: function (res) {    console.log('readBLECharacteristicValue:', res.characteristic.value)  }})

          Bug & Tip

          1. tip: 并行调用多次读写接口存在读写失败的可能性。
          2. tip:read接口读取到的信息需要在onBLECharacteristicValueChange方法注册的回调中获取。

          wx.writeBLECharacteristicValue(OBJECT)

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

          向低功耗蓝牙设备特征值中写入二进制数据。注意:必须设备的特征值支持write才可以成功调用,具体参照 characteristic 的 properties 属性

          tips: 并行调用多次读写接口存在读写失败的可能性

          OBJECT参数说明:

          参数类型必填说明
          deviceIdstring蓝牙设备 id,参考 device 对象
          serviceIdstring蓝牙特征值对应服务的 uuid
          characteristicIdstring蓝牙特征值的 uuid
          valueArrayBuffer蓝牙设备特征值对应的二进制值(注意:vConsole 无法打印出 ArrayBuffer 类型数据)
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          errMsgstring成功:ok,错误:详细信息

          示例代码:

          // 这里的回调可以获取到 write 导致的特征值改变wx.onBLECharacteristicValueChange(function(characteristic) {  console.log('characteristic value changed:', characteristic)})// 向蓝牙设备发送一个0x00的16进制数据let buffer = new ArrayBuffer(1)let dataView = new DataView(buffer)dataView.setUint8(0, 0)wx.writeBLECharacteristicValue({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取  characteristicId: characteristicId,  // 这里的value是ArrayBuffer类型  value: buffer,  success: function (res) {    console.log('writeBLECharacteristicValue success', res.errMsg)  }})

          wx.notifyBLECharacteristicValueChanged(OBJECT)


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

          启用低功耗蓝牙设备特征值变化时的 notify 功能。注意:必须设备的特征值支持notify才可以成功调用,具体参照 characteristic 的 properties 属性

          另外,必须先启用notify才能监听到设备 characteristicValueChange 事件

          OBJECT参数说明:

          参数类型必填说明
          deviceIdstring蓝牙设备 id,参考 device 对象
          serviceIdstring蓝牙特征值对应服务的 uuid
          characteristicIdstring蓝牙特征值的 uuid
          statebooleantrue: 启用 notify; false: 停用 notify
          successFunction成功则返回本机蓝牙适配器状态
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数:

          参数类型说明
          errMsgstring成功:ok,错误:详细信息

          示例代码:

          wx.notifyBLECharacteristicValueChanged({  state: true, // 启用 notify 功能  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取  characteristicId: characteristicId,  success: function (res) {    console.log('notifyBLECharacteristicValueChanged success', res.errMsg)  }})

          wx.onBLEConnectionStateChanged(CALLBACK)

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

          监听低功耗蓝牙连接的错误事件,包括设备丢失,连接异常断开等等。

          CALLBACK参数说明:

          参数类型说明
          deviceIdstring蓝牙设备 id,参考 device 对象
          connectedboolean连接目前的状态

          示例代码:

          wx.onBLEConnectionStateChanged(function(res) {  // 该方法回调中可以用于处理连接意外断开等异常情况  console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)})

          wx.onBLECharacteristicValueChange(CALLBACK)

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

          监听低功耗蓝牙设备的特征值变化。必须先启用notify接口才能接收到设备推送的notification。

          CALLBACK参数说明:

          参数类型说明
          deviceIdstring蓝牙设备 id,参考 device 对象
          serviceIdstring特征值所属服务 uuid
          characteristicIdstring特征值 uuid
          valueArrayBuffer特征值最新的值(注意:vConsole 无法打印出 ArrayBuffer 类型数据)

          示例代码:

          wx.onBLECharacteristicValueChange(function(res) {  console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`)})

          蓝牙错误码(errCode)列表

          错误码说明备注
          0ok正常
          10000not init未初始化蓝牙适配器
          10001not available当前蓝牙适配器不可用
          10002no device没有找到指定设备
          10003connection fail连接失败
          10004no service没有找到指定服务
          10005no characteristic没有找到指定特征值
          10006no connection当前连接已断开
          10007property not support当前特征值不支持此操作
          10008system error其余所有系统上报的异常
          10009system not supportAndroid 系统特有,系统版本低于 4.3 不支持BLE
          10010no descriptor没有找到指定描述符

          wx.makeBluetoothPair(Object object)

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

          蓝牙配对接口,仅安卓使用。安卓上蓝牙连接时,部分设备需先配对。

          参数

          Object object

          属性类型默认值必填说明
          deviceIdstring蓝牙设备 id
          pinArrayBufferpin 码
          timeoutnumber20超时时间
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          wx.startBeaconDiscovery(OBJECT)

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

          开始搜索附近的iBeacon设备

          OBJECT参数说明:

          参数名类型必填说明
          uuidsStringArrayiBeacon设备广播的 uuids
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数名类型说明
          errMsgString调用结果

          示例代码:

          wx.startBeaconDiscovery({    success(res) {    }})

          wx.stopBeaconDiscovery(OBJECT)

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

          停止搜索附近的iBeacon设备

          OBJECT参数说明:

          参数名类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数名类型说明
          errMsgString调用结果

          wx.getBeacons(OBJECT)

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

          获取所有已搜索到的iBeacon设备

          OBJECT参数说明:

          参数名类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数名类型说明
          beaconsObjectArrayiBeacon 设备列表
          errMsgString调用结果

          iBeacon 结构:

          参数类型说明
          uuidStringiBeacon 设备广播的 uuid
          majorStringiBeacon 设备的主 id
          minorStringiBeacon 设备的次 id
          proximityNumber表示设备距离的枚举值
          accuracyNumberiBeacon 设备的距离
          rssiNumber表示设备的信号强度

          wx.onBeaconUpdate(CALLBACK)

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

          监听iBeacon设备的更新事件

          CALLBACK返回参数说明:

          参数名类型说明
          beaconsarray object当前搜寻到的所有 iBeacon 设备列表

          iBeacon 结构:

          参数类型说明
          uuidStringiBeacon 设备广播的 uuid
          majorStringiBeacon 设备的主 id
          minorStringiBeacon 设备的次 id
          proximityNumber表示设备距离的枚举值
          accuracyNumberiBeacon 设备的距离
          rssiNumber表示设备的信号强度

          wx.onBeaconServiceChange(CALLBACK)

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

          监听iBeacon服务的状态变化

          CALLBACK返回参数说明:

          参数名类型说明
          availableBoolean服务目前是否可用
          discoveringBoolean目前是否处于搜索状态

          错误码列表

          错误码说明备注
          0ok正常
          11000unsupport系统或设备不支持
          11001bluetooth service unavailable蓝牙服务不可用
          11002location service unavailable位置服务不可用
          11003already start已经开始搜索

          wx.setScreenBrightness(OBJECT)

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

          设置屏幕亮度。

          OBJECT参数说明:

          参数类型必填说明
          valueNumber屏幕亮度值,范围 0~1,0 最暗,1 最亮
          successFunction接口调用成功
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          wx.getScreenBrightness(OBJECT)

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

          获取屏幕亮度。

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数类型说明
          valueNumber屏幕亮度值,范围 0~1,0 最暗,1 最亮

          wx.setKeepScreenOn(OBJECT)

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

          设置是否保持常亮状态。仅在当前小程序生效,离开小程序后设置失效。

          OBJECT参数说明:

          参数名类型必填说明
          keepScreenOnBoolean是否保持屏幕常亮
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数名类型说明
          errMsgString调用结果

          示例代码:

          // 保持屏幕常亮wx.setKeepScreenOn({    keepScreenOn: true})


          wx.onUserCaptureScreen(CALLBACK)

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

          监听用户主动截屏事件,用户使用系统截屏按键截屏时触发此事件

          CALLBACK返回参数:

          示例代码:

          wx.onUserCaptureScreen(function(res) {    console.log('用户截屏了')})

          wx.vibrateLong(OBJECT)

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

          使手机发生较长时间的振动(400ms)

          OBJECT参数说明:

          参数名类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          wx.vibrateShort(OBJECT)

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

          使手机发生较短时间的振动(15ms)

          OBJECT参数说明:

          参数名类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          Bug & Tip

          1. tipvibrateShort接口仅在 iPhone7/iPhone7Plus 及 Android 机型生效
          2. tip:getScreenBrightness接口若安卓系统设置中开启了自动调节亮度功能,则屏幕亮度会根据光线自动调整,该接口仅能获取自动调节亮度之前的值,而非实时的亮度值。

          wx.addPhoneContact(OBJECT)

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

          调用后,用户可以选择将该表单以“新增联系人”或“添加到已有联系人”的方式,写入手机系统通讯录,完成手机通讯录联系人和联系方式的增加。

          OBJECT参数说明:

          参数类型必填说明
          photoFilePathString头像本地文件路径
          nickNameString昵称
          lastNameString姓氏
          middleNameString中间名
          firstNameString名字
          remarkString备注
          mobilePhoneNumberString手机号
          weChatNumberString微信号
          addressCountryString联系地址国家
          addressStateString联系地址省份
          addressCityString联系地址城市
          addressStreetString联系地址街道
          addressPostalCodeString联系地址邮政编码
          organizationString公司
          titleString职位
          workFaxNumberString工作传真
          workPhoneNumberString工作电话
          hostNumberString公司电话
          emailString电子邮件
          urlString网站
          workAddressCountryString工作地址国家
          workAddressStateString工作地址省份
          workAddressCityString工作地址城市
          workAddressStreetString工作地址街道
          workAddressPostalCodeString工作地址邮政编码
          homeFaxNumberString住宅传真
          homePhoneNumberString住宅电话
          homeAddressCountryString住宅地址国家
          homeAddressStateString住宅地址省份
          homeAddressCityString住宅地址城市
          homeAddressStreetString住宅地址街道
          homeAddressPostalCodeString住宅地址邮政编码
          successFunction接口调用成功
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          回调结果:

          回调类型errMsg说明
          successok添加成功
          failfail cancel用户取消操作
          failfail ${detail}调用失败,detail 加上详细信息

          wx.onMemoryWarning(function callback)

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

          监听内存不足告警事件。

          当 iOS/Android 向小程序进程发出内存警告时,触发该事件。触发该事件不意味小程序被杀,大部分情况下仅仅是告警,开发者可在收到通知后回收一些不必要资源避免进一步加剧内存紧张。

          参数

          function callback

          内存不足告警事件的回调函数

          参数

          Object res
          属性类型说明
          levelnumber内存告警等级,只有 Android 才有,对应系统宏定义

          level 的合法值

          说明最低版本
          5TRIM_MEMORY_RUNNING_MODERATE
          10TRIM_MEMORY_RUNNING_LOW
          15TRIM_MEMORY_RUNNING_CRITICAL

          示例代码

          wx.onMemoryWarning(function () {  console.log('onMemoryWarningReceive')})

          wx.offMemoryWarning(function callback)

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

          取消监听内存不足告警事件。

          参数

          function callback

          内存不足告警事件的回调函数


          wx.stopGyroscope(Object object)

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

          停止监听陀螺仪数据。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          wx.startGyroscope(Object object)

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

          开始监听陀螺仪数据。

          参数

          Object object

          属性类型默认值必填说明
          intervalstringnormal监听陀螺仪数据回调函数的执行频率
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.interval 的合法值

          说明最低版本
          game适用于更新游戏的回调频率,在 20ms/次 左右
          ui适用于更新 UI 的回调频率,在 60ms/次 左右
          normal普通的回调频率,在 200ms/次 左右

          wx.onGyroscopeChange(function callback)

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

          监听陀螺仪数据变化事件。频率根据 wx.startGyroscope() 的 interval 参数。可以使用 wx.stopGyroscope() 停止监听。

          参数

          function callback

          陀螺仪数据变化事件的回调函数

          参数

          Object res
          属性类型说明
          xnumberx 轴的角速度
          ynumbery 轴的角速度
          znumberz 轴的角速度

          wx.offGyroscopeChange(function callback)

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

          取消监听陀螺仪数据变化事件。

          参数

          function callback

          陀螺仪数据变化事件的回调函数


          wx.stopDeviceMotionListening(Object object)

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

          停止监听设备方向的变化。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          wx.startDeviceMotionListening(Object object)

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

          开始监听设备方向的变化。

          参数

          Object object

          属性类型默认值必填说明
          intervalstringnormal监听设备方向的变化回调函数的执行频率
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.interval 的合法值

          说明最低版本
          game适用于更新游戏的回调频率,在 20ms/次 左右
          ui适用于更新 UI 的回调频率,在 60ms/次 左右
          normal普通的回调频率,在 200ms/次 左右

          wx.onDeviceMotionChange(function callback)

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

          监听设备方向变化事件。频率根据 wx.startDeviceMotionListening() 的 interval 参数。可以使用 wx.stopDeviceMotionListening() 停止监听。

          参数

          function callback

          设备方向变化事件的回调函数

          参数

          Object res
          属性类型说明
          alphanumber当 手机坐标 X/Y 和 地球 X/Y 重合时,绕着 Z 轴转动的夹角为 alpha,范围值为 [0, 2*PI)。逆时针转动为正。
          betanumber当手机坐标 Y/Z 和地球 Y/Z 重合时,绕着 X 轴转动的夹角为 beta。范围值为 [-1*PI, PI) 。顶部朝着地球表面转动为正。也有可能朝着用户为正。
          gammanumber当手机 X/Z 和地球 X/Z 重合时,绕着 Y 轴转动的夹角为 gamma。范围值为 [-1*PI/2, PI/2)。右边朝着地球表面转动为正。

          wx.offDeviceMotionChange(function callback)

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

          取消监听设备方向变化事件,参数为空,则取消所有的事件监听。

          参数

          function callback

          设备方向变化事件的回调函数


          wx.offDeviceMotionChange(function callback)

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

          取消监听设备方向变化事件,参数为空,则取消所有的事件监听。

          参数

          function callback

          设备方向变化事件的回调函数


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

          取消监听设备方向变化事件,参数为空,则取消所有的事件监听。

          参数

          function callback

          设备方向变化事件的回调函数


          Object wx.getBatteryInfoSync()

          wx.getBatteryInfo 的同步版本

          返回值

          Object res

          属性类型说明
          levelstring设备电量,范围 1 - 100
          isChargingboolean是否正在充电中

          wx.getBatteryInfo(Object object)

          获取设备电量。同步 API wx.getBatteryInfoSync 在 iOS 上不可用。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          levelstring设备电量,范围 1 - 100
          isChargingboolean是否正在充电中


          wx.stopWifi(Object object)

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

          关闭 Wi-Fi 模块。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          错误

          错误码错误信息说明
          0ok正常
          12000not init未先调用 startWifi 接口
          12001system not support当前系统不支持相关能力
          12002password error Wi-Fi密码错误
          12003connection timeout连接超时
          12004duplicate request重复连接 Wi-Fi
          12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
          12006gps not turned onAndroid 特有,未打开 GPS 定位开关
          12007user denied用户拒绝授权链接 Wi-Fi
          12008invalid SSID无效 SSID
          12009system config err系统运营商配置拒绝连接 Wi-Fi
          12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
          12011weapp in background应用在后台无法配置 Wi-Fi
          12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

          示例代码

          wx.stopWifi({  success (res) {    console.log(res.errMsg)  }})

          wx.startWifi(Object object)

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

          初始化 Wi-Fi 模块。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          错误

          错误码错误信息说明
          0ok正常
          12000not init未先调用 startWifi 接口
          12001system not support当前系统不支持相关能力
          12002password error Wi-Fi密码错误
          12003connection timeout连接超时
          12004duplicate request重复连接 Wi-Fi
          12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
          12006gps not turned onAndroid 特有,未打开 GPS 定位开关
          12007user denied用户拒绝授权链接 Wi-Fi
          12008invalid SSID无效 SSID
          12009system config err系统运营商配置拒绝连接 Wi-Fi
          12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
          12011weapp in background应用在后台无法配置 Wi-Fi
          12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

          示例代码

          wx.startWifi({  success (res) {    console.log(res.errMsg)  }})

          wx.setWifiList(Object object)

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

          设置 wifiList 中 AP 的相关信息。在 onGetWifiList 回调后调用,iOS特有接口。

          参数

          Object object

          属性类型默认值必填说明
          wifiListArray.<Object>提供预设的 Wi-Fi 信息列表
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.wifiList 的结构

          属性类型默认值必填说明
          SSIDstringWi-Fi 的 SSID
          BSSIDstringWi-Fi 的 BSSID
          passwordstringWi-Fi 设备密码

          错误

          错误码错误信息说明
          0ok正常
          12000not init未先调用 startWifi 接口
          12001system not support当前系统不支持相关能力
          12002password error Wi-Fi密码错误
          12003connection timeout连接超时
          12004duplicate request重复连接 Wi-Fi
          12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
          12006gps not turned onAndroid 特有,未打开 GPS 定位开关
          12007user denied用户拒绝授权链接 Wi-Fi
          12008invalid SSID无效 SSID
          12009system config err系统运营商配置拒绝连接 Wi-Fi
          12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
          12011weapp in background应用在后台无法配置 Wi-Fi
          12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

          注意

          • 该接口只能在 onGetWifiList 回调之后才能调用。
          • 此时客户端会挂起,等待小程序设置 Wi-Fi 信息,请务必尽快调用该接口,若无数据请传入一个空数组。
          • 有可能随着周边 Wi-Fi 列表的刷新,单个流程内收到多次带有存在重复的 Wi-Fi 列表的回调。

          示例代码

          wx.onGetWifiList(function(res) {  if (res.wifiList.length) {    wx.setWifiList({      wifiList: [{        SSID: res.wifiList[0].SSID,        BSSID: res.wifiList[0].BSSID,        password: '123456'      }]    })  } else {    wx.setWifiList({      wifiList: []    })  }})wx.getWifiList()


          wx.onWifiConnected(function callback)

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

          监听连接上 Wi-Fi 的事件

          参数

          function callback

          连接上 Wi-Fi 的事件的回调函数

          参数

          Object res
          属性类型说明
          wifiWifiInfoWi-Fi 信息

          wx.onGetWifiList(function callback)

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

          监听获取到 Wi-Fi 列表数据事件

          参数

          function callback

          获取到 Wi-Fi 列表数据事件的回调函数

          参数

          Object res
          属性类型说明
          wifiListArray.<WifiInfo>Wi-Fi 列表数据

          wx.offWifiConnected(function callback)

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

          取消监听连接上 Wi-Fi 的事件。

          参数

          function callback

          连接上 Wi-Fi 的事件的回调函数


          wx.offGetWifiList(function callback)

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

          取消监听获取到 Wi-Fi 列表数据事件。

          参数

          function callback

          获取到 Wi-Fi 列表数据事件的回调函数


          wx.getWifiList(Object object)

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

          请求获取 Wi-Fi 列表。在 onGetWifiList 注册的回调中返回 wifiList 数据。 Android 调用前需要 用户授权 scope.userLocation。

          iOS 将跳转到系统的 Wi-Fi 界面,Android 不会跳转。 iOS 11.0 及 iOS 11.1 两个版本因系统问题,该方法失效。但在 iOS 11.2 中已修复。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          错误

          错误码错误信息说明
          0ok正常
          12000not init未先调用 startWifi 接口
          12001system not support当前系统不支持相关能力
          12002password error Wi-Fi密码错误
          12003connection timeout连接超时
          12004duplicate request重复连接 Wi-Fi
          12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
          12006gps not turned onAndroid 特有,未打开 GPS 定位开关
          12007user denied用户拒绝授权链接 Wi-Fi
          12008invalid SSID无效 SSID
          12009system config err系统运营商配置拒绝连接 Wi-Fi
          12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
          12011weapp in background应用在后台无法配置 Wi-Fi
          12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

          wx.getConnectedWifi(Object object)

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

          获取已连接中的 Wi-Fi 信息。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          wifiWifiInfo Wi-Fi 信息

          错误

          错误码错误信息说明
          0ok正常
          12000not init未先调用 startWifi 接口
          12001system not support当前系统不支持相关能力
          12002password error Wi-Fi密码错误
          12003connection timeout连接超时
          12004duplicate request重复连接 Wi-Fi
          12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
          12006gps not turned onAndroid 特有,未打开 GPS 定位开关
          12007user denied用户拒绝授权链接 Wi-Fi
          12008invalid SSID无效 SSID
          12009system config err系统运营商配置拒绝连接 Wi-Fi
          12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
          12011weapp in background应用在后台无法配置 Wi-Fi
          12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

          wx.connectWifi(Object object)

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

          连接 Wi-Fi。若已知 Wi-Fi 信息,可以直接利用该接口连接。仅 Android 与 iOS 11 以上版本支持。

          参数

          Object object

          属性类型默认值必填说明最低版本
          SSIDstringWi-Fi 设备 SSID
          BSSIDstringWi-Fi 设备 BSSID
          passwordstringWi-Fi 设备密码
          maunalbooleanfalse跳转到系统设置页进行连接,仅安卓生效2.12.0
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          错误

          错误码错误信息说明
          0ok正常
          12000not init未先调用 startWifi 接口
          12001system not support当前系统不支持相关能力
          12002password error Wi-Fi密码错误
          12003connection timeout连接超时
          12004duplicate request重复连接 Wi-Fi
          12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
          12006gps not turned onAndroid 特有,未打开 GPS 定位开关
          12007user denied用户拒绝授权链接 Wi-Fi
          12008invalid SSID无效 SSID
          12009system config err系统运营商配置拒绝连接 Wi-Fi
          12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
          12011weapp in background应用在后台无法配置 Wi-Fi
          12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

          示例代码

          wx.connectWifi({  SSID: '',  password: '',  success (res) {    console.log(res.errMsg)  }})

          WifiInfo

          Wifi 信息

          属性

          string SSID

          Wi-Fi 的 SSID

          string BSSID

          Wi-Fi 的 BSSID

          boolean secure

          Wi-Fi 是否安全

          number signalStrength

          Wi-Fi 信号强度

          number frequency

          基础库 2.12.0 开始支持,低版本需做兼容处理。

          Wi-Fi 频段单位 MHz


          wx.stopHCE(Object object)

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

          关闭 NFC 模块。仅在安卓系统下有效。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          错误

          错误码错误信息说明
          0ok正常
          13000当前设备不支持NFC
          13001当前设备支持NFC,但系统NFC开关未开启
          13002当前设备支持NFC,但不支持HCE
          13003AID列表参数格式错误
          13004未设置微信为默认NFC支付应用
          13005返回的指令不合法
          13006注册AID失败

          示例代码

          wx.stopHCE({  success (res) {    console.log(res.errMsg)  }})


          wx.startHCE(Object object)

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

          初始化 NFC 模块。

          参数

          Object object

          属性类型默认值必填说明
          aid_listArray.<string>需要注册到系统的 AID 列表
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          错误

          错误码错误信息说明
          0ok正常
          13000当前设备不支持NFC
          13001当前设备支持NFC,但系统NFC开关未开启
          13002当前设备支持NFC,但不支持HCE
          13003AID列表参数格式错误
          13004未设置微信为默认NFC支付应用
          13005返回的指令不合法
          13006注册AID失败

          示例代码

          wx.startHCE({  aid_list: ['F222222222'],  success (res) {    console.log(res.errMsg)  }})


          wx.sendHCEMessage(Object object)

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

          发送 NFC 消息。仅在安卓系统下有效。

          参数

          Object object

          属性类型默认值必填说明
          dataArrayBuffer二进制数据
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          错误

          错误码错误信息说明
          0ok正常
          13000当前设备不支持NFC
          13001当前设备支持NFC,但系统NFC开关未开启
          13002当前设备支持NFC,但不支持HCE
          13003AID列表参数格式错误
          13004未设置微信为默认NFC支付应用
          13005返回的指令不合法
          13006注册AID失败

          示例代码

          const buffer = new ArrayBuffer(1)const dataView = new DataView(buffer)dataView.setUint8(0, 0)wx.startHCE({  success (res) {    wx.onHCEMessage(function(res) {      if (res.messageType === 1) {        wx.sendHCEMessage({data: buffer})      }    })  }})


          wx.onHCEMessage(function callback)

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

          监听接收 NFC 设备消息事件,仅能注册一个监听

          参数

          function callback

          接收 NFC 设备消息事件的回调函数

          参数

          Object res
          属性类型说明
          messageTypenumber消息类型
          dataArrayBuffermessageType=1 时 ,客户端接收到 NFC 设备的指令
          reasonnumbermessageType=2 时,原因

          messageType 的合法值


          说明最低版本
          1HCE APDU Command类型,小程序需对此指令进行处理,并调用 sendHCEMessage 接口返回处理指令
          2设备离场事件类型


          wx.offHCEMessage(function callback)

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

          接收 NFC 设备消息事件,取消事件监听。

          参数

          function callback

          接收 NFC 设备消息事件的回调函数


          NFCAdapter wx.getNFCAdapter()

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

          获取 NFC 实例

          返回值

          NFCAdapter

          NFC 实例

          错误

          错误码错误信息说明
          13000设备不支持NFC
          13001系统NFC开关未打开
          13010未知错误
          13019user is not authorized用户未授权
          13011invalid parameter参数无效
          13012parse NdefMessage failed将参数解析为NdefMessage失败
          13021NFC discovery already started已经开始NFC扫描
          13018NFC discovery has not started尝试在未开始NFC扫描时停止NFC扫描
          13022Tech already connected标签已经连接
          13023Tech has not connected尝试在未连接标签时断开连接
          13013NFC tag has not been discovered未扫描到NFC标签
          13014invalid tech无效的标签技术
          13015unavailable tech从标签上获取对应技术失败
          13024function not support当前标签技术不支持该功能
          13017system internal error相关读写操作失败
          13016connect fail连接失败




          wx.getHCEState(Object object)

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

          判断当前设备是否支持 HCE 能力。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          错误

          错误码错误信息说明
          0ok正常
          13000当前设备不支持NFC
          13001当前设备支持NFC,但系统NFC开关未开启
          13002当前设备支持NFC,但不支持HCE
          13003AID列表参数格式错误
          13004未设置微信为默认NFC支付应用
          13005返回的指令不合法
          13006注册AID失败

          示例代码

          wx.getHCEState({  success (res) {    console.log(res.errCode)  }})


          IsoDep

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

          IsoDep 标签


          方法:

          IsoDep.close(Object object)

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

          断开连接

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          IsoDep.connect(Object object)

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

          连接 NFC 标签

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          IsoDep.getHistoricalBytes(Object object)

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

          获取复位信息

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          histBytesArrayBuffer返回历史二进制数据


          IsoDep.getMaxTransceiveLength(Object object)

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

          获取最大传输长度

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          lengthnumber最大传输长度


          IsoDep.setTimeout(Object object)

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

          设置超时时间

          参数

          Object object

          属性类型默认值必填说明
          timeoutnumber设置超时时间 (ms)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          IsoDep.transceive(Object object)

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

          发送数据

          参数

          Object object

          属性类型默认值必填说明
          dataArrayBuffer需要传递的二进制数据
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          dataArrayBuffer


          MifareClassic

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

          MifareClassic 标签


          方法:

          MifareClassic.close(Object object)

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

          断开连接

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          MifareClassic.connect(Object object)

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

          连接 NFC 标签

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          MifareClassic.getMaxTransceiveLength(Object object)

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

          获取最大传输长度

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          lengthnumber最大传输长度


          MifareClassic.setTimeout(Object object)

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

          设置超时时间

          参数

          Object object

          属性类型默认值必填说明
          timeoutnumber设置超时时间 (ms)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          MifareClassic.transceive(Object object)

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

          发送数据

          参数

          Object object

          属性类型默认值必填说明
          dataArrayBuffer需要传递的二进制数据
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          dataArrayBuffer




          MifareUltralight

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

          MifareUltralight 标签


          方法:

          MifareUltralight.close(Object object)

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

          断开连接

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          MifareUltralight.connect(Object object)

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

          连接 NFC 标签

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          MifareUltralight.getMaxTransceiveLength(Object object)

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

          获取最大传输长度

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          lengthnumber最大传输长度


          MifareUltralight.setTimeout(Object object)

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

          设置超时时间

          参数

          Object object

          属性类型默认值必填说明
          timeoutnumber设置超时时间 (ms)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          complete
          function接口调用结束的回调函数(调用成功、失败都会执行)


          MifareUltralight.transceive(Object object)

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

          发送数据

          参数

          Object object

          属性类型默认值必填说明
          dataArrayBuffer需要传递的二进制数据
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          dataArrayBuffer




          Ndef

          基础库 2.11.2 开始支持,低版本需做兼容处理。

          Ndef 标签


          方法:

          Ndef.close(Object object)

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

          断开连接

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          Ndef.connect(Object object)

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

          连接 NFC 标签

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          Ndef.offNdefMessage(function callback)

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

          取消监听 Ndef 消息

          参数

          function callback


          Ndef.onNdefMessage(function callback)

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

          监听 Ndef 消息

          参数

          function callback


          Ndef.setTimeout(Object object)

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

          设置超时时间

          参数

          Object object

          属性类型默认值必填说明
          timeoutnumber设置超时时间 (ms)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          Ndef.writeNdefMessage(Object object)

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

          重写 Ndef 标签内容

          参数

          Object object

          属性类型默认值必填说明
          urisArrayuri 数组
          textsArraytext 数组
          recordsArray二进制对象数组, 需要指明 id, type 以及 payload (均为 ArrayBuffer 类型)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcA

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

          NfcA 标签


          方法:

          NfcA.close(Object object)

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

          断开连接

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcA.connect(Object object)

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

          连接 NFC 标签

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcA.getAtqa(Object object)

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

          获取ATQA信息

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          atqaArrayBuffer返回 ATQA/SENS_RES 数据


          NfcA.getMaxTransceiveLength(Object object)

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

          获取最大传输长度

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          lengthnumber最大传输长度


          NfcA.getSak(Object object)

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

          获取SAK信息

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          saknumber返回 SAK/SEL_RES 数据


          NfcA.setTimeout(Object object)

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

          设置超时时间

          参数

          Object object

          属性类型默认值必填说明
          timeoutnumber设置超时时间 (ms)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcA.transceive(Object object)

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

          发送数据

          参数

          Object object

          属性类型默认值必填说明
          dataArrayBuffer需要传递的二进制数据
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          dataArrayBuffer




          NFCAdapter

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

          属性

          Object tech

          标签类型枚举

          属性类型说明
          ndefstring对应Ndef实例,实例支持对NDEF格式的NFC标签上的NDEF数据的读写
          nfcAstring对应NfcA实例,实例支持NFC-A (ISO 14443-3A)标准的读写
          nfcBstring对应NfcB实例,实例支持NFC-B (ISO 14443-3B)标准的读写
          isoDepstring对应IsoDep实例,实例支持ISO-DEP (ISO 14443-4)标准的读写
          nfcFstring对应NfcF实例,实例支持NFC-F (JIS 6319-4)标准的读写
          nfcVstring对应NfcV实例,实例支持NFC-V (ISO 15693)标准的读写
          mifareClassicstring对应MifareClassic实例,实例支持MIFARE Classic标签的读写
          mifareUltralightstring对应MifareUltralight实例,实例支持MIFARE Ultralight标签的读写

          方法:

          IsoDep NFCAdapter.getIsoDep()

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

          获取IsoDep实例,实例支持ISO-DEP (ISO 14443-4)标准的读写

          返回值

          IsoDep


          MifareClassic NFCAdapter.getMifareClassic()

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

          获取MifareClassic实例,实例支持MIFARE Classic标签的读写

          返回值

          MifareClassic


          MifareUltralight NFCAdapter.getMifareUltralight()

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

          获取MifareUltralight实例,实例支持MIFARE Ultralight标签的读写

          返回值

          MifareUltralight


          Ndef NFCAdapter.getNdef()

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

          获取Ndef实例,实例支持对NDEF格式的NFC标签上的NDEF数据的读写

          返回值

          Ndef


          NfcA NFCAdapter.getNfcA()

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

          获取NfcA实例,实例支持NFC-A (ISO 14443-3A)标准的读写

          返回值

          NfcA


          NfcB NFCAdapter.getNfcB()

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

          获取NfcB实例,实例支持NFC-B (ISO 14443-3B)标准的读写

          返回值

          NfcB


          NfcF NFCAdapter.getNfcF()

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

          获取NfcF实例,实例支持NFC-F (JIS 6319-4)标准的读写

          返回值

          NfcF


          NfcV NFCAdapter.getNfcV()

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

          获取NfcV实例,实例支持NFC-V (ISO 15693)标准的读写

          返回值

          NfcV


          NFCAdapter.offDiscovered(function callback)

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

          取消监听 NFC Tag

          参数

          function callback

          的回调函数


          NFCAdapter.onDiscovered(function callback)

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

          监听 NFC Tag

          参数

          function callback

          的回调函数

          参数

          Object res
          属性类型说明
          techsArraytech 数组,用于匹配NFC卡片具体可以使用什么标准(NfcA等实例)处理
          messagesArrayNdefMessage 数组


          NFCAdapter.startDiscovery(Object object)

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

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NFCAdapter.stopDiscovery(Object object)

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

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)



          NfcB

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

          NfcB 标签


          方法:

          NfcB.close(Object object)

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

          断开连接

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcB.connect(Object object)

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

          连接 NFC 标签

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcB.getMaxTransceiveLength(Object object)

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

          获取最大传输长度

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          lengthnumber最大传输长度


          NfcB.setTimeout(Object object)

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

          设置超时时间

          参数

          Object object

          属性类型默认值必填说明
          timeoutnumber设置超时时间 (ms)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcB.transceive(Object object)

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

          发送数据

          参数

          Object object

          属性类型默认值必填说明
          dataArrayBuffer需要传递的二进制数据
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          dataArrayBuffer


          NfcF

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

          NfcF 标签


          方法:

          NfcF.close(Object object)

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

          断开连接

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcF.connect(Object object)

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

          连接 NFC 标签

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcF.getMaxTransceiveLength(Object object)

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

          获取最大传输长度

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          lengthnumber最大传输长度


          NfcF.setTimeout(Object object)

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

          设置超时时间

          参数

          Object object

          属性类型默认值必填说明
          timeoutnumber设置超时时间 (ms)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcF.transceive(Object object)

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

          发送数据

          参数

          Object object

          属性类型默认值必填说明
          dataArrayBuffer需要传递的二进制数据
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          dataArrayBuffer


          NfcV

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

          NfcV 标签


          方法:

          NfcV.close(Object object)

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

          断开连接

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcV.connect(Object object)

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

          连接 NFC 标签

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcV.getMaxTransceiveLength(Object object)

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

          获取最大传输长度

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          lengthnumber最大传输长度


          NfcV.setTimeout(Object object)

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

          设置超时时间

          参数

          Object object

          属性类型默认值必填说明
          timeoutnumber设置超时时间 (ms)
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          NfcV.transceive(Object object)

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

          发送数据

          参数

          Object object

          属性类型默认值必填说明
          dataArrayBuffer需要传递的二进制数据
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          dataArrayBuffer



          wx.showToast(OBJECT)

          显示消息提示框。

          OBJECT参数说明:

          参数类型必填说明最低版本
          titleString提示的内容 
          iconString图标,有效值"success"、"loading" 
          imageString自定义图标的本地路径,image 的优先级高于 icon1.1.0
          durationNumber提示的延迟时间,单位毫秒,默认:1500 
          maskBoolean是否显示透明蒙层,防止触摸穿透,默认:false 
          successFunction接口调用成功的回调函数 
          failFunction接口调用失败的回调函数 
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行) 

          示例代码:

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

          wx.showLoading(OBJECT)

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

          显示 loading 提示框, 需主动调用 wx.hideLoading 才能关闭提示框

          OBJECT参数说明:

          参数类型必填说明
          titleString提示的内容
          maskBoolean是否显示透明蒙层,防止触摸穿透,默认:false
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          wx.hideToast()

          隐藏消息提示框

          wx.hideLoading()


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

          隐藏loading提示框

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

          wx.showModal(OBJECT)

          ​显示模态弹窗

          OBJECT参数说明:

          参数类型必填说明
          titleString提示的标题
          contentString提示的内容
          showCancelBoolean是否显示取消按钮,默认为 true
          cancelTextString取消按钮的文字,默认为"取消",最多 4 个字符
          cancelColorHexColor取消按钮的文字颜色,默认为"#000000"
          confirmTextString确定按钮的文字,默认为"确定",最多 4 个字符
          confirmColorHexColor确定按钮的文字颜色,默认为"#3CC51F"
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          succes返回参数说明:

          参数类型说明最低版本
          confirmBoolean为 true 时,表示用户点击了确定按钮 
          cancelBoolean为 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参数说明:

          参数类型必填说明
          itemListString Array按钮的文字数组,数组长度最大为6个
          itemColorHexColor按钮的文字颜色,默认为"#000000"
          successFunction接口调用成功的回调函数,详见返回参数说明
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

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

          示例代码:

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

          Bug & Tip

          1. bug:Android6.3.30,wx.showModal 的返回的 confirm 一直为 true;
          2. tip: wx.showActionSheet 点击取消或蒙层时,回调fail, errMsg 为 "showActionSheet:fail cancel";
          3. tip: wx.showLoading 和 wx.showToast 同时只能显示一个,使用 wx.hideToast/wx.hideLoading 都可以关闭提示框;
          4. tip: iOS wx.showModal 点击蒙层不会关闭模态弹窗,所以尽量避免使用“取消”分支中实现业务逻辑。

          wx.setNavigationBarTitle(OBJECT)


          动态设置当前页面的标题。

          OBJECT参数说明:

          参数类型必填说明
          titleString页面标题
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

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

          wx.showNavigationBarLoading()

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

          wx.hideNavigationBarLoading()

          隐藏导航条加载动画。

          wx.setNavigationBarColor(OBJECT)

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

          OBJECT参数说明:

          参数名类型必填说明
          frontColorString前景颜色值,包括按钮、标题、状态栏的颜色,仅支持 #ffffff 和 #000000
          backgroundColorString背景颜色值,有效值为十六进制颜色
          animationObject动画效果
          animation.durationNumber动画变化时间,默认0,单位:毫秒
          animation.timingFuncString动画变化方式,默认 linear
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          animation.timingFunc 有效值:

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

          success返回参数说明:

          参数名类型说明
          errMsgString调用结果

          示例代码:

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


          wx.setTopBarText(OBJECT)

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

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

          OBJECT参数说明:

          参数类型必填说明
          textString置顶栏文字内容
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.setTopBarText({  text: 'hello, world!'})
          为了满足大家查询需要,我们收集并整理了一份 : 微信小程序导航大全 你可以很方便的通过扫二维码去使用这些小程序。

          wx.navigateTo(OBJECT)

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

          OBJECT 参数说明:

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

          示例代码:

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

          注意:为了不让用户在使用小程序时造成困扰,我们规定页面路径只能是五层,请尽量避免多层级的交互方式。


          wx.redirectTo(OBJECT)

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

          OBJECT 参数说明:

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

          示例代码:

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

          wx.reLaunch(OBJECT)

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

          关闭所有页面,打开到应用内的某个页面。

          OBJECT 参数说明:

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

          示例代码:

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

          wx.switchTab(OBJECT)

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

          OBJECT 参数说明:

          参数类型必填说明
          urlString需要跳转的 tabBar 页面的路径(需在 app.json 的 tabBar 字段定义的页面),路径后不能带参数
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

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

          wx.navigateBack(OBJECT)

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

          OBJECT 参数说明:

          参数类型默认值说明
          deltaNumber1返回的页面数,如果 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

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

          wx.showNavigationBarLoading(Object object)

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

          OBJECT 参数说明:

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          wx.setNavigationBarTitle(Object object)

          动态设置当前页面的标题

          OBJECT 参数说明:

          属性类型默认值必填说明
          titlestring页面标题
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

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

          wx.setNavigationBarColor(Object object)

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

          设置页面导航条颜色

          OBJECT 参数说明:

          属性类型默认值必填说明
          frontColorstring前景颜色值,包括按钮、标题、状态栏的颜色,仅支持 #ffffff 和 #000000
          backgroundColorstring背景颜色值,有效值为十六进制颜色
          animationObject动画效果
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.animation 的结构

          属性类型默认值必填说明
          durationnumber0动画变化时间,单位 ms
          timingFuncstring'linear'动画变化方式

          object.animation.timingFunc 的合法值

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

          示例代码

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

          wx.hideNavigationBarLoading(Object object)

          在当前页面隐藏导航条加载动画

          OBJECT 参数说明:

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          wx.hideHomeButton(Object object)

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

          隐藏返回首页按钮。微信7.0.7版本起,当用户打开的小程序最底层页面是非首页时,默认展示“返回首页”按钮,开发者可在页面 onShow 中调用 hideHomeButton 进行隐藏。

          OBJECT 参数说明:

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          wx.createAnimation(OBJECT)


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

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

          OBJECT参数说明:

          参数类型必填默认值说明
          durationInteger400动画持续时间,单位ms
          timingFunctionString"linear"定义动画的效果
          delayInteger0动画延迟时间,单位 ms
          transformOriginString"50% 50% 0"设置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) transform-function rotate3d

          缩放:

          方法 参数 说明
          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) transform-function matrix
          matrix3d   transform-function matrix3d

          动画队列


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

          示例:

          <view animation="{{animationData}}" style="background:red,height:100rpx,width:100rpx"></view>
          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:animation.export()    })  },  rotateThenScale: function () {    // 先旋转后放大    this.animation.rotate(45).step()    this.animation.scale(2, 2).step()    this.setData({      animationData:animation.export()    })  },  rotateAndScaleThenTranslate: function () {    // 先旋转同时放大,然后平移    this.animation.rotate(45).scale(2, 2).step()    this.animation.translate(100, 100).step({ duration: 1000 })    this.setData({      animationData:animation.export()    })  }})

          bug & tip

          1. bugiOS/Android6.3.30通过 step() 分隔动画,只有第一步动画能生效

          wx.pageScrollTo(OBJECT)

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

          将页面滚动到目标位置。

          OBJECT参数说明:

          属性 类型 默认值 必填 说明 最低版本
           scrollTop number 否 滚动到页面的目标位置,单位 px 
           duration number 300否  滚动动画的时长,单位 ms 
           selector string 否  选择器 2.7.3
           success function 否  接口调用成功的回调函数 
           fail function 否  接口调用失败的回调函数 
           complete function 否  接口调用结束的回调函数(调用成功、失败都会执行) 

          selector 语法

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

          • ID选择器:#the-id
          • class选择器(可以连续指定多个):.a-class.another-class
          • 子元素选择器:.the-parent > .the-child
          • 后代选择器:.the-ancestor .the-descendant
          • 跨自定义组件的后代选择器:.the-ancestor >>> .the-descendant
          • 多选择器的并集:#a-node, .some-other-nodes

          示例代码:

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


          API 接口


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

          context 对象的方法列表


          颜色,样式,阴影

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

          渐变

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

          线条样式

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

          矩形

          方法说明
          rect创建一个矩形
          fillRect填充一个矩形
          strokeRect画一个矩形(不填充)
          clearRect在给定的矩形区域内,清除画布上的像素

          路径

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

          变形

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

          文字

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

          图片

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

          混合

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

          其他

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

          微信小程序 canvas接口和方法绘图接口和方法


          在Canvas上画图


          所有在<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)

          第三步:画图

          告诉<canvas/>组件你要将刚刚的描述绘制上去:

          ctx.draw()

          结果:

          微信小程序 绘图接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          Canvas 坐标系


          canvas 是在一个二维的网格当中。

          左上角的坐标为(0, 0)

          在之前的章节,我们用了这个方法fillRect(0, 0, 150, 75)

          它的含义为:从左上角(0, 0)开始,画一个150 x 75px 的矩形。

          坐标系例子:

          我们可以在<canvas/>中加上一些事件,来观测它的坐标系

          <canvas canvas-id="myCanvas"  style="margin: 5px; border:1px solid #d3d3d3;"  bindtouchstart="start"  bindtouchmove="move"  bindtouchend="end"/><view hidden="{{hidden}}">  Coordinates: ({{x}}, {{y}})</view>
          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    })  }})

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

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 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 gradientconst grd = ctx.createLinearGradient(0, 0, 200, 0)grd.addColorStop(0, 'red')grd.addColorStop(1, 'white')// Fill with gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()



          使用 createCircularGradient()

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


          微信小程序 canvas接口和方法绘图接口和方法

          Color

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

          • RGB 颜色:如'rgb(255, 0, 0)'
          • RGBA 颜色:如'rgba(255, 0, 0, 0.3)'
          • 16 进制颜色:如'#FF0000'
          • 预定义的颜色:如'red'

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

          Note: Color Name 大小写不敏感

          Color NameHEX
          AliceBlue#F0F8FF
          AntiqueWhite#FAEBD7
          Aqua#00FFFF
          Aquamarine#7FFFD4
          Azure#F0FFFF
          Beige#F5F5DC
          Bisque#FFE4C4
          Black#000000
          BlanchedAlmond#FFEBCD
          Blue#0000FF
          BlueViolet#8A2BE2
          Brown#A52A2A
          BurlyWood#DEB887
          CadetBlue#5F9EA0
          Chartreuse#7FFF00
          Chocolate#D2691E
          Coral#FF7F50
          CornflowerBlue#6495ED
          Cornsilk#FFF8DC
          Crimson#DC143C
          Cyan#00FFFF
          DarkBlue#00008B
          DarkCyan#008B8B
          DarkGoldenRod#B8860B
          DarkGray#A9A9A9
          DarkGrey#A9A9A9
          DarkGreen#006400
          DarkKhaki#BDB76B
          DarkMagenta#8B008B
          DarkOliveGreen#556B2F
          DarkOrange#FF8C00
          DarkOrchid#9932CC
          DarkRed#8B0000
          DarkSalmon#E9967A
          DarkSeaGreen#8FBC8F
          DarkSlateBlue#483D8B
          DarkSlateGray#2F4F4F
          DarkSlateGrey#2F4F4F
          DarkTurquoise#00CED1
          DarkViolet#9400D3
          DeepPink#FF1493
          DeepSkyBlue#00BFFF
          DimGray#696969
          DimGrey#696969
          DodgerBlue#1E90FF
          FireBrick#B22222
          FloralWhite#FFFAF0
          ForestGreen#228B22
          Fuchsia#FF00FF
          Gainsboro#DCDCDC
          GhostWhite#F8F8FF
          Gold#FFD700
          GoldenRod#DAA520
          Gray#808080
          Grey#808080
          Green#008000
          GreenYellow#ADFF2F
          HoneyDew#F0FFF0
          HotPink#FF69B4
          IndianRed#CD5C5C
          Indigo#4B0082
          Ivory#FFFFF0
          Khaki#F0E68C
          Lavender#E6E6FA
          LavenderBlush#FFF0F5
          LawnGreen#7CFC00
          LemonChiffon#FFFACD
          LightBlue#ADD8E6
          LightCoral#F08080
          LightCyan#E0FFFF
          LightGoldenRodYellow#FAFAD2
          LightGray#D3D3D3
          LightGrey#D3D3D3
          LightGreen#90EE90
          LightPink#FFB6C1
          LightSalmon#FFA07A
          LightSeaGreen#20B2AA
          LightSkyBlue#87CEFA
          LightSlateGray#778899
          LightSlateGrey#778899
          LightSteelBlue#B0C4DE
          LightYellow#FFFFE0
          Lime#00FF00
          LimeGreen#32CD32
          Linen#FAF0E6
          Magenta#FF00FF
          Maroon#800000
          MediumAquaMarine#66CDAA
          MediumBlue#0000CD
          MediumOrchid#BA55D3
          MediumPurple#9370DB
          MediumSeaGreen#3CB371
          MediumSlateBlue#7B68EE
          MediumSpringGreen#00FA9A
          MediumTurquoise#48D1CC
          MediumVioletRed#C71585
          MidnightBlue#191970
          MintCream#F5FFFA
          MistyRose#FFE4E1
          Moccasin#FFE4B5
          NavajoWhite#FFDEAD
          Navy#000080
          OldLace#FDF5E6
          Olive#808000
          OliveDrab#6B8E23
          Orange#FFA500
          OrangeRed#FF4500
          Orchid#DA70D6
          PaleGoldenRod#EEE8AA
          PaleGreen#98FB98
          PaleTurquoise#AFEEEE
          PaleVioletRed#DB7093
          PapayaWhip#FFEFD5
          PeachPuff#FFDAB9
          Peru#CD853F
          Pink#FFC0CB
          Plum#DDA0DD
          PowderBlue#B0E0E6
          Purple#800080
          RebeccaPurple#663399
          Red#FF0000
          RosyBrown#BC8F8F
          RoyalBlue#4169E1
          SaddleBrown#8B4513
          Salmon#FA8072
          SandyBrown#F4A460
          SeaGreen#2E8B57
          SeaShell#FFF5EE
          Sienna#A0522D
          Silver#C0C0C0
          SkyBlue#87CEEB
          SlateBlue#6A5ACD
          SlateGray#708090
          SlateGrey#708090
          Snow#FFFAFA
          SpringGreen#00FF7F
          SteelBlue#4682B4
          Tan#D2B48C
          Teal#008080
          Thistle#D8BFD8
          Tomato#FF6347
          Turquoise#40E0D0
          Violet#EE82EE
          Wheat#F5DEB3
          White#FFFFFF
          WhiteSmoke#F5F5F5
          Yellow#FFFF00
          YellowGreen#9ACD32

          微信小程序 canvas接口和方法绘图接口和方法


          wx.createCanvasContext(canvasId)


          定义

          创建 canvas 绘图上下文(指定 canvasId)

          Tip: 需要指定 canvasId,该绘图上下文只作用于对应的<canvas/>

          参数

          参数类型说明
          canvasIdString画布表示,传入定义在<canvas/>的 canvas-id

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          wx.createContext (不推荐使用)


          创建并返回绘图上下文。

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          drawCanvas (不推荐使用)


          定义

          用所提供的 actions 在所给的 canvas-id 对应的 canvas 上进行绘图。

          参数

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

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          wx.canvasToTempFilePath(OBJECT)


          把当前画布指定区域的内容导出生成指定大小的图片,并返回文件路径。

          OBJECT参数说明:

          参数类型必填说明最低版本
          xNumber画布x轴起点(默认0)1.2.0
          yNumber画布y轴起点(默认0)1.2.0
          widthNumber画布宽度(默认为canvas宽度-x)1.2.0
          heightNumber画布高度(默认为canvas高度-y)1.2.0
          destWidthNumber输出图片宽度(默认为width)1.2.0
          destHeightNumber输出图片高度(默认为height)1.2.0
          canvasIdString画布标识,传入 <canvas/> 的 cavas-id
          fileTypeString目标文件的类型,只支持 'jpg' 或 'png'。默认为 'png'1.7.0
          qualityNumber图片的质量,取值范围为 (0, 1],不在范围内时当作1.0处理1.7.0
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)


          示例代码

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

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.setFillStyle


          定义

          设置填充色。

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

          参数

          参数类型定义 
          colorColor Gradient Object填充色

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.setStrokeStyle


          定义

          设置边框颜色。

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

          参数

          参数类型定义 
          colorColorGradient Object填充色

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.setShadow


          定义

          设置阴影样式。

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

          参数

          参数类型范围定义
          offsetXNumber 阴影相对于形状在水平方向的偏移
          offsetYNumber 阴影相对于形状在竖直方向的偏移
          blurNumber0~100阴影的模糊级别,数值越大越模糊
          colorColor 阴影的颜色

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.createLinearGradient


          定义

          创建一个线性的渐变颜色。

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

          参数

          参数类型定义
          x0Number起点的x坐标
          y0Number起点的y坐标
          x1Number终点的x坐标
          y1Number终点的y坐标

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.createCircularGradient


          定义

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

          Tip: 起点在圆心,终点在圆环。

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

          参数

          参数类型定义
          xNumber圆心的x坐标
          yNumber圆心的y坐标
          rNumber圆的半径

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.addColorStop


          定义

          创建一个颜色的渐变点。

          Tip: 小于最小 stop 的部分会按最小 stop 的 color 来渲染,大于最大 stop 的部分会按最大 stop 的 color 来渲染。

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

          参数

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

          例子

          const ctx = wx.crateCanvasContext('myCanvas')// Create circular gradientconst grd = ctx.createCircularGradient(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 gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.setLineWidth


          定义

          设置线条的宽度。

          参数

          参数类型说明
          lineWidthNumber线条的宽度(单位是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()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.setLineCap


          定义

          设置线条的端点样式。

          参数

          参数类型范围说明
          lineCapString'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()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.setLineJoin


          定义

          设置线条的交点样式。

          参数

          参数类型范围说明
          lineJoinString'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()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.setMiterLimit


          定义

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

          参数

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

          例子

          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()

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.rect


          定义

          创建一个矩形。

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

          参数

          参数类型说明
          xNumber矩形路径左上角的x坐标
          yNumber矩形路径左上角的y坐标
          widthNumber矩形路径的宽度
          heightNumber矩形路径的高度

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.fillRect


          定义

          填充一个矩形。

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

          参数

          参数类型说明
          xNumber矩形路径左上角的x坐标
          yNumber矩形路径左上角的y坐标
          widthNumber矩形路径的宽度
          heightNumber矩形路径的高度

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.strokeRect


          定义

          画一个矩形(非填充)。

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

          参数

          参数类型范围说明
          xNumber 矩形路径左上角的x坐标
          yNumber 矩形路径左上角的y坐标
          widthNumber 矩形路径的宽度
          heightNumber 矩形路径的高度

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.clearRect


          定义

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

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

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

          参数

          参数类型说明
          xNumber矩形区域左上角的x坐标
          yNumber矩形区域左上角的y坐标
          widthNumber矩形区域的宽度
          heightNumber矩形区域的高度

          例子

          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()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.fill


          定义

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

          Tip: 如果当前路径没有闭合,fill()方法会将起点和终点进行连接,然后填充,详情见例一。

          Tip: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 pathctx.rect(10, 10, 100, 30)ctx.setFillStyle('yellow')ctx.fill()// begin another pathctx.beginPath()ctx.rect(10, 40, 100, 30)// only fill this rect, not in current pathctx.setFillStyle('blue')ctx.fillRect(10, 70, 100, 30)ctx.rect(10, 100, 100, 30)// it will fill current pathctx.setFillStyle('red')ctx.fill()ctx.draw()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          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 pathctx.rect(10, 10, 100, 30)ctx.setStrokeStyle('yellow')ctx.stroke()// begin another pathctx.beginPath()ctx.rect(10, 40, 100, 30)// only stoke this rect, not in current pathctx.setStrokeStyle('blue')ctx.strokeRect(10, 70, 100, 30)ctx.rect(10, 100, 100, 30)// it will stroke current pathctx.setStrokeStyle('red')ctx.stroke()ctx.draw()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.beginPath


          定义

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

          Tip: 在最开始的时候相当于调用了一次beginPath()

          Tip: 同一个路径内的多次setFillStyle()setStrokeStyle()setLineWidth()等设置,以最后一次设置为准。

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.closePath


          定义

          关闭一个路径

          Tip: 关闭路径会连接起点和终点。

          Tip: 如果关闭路径后没有调用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 pathctx.rect(10, 10, 100, 30)ctx.closePath()// begin another pathctx.beginPath()ctx.rect(10, 40, 100, 30)// only fill this rect, not in current pathctx.setFillStyle('blue')ctx.fillRect(10, 70, 100, 30)ctx.rect(10, 100, 100, 30)// it will fill current pathctx.setFillStyle('red')ctx.fill()ctx.draw()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.moveTo


          定义

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

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

          参数

          参数类型说明
          xNumber目标位置的x坐标
          yNumber目标位置的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()

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.lineTo


          定义

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

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

          参数

          参数类型说明
          xNumber目标位置的x坐标
          yNumber目标位置的y坐标

          例子

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

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          canvasContext.arc


          定义

          画一条弧线。

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

          Tip: 用stroke()或者fill()方法来在 canvas 中画弧线。

          参数

          参数类型说明
          xNumber圆的x坐标
          yNumber圆的y坐标
          rNumber圆的半径
          sAngleNumber起始弧度,单位弧度(在3点钟方向)
          eAngleNumber终止弧度
          counterclockwiseBoolean可选。指定弧度的方向是逆时针还是顺时针。默认是false,即顺时针。

          例子

          const ctx = wx.createCanvasContext('myCanvas')// Draw coordinatesctx.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 pointsctx.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 arcctx.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)

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.quadraticCurveTo


          定义

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

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

          参数

          参数类型说明
          cpxNumber贝塞尔控制点的x坐标
          cpyNumber贝塞尔控制点的y坐标
          xNumber结束点的x坐标
          yNumber结束点的y坐标

          例子

          const ctx = wx.createCanvasContext('myCanvas')// Draw pointsctx.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 guidesctx.beginPath()ctx.moveTo(20, 20)ctx.lineTo(20, 100)ctx.lineTo(200, 20)ctx.setStrokeStyle('#AAAAAA')ctx.stroke()// Draw quadratic curvectx.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)

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.bezierCurveTo


          定义

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

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

          参数

          参数类型说明
          cp1xNumber第一个贝塞尔控制点的 x 坐标
          cp1yNumber第一个贝塞尔控制点的 y 坐标
          cp2xNumber第二个贝塞尔控制点的 x 坐标
          cp2yNumber第二个贝塞尔控制点的 y 坐标
          xNumber结束点的 x 坐标
          yNumber结束点的 y 坐标

          例子

          const ctx = wx.createCanvasContext('myCanvas')// Draw pointsctx.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 guidesctx.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 curvectx.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)

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.scale


          定义

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

          参数

          参数类型说明
          scaleWidthNumber横坐标缩放的倍数 (1 = 100%,0.5 = 50%,2 = 200%)
          scaleHeightNumber纵坐标轴缩放的倍数 (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()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.rotate


          定义

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

          参数

          参数类型说明
          rotateNumber旋转角度,以弧度计(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()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.translate


          定义

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

          参数

          参数类型说明
          xNumber水平坐标平移量
          yNumber竖直坐标平移量

          例子

          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()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.setFontSize


          定义

          设置字体的字号。

          参数

          参数类型说明
          fontSizeNumber字体的字号

          例子

          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()


          微信小程序 canvas接口和方法绘图接口和方法

          绘图接口和方法

          canvasContext.fillText


          定义

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

          参数

          string text

          在画布上输出的文本

          number x

          绘制文本的左上角 x 坐标位置

          number y

          绘制文本的左上角 y 坐标位置

          number maxWidth

          需要绘制的最大宽度,可选

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法


          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.setTextAlign


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

          定义

          用于设置文字的对齐

          参数

          参数类型定义
          alignString可选值 '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()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.setTextBaseline

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

          定义

          用于设置文字的水平对齐

          参数

          参数类型定义
          textBaselineString可选值 '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()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.drawImage


          定义

          绘制图像,图像保持原始尺寸。

          参数

          参数类型说明
          imageResourceString所要绘制的图片资源
          xNumber图像左上角的x坐标
          yNumber图像左上角的y坐标
          widthNumber图像宽度
          heightNumber图像高度

          例子

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

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.setGlobalAlpha


          定义

          设置全局画笔透明度。

          参数

          参数类型范围说明
          alphaNumber0~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()


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.save


          定义

          保存当前的绘图上下文。

          restore


          定义

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

          例子

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


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.draw


          定义

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

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

          参数

          参数类型说明最低版本
          reserveBoolean非必填。本次绘制是否接着上一次绘制,即reserve参数为false,则在本次调用drawCanvas绘制之前native层应先清空画布再继续绘制;若reserver参数为true,则保留当前画布上的内容,本次调用drawCanvas绘制的内容覆盖在上面,默认 false
          callbackFunction绘制完成后回调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)


          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法


          getActions (不推荐使用)


          返回绘图上下文的绘图动作。

          微信小程序 canvas接口和方法绘图接口和方法

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.clearActions (不推荐使用)


          清空绘图上下文的绘图动作。

          微信小程序 canvas接口和方法绘图接口和方法

          canvasContext.measureText


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

          定义

          测量文本尺寸信息,目前仅返回文本宽度。同步接口。

          参数

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

          返回

          返回 TextMetrics 对象,结构如下:

          参数类型说明
          widthNumber文本的宽度

          例子

          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

          参数

          属性值类型说明
          typeString标识要使用哪种合成或混合模式操作

          type 支持的操作有:

          平台操作
          安卓xor, source-over, source-atop, destination-out, lighter, overlay, darken, lighten, hard-light
          iOSxor, 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

          canvasContext.arcTo


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

          定义

          根据控制点和半径绘制圆弧路径。

          语法

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

          参数

          属性值类型说明
          x1Number第一个控制点的 x 轴坐标
          y1Number第一个控制点的 y 轴坐标
          x2Number第二个控制点的 x 轴坐标
          y2Number第二个控制点的 y 轴坐标
          radiusNumber圆弧的半径

          canvasContext.strokeText


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

          定义

          给定的 (x, y) 位置绘制文本描边的方法

          语法

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

          参数

          属性值类型说明
          textString要绘制的文本
          xNumber文本起始点的 x 轴坐标
          yNumber文本起始点的 y 轴坐标
          maxWidthNumber需要绘制的最大宽度,可选

          canvasContext.lineDashOffset


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

          定义

          设置虚线偏移量的属性

          语法

          canvasContext.lineDashOffset = value

          参数

          属性值类型说明
          valueNumber偏移量,初始值为 0

          canvasContext.createPattern


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

          定义

          对指定的图像创建模式的方法,可在指定的方向上重复元图像

          语法

          canvasContext.createPattern(image, repetition)

          参数

          属性值类型说明
          imageString重复的图像源,仅支持包内路径和临时路径
          repetitionString指定如何重复图像,有效值有: repeat, repeat-x, repeat-y, no-repeat

          例子

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

          onPullDownRefresh


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

          • 需要在configwindow选项中开启enablePullDownRefresh
          • 当处理完数据刷新后,wx.stopPullDownRefresh可以停止当前页面的下拉刷新。

          wx.startPullDownRefresh(OBJECT)

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

          开始下拉刷新,调用后触发下拉刷新动画,效果与用户手动下拉刷新一致

          Object参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

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

          示例代码:

          wx.startPullDownRefresh()

          wx.stopPullDownRefresh()

          停止当前页面下拉刷新。

          示例代码:

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


          wx.setBackgroundTextStyle(Object object)

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

          动态设置下拉背景字体、loading 图的样式

          参数

          Object object

          属性类型默认值必填说明
          textStylestring下拉背景字体、loading 图的样式。
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.textStyle 的合法值

          说明最低版本
          darkdark 样式
          lightlight 样式

          示例代码

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

          wx.setBackgroundColor(Object object)

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

          动态设置窗口的背景色

          参数

          Object object

          属性类型默认值必填说明
          backgroundColorstring窗口的背景色,必须为十六进制颜色值
          backgroundColorTopstring顶部窗口的背景色,必须为十六进制颜色值,仅 iOS 支持
          backgroundColorBottomstring底部窗口的背景色,必须为十六进制颜色值,仅 iOS 支持
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

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


          wx.pageScrollTo(Object object)

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

          将页面滚动到目标位置,支持选择器和滚动距离两种方式定位

          参数

          Object object

          属性类型默认值必填说明最低版本
          scrollTopnumber滚动到页面的目标位置,单位 px
          durationnumber300滚动动画的时长,单位 ms
          selectorstring选择器2.7.3
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          selector 语法

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

          • ID选择器:#the-id
          • class选择器(可以连续指定多个):.a-class.another-class
          • 子元素选择器:.the-parent > .the-child
          • 后代选择器:.the-ancestor .the-descendant
          • 跨自定义组件的后代选择器:.the-ancestor >>> .the-descendant
          • 多选择器的并集:#a-node, .some-other-nodes

          示例代码

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


          wx.loadFontFace(Object object)

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

          动态加载网络字体,文件地址需为下载类型。'2.10.0'起支持全局生效,需在 app.js 中调用。

          注意:

          1. 字体文件返回的 contet-type 参考 font,格式不正确时会解析失败。
          2. 字体链接必须是https(ios不支持http)
          3. 字体链接必须是同源下的,或开启了cors支持,小程序的域名是servicewechat.com
          4. canvas等原生组件不支持使用接口添加的字体
          5. 工具里提示 Faild to load font可以忽略
          6. '2.10.0' 以前仅在调用页面生效。

          参数

          Object object

          属性类型默认值必填说明最低版本
          globalbooleanfalse是否全局生效2.10.0
          familystring定义的字体名称
          sourcestring字体资源的地址。建议格式为 TTF 和 WOFF,WOFF2 在低版本的iOS上会不兼容。
          descObject可选的字体描述符
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.desc 的结构

          属性类型默认值必填说明
          stylestring'normal'字体样式,可选值为 normal / italic / oblique
          weightstring'normal'字体粗细,可选值为 normal / bold / 100 / 200../ 900
          variantstring'normal'设置小型大写字母的字体显示文本,可选值为 normal / small-caps / inherit

          object.success 回调函数

          参数
          Object res
          属性类型说明
          statusstring加载字体结果

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          statusstring加载字体结果

          object.complete 回调函数

          参数
          Object res
          属性类型说明
          statusstring加载字体结果

          示例代码

          在开发者工具中预览效果

          wx.loadFontFace({  family: 'Bitstream Vera Serif Bold',  source: 'url("https://sungd.github.io/Pacifico.ttf")',  success: console.log})


          wx.showTabBarRedDot(Object object)

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

          显示 tabBar 某一项的右上角的红点

          参数

          Object object

          属性类型默认值必填说明
          indexnumbertabBar 的哪一项,从左边算起
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          wx.showTabBar(Object object)

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

          显示 tabBar

          参数

          Object object

          属性类型默认值必填说明
          animationbooleanfalse是否需要动画效果
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)




          wx.setTabBarStyle(Object object)

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

          动态设置 tabBar 的整体样式

          参数

          Object object

          属性类型默认值必填说明
          colorstringtab 上的文字默认颜色,HexColor
          selectedColorstringtab 上的文字选中时的颜色,HexColor
          backgroundColorstringtab 的背景色,HexColor
          borderStylestringtabBar上边框的颜色, 仅支持 black/white
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

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




          wx.setTabBarItem(Object object)

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

          动态设置 tabBar 某一项的内容,2.7.0 起图片支持临时文件和网络文件。

          参数

          Object object

          属性类型默认值必填说明
          indexnumbertabBar 的哪一项,从左边算起
          textstringtab 上的按钮文字
          iconPathstring图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px,当 postion 为 top 时,此参数无效
          selectedIconPathstring选中时的图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px ,当 postion 为 top 时,此参数无效
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

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




          wx.setTabBarBadge(Object object)

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

          为 tabBar 某一项的右上角添加文本

          参数

          Object object

          属性类型默认值必填说明
          indexnumbertabBar 的哪一项,从左边算起
          textstring显示的文本,超过 4 个字符则显示成 ...
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

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




          wx.removeTabBarBadge(Object object)

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

          移除 tabBar 某一项右上角的文本

          参数

          Object object

          属性类型默认值必填说明
          indexnumbertabBar 的哪一项,从左边算起
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)




          wx.hideTabBarRedDot(Object object)

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

          隐藏 tabBar 某一项的右上角的红点

          参数

          Object object

          属性类型默认值必填说明
          indexnumbertabBar 的哪一项,从左边算起
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)




          wx.hideTabBar(Object object)

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

          隐藏 tabBar

          参数

          Object object

          属性类型默认值必填说明
          animationbooleanfalse是否需要动画效果
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          wx.setWindowSize(Object object)

          基础库 2.10.1 开始支持,低版本需做兼容处理
          从基础库 2.11.0 开始,本接口停止维护

          设置窗口大小,该接口仅适用于 PC 平台,使用细则请参见指南

          参数

          Object object

          属性类型默认值必填说明
          widthnumber窗口宽度,以像素为单位
          heightnumber窗口高度,以像素为单位
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)




          wx.onWindowResize(function callback)

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

          监听窗口尺寸变化事件

          参数

          function callback

          窗口尺寸变化事件的回调函数

          参数

          Object res
          属性类型说明
          sizeObject

          size 的结构

          属性类型说明
          windowWidthnumber变化后的窗口宽度,单位 px
          windowHeightnumber变化后的窗口高度,单位 px




          wx.offWindowResize(function callback)

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

          取消监听窗口尺寸变化事件

          参数

          function callback

          窗口尺寸变化事件的回调函数


          Object wx.getMenuButtonBoundingClientRect()

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

          获取菜单按钮(右上角胶囊按钮)的布局位置信息。坐标信息以屏幕左上角为原点。

          返回值

          Object

          菜单按钮的布局位置信息

          属性类型说明
          widthnumber宽度,单位:px
          heightnumber高度,单位:px
          topnumber上边界坐标,单位:px
          rightnumber右边界坐标,单位:px
          bottomnumber下边界坐标,单位:px
          leftnumber左边界坐标,单位:px


          wx.createSelectorQuery()

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

          返回一个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 对象的方法列表:

          方法参数说明
          selectselector参考下面详细介绍
          selectAllselector参考下面详细介绍
          selectViewport 参考下面详细介绍
          exec[callback]参考下面详细介绍

          selectorQuery.select(selector)

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

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

          • ID选择器:#the-id
          • class选择器(可以连续指定多个):.a-class.another-class
          • 子元素选择器:.the-parent > #the-child.a-class
          • 多选择器的并集:#a-node, .some-other-nodes

          selectorQuery.selectAll(selector)

          在当前页面下选择匹配选择器selector的节点,返回一个NodesRef对象实例。 与selectorQuery.selectNode(selector)不同的是,它选择所有匹配选择器的节点。

          selectorQuery.selectViewport()

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

          nodesRef.boundingClientRect([callback])

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

          返回的节点信息中,每个节点的位置用leftrighttopbottomwidthheight字段描述。如果提供了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。

          返回的节点信息中,每个节点的滚动位置用scrollLeftscrollHeight字段描述。如果提供了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 和事件绑定的属性值不可获取)

          示例代码:

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

          selectorQuery.exec([callback])

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

          wx.getExtConfig(OBJECT)

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

          获取第三方平台自定义的数据字段。

          OBJECT参数说明:

          参数类型必填返回
          successFunction返回第三方平台自定义的数据
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数类型说明
          errMsgString调用结果
          extConfigObject第三方平台自定义的数据

          Bug & Tip

          1. wx.getExtConfig暂时无法通过wx.canIUse判断是否兼容,开发者需要自行判断wx.getExtConfig是否存在来兼容

          示例代码:

          if(wx.getExtConfig) {  wx.getExtConfig({    success: function (res) {      console.log(res.extConfig)    }  })}

          wx.getExtConfigSync()

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

          获取第三方平台自定义的数据字段的同步接口。

          返回说明:

          参数类型说明
          extConfigObject第三方平台自定义的数据

          Bug & Tip

          1. wx.getExtConfigSync暂时无法通过wx.canIUse判断是否兼容,开发者需要自行判断wx.getExtConfigSync是否存在来兼容

          示例代码:

          let extConfig = wx.getExtConfigSync? wx.getExtConfigSync(): {}console.log(extConfig)

          wx.login(OBJECT)


          调用接口获取登录凭证(code)进而换取用户登录态信息,包括用户的唯一标识(openid) 及本次登录的 会话密钥(session_key)用户数据的加解密通讯需要依赖会话密钥完成。


          OBJECT参数说明:

          参数名类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数名类型说明
          errMsgString调用结果
          codeString用户允许登录后,回调内容会带上 code(有效期五分钟),开发者需要将 code 发送到开发者服务器后台,使用code 换取 session_key api,将 code 换成 openid 和 session_key

          示例代码:

          //app.jsApp({  onLaunch: function() {    wx.login({      success: function(res) {        if (res.code) {          //发起网络请求          wx.request({            url: 'https://test.com/onLogin',            data: {              code: res.code            }          })        } else {          console.log('获取用户登录态失败!' + res.errMsg)        }      }    });  }})

          code 换取 session_key

          ​这是一个 HTTPS 接口,开发者服务器使用登录凭证 code 获取 session_key 和 openid。其中 session_key 是对用户数据进行加密签名的密钥。为了自身应用安全,session_key 不应该在网络上传输

          接口地址:

          https://api.weixin.qq.com/sns/jscode2session?appid=APPID&secret=SECRET&js_code=JSCODE&grant_type=authorization_code

          请求参数:

          参数必填说明
          appid小程序唯一标识
          secret小程序的 app secret
          js_code登录时获取的 code
          grant_type填写为 authorization_code

          返回参数:

          参数说明
          openid用户唯一标识
          session_key会话密钥
          unionid用户在开放平台的唯一标识符。本字段在满足一定条件的情况下才返回。具体参看UnionID机制说明

          返回说明:

          //正常返回的JSON数据包{      "openid": "OPENID",      "session_key": "SESSIONKEY"      "unionid":  "UNIONID"}//错误时返回JSON数据包(示例为Code无效){    "errcode": 40029,    "errmsg": "invalid code"}


          wx.checkSession(OBJECT)


          通过上述接口获得的用户登录态拥有一定的时效性。用户越久未使用小程序,用户登录态越有可能失效。反之如果用户一直在使用小程序,则用户登录态一直保持有效。具体时效逻辑由微信维护,对开发者透明。开发者只需要调用wx.checkSession接口检测当前用户登录态是否有效。登录态过期后开发者可以再调用wx.login获取新的用户登录态。

          OBJECT参数说明:

          参数名类型必填说明
          successFunction接口调用成功的回调函数,登陆态未过期
          failFunction接口调用失败的回调函数,登陆态已过期
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.checkSession({  success: function(){    //session 未过期,并且在本生命周期一直有效  },  fail: function(){    //登录态过期    wx.login() //重新登录    ....  }})


          登录态维护

          通过wx.login()获取到用户登录态之后,需要维护登录态。开发者要注意不应该直接把 session_key、openid 等字段作为用户的标识或者 session 的标识,而应该自己派发一个 session 登录态(请参考登录时序图)。对于开发者自己生成的 session,应该保证其安全性且不应该设置较长的过期时间。session 派发到小程序客户端之后,可将其存储在 storage ,用于后续通信使用。

          通过wx.checkSession()检测用户登录态是否失效。并决定是否调用wx.login() 重新获取登录态

          登录时序图

          登录时序图


          Bug & Tip

          1. bug: iOS/Android 6.3.30,在 App.onLaunch 调用 wx.login 会出现异常;

          用户数据的签名验证和加解密


          数据签名校验

          为了确保 开放接口 返回用户数据的安全性,微信会对明文数据进行签名。开发者可以根据业务需要对数据包进行签名校验,确保数据的完整性。

          1. 签名校验算法涉及用户的session_key,通过 wx.login 登录流程获取用户session_key,并自行维护与应用自身登录态的对应关系。
          2. 通过调用接口(如 wx.getUserInfo)获取数据时,接口会同时返回 rawData、signature,其中 signature = sha1( rawData + session_key )
          3. 开发者将 signature、rawData 发送到开发者服务器进行校验。服务器利用用户对应的 session_key 使用相同的算法计算出签名 signature2 ,比对 signature 与 signature2 即可校验数据的完整性。

          如wx.getUserInfo的数据校验:

          接口返回的rawData:

          {  "nickName": "Band",  "gender": 1,  "language": "zh_CN",  "city": "Guangzhou",  "province": "Guangdong",  "country": "CN",  "avatarUrl": "http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"}

          用户的 session-key:

          HyVFkGl5F5OQWJZZaNzBBg==

          所以,用于签名的字符串为:

          {"nickName":"Band","gender":1,"language":"zh_CN","city":"Guangzhou","province":"Guangdong","country":"CN","avatarUrl":"http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"}HyVFkGl5F5OQWJZZaNzBBg==

          使用sha1得到的结果为

          75e81ceda165f4ffa64f4068af58c64b8f54b88c

          加密数据解密算法

          接口如果涉及敏感数据(如wx.getUserInfo当中的 openId 和unionId ),接口的明文内容将不包含这些敏感数据。开发者如需要获取敏感数据,需要对接口返回的加密数据( encryptedData )进行对称解密。解密算法如下:

          1. 对称解密使用的算法为 AES-128-CBC,数据采用PKCS#7填充。
          2. 对称解密的目标密文为 Base64_Decode(encryptedData),
          3. 对称解密秘钥 aeskey = Base64_Decode(session_key), aeskey 是16字节
          4. 对称解密算法初始向量 iv 会在数据接口中返回。

          微信官方提供了多种编程语言的示例代码(点击下载)。每种语言类型的接口名字均一致。调用方式可以参照示例。

          另外,为了应用能校验数据的有效性,我们会在敏感数据加上数据水印( watermark )

          watermark参数说明:

          参数类型说明
          watermarkOBJECT数据水印
          appidString敏感数据归属appid,开发者可校验此参数与自身appid是否一致
          timestampDateInt敏感数据获取的时间戳, 开发者可以用于数据时效性校验

          如接口wx.getUserInfo敏感数据当中的watermark:

          {    "openId": "OPENID",    "nickName": "NICKNAME",    "gender": GENDER,    "city": "CITY",    "province": "PROVINCE",    "country": "COUNTRY",    "avatarUrl": "AVATARURL",    "unionId": "UNIONID",    "watermark":    {        "appid":"APPID",        "timestamp":TIMESTAMP    }}

          注:此前提供的加密数据(encryptData)以及对应的加密算法将被弃用,请开发者不要再依赖旧逻辑。

          wx.navigateToMiniProgram(OBJECT)


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

          iOS 微信客户端 6.5.9 版本开始支持,Android 客户端即将在 6.5.10 版本开始支持,请先使用 iOS 客户端进行调试

          打开同一公众号下关联的另一个小程序。

          OBJECT参数说明:

          参数名类型必填说明
          appIdString要打开的小程序 appId
          pathString打开的页面路径,如果为空则打开首页
          extraDataObject需要传递给目标小程序的数据,目标小程序可在 App.onLaunch()App.onShow()中获取到这份数据。详情
          envVersionString要打开的小程序版本,有效值 develop(开发版),trial(体验版),release(正式版) ,仅在当前小程序为开发版或体验版时此参数有效;如果当前小程序是体验版或正式版,则打开的小程序必定是正式版。默认值 release
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数名类型说明
          errMsgString调用结果

          示例代码:

          wx.navigateToMiniProgram({  appId: '',  path: 'pages/index/index?id=123',  extraData: {    foo: 'bar'  },  envVersion: 'develop',  success(res) {    // 打开成功  }})

          Bug & Tip

          1. tip: 在开发者工具上调用此 API 并不会真实的跳转到另外的小程序,但是开发者工具会校验本次调用跳转是否成功详情
          2. tip: 开发者工具上支持被跳转的小程序处理接收参数的调试详情
          3. tip: 只有同一公众号下的关联的小程序之间才可相互跳转 详情

          wx.navigateBackMiniProgram(OBJECT)


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

          iOS 微信客户端 6.5.9 版本开始支持,Android 客户端即将在 6.5.10 版本开始支持,请先使用 iOS 客户端进行调试

          返回到上一个小程序,只有在当前小程序是被其他小程序打开时可以调用成功

          OBJECT参数说明:

          参数名类型必填说明
          extraDataObject需要返回给上一个小程序的数据,上一个小程序可在App.onShow()中获取到这份数据。详情
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数名类型说明
          errMsgString调用结果

          示例代码:

          wx.navigateBackMiniProgram({  extraData: {    foo: 'bar'  },  success(res) {    // 返回成功  }})


          Object wx.getAccountInfoSync()

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

          获取当前帐号信息。线上小程序版本号仅支持在正式版小程序中获取,开发版和体验版中无法获取。

          返回值

          Object

          帐号信息

          属性类型说明
          miniProgramObject小程序帐号信息
          pluginObject插件帐号信息(仅在插件中调用时包含这一项)

          miniProgram 的结构

          属性类型说明最低版本
          appIdstring小程序 appId
          envVersionstring小程序版本2.10.0
          versionstring线上小程序版本号2.10.2

          miniProgram.envVersion 的合法值

          说明最低版本
          develop开发版
          trial体验版
          release正式版

          plugin 的结构

          属性类型说明
          appIdstring插件 appId
          versionstring插件版本号

          示例代码

          const accountInfo = wx.getAccountInfoSync();console.log(accountInfo.miniProgram.appId) // 小程序 appIdconsole.log(accountInfo.plugin.appId) // 插件 appIdconsole.log(accountInfo.plugin.version) // 插件版本号, 'a.b.c' 这样的形式


          wx.getUserInfo(OBJECT)

          ​获取用户信息,withCredentials 为 true 时需要先调用wx.login接口

          OBJECT参数说明:

          参数名类型必填说明最低版本
          withCredentialsBoolean是否带上登录态信息1.1.0
          langString指定返回用户信息的语言,zh_CN 简体中文,zh_TW 繁体中文,en 英文1.4.0
          successFunction接口调用成功的回调函数 
          failFunction接口调用失败的回调函数 
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行) 

          注:当 withCredentials 为 true 时,要求此前有调用过 wx.login 且登录态尚未过期,此时返回的数据会包含 encryptedData, iv 等敏感信息;当 withCredentials 为 false 时,不要求有登录态,返回的数据不包含 encryptedData, iv 等敏感信息。

          success返回参数说明:
          参数类型说明
          userInfoOBJECT用户信息对象,不包含 openid 等敏感信息
          rawDataString不包括敏感信息的原始数据字符串,用于计算签名。
          signatureString使用 sha1( rawData + sessionkey ) 得到字符串,用于校验用户信息,参考文档signature
          encryptedDataString包括敏感数据在内的完整用户信息的加密数据,详细见加密数据解密算法
          ivString加密算法的初始向量,详细见加密数据解密算法

          示例代码:

          wx.getUserInfo({  success: function(res) {    var userInfo = res.userInfo    var nickName = userInfo.nickName    var avatarUrl = userInfo.avatarUrl    var gender = userInfo.gender //性别 0:未知、1:男、2:女     var province = userInfo.province    var city = userInfo.city    var country = userInfo.country  }})

          encryptedData 解密后为以下 json 结构,详见加密数据解密算法

          {    "openId": "OPENID",    "nickName": "NICKNAME",    "gender": GENDER,    "city": "CITY",    "province": "PROVINCE",    "country": "COUNTRY",    "avatarUrl": "AVATARURL",    "unionId": "UNIONID",    "watermark":    {        "appid":"APPID",    "timestamp":TIMESTAMP    }}

          Bug & Tip

          1. tip:wx.getUserInfo接口需要用户授权,请兼容用户拒绝授权的场景。

          UnionID机制说明:

          如果开发者拥有多个移动应用、网站应用、和公众帐号(包括小程序),可通过unionid来区分用户的唯一性,因为只要是同一个微信开放平台帐号下的移动应用、网站应用和公众帐号(包括小程序),用户的unionid是唯一的。换句话说,同一用户,对同一个微信开放平台下的不同应用,unionid是相同的。

          同一个微信开放平台下的相同主体的App、公众号、小程序,如果用户已经关注公众号,或者曾经登录过App或公众号,则用户打开小程序时,开发者可以直接通过wx.login获取到该用户UnionID,无须用户再次授权。

          微信开放平台绑定小程序流程

          前提:微信开放平台帐号必须已完成开发者资质认证

          开发者资质认证流程:

          登录微信开放平台(open.weixin.qq.com) – 帐号中心 – 开发者资质认证

          绑定流程:

          登录微信开放平台(open.weixin.qq.com)—管理中心—公众帐号—绑定公众帐号





          wx.reportMonitor(string name, number value)

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

          自定义业务数据监控上报接口。

          参数

          string name

          监控ID,在「小程序管理后台」新建数据指标后获得

          number value

          上报数值,经处理后会在「小程序管理后台」上展示每分钟的上报总量

          使用说明

          使用前,需要在「小程序管理后台-运维中心-性能监控-业务数据监控」中新建监控事件,配置监控描述与告警类型。每一个监控事件对应唯一的监控ID,开发者最多可以创建128个监控事件。

          示例代码

          wx.reportMonitor('1', 1)


          wx.reportAnalytics(string eventName, Object data)

          自定义分析数据上报接口。使用前,需要在小程序管理后台自定义分析中新建事件,配置好事件名与字段。

          参数

          string eventName

          事件名

          Object data

          上报的自定义数据,key 为配置中的字段名,value 为上报的数据。

          示例代码

          wx.reportAnalytics('purchase', {  price: 120,  color: 'red'})


          wx.requestPayment(OBJECT)

          发起微信支付。

          Object参数说明:

          参数类型必填说明
          timeStampString时间戳从1970年1月1日00:00:00至今的秒数,即当前的时间
          nonceStrString随机字符串,长度为32个字符以下。
          packageString统一下单接口返回的 prepay_id 参数值,提交格式如:prepay_id=*
          signTypeString签名算法,暂支持 MD5
          paySignString签名,具体签名方案参见小程序支付接口文档;
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          了解更多信息,请查看微信支付接口文档

          回调结果:

          回调类型errMsg说明
          successrequestPayment:ok调用支付成功
          failrequestPayment:fail cancel用户取消支付
          failrequestPayment:fail (detail message)调用支付失败,其中 detail message 为后台返回的详细失败原因


          示例代码:

          wx.requestPayment({   "timeStamp": "",   "nonceStr": "",   "package": "",   "signType": "MD5",   "paySign": "",   "success":function(res){   },   "fail":function(res){   }})


          Bug & Tip

          1. bug: 6.5.2 及之前版本中,用户取消支付不会触发 fail 回调,只会触发 complete 回调,回调 errMsg 为 'requestPayment:cancel'

          wx.authorize(OBJECT)


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

          部分接口需要获得同意后才能调用。此类接口调用时,如果用户未授权过,会弹窗询问用户,用户点击同意后方可调用接口。如果用户点了拒绝,则短期内调用不会出现弹窗,而是直接进入 fail 回调。用户可以在小程序设置界面中修改对该小程序的授权信息。本接口用于提前向用户发起授权,调用后会立刻弹窗询问用户是否同意小程序使用某项功能或获取用户的某些数据,但不会实际调用接口。如果用户之前已经同意,则不会出现弹窗,直接返回成功。

          OBJECT参数说明:

          参数名类型必填说明
          scopeString需要获取权限的scope,详见 scope 列表
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数名类型说明
          errMsgString调用结果

          示例代码:

          // 可以通过 wx.getSetting 先查询一下用户是否授权了 "scope.record" 这个 scopewx.getSetting({    success(res) {        if (!res.authSetting['scope.record']) {            wx.authorize({                scope: 'scope.record',                success() {                    // 用户已经同意小程序使用录音功能,后续调用 wx.startRecord 接口不会弹窗询问                    wx.startRecord()                }            })        }    }})

          scope 列表

          scope对应接口描述
          scope.userInfowx.getUserInfo用户信息
          scope.userLocationwx.getLocation, wx.chooseLocation地理位置
          scope.addresswx.chooseAddress通讯地址
          scope.recordwx.startRecord录音功能
          scope.writePhotosAlbumwx.saveImageToPhotosAlbum, wx.saveVideoToPhotosAlbum保存到相册

          wx.openSetting(OBJECT)


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

          调起客户端小程序设置界面,返回用户设置的操作结果

          Object 参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数,返回内容详见返回参数说明。
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数类型说明
          authSettingObject用户授权结果,其中 key 为 scope 值,value 为 Bool 值,表示用户是否允许授权,详见 scope 列表

          示例代码:

          wx.openSetting({  success: (res) => {    /*     * res.authSetting = {     *   "scope.userInfo": true,     *   "scope.userLocation": true     * }     */  }})

          OpenSettingButton wx.createOpenSettingButton(string type, string text, string image, Object style)


          支持版本 >= 2.0.7

          创建打开设置页面的按钮。

          参数

          string type

          按钮的类型

          type 的合法值:

          说明
          text可以设置背景色和文本的按钮
          image只能设置背景贴图的按钮,背景贴图会直接拉伸到按钮的宽高

          string text

          按钮上的文本,仅当 type 为 text 时有效

          string image

          按钮的背景图片,仅当 type 为 image 时有效

          Object style

          按钮的样式

          属性类型默认值是否必填说明支持版本
          leftnumber左上角横坐标
          topnumber左上角纵坐标
          widthnumber宽度
          heightnumber高度
          backgroundColorstring背景颜色
          borderColorstring边框颜色
          borderWidthnumber边框宽度
          borderRadiusnumber边框圆角
          textAlignstring文本的水平居中方式
          fontSizenumber字号
          lineHeightnumber文本的行高

          style.textAlign 的合法值:

          说明
          left居左
          center居中
          right居右

          返回值

          OpenSettingButton

          示例代码

          let button = wx.createOpenSettingButton({    type: 'text',    text: '打开设置页面',    style: {        left: 10,        top: 76,        width: 200,        height: 40,        lineHeight: 40,        backgroundColor: '#ff0000',        color: '#ffffff',        textAlign: 'center',        fontSize: 16,        borderRadius: 4    }})

          wx.getSetting(OBJECT)


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

          获取用户的当前设置

          Object 参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数,返回内容详见返回参数说明。
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数类型说明
          authSettingObject用户授权结果,其中 key 为 scope 值,value 为 Bool 值,表示用户是否允许授权,详见 scope 列表

          示例代码:

          wx.getSetting({  success: (res) => {    /*     * res.authSetting = {     *   "scope.userInfo": true,     *   "scope.userLocation": true     * }     */  }})


          wx.chooseAddress(OBJECT)


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

          调起用户编辑收货地址原生界面,并在编辑完成后返回用户选择的地址。

          OBJECT参数说明:

          参数类型必填返回
          successFunction返回用户选择的收货地址信息
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数类型说明
          errMsgString调用结果
          userNameString收货人姓名
          postalCodeString邮编
          provinceNameString国标收货地址第一级地址
          cityNameString国标收货地址第二级地址
          countyNameString国标收货地址第三级地址
          detailInfoString详细收货地址信息
          nationalCodeString收货地址国家码
          telNumberString收货人手机号码

          示例代码:

          wx.chooseAddress({  success: function (res) {    console.log(res.userName)    console.log(res.postalCode)    console.log(res.provinceName)    console.log(res.cityName)    console.log(res.countyName)    console.log(res.detailInfo)    console.log(res.nationalCode)    console.log(res.telNumber)  }})

          Bug & Tip

          1. tip:wx.chooseAddress接口需要用户授权,请兼容用户拒绝授权的场景。

          wx.addCard(OBJECT)


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

          批量添加卡券。

          Object参数说明:

          参数类型必填说明
          cardListObjectArray需要添加的卡券列表,列表内对象说明请参见请求对象说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          请求对象说明

          参数类型说明
          cardIdString卡券 Id
          cardExtString卡券的扩展参数

          cardExt 说明

          参数类型必填是否参与签名说明
          codeString用户领取的 code,仅自定义 code 模式的卡券须填写,非自定义 code 模式卡券不可填写,详情
          openidString指定领取者的openid,只有该用户能领取。 bind_openid 字段为 true 的卡券必须填写,bind_openid 字段为 false 不可填写。
          timestampNumber时间戳,东八区时间,UTC+8,单位为秒
          nonce_strString随机字符串,由开发者设置传入,加强安全性(若不填写可能被重放请求)。随机字符串,不长于 32 位。推荐使用大小写字母和数字,不同添加请求的 nonce_str 须动态生成,若重复将会导致领取失败。
          fixed_begintimestampNumber卡券在第三方系统的实际领取时间,为东八区时间戳(UTC+8,精确到秒)。当卡券的有效期类为 DATE_TYPE_FIX_TERM 时专用,标识卡券的实际生效时间,用于解决商户系统内起始时间和领取微信卡券时间不同步的问题。
          outer_strString领取渠道参数,用于标识本次领取的渠道值。
          signatureString-签名,商户将接口列表中的参数按照指定方式进行签名,签名方式使用 SHA1,具体签名方案参见:卡券签名

          注:cardExt 需进行 JSON 序列化为字符串传入

          回调结果:

          回调类型errMsg说明
          successaddCard:ok添加卡券成功
          failaddCard:fail cancel用户取消添加卡券
          failaddCard:fail (detail message)添加卡券失败,其中 detail message 为后台返回的详细失败原因

          success返回参数:

          参数类型说明
          cardListObjectArray卡券添加结果列表,列表内对象说明请详见返回对象说明

          返回对象说明

          参数类型说明
          codeString加密 code,为用户领取到卡券的code加密后的字符串,解密请参照:code 解码接口
          cardIdString用户领取到卡券的Id
          cardExtString用户领取到卡券的扩展参数,与调用时传入的参数相同
          isSuccessBoolean是否成功

          示例代码:

          wx.addCard({  cardList: [    {      cardId: '',      cardExt: '{"code": "", "openid": "", "timestamp": "", "signature":""}'    }, {      cardId: '',      cardExt: '{"code": "", "openid": "", "timestamp": "", "signature":""}'    }  ],  success: function(res) {    console.log(res.cardList) // 卡券添加结果  }})

          wx.openCard(OBJECT)


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

          查看微信卡包中的卡券。

          Object参数说明:

          参数类型必填说明
          cardListObjectArray需要打开的卡券列表,列表内参数详见openCard 请求对象说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          openCard 请求对象说明

          参数类型说明
          cardIdString需要打开的卡券 Id
          codeString由 addCard 的返回对象中的加密 code 通过解密后得到,解密请参照:code 解码接口

          示例代码:

          wx.openCard({  cardList: [    {      cardId: '',      code: ''    }, {      cardId: '',      code: ''    }  ],  success: function(res) {  }})

          Tip

          1. tip: 目前只有认证小程序才能使用卡券接口,可参考指引进行认证。
          2. tip: 了解更多信息,请查看微信卡券接口文档

          基于微信的通知渠道,我们为开发者提供了可以高效触达用户的模板消息能力,以便实现服务的闭环并提供更佳的体验。

          模板推送位置:服务通知

          模板下发条件:用户本人在微信体系内与页面有交互行为后触发,详见下发条件说明

          模板跳转能力:点击查看详情仅能跳转下发模板的该帐号的各个页面

          使用说明

          步骤一:获取模板ID

          有两个方法可以获取模版ID

          1. 通过模版消息管理接口获取模版ID(详见模版消息管理
          2. 在微信公众平台手动配置获取模版ID

          ​登录https://mp.weixin.qq.com获取模板,如果没有合适的模板,可以申请添加新模板,审核通过后可使用,详见模板审核说明

          小程序 模板消息

          步骤二:页面的<form/>组件,属性report-submittrue时,可以声明为需发模板消息,此时点击按钮提交表单可以获取formId,用于发送模板消息。或者当用户完成支付行为,可以获取prepay_id用于发送模板消息。

          步骤三:调用接口下发模板消息(详见发送模板消息


          模版消息管理

          1.获取小程序模板库标题列表

          接口地址

          https://api.weixin.qq.com/cgi-bin/wxopen/template/library/list?access_token=ACCESS_TOKEN

          HTTP请求方式:

          POST

          POST参数说明:

          参数必填说明
          access_token接口调用凭证
          offsetoffset和count用于分页,表示从offset开始,拉取count条记录,offset从0开始,count最大为20。
          countoffset和count用于分页,表示从offset开始,拉取count条记录,offset从0开始,count最大为20。

          示例:

          {"offset":0,"count":5}

          返回码说明:

          在调用模板消息接口后,会返回JSON数据包。

          正常时的返回JSON数据包示例:

          {"errcode":0,"errmsg":"ok","list":[{"id":"AT0002","title":"购买成功通知"},{"id":"AT0003","title":"购买失败通知"},{"id":"AT0004","title":"交易提醒"},{"id":"AT0005","title":"付款成功通知"},{"id":"AT0006","title":"付款失败通知"}],"total_count":599}

          返回参数说明:

          参数说明
          id模板标题id(获取模板标题下的关键词库时需要)
          title模板标题内容
          total_count模板库标题总数

          2.获取模板库某个模板标题下关键词库

          接口地址

          https://api.weixin.qq.com/cgi-bin/wxopen/template/library/get?access_token=ACCESS_TOKEN

          HTTP请求方式:

          POST

          POST参数说明:

          参数必填说明
          access_token接口调用凭证
          id模板标题id,可通过接口获取,也可登录小程序后台查看获取

          示例:

          {"id":"AT0002"}

          返回码说明:

          在调用模板消息接口后,会返回JSON数据包。

          正常时的返回JSON数据包示例:

          {    "errcode": 0,    "errmsg": "ok",    "id": "AT0002",    "title": "购买成功通知",    "keyword_list": [        {            "keyword_id": 3,            "name": "购买地点",            "example": "TIT造舰厂"        },        {            "keyword_id": 4,            "name": "购买时间",            "example": "2016年6月6日"        },        {            "keyword_id": 5,            "name": "物品名称",            "example": "咖啡"        }    ]}

          返回参数说明:

          参数说明
          keyword_id关键词id,添加模板时需要
          name关键词内容
          example关键词内容对应的示例

          3.组合模板并添加至帐号下的个人模板库

          接口地址

          https://api.weixin.qq.com/cgi-bin/wxopen/template/add?access_token=ACCESS_TOKEN

          HTTP请求方式:

          POST

          POST参数说明:

          参数必填说明
          access_token接口调用凭证
          id模板标题id,可通过接口获取,也可登录小程序后台查看获取
          keyword_id_list开发者自行组合好的模板关键词列表,关键词顺序可以自由搭配(例如[3,5,4]或[4,5,3]),最多支持10个关键词组合

          示例:

          {"id":"AT0002", "keyword_id_list":[3,4,5] }

          返回码说明:

          在调用模板消息接口后,会返回JSON数据包。

          正常时的返回JSON数据包示例:

          {"errcode": 0,"errmsg": "ok","template_id": "wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc"}

          返回参数说明:

          参数说明
          template_id添加至帐号下的模板id,发送小程序模板消息时所需

          4.获取帐号下已存在的模板列表

          接口地址

          https://api.weixin.qq.com/cgi-bin/wxopen/template/list?access_token=ACCESS_TOKEN

          HTTP请求方式:

          POST

          POST参数说明:

          参数必填说明
          access_token接口调用凭证
          offsetoffset和count用于分页,表示从offset开始,拉取count条记录,offset从0开始,count最大为20。最后一页的list长度可能小于请求的count
          countoffset和count用于分页,表示从offset开始,拉取count条记录,offset从0开始,count最大为20。最后一页的list长度可能小于请求的count

          示例:

          {"offset":0,"count":1}

          返回码说明:

          在调用模板消息接口后,会返回JSON数据包。

          正常时的返回JSON数据包示例:

          {"errcode": 0,"errmsg": "ok","list": [        {            "template_id": "wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc",            "title": "购买成功通知",            "content": "购买地点{{keyword1.DATA}}
          购买时间{{keyword2.DATA}}
          物品名称{{keyword3.DATA}}
          ",            "example": "购买地点:TIT造舰厂
          购买时间:2016年6月6日
          物品名称:咖啡
          "        }    ]}

          返回参数说明:

          参数说明
          list帐号下的模板列表
          template_id添加至帐号下的模板id,发送小程序模板消息时所需
          title模板标题
          content模板内容
          example模板内容示例

          5.删除帐号下的某个模板

          接口地址

          https://api.weixin.qq.com/cgi-bin/wxopen/template/del?access_token=ACCESS_TOKEN

          HTTP请求方式:

          POST

          POST参数说明:

          参数必填说明
          access_token接口调用凭证
          template_id要删除的模板id

          示例:

          {"template_id":"wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc"}

          返回码说明:

          在调用模板消息接口后,会返回JSON数据包。

          正常时的返回JSON数据包示例:

          {"errcode": 0,"errmsg": "ok"}


          发送模板消息


          1. 获取access_token

          access_token是全局唯一接口调用凭据,开发者调用各接口时都需使用access_token,请妥善保存。access_token的存储至少要保留512个字符空间。access_token的有效期目前为2个小时,需定时刷新,重复获取将导致上次获取的access_token失效。

          公众平台的API调用所需的access_token的使用及生成方式说明:

          1. 为了保密appsecrect,第三方需要一个access_token获取和刷新的中控服务器。而其他业务逻辑服务器所使用的access_token均来自于该中控服务器,不应该各自去刷新,否则会造成access_token覆盖而影响业务;
          2. 目前access_token的有效期通过返回的expire_in来传达,目前是7200秒之内的值。中控服务器需要根据这个有效时间提前去刷新新access_token。在刷新过程中,中控服务器对外输出的依然是老access_token,此时公众平台后台会保证在刷新短时间内,新老access_token都可用,这保证了第三方业务的平滑过渡;
          3. access_token的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新access_token的接口,这样便于业务服务器在API调用获知access_token已超时的情况下,可以触发access_token的刷新流程。

          开发者可以使用AppID和AppSecret调用本接口来获取access_token。AppID和AppSecret可登录微信公众平台官网-设置-开发设置中获得(需要已经绑定成为开发者,且帐号没有异常状态)。AppSecret生成后请自行保存,因为在公众平台每次生成查看都会导致AppSecret被重置。注意调用所有微信接口时均需使用https协议。如果第三方不使用中控服务器,而是选择各个业务逻辑点各自去刷新access_token,那么就可能会产生冲突,导致服务不稳定。

          接口地址:

          https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

          HTTP请求方式:

          GET

          参数说明 :

          参数 必填 说明
          grant_type 获取access_token填写client_credential
          appid 第三方用户唯一凭证
          secret 第三方用户唯一凭证密钥,即appsecret

          返回参数说明:

          正常情况下,微信会返回下述JSON数据包给开发者:

          {"access_token":"ACCESS_TOKEN","expires_in":7200}
          参数 说明
          access_token 获取到的凭证
          expires_in 凭证有效时间,单位:秒

          错误时微信会返回错误码等信息,JSON数据包示例如下(该示例为AppID无效错误):

          {"errcode":40013,"errmsg":"invalid appid"}

          2. 发送模板消息

          接口地址:(ACCESS_TOKEN需换成上文获取到的access_token)

          https://api.weixin.qq.com/cgi-bin/message/wxopen/template/send?access_token=ACCESS_TOKEN

          HTTP请求方式:

          POST

          POST参数说明:

          参数 必填 说明
          touser 接收者(用户)的openid
          template_id 所需下发的模板消息的id
          page 点击模板查看详情跳转页面,不填则模板无跳转
          form_id 表单提交场景下,为submit事件带上的formId;支付场景下,为本次支付的prepay_id
          value 模板内容,不填则下发空模板
          color 模板内容字体的颜色,不填默认黑色
          emphasis_keyword 模板需要放大的关键词,不填则默认无放大

          示例:

          {  "touser": "OPENID",    "template_id": "TEMPLATE_ID",   "page": "index",            "form_id": "FORMID",           "data": {      "keyword1": {          "value": "339208499",           "color": "#173177"      },       "keyword2": {          "value": "2015年01月05日 12:30",           "color": "#173177"      },       "keyword3": {          "value": "粤海喜来登酒店",           "color": "#173177"      } ,       "keyword4": {          "value": "广州市天河区天河路208号",           "color": "#173177"      }   },  "emphasis_keyword": "keyword1.DATA" }

          返回码说明:

          在调用模板消息接口后,会返回JSON数据包。

          正常时的返回JSON数据包示例:

          {  "errcode":0,  "errmsg":"ok",}

          错误时会返回错误码信息,说明如下:

          返回码说明
          40037template_id不正确
          41028form_id不正确,或者过期
          41029form_id已被使用
          41030page不正确
          45009接口调用超过限额(目前默认每个帐号日调用限额为100万)

          使用效果:

          模板消息

          下发条件说明

          1. 支付

            当用户在小程序内完成过支付行为,可允许开发者向用户在7天内推送有限条数的模板消息(1次支付可下发3条,多次支付下发条数独立,互相不影响)

          2. 提交表单

            当用户在小程序内发生过提交表单行为且该表单声明为要发模板消息的,开发者需要向用户提供服务时,可允许开发者向用户在7天内推送有限条数的模板消息(1次提交表单可下发1条,多次提交下发条数独立,相互不影响)


          审核说明

          1.标题

          1.1标题不能存在相同

          1.2标题意思不能存在过度相似

          1.3标题必须以“提醒”或“通知”结尾

          1.4标题不能带特殊符号、个性化字词等没有行业通用性的内容

          1.5标题必须能体现具体服务场景

          1.6标题不能涉及营销相关内容,包括不限于:

          消费优惠类、购物返利类、商品更新类、优惠券类、代金券类、红包类、会员卡类、积分类、活动类等营销倾向通知

          2.关键词

          2.1同一标题下,关键词不能存在相同

          2.2同一标题下,关键词不能存在过度相似

          2.3关键词不能带特殊符号、个性化字词等没有行业通用性的内容

          2.4关键词内容示例必须与关键词对应匹配

          2.5关键词不能太过宽泛,需要具有限制性,例如:“内容”这个就太宽泛,不能审核通过

          违规说明


          除不能违反运营规范外,还不能违反以下规则,包括但不限于:

          1. 不允许恶意诱导用户进行触发操作,以达到可向用户下发模板目的
          2. 不允许恶意骚扰,下发对用户造成骚扰的模板
          3. 不允许恶意营销,下发营销目的模板

          处罚说明


          根据违规情况给予相应梯度的处罚,一般处罚规则如下:

          第一次违规,删除违规模板以示警告,

          第二次违规,封禁接口7天,

          第三次违规,封禁接口30天,

          第四次违规,永久封禁接口

          处罚结果及原因以站内信形式告知


          Bug & Tip

          1. tip: 微信6.5.2及以上版本支持模板功能。低于该版本将无法收到模板消息。

          接收消息和事件


          在页面中使用 <button open-type="contact" /> 可以显示进入客服会话按钮。

          当用户在客服会话发送消息、或由某些特定的用户操作引发事件推送时,微信服务器会将消息或事件的数据包发送到开发者填写的 URL,如果使用的是云开发,则可以推送到指定的云函数(详情请参考消息推送)。开发者收到请求后可以使用 发送客服消息 接口进行异步回复。

          各消息类型的推送JSON、XML数据包结构如下。

          文本消息

          用户在客服会话中发送文本消息时将产生如下数据包:

          XML 格式

          <xml>   <ToUserName><![CDATA[toUser]]></ToUserName>   <FromUserName><![CDATA[fromUser]]></FromUserName>   <CreateTime>1482048670</CreateTime>   <MsgType><![CDATA[text]]></MsgType>   <Content><![CDATA[this is a test]]></Content>   <MsgId>1234567890123456</MsgId></xml>

          JSON 格式

          {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "text",  "Content": "this is a test",  "MsgId": 1234567890123456}

          参数说明

          参数说明
          ToUserName小程序的原始ID
          FromUserName发送者的openid
          CreateTime消息创建时间(整型)
          MsgTypetext
          Content文本消息内容
          MsgId消息id,64位整型

          图片消息

          用户在客服会话中发送图片消息时将产生如下数据包:

          XML 格式

          <xml>      <ToUserName><![CDATA[toUser]]></ToUserName>      <FromUserName><![CDATA[fromUser]]></FromUserName>      <CreateTime>1482048670</CreateTime>      <MsgType><![CDATA[image]]></MsgType>      <PicUrl><![CDATA[this is a url]]></PicUrl>      <MediaId><![CDATA[media_id]]></MediaId>      <MsgId>1234567890123456</MsgId></xml>

          JSON 格式

          {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "image",  "PicUrl": "this is a url",  "MediaId": "media_id",  "MsgId": 1234567890123456}

          参数说明

          参数说明
          ToUserName小程序的原始ID
          FromUserName发送者的openid
          CreateTime消息创建时间(整型)
          MsgTypeimage
          PicUrl图片链接(由系统生成)
          MediaId图片消息媒体id,可以调用[获取临时素材]((getTempMedia)接口拉取数据。
          MsgId消息id,64位整型

          小程序卡片消息

          用户在客服会话中发送小程序卡片消息时将产生如下数据包:

          XML 格式

          <xml>  <ToUserName><![CDATA[toUser]]></ToUserName>  <FromUserName><![CDATA[fromUser]]></FromUserName>  <CreateTime>1482048670</CreateTime>  <MsgType><![CDATA[miniprogrampage]]></MsgType>  <MsgId>1234567890123456</MsgId>  <Title><![CDATA[Title]]></Title>  <AppId><![CDATA[AppId]]></AppId>  <PagePath><![CDATA[PagePath]]></PagePath>  <ThumbUrl><![CDATA[ThumbUrl]]></ThumbUrl>  <ThumbMediaId><![CDATA[ThumbMediaId]]></ThumbMediaId></xml>

          JSON 格式

          {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "miniprogrampage",  "MsgId": 1234567890123456,  "Title":"title",  "AppId":"appid",  "PagePath":"path",  "ThumbUrl":"",  "ThumbMediaId":""}

          参数说明

          参数说明
          ToUserName小程序的原始ID
          FromUserName发送者的openid
          CreateTime消息创建时间(整型)
          MsgTypeminiprogrampage
          MsgId消息id,64位整型
          Title标题
          AppId小程序appid
          PagePath小程序页面路径
          ThumbUrl封面图片的临时cdn链接
          ThumbMediaId封面图片的临时素材id

          进入会话事件

          用户在小程序“客服会话按钮”进入客服会话时将产生如下数据包:

          XML 格式

          <xml>    <ToUserName><![CDATA[toUser]]></ToUserName>    <FromUserName><![CDATA[fromUser]]></FromUserName>    <CreateTime>1482048670</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[user_enter_tempsession]]></Event>    <SessionFrom><![CDATA[sessionFrom]]></SessionFrom></xml>

          JSON 格式

          {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "event",  "Event": "user_enter_tempsession",  "SessionFrom": "sessionFrom"}

          参数说明

          参数说明
          ToUserName小程序的原始ID
          FromUserName发送者的openid
          CreateTime事件创建时间(整型)
          MsgTypeevent
          Event事件类型,user_enter_tempsession
          SessionFrom开发者在客服会话按钮设置的 session-from 属性


          发送客服消息


          当用户和小程序客服产生特定动作的交互时(具体动作列表请见下方说明),微信将会把消息数据推送给开发者,开发者可以在一段时间内(目前修改为48小时)调用客服接口,通过POST一个JSON数据包来发送消息给普通用户。此接口主要用于客服等有人工消息处理环节的功能,方便开发者为用户提供更加优质的服务。

          目前允许的动作列表如下,不同动作触发后,允许的客服接口下发消息条数和下发时限不同。下发条数达到上限后,会收到错误返回码,具体请见返回码说明页:

          用户动作允许下发条数限制下发时限
          用户通过客服消息按钮进入会话1条1分钟
          用户发送信息5条48小时

          客服接口-发消息

          接口调用请求说明

          http请求方式: POSThttps://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

          各消息类型所需的JSON数据包如下:

          发送文本消息

          {    "touser":"OPENID",    "msgtype":"text",    "text":    {         "content":"Hello World"    }}

          发送图片消息

          {    "touser":"OPENID",    "msgtype":"image",    "image":    {      "media_id":"MEDIA_ID"    }

          发送图文链接

          每次可以发送一个图文链接

          {    "touser": "OPENID",    "msgtype": "link",    "link": {          "title": "Happy Day",          "description": "Is Really A Happy Day",          "url": "URL",          "thumb_url": "THUMB_URL"    }}

          参数说明

          参数是否必须说明
          access_token调用接口凭证
          touser普通用户(openid)
          msgtype消息类型,文本为text,图文链接为link
          content文本消息内容
          media_id发送的图片的媒体ID,通过新增素材接口上传图片文件获得。
          title图文链接消息标题
          description图文链接消息
          url图文链接消息被点击后跳转的链接
          picurl图文链接消息的图片链接,支持 JPG、PNG 格式,较好的效果为大图 640 X 320,小图 80 X 80

          返回码说明

          参数说明
          -1系统繁忙,此时请开发者稍候再试
          0请求成功
          40001获取access_token时AppSecret错误,或者access_token无效。请开发者认真比对AppSecret的正确性,或查看是否正在为恰当的小程序调用接口
          40002不合法的凭证类型
          40003不合法的OpenID,请开发者确认OpenID否是其他小程序的OpenID
          45015回复时间超过限制
          45047客服接口下行条数超过上限
          48001api功能未授权,请确认小程序已获得该接口

          转发消息

          如果小程序设置了消息推送,普通微信用户向小程序客服发消息时,微信服务器会先将消息 POST 到开发者填写的 url 上,如果希望将消息转发到网页版客服工具,则需要开发者在响应包中返回 MsgType 为 transfer_customer_service 的消息,微信服务器收到响应后会把当次发送的消息转发至客服系统。

          用户被客服接入以后,客服关闭会话以前,处于会话过程中时,用户发送的消息均会被直接转发至客服系统。当会话超过 30 分钟客服没有关闭时,微信服务器会自动停止转发至客服,而将消息恢复发送至开发者填写的 url 上。

          用户在等待队列中时,用户发送的消息仍然会被推送至开发者填写的 url 上。

          这里特别要注意,只针对微信用户发来的消息才进行转发,而对于其他事件(比如用户从小程序唤起客服会话)都不应该转接,否则客服在客服系统上就会看到一些无意义的消息了。

          消息转发到网页版客服工具

          开发者只在响应包中返回 MsgType 为 transfer_customer_service 的消息,微信服务器收到响应后就会把当次发送的消息转发至客服系统。

           <xml>     <ToUserName><![CDATA[touser]]></ToUserName>     <FromUserName><![CDATA[fromuser]]></FromUserName>     <CreateTime>1399197672</CreateTime>     <MsgType><![CDATA[transfer_customer_service]]></MsgType> </xml>

          参数说明

          参数是否必须描述
          ToUserName接收方帐号(收到的OpenID)
          FromUserName开发者微信号
          CreateTime消息创建时间 (整型)
          MsgTypetransfer_customer_service

          临时素材接口


          获取临时素材

          小程序可以使用本接口获取客服消息内的临时素材(即下载临时的多媒体文件)。目前小程序仅支持下载图片文件。

          接口调用请求说明

          HTTP 请求方式: GET,HTTPS 调用

          https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID

          请求示例(示例为通过curl命令获取多媒体文件)

          curl -I -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

          参数说明

          参数是否必须说明
          access_token调用接口凭证
          media_id媒体文件ID

          返回说明

          正确情况下的返回 HTTP 头如下:

          HTTP/1.1 200 OKConnection: closeContent-Type: image/jpeg Content-disposition: attachment; filename="MEDIA_ID.jpg"Date: Sun, 06 Jan 2013 10:20:18 GMTCache-Control: no-cache, must-revalidateContent-Length: 339721curl -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

          如果返回的是视频消息素材,则内容如下:

          { "video_url":DOWN_URL}

          错误情况下的返回JSON数据包示例如下(示例为无效媒体ID错误):

          {  "errcode":40007,  "errmsg":"invalid media_id"}


          新增临时素材

          小程序可以使用本接口把媒体文件(目前仅支持图片)上传到微信服务器,用户发送客服消息或被动回复用户消息。

          接口调用请求说明

          HTTP 请求方式:POST/FORM,HTTPS 调用

          https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE

          调用示例(使用curl命令,用FORM表单方式上传一个多媒体文件):

          curl -F media=@test.jpg "https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE"

          参数说明

          参数是否必须说明
          access_token调用接口凭证
          typeimage
          mediaform-data中媒体文件标识,有filename、filelength、content-type等信息

          返回说明

          正确情况下的返回 JSON 数据包结果如下:

          {  "type":"TYPE",  "media_id":"MEDIA_ID",  "created_at":123456789}


          参数描述
          typeimage
          media_id媒体文件上传后,获取标识
          created_at媒体文件上传时间戳

          错误情况下的返回JSON数据包示例如下(示例为无效媒体类型错误):

          {  "errcode":40004,  "errmsg":"invalid media type"}

          接入概述


          接入微信小程序消息服务,开发者需要按照如下步骤完成:

          1、填写服务器配置

          2、验证服务器地址的有效性

          3、依据接口文档实现业务逻辑

          下面详细介绍这3个步骤。

          第一步:填写服务器配置

          登录微信小程序官网后,在小程序官网的“设置-消息服务器”页面,管理员扫码启用消息服务,填写服务器地址(URL)、Token 和 EncodingAESKey。

          URL是开发者用来接收微信消息和事件的接口URL。Token可由开发者可以任意填写,用作生成签名(该Token会和接口URL中包含的Token进行比对,从而验证安全性)。EncodingAESKey由开发者手动填写或随机生成,将用作消息体加解密密钥。

          同时,开发者可选择消息加解密方式:明文模式、兼容模式和安全模式。可以选择消息数据格式:XML格式或JSON格式。加密方式的默认状态是明文格式,而数据格式的默认状态是XML格式。

          模式的选择与服务器配置在提交后都会立即生效,请开发者谨慎填写及选择。切换加密方式和数据格式需要提前配置好相关代码,详情请参考消息加解密说明

          填写服务器配置


          第二步:验证消息的确来自微信服务器

          开发者提交信息后,微信服务器将发送GET请求到填写的服务器地址URL上,GET请求携带参数如下表所示:

          参数描述
          signature微信加密签名,signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。
          timestamp时间戳
          nonce随机数
          echostr随机字符串

          开发者通过检验signature对请求进行校验(下面有校验方式)。若确认此次GET请求来自微信服务器,请原样返回echostr参数内容,则接入生效,成为开发者成功,否则接入失败。加密/校验流程如下:1、将token、timestamp、nonce三个参数进行字典序排序;2、将三个参数字符串拼接成一个字符串进行sha1加密;3、开发者获得加密后的字符串可与signature对比,标识该请求来源于微信

          检验signature的PHP示例代码:

          private function checkSignature(){    $signature = $_GET["signature"];    $timestamp = $_GET["timestamp"];    $nonce = $_GET["nonce"];    $token = TOKEN;    $tmpArr = array($token, $timestamp, $nonce);    sort($tmpArr, SORT_STRING);    $tmpStr = implode( $tmpArr );    $tmpStr = sha1( $tmpStr );    if( $tmpStr == $signature ){        return true;    }else{        return false;    }}

          PHP示例代码下载:下载


          第三步:依据接口文档实现业务逻辑

          验证URL有效性成功后即接入生效,成为开发者。至此用户向小程序客服发送消息、或者进入会话等情况时,开发者填写的服务器配置URL将得到微信服务器推送过来的消息和事件,开发者可以依据自身业务逻辑进行响应。

          另请注意,开发者所填写的URL必须以 http:// 或 https:// 开头,分别支持80端口和443端口。

          onShareAppMessage(options)


          在 Page 中定义 onShareAppMessage 函数,设置该页面的转发信息。

          • 只有定义了此事件处理函数,右上角菜单才会显示“转发”按钮
          • 用户点击转发按钮的时候会调用
          • 此事件需要 return 一个 Object,用于自定义转发内容

          options 参数说明

          参数类型说明最低版本
          fromString转发事件来源。button:页面内转发按钮;menu:右上角转发菜单1.2.4
          targetObject如果 from 值是 button,则 target 是触发这次转发事件的 button,否则为 undefined1.2.4
          自定义转发字段

          字段说明默认值最低版本
          title转发标题当前小程序名称 
          path转发路径当前页面 path ,必须是以 / 开头的完整路径 
          success转发成功的回调函数 1.1.0
          fail转发失败的回调函数 1.1.0
          complete转发结束的回调函数(转发成功、失败都会执行 1.1.0

          回调结果:

          回调类型errMsg说明
          successshareAppMessage:ok转发成功
          failshareAppMessage:fail cancel用户取消转发
          failshareAppMessage:fail (detail message)转发失败,其中 detail message 为详细失败信息

          success回调参数说明:

          参数类型说明最低版本
          shareTicketsStringArrayshareTicket 数组,每一项是一个 shareTicket ,对应一个转发对象1.1.0

          示例代码:

          Page({  onShareAppMessage: function (res) {    if (res.from === 'button') {      // 来自页面内转发按钮      console.log(res.target)    }    return {      title: '自定义转发标题',      path: '/page/user?id=123',      success: function(res) {        // 转发成功      },      fail: function(res) {        // 转发失败      }    }  }})

          wx.showShareMenu(OBJECT)

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

          显示当前页面的转发按钮

          OBJECT参数说明:

          参数类型必填说明
          withShareTicketBoolean是否使用带 shareTicket 的转发详情
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.showShareMenu({  withShareTicket: true})

          wx.hideShareMenu(OBJECT)

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

          隐藏转发按钮

          OBJECT参数说明:

          参数类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.hideShareMenu()

          wx.updateShareMenu(OBJECT)

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

          更新转发属性

          OBJECT参数说明:

          参数类型必填说明
          withShareTicketBoolean是否使用带 shareTicket 的转发详情
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码:

          wx.updateShareMenu({  withShareTicket: true,  success() {  }})

          wx.getShareInfo(OBJECT)

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

          获取转发详细信息

          OBJECT参数说明:

          参数类型必填说明
          shareTicketStringshareTicket
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          CALLBACK 参数说明:

          参数类型说明
          errMsgString错误信息
          encryptedDataString包括敏感数据在内的完整转发信息的加密数据,详细见加密数据解密算法
          ivString加密算法的初始向量,详细见加密数据解密算法

          encryptedData 解密后为一个 JSON 结构,包含字段如下:

          字段说明
          openGId群对当前小程序的唯一 ID

          Tip: 如需要展示群名称,可以使用开放数据组件

          获取更多转发信息

          通常开发者希望转发出去的小程序被二次打开的时候能够获取到一些信息,例如群的标识。现在通过调用 wx.showShareMenu 并且设置 withShareTicket 为 true ,当用户将小程序转发到任一群聊之后,可以获取到此次转发的 shareTicket,此转发卡片在群聊中被其他用户打开时,可以在 App.onLaunch() 或 App.onShow 获取到另一个 shareTicket。这两步获取到的 shareTicket 均可通过 wx.getShareInfo() 接口可以获取到相同的转发信息。

          页面内发起转发

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

          通过给 button 组件设置属性 open-type="share",可以在用户点击按钮后触发 Page.onShareAppMessage() 事件,如果当前页面没有定义此事件,则点击后无效果。相关组件:button

          使用指引

          转发按钮,旨在帮助用户更流畅地与好友分享内容和服务。转发,应是用户自发的行为,且在需要时触手可及。开发者在使用时若遵从以下指引,会得到更佳的用户体验。

          1. 含义清晰:明确、一目了然的图形按钮,将为用户减少理解的时间。在我们的资源下载中心,你可以找到这样的按钮素材并直接使用。或者你可以根据自己业务的设计风格,灵活设计含义清晰的按钮的样式。当然,你也可以直接使用带文案的按钮,“转发给好友”,它也足够明确。
          2. 方便点击:按钮点击热区不宜过小,亦不宜过大。同时,转发按钮与其他按钮一样,热区也不宜过密,以免用户误操作。
          3. 按需出现:并非所有页面都适合放置转发按钮,涉及用户隐私的非公开内容,或可能打断用户完成当前操作体验的场景,该功能并不推荐使用。同时,由于转发过程中,我们将截取用户屏幕图像作为配图,因此,需要注意帮助用户屏蔽个人信息。
          4. 尊重意愿:理所当然,并非所有的用户,都喜欢与朋友分享你的小程序。因此,它不应该成为一个诱导或强制行为,如转发后才能解锁某项功能等。请注意,这类做法不仅不被推荐,还可能违反我们的《运营规范》,我们强烈建议你在使用前阅读这部分内容。

          以上,我们陈列了最重要的几点,如果你有时间,可以完整浏览《设计指南》,相信会有更多的收获。

          Bug & Tip

          1. tip: 转发图片不能自定义;会取当前页面,从顶部开始,高度为 80% 屏幕宽度的图像作为转发图片。
          2. tip: 转发的调试支持请查看 普通转发的调试支持 和 带 shareTicket 的转发
          3. tip: 只有转发到群聊中打开才可以获取到 shareTickets 返回值,单聊没有 shareTickets
          4. tipshareTicket 仅在当前小程序生命周期内有效
          5. tip: 由于策略变动,小程序群相关能力进行调整,开发者可先使用wx.getShareInfo接口中的群ID进行功能开发。




          获取二维码


          通过后台接口可以获取小程序任意页面的二维码,扫描该二维码可以直接进入小程序对应的页面。目前微信支持两种二维码,小程序码(左),小程序二维码(右),如下所示:

          小程序二维码

          可以使用开发工具 1.02.1803130 及以后版本通过二维码编译功能调试所获得的二维码

          qrcodecompile

          获取小程序码

          我们推荐生成并使用小程序码,它具有更好的辨识度。目前有两个接口可以生成小程序码,开发者可以根据自己的需要选择合适的接口。

          接口A: 适用于需要的码数量较少的业务场景

          接口地址:

          https://api.weixin.qq.com/wxa/getwxacode?access_token=ACCESS_TOKEN

          获取 access_token 详见文档

          POST 参数说明

          参数类型默认值说明
          pathString 不能为空,最大长度 128 字节
          widthInt430二维码的宽度
          auto_colorBoolfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调
          line_colorObject{"r":"0","g":"0","b":"0"}auth_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"}

          注意:通过该接口生成的小程序码,永久有效,数量限制见文末说明,请谨慎使用。用户扫描该码进入小程序后,将直接进入 path 对应的页面。

          接口B:适用于需要的码数量极多,或仅临时使用的业务场景

          接口地址:

          https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=ACCESS_TOKEN

          获取 access_token 详见文档

          POST 参数说明

          参数类型默认值说明
          sceneString 最大32个可见字符,只支持数字,大小写英文以及部分特殊字符:!#$&'()*+,/:;=?@-._~,其它字符请自行编码为合法字符(因不支持%,中文无法使用 urlencode 处理,请使用其他编码方式)
          pageString 必须是已经发布的小程序页面,例如 "pages/index/index" ,如果不填写这个字段,默认跳主页面
          widthInt430二维码的宽度
          auto_colorBoolfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调
          line_colorObject{"r":"0","g":"0","b":"0"}auto_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"}

          注意:通过该接口生成的小程序码,永久有效,数量暂无限制。用户扫描该码进入小程序后,开发者需在对应页面获取的码中 scene 字段的值,再做处理逻辑。使用如下代码可以获取到二维码中的 scene 字段的值。调试阶段可以使用开发工具的条件编译自定义参数 scene=xxxx 进行模拟,开发工具模拟时的 scene 的参数值需要进行 urlencode

          // 这是首页的 jsPage({  onLoad: function(options) {    // options 中的 scene 需要使用 decodeURIComponent 才能获取到生成二维码时传入的 scene    var scene = decodeURIComponent(options.scene)  }})

          获取小程序二维码

          接口C:适用于需要的码数量较少的业务场景

          接口地址:

          https://api.weixin.qq.com/cgi-bin/wxaapp/createwxaqrcode?access_token=ACCESS_TOKEN

          获取 access_token 详见文档

          POST 参数说明

          参数类型默认值说明
          pathString 不能为空,最大长度 128 字节
          widthInt430二维码的宽度

          注意:通过该接口生成的小程序二维码,永久有效,数量限制见文末说明,请谨慎使用。用户扫描该码进入小程序后,将直接进入 path 对应的页面。

          示例:

          {"path": "pages/index?query=1", "width": 430}

          注:pages/index 需要在app.json的 pages 中定义

          Bug & Tip

          1. tip:通过该接口,仅能生成已发布的小程序的二维码。
          2. tip:可以在开发者工具预览时生成开发版的带参二维码。
          3. tip:接口A加上接口C,总共生成的码数量限制为100,000,请谨慎调用。
          4. tip: POST 参数需要转成 json 字符串,不支持 form 表单提交。
          5. tip: auto_color line_color 参数仅对小程序码生效。

          错误码

          45009:B接口调用分钟频率受限(目前5000次/分钟,会调整),如需大量小程序码,建议预生成。

          45029:A接口和C接口生成码个数总和到达最大个数限制。 

          41030:B接口所传page页面不存在,或者小程序没有发布,请注意B接口没有path参数,传path参数虽然可以生成小程序码,但是只能跳主页面。

          wx.getWeRunData(OBJECT)


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

          获取用户过去三十天微信运动步数,需要先调用 wx.login 接口。

          OBJECT参数说明:

          参数名类型必填说明
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数名类型说明
          errMsgString调用结果
          encryptedDataString包括敏感数据在内的完整用户信息的加密数据,详细见加密数据解密算法
          ivString加密算法的初始向量,详细见加密数据解密算法

          示例代码:

          wx.getWeRunData({    success(res) {        const encryptedData = res.encryptedData    }})

          encryptedData 解密后为以下 json 结构,详见加密数据解密算法

          属性类型说明
          stepInfoListObjectArray用户过去三十天的微信运动步数

          stepInfo 结构如下

          属性类型说明
          timestampNumber时间戳,表示数据对应的时间
          stepNumber微信运动步数

          {    "stepInfoList": [        {            "timestamp": 1445866601,            "step": 100        },        {            "timestamp": 1445866602,            "step": 100        }    ]}

          wx.chooseInvoiceTitle(OBJECT)


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

          选择用户的发票抬头

          Object参数说明:

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

          success返回参数说明:

          参数名 类型 说明
          type String 抬头类型(0:单位,1:个人)
          title String 抬头名称
          taxNumber String 抬头税号
          companyAddress String 单位地址
          telephone String 手机号码
          bankName String 银行名称
          bankAccount String 银行账号
          errMsg String 接口调用结果

          示例代码:

          wx.chooseInvoiceTitle({
          success(res) {
          }
          })

          wx.checkIsSupportSoterAuthentication(OBJECT)


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

          获取本机支持的 SOTER 生物认证方式

          Object参数说明:

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

          success返回参数说明:

          参数名 类型 说明
          supportMode StringArray 该设备支持的可被SOTER识别的生物识别方式
          errMsg String 接口调用结果

          supportMode 有效值:

          说明
          fingerPrint 指纹识别
          facial 人脸识别(暂未支持)
          speech 声纹识别(暂未支持)

          示例代码:

          wx.checkIsSupportSoterAuthentication({
          success(res) {
          // res.supportMode = [] 不具备任何被SOTER支持的生物识别方式
          // res.supportMode = ['fingerPrint'] 只支持指纹识别
          // res.supportMode = ['fingerPrint', 'facial'] 支持指纹识别和人脸识别
          }
          })


          wx.reportPerformance(Number id, Number value, String|Array dimensions)

          基础库 2.9.2 开始支持,低版本需做兼容处理。

          小程序测速上报。使用前,需要在小程序管理后台配置。 

          参数

          Number id

          指标 id

          Number value

          需要上报的数值

          String|Array dimensions

          自定义维度 (选填)

          示例代码

          wx.reportPerformance(1101, 680)wx.reportPerformance(1101, 680, 'custom')


          wx.getPerformance()

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

          获取当前小程序性能相关的信息。

          目前支持获取以下几类性能指标:

          类别名称 (entryType)指标
          路由navigationroute, appLaunch
          渲染renderfirstRender
          脚本scriptevaluateScript
          • route: 路由性能
          • appLaunch: 小程序启动耗时
          • firstRender: 页面首次渲染耗时
          • evaluateScript: 注入脚本耗时

          示例代码

          const performance = wx.getPerformance()const observer = performance.createObserver((entryList) => {  console.log(entryList.getEntries())})observer.observe({ entryTypes: ['render', 'script'] })


          EntryList

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

          EntryList 对象


          方法:

          Array EntryList.getEntries()

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

          该方法返回当前列表中的所有性能数据

          返回值

          Array



          Array EntryList.getEntriesByName(string name, string entryType)

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

          获取当前列表中所有名称为 [name] 且类型为 [entryType] 的性能数据

          参数

          string name

          string entryType

          返回值

          Array



          Array EntryList.getEntriesByType(string entryType)

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

          获取当前列表中所有类型为 [entryType] 的性能数据

          参数

          string entryType

          返回值

          Array


          Performance

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

          Performance 对象,用于获取性能数据及创建性能监听器


          方法:

          PerformanceObserver Performance.createObserver(function callback)

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

          创建全局性能事件监听器

          参数

          function callback

          返回值

          PerformanceObserver



          Array Performance.getEntries()

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

          该方法返回当前缓冲区中的所有性能数据

          返回值

          Array



          Array Performance.getEntriesByName(string name, string entryType)

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

          获取当前缓冲区中所有名称为 [name] 且类型为 [entryType] 的性能数据

          参数

          string name

          string entryType

          返回值

          Array



          Array Performance.getEntriesByType(string entryType)

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

          获取当前缓冲区中所有类型为 [entryType] 的性能数据

          参数

          string entryType

          返回值

          Array



          Performance.setBufferSize(number size)

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

          设置缓冲区大小, 默认缓冲 30 条性能数据

          参数

          number size


          PerformanceObserver

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

          PerformanceObserver 对象, 用于监听性能相关事件

          属性

          Array supportedEntryTypes

          获取当前支持的所有性能指标类型


          方法:

          PerformanceObserver.disconnect()

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

          停止监听




          PerformanceObserver.observe(Object options)

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

          开始监听

          参数

          Object options

          设置 type 监听单个类型的指标,设置 entryTypes 监听多个类型指标。


          wx.requestSubscribeMessage(Object object)

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

          调起客户端小程序订阅消息界面,返回用户订阅消息的操作结果。当用户勾选了订阅面板中的“总是保持以上选择,不再询问”时,模板消息会被添加到用户的小程序设置页,通过 wx.getSetting 接口可获取用户对相关模板消息的订阅状态。

          注意事项

          • 一次性模板 id 和永久模板 id 不可同时使用。
          • 低版本基础库2.4.4~2.8.3 已支持订阅消息接口调用,仅支持传入一个一次性 tmplId / 永久 tmplId。
          • 2.8.2 版本开始,用户发生点击行为或者发起支付回调后,才可以调起订阅消息界面。
          • 2.10.0 版本开始,开发版和体验版小程序将禁止使用模板消息 formId。

          参数

          Object object

          属性类型默认值必填说明
          tmplIdsArray需要订阅的消息模板的id的集合,一次调用最多可订阅3条消息(注意:iOS客户端7.0.6版本、Android客户端7.0.7版本之后的一次性订阅/长期订阅才支持多个模板消息,iOS客户端7.0.5版本、Android客户端7.0.6版本之前的一次订阅只支持一个模板消息)消息模板id在[微信公众平台(mp.weixin.qq.com)-功能-订阅消息]中配置
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          errMsgString接口调用成功时errMsg值为'requestSubscribeMessage:ok'
          TEMPLATE_IDString[TEMPLATE_ID]是动态的键,即模板id,值包括'accept'、'reject'、'ban'。'accept'表示用户同意订阅该条id对应的模板消息,'reject'表示用户拒绝订阅该条id对应的模板消息,'ban'表示已被后台封禁。例如 { errMsg: "requestSubscribeMessage:ok", zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: "accept"} 表示用户同意订阅zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE这条消息

          object.fail 回调函数

          参数
          Object res
          属性类型说明
          errMsgString接口调用失败错误信息
          errCodeNumber接口调用失败错误码

          错误码

          errCodeerrMsg说明
          10001TmplIds can't be empty参数传空了
          10002Request list fail网络问题,请求消息列表失败
          10003Request subscribe fail网络问题,订阅请求发送失败
          10004Invalid template id参数类型错误
          10005Cannot show subscribe message UI无法展示 UI,一般是小程序这个时候退后台了导致的
          20001No template data return, verify the template id exist没有模板数据,一般是模板 ID 不存在 或者和模板类型不对应 导致的
          20002Templates type must be same模板消息类型 既有一次性的又有永久的
          20003Templates count out of max bounds模板消息数量超过上限
          20004The main switch is switched off用户关闭了主开关,无法进行订阅
          20005This mini program was banned from subscribing messages小程序被禁封

          示例代码

          wx.requestSubscribeMessage({  tmplIds: [''],  success (res) { }})


          数据分析接口

          开发者通过数据分析接口,可获取到小程序的各项数据指标,便于进行数据存储和整理。数据分析详细功能介绍及指标解释参见数据分析文档

          概况

          用户访问小程序的详细数据可从访问分析中获取,概况中提供累计用户数等部分指标数据。

          概况趋势

          接口地址

          https://api.weixin.qq.com/datacube/getweanalysisappiddailysummarytrend?access_token=ACCESS_TOKEN

          获取 access_token 详见文档

          POST 请求参数说明:

          参数是否必填说明
          begin_date开始日期
          end_date结束日期,限定查询1天数据,end_date允许设置的最大值为昨日

          POST 内容示例:

          {  "begin_date" : "20170313",  "end_date" : "20170313"}

          返回参数说明:

          参数说明
          visit_total累计用户数
          share_pv转发次数
          share_uv转发人数

          返回数据示例:

          {  "list": [    {      "ref_date": "20170313",      "visit_total": 391,      "share_pv": 572,      "share_uv": 383    }  ]}

          访问分析

          获取小程序访问分析数据,数据说明参见访问分析

          访问趋势

          日趋势

          接口地址

          https://api.weixin.qq.com/datacube/getweanalysisappiddailyvisittrend?access_token=ACCESS_TOKEN

          POST 参数说明

          参数是否必填说明
          begin_date开始日期
          end_date结束日期,限定查询1天数据,end_date允许设置的最大值为昨日

          POST 内容示例:

          {  "begin_date" : "20170313",  "end_date" : "20170313"}

          返回参数说明:

          参数说明
          ref_date时间: 如: "20170313"
          session_cnt打开次数
          visit_pv访问次数
          visit_uv访问人数
          visit_uv_new新用户数
          stay_time_uv人均停留时长 (浮点型,单位:秒)
          stay_time_session次均停留时长 (浮点型,单位:秒)
          visit_depth平均访问深度 (浮点型)

          返回数据示例:

          {  "list": [    {      "ref_date": "20170313",      "session_cnt": 142549,      "visit_pv": 472351,      "visit_uv": 55500,      "visit_uv_new": 5464,      "stay_time_session": 0,      "visit_depth": 1.9838    }  ]}

          周趋势

          接口地址

          https://api.weixin.qq.com/datacube/getweanalysisappidweeklyvisittrend?access_token=ACCESS_TOKEN

          POST 参数说明:

          参数是否必填说明
          begin_date开始日期,为周一日期
          end_date结束日期,为周日日期,限定查询一周数据

          注意:请求json和返回json与天的一致,这里限定查询一个自然周的数据,时间必须按照自然周的方式输入: 如:20170306(周一), 20170312(周日)

          POST 内容示例:

          {"begin_date":"20170306","end_date":"20170312"}

          返回参数说明:

          参数说明
          ref_date时间,如:"20170306-20170312"
          session_cnt打开次数(自然周内汇总)
          visit_pv访问次数(自然周内汇总)
          visit_uv访问人数(自然周内去重)
          visit_uv_new新用户数(自然周内去重)
          stay_time_uv人均停留时长 (浮点型,单位:秒)
          stay_time_session次均停留时长 (浮点型,单位:秒)
          visit_depth平均访问深度 (浮点型)

          返回内容示例:

          {  "list": [    {      "ref_date": "20170306-20170312",      "session_cnt": 986780,      "visit_pv": 3251840,      "visit_uv": 189405,      "visit_uv_new": 45592,      "stay_time_session": 54.5346,      "visit_depth": 1.9735    }  ]}

          月趋势

          接口地址

          https://api.weixin.qq.com/datacube/getweanalysisappidmonthlyvisittrend?access_token=ACCESS_TOKEN

          POST 参数说明:

          参数是否必填说明
          begin_date开始日期,为自然月第一天
          end_date结束日期,为自然月最后一天,限定查询一个月数据

          注意:请求json和返回json与天的一致,这里限定查询一个自然月的数据,时间必须按照自然月的方式输入: 如:20170201(月初), 20170228(月末)

          POST 内容示例:

          {"begin_date":"20170201","end_date":"20170228"}

          返回参数说明:

          参数说明
          ref_date时间,如:"201702"
          session_cnt打开次数(自然月内汇总)
          visit_pv访问次数(自然月内汇总)
          visit_uv访问人数(自然月内去重)
          visit_uv_new新用户数(自然月内去重)
          stay_time_uv人均停留时长 (浮点型,单位:秒)
          stay_time_session次均停留时长 (浮点型,单位:秒)
          visit_depth平均访问深度 (浮点型)

          返回内容示例:

          {  "list": [    {      "ref_date": "201702",      "session_cnt": 126513,      "visit_pv": 426113,      "visit_uv": 48659,      "visit_uv_new": 6726,      "stay_time_session": 56.4112,      "visit_depth": 2.0189    }  ]}

          访问分布

          接口地址

          https://api.weixin.qq.com/datacube/getweanalysisappidvisitdistribution?access_token=ACCESS_TOKEN

          POST 参数说明:

          参数是否必填说明
          begin_date开始日期
          end_date结束日期,限定查询1天数据,end_date允许设置的最大值为昨日

          POST 内容示例:

          {"begin_date":"20170313","end_date":"20170313"}

          返回参数说明:

          参数说明
          ref_date时间: 如: "20170313"
          list存入所有类型的指标情况

          list 的每一项包括:

          参数说明
          index分布类型
          item_list分布数据列表

          分布类型(index)的取值范围:

          说明
          access_source_session_cnt访问来源分布
          access_staytime_info访问时长分布
          access_depth_info访问深度的分布

          每个数据项包括:

          参数说明
          key场景 id
          value 场景下的值(均为整数型)

          key对应关系如下:

          访问来源:(index="access_source_session_cnt")

          1:小程序历史列表

          2:搜索

          3:会话

          4:二维码

          5:公众号主页

          6:聊天顶部

          7:系统桌面

          8:小程序主页

          9:附近的小程序

          10:其他

          11:模板消息

          12:客服消息

          13: 公众号菜单

          14: APP分享

          15: 支付完成页

          16: 长按识别二维码

          17:相册选取二维码

          18: 公众号文章

          访问时长:(index="access_staytime_info")

          1: 0-2s

          2: 3-5s

          3: 6-10s

          4: 11-20s

          5: 20-30s

          6: 30-50s

          7: 50-100s

          8: > 100s

          平均访问深度:(index="access_depth_info")

          1: 1页

          2: 2页

          3: 3页

          4: 4页

          5: 5页

          6: 6-10页

          7: >10页

          返回数据示例:

          {  "ref_date": "20170313",  "list": [    {      "index": "access_source_session_cnt",      "item_list": [        {          "key": 10,          "value": 5        },        {          "key": 8,          "value": 687        },        {          "key": 7,          "value": 10740        },        {          "key": 6,          "value": 1961        },        {          "key": 5,          "value": 677        },        {          "key": 4,          "value": 653        },        {          "key": 3,          "value": 1120        },        {          "key": 2,          "value": 10243        },        {          "key": 1,          "value": 116578        }      ]    },    {      "index": "access_staytime_info",      "item_list": [        {          "key": 8,          "value": 16329        },        {          "key": 7,          "value": 19322        },        {          "key": 6,          "value": 21832        },        {          "key": 5,          "value": 19539        },        {          "key": 4,          "value": 29670        },        {          "key": 3,          "value": 19667        },        {          "key": 2,          "value": 11794        },        {          "key": 1,          "value": 4511        }      ]    },    {      "index": "access_depth_info",      "item_list": [        {          "key": 5,          "value": 217        },        {          "key": 4,          "value": 3259        },        {          "key": 3,          "value": 32445        },        {          "key": 2,          "value": 63542        },        {          "key": 1,          "value": 43201        }      ]    }  ]}

          访问留存

          日留存

          接口地址

          https://api.weixin.qq.com/datacube/getweanalysisappiddailyretaininfo?access_token=ACCESS_TOKEN

          POST 参数说明:

          参数是否必填说明
          begin_date开始日期
          end_date结束日期,限定查询1天数据,end_date允许设置的最大值为昨日

          POST 内容示例:

          {  "begin_date" : "20170313",  "end_date" : "20170313"}

          返回参数说明:

          参数说明
          visit_uv_new新增用户留存
          visit_uv活跃用户留存

          visit_uv、visit_uv_new 的每一项包括:

          参数说明
          key标识,0开始,0表示当天,1表示1天后,依此类推,key取值分别是:0,1,2,3,4,5,6,7,14,30
          valuekey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          返回数据示例:

          {  "ref_date": "20170313",  "visit_uv_new": [    {      "key": 0,      "value": 5464    }  ],  "visit_uv": [    {      "key": 0,      "value": 55500    }  ]}

          周留存

          接口地址

          https://api.weixin.qq.com/datacube/getweanalysisappidweeklyretaininfo?access_token=ACCESS_TOKEN

          POST 参数说明:

          参数是否必填说明
          begin_date开始日期,为周一日期
          end_date结束日期,为周日日期,限定查询一周数据

          注意:请求json和返回json与天的一致,这里限定查询一个自然周的数据,时间必须按照自然周的方式输入: 如:20170306(周一), 20170312(周日)

          POST 内容示例:

          {  "begin_date" : "20170306",  "end_date" : "20170312"}

          返回参数说明:

          参数说明
          ref_date时间,如:"20170306-20170312"
          visit_uv_new新增用户留存
          visit_uv活跃用户留存

          visit_uv、visit_uv_new 的每一项包括:

          参数说明
          key标识,0开始,0表示当周,1表示1周后,依此类推,key取值分别是:0,1,2,3,4
          valuekey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          返回内容示例:

          {  "ref_date": "20170306-20170312",  "visit_uv_new": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 16853    }  ],  "visit_uv": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 99310    }  ]}

          月留存

          接口地址

          https://api.weixin.qq.com/datacube/getweanalysisappidmonthlyretaininfo?access_token=ACCESS_TOKEN

          POST 参数说明:

          参数是否必填说明
          begin_date开始日期,为自然月第一天
          end_date结束日期,为自然月最后一天,限定查询一个月数据

          注意:请求json和返回json与天的一致,这里限定查询一个自然月的数据,时间必须按照自然月的方式输入: 如:20170201(月初), 20170228(月末)

          POST 内容示例:

          {  "begin_date":"20170201",  "end_date":"20170228"}

          返回参数说明:

          参数说明
          ref_date时间,如:"201702"
          visit_uv_new新增用户留存
          visit_uv活跃用户留存

          visit_uv、visit_uv_new 的每一项包括:

          参数说明
          key标识,0开始,0表示当月,1表示1月后,key取值分别是:0,1
          valuekey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          返回内容示例:

          {  "ref_date": "201702",  "visit_uv_new": [    {      "key": 0,      "value": 346249    }  ],  "visit_uv": [    {      "key": 0,      "value": 346249    }  ]}

          访问页面

          访问页面

          接口地址

          https://api.weixin.qq.com/datacube/getweanalysisappidvisitpage?access_token=ACCESS_TOKEN

          POST 参数说明:

          参数是否必填说明
          begin_date开始日期
          end_date结束日期,限定查询1天数据,end_date允许设置的最大值为昨日

          POST 内容示例:

          {  "begin_date":"20170313",  "end_date":"20170313"}

          返回参数说明:

          参数说明
          page_path页面路径
          page_visit_pv访问次数
          page_visit_uv访问人数
          page_staytime_pv次均停留时长
          entrypage_pv进入页次数
          exitpage_pv退出页次数
          page_share_pv转发次数
          page_share_uv转发人数

          返回内容示例:

          {  "ref_date": "20170313",  "list": [    {      "page_path": "pages/main/main.html",      "page_visit_pv": 213429,      "page_visit_uv": 55423,      "page_staytime_pv": 8.139198,      "entrypage_pv": 117922,      "exitpage_pv": 61304,      "page_share_pv": 180,      "page_share_uv": 166    },    {      "page_path": "pages/linedetail/linedetail.html",      "page_visit_pv": 155030,      "page_visit_uv": 42195,      "page_staytime_pv": 35.462395,      "entrypage_pv": 21101,      "exitpage_pv": 47051,      "page_share_pv": 47,      "page_share_uv": 42    },    {      "page_path": "pages/search/search.html",      "page_visit_pv": 65011,      "page_visit_uv": 24716,      "page_staytime_pv": 6.889634,      "entrypage_pv": 1811,      "exitpage_pv": 3198,      "page_share_pv": 0,      "page_share_uv": 0    },    {      "page_path": "pages/stationdetail/stationdetail.html",      "page_visit_pv": 29953,      "page_visit_uv": 9695,      "page_staytime_pv": 7.558508,      "entrypage_pv": 1386,      "exitpage_pv": 2285,      "page_share_pv": 0,      "page_share_uv": 0    },    {      "page_path": "pages/switch-city/switch-city.html",      "page_visit_pv": 8928,      "page_visit_uv": 4017,      "page_staytime_pv": 9.22659,      "entrypage_pv": 748,      "exitpage_pv": 1613,      "page_share_pv": 0,      "page_share_uv": 0    }  ]}

          返回参数说明:

          参数说明
          page_path页面路径
          page_visit_pv访问次数
          page_visit_uv访问人数
          page_staytime_pv次均停留时长
          entrypage_pv进入页次数
          exitpage_pv退出页次数
          page_share_pv转发次数
          page_share_uv转发人数

          注意:目前只提供按 page_visit_pv 排序的 top200

          用户画像

          获取小程序新增或活跃用户的画像分布数据。时间范围支持昨天、最近7天、最近30天。其中,新增用户数为时间范围内首次访问小程序的去重用户数,活跃用户数为时间范围内访问过小程序的去重用户数。画像属性包括用户年龄、性别、省份、城市、终端类型、机型。

          接口地址: https://api.weixin.qq.com/datacube/getweanalysisappiduserportrait?access_token=ACCESS_TOKEN

          POST 请求参数说明:

          参数是否必填说明
          begin_date开始日期
          end_date结束日期,开始日期与结束日期相差的天数限定为0/6/29,分别表示查询最近1/7/30天数据,end_date允许设置的最大值为昨日

          POST 内容示例:

          {    "begin_date" : "2017-06-11",    "end_date" : "2017-06-17"}

          返回参数说明:

          每次请求返回选定的时间范围及以下指标项:

          参数说明
          ref_date时间范围,如: "20170611-20170617"
          visit_uv_new新用户
          visit_uv活跃用户

          每个指标项下包括的属性:

          参数说明
          province省份,如北京、广东等
          city城市,如北京、广州等
          genders性别,包括男、女、未知
          platfomrs终端类型,包括iPhone, android,其他
          devices机型,如苹果iPhone6, OPPO R9等
          ages年龄,包括17岁以下、18-24岁等区间

          每个属性下包括的数据项:

          参数说明
          id属性值id
          name属性值名称,与id一一对应。如属性为province时,返回的属性值名称包括“广东”等
          value属性值对应的指标值,如指标为visit_uv,属性为province,属性值为"广东省”,value对应广东地区的活跃用户数

          返回数据示例:

          {  "ref_date": "20170611",  "visit_uv_new": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 215      }    ],    "city": [     {        "id": 3102,        "name": "广州",        "value": 78      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 2146      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 27642      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 61      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 151      }    ]  },  "visit_uv": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 1341      }    ],    "city": [     {        "id": 3102,        "name": "广州",        "value": 234      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 14534      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 21750      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 617      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 3156      }    ]  }}

          注:

          1. 由于部分用户属性数据缺失,属性值可能出现 “未知”。
          2. 机型数据无 id 字段,暂只提供用户数最多的 top20。

          wx.reportAnalytics(eventName, data)

          自定义分析数据上报接口。使用前,需要在小程序管理后台自定义分析中新建事件,配置好事件名与字段。

          参数说明:

          参数类型必填说明
          eventNameString事件名。
          dataObject上报的自定义数据。key为配置中的字段名,value为上报的数据

          示例代码:

          wx.reportAnalytics('purchase', {  price: 120,  color: 'red'})

          wx.getUpdateManager()


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

          获取全局唯一的版本更新管理器,用于管理小程序更新。

          关于小程序的更新机制,可以查看 运行机制 文档。

          updateManager


          updateManager 对象的方法列表:

          方法参数说明
          onCheckForUpdatecallback当向微信后台请求完新版本信息,会进行回调
          onUpdateReadycallback当新版本下载完成,会进行回调
          onUpdateFailedcallback当新版本下载失败,会进行回调
          applyUpdate当新版本下载完成,调用该方法会强制当前小程序应用上新版本并重启

          onCheckForUpdate(callback) 回调结果说明:

          属性类型说明
          hasUpdateBoolean是否有新的版本

          注: 检查更新操作由微信在小程序冷启动时自动触发,不需由开发者主动触发,开发者只需监听检查结果即可。

          onUpdateReady(callback) 回调结果说明:

          当微信检查到小程序有新版本,会主动触发下载操作(无需开发者触发),当下载完成后,会通过 onUpdateReady 告知开发者。

          onUpdateFailed(callback) 回调结果说明:

          当微信检查到小程序有新版本,会主动触发下载操作(无需开发者触发),如果下载失败(可能是网络原因等),会通过 onUpdateFailed 告知开发者。

          applyUpdate() 说明:

          当小程序新版本已经下载时(即收到 onUpdateReady 回调),可以通过这个方法强制重启小程序并应用上最新版本。

          示例代码:

          const updateManager = wx.getUpdateManager()updateManager.onCheckForUpdate(function (res) {  // 请求完新版本信息的回调  console.log(res.hasUpdate)})updateManager.onUpdateReady(function () {  // 新的版本已经下载好,调用 applyUpdate 应用新版本并重启  updateManager.applyUpdate()})updateManager.onUpdateFailed(function () {  // 新的版本下载失败})

          wx.updateWeChatApp()

          基础库 2.12.0 开始支持,低版本需做兼容处理。

          更新客户端版本。当判断用户小程序所在客户端版本过低时,可使用该接口跳转到更新微信页面。

          参数

          Object object

          属性类型默认值必填说明
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)


          wx.arrayBufferToBase64(arrayBuffer)


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

          将 ArrayBuffer 数据转成 Base64 字符串

          示例代码

          const arrayBuffer = new Uint8Array([11, 22, 33])const base64 = wx.arrayBufferToBase64(arrayBuffer)

          wx.base64ToArrayBuffer(base64)


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

          将 Base64 字符串转成 ArrayBuffer 数据

          示例代码

          const base64 = 'CxYh'const arrayBuffer = wx.base64ToArrayBuffer(base64)

          wx.createWorker(scriptPath)


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

          在使用 createWorker 前,请查阅 多线程 文档了解基础知识和配置方法。

          创建一个 Worker 线程,并返回 Worker 实例,目前限制最多只能创建一个 Worker,创建下一个 Worker 前请调用 Worker.terminate。

          scriptPath 为 worker 的入口文件路径,需填写绝对路径。

          Worker

          Worker 对象的方法列表:

          方法参数说明
          postMessageObject向 Worker 线程发送的消息。
          onMessagecallback监听 Worker 线程向当前线程发送的消息
          terminate结束当前 Worker 线程,仅限在主线程 Worker 实例上调用。

          postMessage(message) 说明:

          向 Worker 线程发送消息,message 参数为需要发送的消息,必须是一个可序列化的 JavaScript 对象。

          onMessage(callback) 回调结果说明:

          属性类型说明
          messageObjectWorker 线程向当前线程发送的消息

          terminate() 说明:

          结束当前 worker 线程,仅限在主线程 Worker 对象上调用。

          示例代码:

          运行以下代码需先进行基础配置,详细请查阅 多线程 文档了解基础知识和配置方法。

          const worker = wx.createWorker('workers/request/index.js') // 文件名指定 worker 的入口文件路径,绝对路径worker.onMessage(function (res) {  console.log(res)})worker.postMessage({  msg: 'hello worker'})worker.terminate()

          wx.setEnableDebug(OBJECT)

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

          设置是否打开调试开关,此开关对正式版也能生效。

          OBJECT参数说明:

          参数名类型必填说明
          enableDebugBoolean是否打开调试
          successFunction接口调用成功的回调函数
          failFunction接口调用失败的回调函数
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success返回参数说明:

          参数名类型说明
          errMsgString调用结果

          示例代码:

          // 打开调试wx.setEnableDebug({    enableDebug: true})// 关闭调试wx.setEnableDebug({    enableDebug: false})


          InterstitialAd wx.createInterstitialAd(Object object)

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

          创建插屏广告组件。请通过 wx.getSystemInfoSync() 返回对象的 SDKVersion 判断基础库版本号后再使用该 API。每次调用该方法创建插屏广告都会返回一个全新的实例(小程序端的插屏广告实例不允许跨页面使用)。

          参数

          Object object

          属性类型默认值必填说明
          adUnitIdstring广告单元 id

          返回值

          InterstitialAd

          插屏广告组件


          InterstitialAd

          插屏广告组件。插屏广告组件是一个原生组件,层级比普通组件高。插屏广告组件每次创建都会返回一个全新的实例(小程序端的插屏广告实例不允许跨页面使用),默认是隐藏的,需要调用 InterstitialAd.show() 将其显示。


          方法:

          InterstitialAd.destroy()

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

          销毁插屏广告实例。


          Promise InterstitialAd.load()

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

          加载插屏广告。

          返回值

          Promise

          插屏广告加载数据的结果


          InterstitialAd.offClose(function callback)

          取消监听插屏广告关闭事件

          参数

          function callback

          插屏广告关闭事件的回调函数


          InterstitialAd.offError(function callback)

          取消监听插屏错误事件

          参数

          function callback

          插屏错误事件的回调函数


          InterstitialAd.offLoad(function callback)

          取消监听插屏广告加载事件

          参数

          function callback

          插屏广告加载事件的回调函数


          InterstitialAd.onClose(function callback)

          监听插屏广告关闭事件。

          参数

          function callback

          插屏广告关闭事件的回调函数


          InterstitialAd.onError(function callback)

          监听插屏错误事件。

          参数

          function callback

          插屏错误事件的回调函数

          参数

          Object res
          属性类型说明
          errMsgstring错误信息
          errCodenumber错误码

          errCode 的合法值

          说明最低版本
          1000后端接口调用失败
          1001参数错误
          1002广告单元无效
          1003内部错误
          1004无合适的广告
          1005广告组件审核中
          1006广告组件被驳回
          1007广告组件被封禁
          1008广告单元已关闭

          错误码信息与解决方案表

          错误码是通过onError获取到的错误信息。调试期间,可以通过异常返回来捕获信息。 在小程序发布上线之后,如果遇到异常问题,可以在“运维中心“里面搜寻错误日志,还可以针对异常返回加上适当的监控信息。

          代码异常情况理由解决方案
          1000后端错误调用失败该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
          1001参数错误使用方法错误可以前往developers.weixin.qq.com确认具体教程(小程序和小游戏分别有各自的教程,可以在顶部选项中,“设计”一栏的右侧进行切换。
          1002广告单元无效可能是拼写错误、或者误用了其他APP的广告ID请重新前往mp.weixin.qq.com确认广告位ID。
          1003内部错误该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
          1004无适合的广告广告不是每一次都会出现,这次没有出现可能是由于该用户不适合浏览广告属于正常情况,且开发者需要针对这种情况做形态上的兼容。
          1005广告组件审核中你的广告正在被审核,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
          1006广告组件被驳回你的广告审核失败,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
          1007广告组件被驳回你的广告能力已经被封禁,封禁期间无法展现广告请前往mp.weixin.qq.com确认小程序广告封禁状态。
          1008广告单元已关闭该广告位的广告能力已经被关闭请前往mp.weixin.qq.com重新打开对应广告位的展现。


          InterstitialAd.onLoad(function callback)

          监听插屏广告加载事件。

          参数

          function callback

          插屏广告加载事件的回调函数


          Promise InterstitialAd.show()

          显示插屏广告。

          返回值

          Promise

          插屏广告显示操作的结果

          错误码信息表

          如果插屏广告显示失败,InterstitialAd.show() 方法会返回一个rejected Promise,开发者可以获取到错误码及对应的错误信息。

          代码异常情况理由
          2001触发频率限制小程序启动一定时间内不允许展示插屏广告
          2002触发频率限制距离小程序插屏广告或者激励视频广告上次播放时间间隔不足,不允许展示插屏广告
          2003触发频率限制当前正在播放激励视频广告或者插屏广告,不允许再次展示插屏广告
          2004广告渲染失败该项错误不是开发者的异常情况,或因小程序页面切换导致广告渲染失败
          2005广告调用异常插屏广告实例不允许跨页面调用


          wx.switchTab(Object object)

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

          参数

          Object object

          属性类型默认值必填说明
          urlstring需要跳转的 tabBar 页面的路径 (代码包路径)(需在 app.json 的 tabBar 字段定义的页面),路径后不能带参数。
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

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


          wx.reLaunch(Object object)

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

          关闭所有页面,打开到应用内的某个页面

          参数

          Object object

          属性类型默认值必填说明
          urlstring需要跳转的应用内页面路径 (代码包路径),路径后可以带参数。参数与路径之间使用?分隔,参数键与参数值用=相连,不同参数用&分隔;如 'path?key=value&key2=value2'
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

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


          wx.redirectTo(Object object)

          关闭当前页面,跳转到应用内的某个页面。但是不允许跳转到 tabbar 页面。

          参数

          Object object

          属性类型默认值必填说明
          urlstring需要跳转的应用内非 tabBar 的页面的路径 (代码包路径), 路径后可以带参数。参数与路径之间使用 ? 分隔,参数键与参数值用 = 相连,不同参数用 & 分隔;如 'path?key=value&key2=value2'
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

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


          wx.navigateTo(Object object)

          保留当前页面,跳转到应用内的某个页面。但是不能跳到 tabbar 页面。使用 wx.navigateBack 可以返回到原页面。小程序中页面栈最多十层。

          参数

          Object object

          属性类型默认值必填说明
          urlstring需要跳转的应用内非 tabBar 的页面的路径 (代码包路径), 路径后可以带参数。参数与路径之间使用 ? 分隔,参数键与参数值用 = 相连,不同参数用 & 分隔;如 'path?key=value&key2=value2'
          eventsObject页面间通信接口,用于监听被打开页面发送到当前页面的数据。基础库 2.7.3 开始支持。
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.success 回调函数

          参数
          Object res
          属性类型说明
          eventChannelEventChannel和被打开页面进行通信

          示例代码

          wx.navigateTo({  url: 'test?id=1',  events: {    // 为指定事件添加一个监听器,获取被打开页面传送到当前页面的数据    acceptDataFromOpenedPage: function(data) {      console.log(data)    },    someEvent: function(data) {      console.log(data)    }    ...  },  success: function(res) {    // 通过eventChannel向被打开页面传送数据    res.eventChannel.emit('acceptDataFromOpenerPage', { data: 'test' })  }})
          //test.jsPage({  onLoad: function(option){    console.log(option.query)    const eventChannel = this.getOpenerEventChannel()    eventChannel.emit('acceptDataFromOpenedPage', {data: 'test'});    eventChannel.emit('someEvent', {data: 'test'});    // 监听acceptDataFromOpenerPage事件,获取上一页面通过eventChannel传送到当前页面的数据    eventChannel.on('acceptDataFromOpenerPage', function(data) {      console.log(data)    })  }})


          wx.navigateBack(Object object)

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

          参数

          Object object

          属性类型默认值必填说明
          deltanumber1返回的页面数,如果 delta 大于现有页面数,则返回到首页。
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          示例代码

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


          EventChannel

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

          页面间事件通信通道

          方法:

          EventChannel.emit(string eventName, any args)

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

          触发一个事件

          参数

          string eventName

          事件名称

          any args

          事件参数


          EventChannel.off(string eventName, function fn)

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

          取消监听一个事件。给出第二个参数时,只取消给出的监听函数,否则取消所有监听函数

          参数

          string eventName

          事件名称

          function fn

          事件监听函数

          参数

          any args

          触发事件参数


          EventChannel.on(string eventName, function fn)

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

          持续监听一个事件

          参数

          string eventName

          事件名称

          function fn

          事件监听函数

          参数

          any args

          触发事件参数


          EventChannel.once(string eventName, function fn)

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

          监听一个事件一次,触发后失效

          参数

          string eventName

          事件名称

          function fn

          事件监听函数

          参数

          any args

          触发事件参数


          auth.code2Session


          auth.code2Session

          本接口应在服务器端调用,详细说明参见服务端API

          登录凭证校验。通过 wx.login 接口获得临时登录凭证 code 后传到开发者服务器调用此接口完成登录流程。更多使用方法详见 小程序登录

          请求地址

          GET https://api.weixin.qq.com/sns/jscode2session?appid=APPID&secret=SECRET&js_code=JSCODE&grant_type=authorization_code

          请求参数

          属性类型默认值必填说明
          appidstring小程序 appId
          secretstring小程序 appSecret
          js_codestring登录时获取的 code
          grant_typestring授权类型,此处只需填写 authorization_code

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          openidstring用户唯一标识
          session_keystring会话密钥
          unionidstring用户在开放平台的唯一标识符,在满足 UnionID 下发条件的情况下会返回。
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          -1系统繁忙,此时请开发者稍候再试
          0请求成功
          40029code 无效
          45011频率限制,每个用户每分钟100次


          auth.getPaidUnionId

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          用户支付完成后,获取该用户的 UnionId,无需用户授权。本接口支持第三方平台代理查询。

          • 注意:调用前需要用户完成支付,且在支付后的五分钟内有效。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/wxa/getpaidunionid?access_token=ACCESS_TOKEN&openid=OPENID

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          openidstring支付用户唯一标识
          transaction_idstring微信支付订单号
          mch_idstring微信支付分配的商户号,和商户订单号配合使用
          out_trade_nostring微信支付商户订单号,和商户号配合使用

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          unionidstring用户唯一标识,调用成功后返回
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          -1系统繁忙,此时请开发者稍候再试
          0请求成功
          40003openid 错误
          89002没有绑定开放平台帐号
          89300订单无效

          使用说明

          以下两种方式任选其一。

          1. 微信支付订单号(transaction_id):
          https://api.weixin.qq.com/wxa/getpaidunionid?access_token=ACCESS_TOKEN&openid=OPENID&transaction_id=TRANSACTION_ID
          1. 微信支付商户订单号和微信支付商户号(out_trade_no 及 mch_id):
           https://api.weixin.qq.com/wxa/getpaidunionid?access_token=ACCESS_TOKEN&openid=OPENID&mch_id=MCH_ID&out_trade_no=OUT_TRADE_NO

          返回数据示例

          {  "unionid": "oTmHYjg-tElZ68xxxxxxxxhy1Rgk",  "errcode": 0,  "errmsg": "ok"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.auth.getPaidUnionId
          需在 config.json 中配置 auth.getPaidUnionId API 的权限,详情

          请求参数

          属性类型默认值必填说明
          openidstring支付用户唯一标识
          transactionIdstring微信支付订单号
          mchIdstring微信支付分配的商户号,和商户订单号配合使用
          outTradeNostring微信支付商户订单号,和商户号配合使用

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          unionidstring用户唯一标识,调用成功后返回
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          -1系统繁忙,此时请开发者稍候再试
          40003openid 错误
          89002没有绑定开放平台帐号
          89300订单无效

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.auth.getPaidUnionId({        openid: '',        transactionId: '',        mchId: '',        outTradeNo: ''      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "unionid": "oTmHYjg-tElZ68xxxxxxxxhy1Rgk",  "errCode": 0,  "errMsg": "openapi.auth.getPaidUnionId:ok"}


          auth.getAccessToken

          本接口应在服务器端调用,详细说明参见服务端API

          获取小程序全局唯一后台接口调用凭据(access_token)。调用绝大多数后台接口时都需使用 access_token,开发者需要进行妥善保存。

          请求地址

          GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

          请求参数

          属性类型默认值必填说明
          grant_typestring填写 client_credential
          appidstring小程序唯一凭证,即 AppID,可在「微信公众平台 - 设置 - 开发设置」页中获得。(需要已经成为开发者,且帐号没有异常状态)
          secretstring小程序唯一凭证密钥,即 AppSecret,获取方式同 appid

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          access_tokenstring获取到的凭证
          expires_innumber凭证有效时间,单位:秒。目前是7200秒之内的值。
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          -1系统繁忙,此时请开发者稍候再试
          0请求成功
          40001AppSecret 错误或者 AppSecret 不属于这个小程序,请开发者确认 AppSecret 的正确性
          40002请确保 grant_type 字段值为 client_credential
          40013不合法的 AppID,请开发者检查 AppID 的正确性,避免异常字符,注意大小写

          返回数据示例

          正常返回

          {"access_token":"ACCESS_TOKEN","expires_in":7200}

          错误时返回

          {"errcode":40013,"errmsg":"invalid appid"}

          access_token 的存储与更新

          • access_token 的存储至少要保留 512 个字符空间;
          • access_token 的有效期目前为 2 个小时,需定时刷新,重复获取将导致上次获取的 access_token 失效;
          • 建议开发者使用中控服务器统一获取和刷新 access_token,其他业务逻辑服务器所使用的 access_token 均来自于该中控服务器,不应该各自去刷新,否则容易造成冲突,导致 access_token 覆盖而影响业务;
          • access_token 的有效期通过返回的 expires_in 来传达,目前是7200秒之内的值,中控服务器需要根据这个有效时间提前去刷新。在刷新过程中,中控服务器可对外继续输出的老 access_token,此时公众平台后台会保证在5分钟内,新老 access_token 都可用,这保证了第三方业务的平滑过渡;
          • access_token 的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新 access_token 的接口,这样便于业务服务器在API调用获知 access_token 已超时的情况下,可以触发 access_token 的刷新流程。


          analysis.getDailyRetain

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取用户访问小程序日留存

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/datacube/getweanalysisappiddailyretaininfo?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          begin_datestring开始日期。格式为 yyyymmdd
          end_datestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          ref_datestring日期
          visit_uv_newObject新增用户留存
          visit_uvObject活跃用户留存

          visit_uv_new 的结构

          属性类型说明
          keynumber标识,0开始,表示当天,1表示1天后。依此类推,key取值分别是:0,1,2,3,4,5,6,7,14,30
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          visit_uv 的结构

          属性类型说明
          keynumber标识,0开始,表示当天,1表示1天后。依此类推,key取值分别是:0,1,2,3,4,5,6,7,14,30
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          请求数据示例

          {  "begin_date" : "20170313",  "end_date" : "20170313"}

          返回数据示例

          {  "ref_date": "20170313",  "visit_uv_new": [    {      "key": 0,      "value": 5464    }  ],  "visit_uv": [    {      "key": 0,      "value": 55500    }  ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.analysis.getDailyRetain
          需在 config.json 中配置 analysis.getDailyRetain API 的权限,详情

          请求参数

          属性类型默认值必填说明
          beginDatestring开始日期。格式为 yyyymmdd
          endDatestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          refDatestring日期
          visitUvNewObject新增用户留存
          visitUvObject活跃用户留存

          visitUvNew 的结构

          属性类型说明
          keynumber标识,0开始,表示当天,1表示1天后。依此类推,key取值分别是:0,1,2,3,4,5,6,7,14,30
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          visitUv 的结构

          属性类型说明
          keynumber标识,0开始,表示当天,1表示1天后。依此类推,key取值分别是:0,1,2,3,4,5,6,7,14,30
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getDailyRetain({        beginDate: '20170313',        endDate: '20170313'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "refDate": "20170313",  "visitUvNew": [    {      "key": 0,      "value": 5464    }  ],  "visitUv": [    {      "key": 0,      "value": 55500    }  ],  "errMsg": "openapi.analysis.getDailyRetain:ok"}

          analysis.getMonthlyRetain

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取用户访问小程序月留存

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/datacube/getweanalysisappidmonthlyretaininfo?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          begin_datestring开始日期,为自然月第一天。格式为 yyyymmdd
          end_datestring结束日期,为自然月最后一天,限定查询一个月数据。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          ref_datestring时间,如:"201702"
          visit_uv_newObject新增用户留存
          visit_uvObject活跃用户留存

          visit_uv_new 的结构

          属性类型说明
          keynumber标识,0开始,表示当月,1表示1月后。key取值分别是:0,1
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          visit_uv 的结构

          属性类型说明
          keynumber标识,0开始,表示当月,1表示1月后。key取值分别是:0,1
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          注意

          请求json和返回json与天的一致,这里限定查询一个自然月的数据,时间必须按照自然月的方式输入: 如:20170201(月初), 20170228(月末)

          请求数据示例

          {  "begin_date" : "20170201",  "end_date" : "20170228"}

          返回数据示例

          {  "ref_date": "201702",  "visit_uv_new": [    {      "key": 0,      "value": 346249    }  ],  "visit_uv": [    {      "key": 0,      "value": 346249    }  ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.analysis.getMonthlyRetain
          需在 config.json 中配置 analysis.getMonthlyRetain API 的权限,详情

          请求参数

          属性类型默认值必填说明
          beginDatestring开始日期,为自然月第一天。格式为 yyyymmdd
          endDatestring结束日期,为自然月最后一天,限定查询一个月数据。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          refDatestring时间,如:"201702"
          visitUvNewObject新增用户留存
          visitUvObject活跃用户留存

          visitUvNew 的结构

          属性类型说明
          keynumber标识,0开始,表示当月,1表示1月后。key取值分别是:0,1
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          visitUv 的结构

          属性类型说明
          keynumber标识,0开始,表示当月,1表示1月后。key取值分别是:0,1
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getMonthlyRetain({        beginDate: '20170201',        endDate: '20170228'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "refDate": "201702",  "visitUvNew": [    {      "key": 0,      "value": 346249    }  ],  "visitUv": [    {      "key": 0,      "value": 346249    }  ],  "errMsg": "openapi.analysis.getMonthlyRetain:ok"}

          analysis.getWeeklyRetain

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取用户访问小程序周留存

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/datacube/getweanalysisappidweeklyretaininfo?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          begin_datestring开始日期,为周一日期。格式为 yyyymmdd
          end_datestring结束日期,为周日日期,限定查询一周数据。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          ref_datestring时间,如:"20170306-20170312"
          visit_uv_newObject新增用户留存
          visit_uvObject活跃用户留存

          visit_uv_new 的结构

          属性类型说明
          keynumber标识,0开始,表示当周,1表示1周后。依此类推,取值分别是:0,1,2,3,4
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          visit_uv 的结构

          属性类型说明
          keynumber标识,0开始,表示当周,1表示1周后。依此类推,取值分别是:0,1,2,3,4
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          注意

          请求json和返回json与天的一致,这里限定查询一个自然周的数据,时间必须按照自然周的方式输入: 如:20170306(周一), 20170312(周日)

          请求数据示例

          {  "begin_date" : "20170306",  "end_date" : "20170312"}

          返回数据示例

          {  "ref_date": "20170306-20170312",  "visit_uv_new": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 16853    }  ],  "visit_uv": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 99310    }  ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.analysis.getWeeklyRetain
          需在 config.json 中配置 analysis.getWeeklyRetain API 的权限,详情

          请求参数

          属性类型默认值必填说明
          beginDatestring开始日期,为周一日期。格式为 yyyymmdd
          endDatestring结束日期,为周日日期,限定查询一周数据。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          refDatestring时间,如:"20170306-20170312"
          visitUvNewObject新增用户留存
          visitUvObject活跃用户留存

          visitUvNew 的结构

          属性类型说明
          keynumber标识,0开始,表示当周,1表示1周后。依此类推,取值分别是:0,1,2,3,4
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          visitUv 的结构

          属性类型说明
          keynumber标识,0开始,表示当周,1表示1周后。依此类推,取值分别是:0,1,2,3,4
          valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getWeeklyRetain({        beginDate: '20170306',        endDate: '20170312'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "refDate": "20170306-20170312",  "visitUvNew": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 16853    }  ],  "visitUv": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 99310    }  ],  "errMsg": "openapi.analysis.getWeeklyRetain:ok"}


          analysis.getDailySummary

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取用户访问小程序数据概况

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/datacube/getweanalysisappiddailysummarytrend?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          begin_datestring开始日期。格式为 yyyymmdd
          end_datestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          listArray.<Object>数据列表

          list 的结构

          属性类型说明
          ref_datestring日期,格式为 yyyymmdd
          visit_totalnumber累计用户数
          share_pvnumber转发次数
          share_uvnumber转发人数

          请求数据示例

          {  "begin_date" : "20170313",  "end_date" : "20170313"}

          返回数据示例

          {  "list": [    {      "ref_date": "20170313",      "visit_total": 391,      "share_pv": 572,      "share_uv": 383    }  ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.analysis.getDailySummary
          需在 config.json 中配置 analysis.getDailySummary API 的权限,详情

          请求参数

          属性类型默认值必填说明
          beginDatestring开始日期。格式为 yyyymmdd
          endDatestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          listArray.<Object>数据列表

          list 的结构

          属性类型说明
          refDatestring日期,格式为 yyyymmdd
          visitTotalnumber累计用户数
          sharePvnumber转发次数
          shareUvnumber转发人数

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getDailySummary({        beginDate: '20170313',        endDate: '20170313'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "list": [    {      "refDate": "20170313",      "visitTotal": 391,      "sharePv": 572,      "shareUv": 383    }  ],  "errMsg": "openapi.analysis.getDailySummary:ok"}


          analysis.getDailyVisitTrend

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取用户访问小程序数据日趋势

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/datacube/getweanalysisappiddailyvisittrend?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          begin_datestring开始日期。格式为 yyyymmdd
          end_datestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          listArray.<Object>数据列表

          list 的结构

          属性类型说明
          ref_datestring日期,格式为 yyyymmdd
          session_cntnumber打开次数
          visit_pvnumber访问次数
          visit_uvnumber访问人数
          visit_uv_newnumber新用户数
          stay_time_uvnumber人均停留时长 (浮点型,单位:秒)
          stay_time_sessionnumber次均停留时长 (浮点型,单位:秒)
          visit_depthnumber平均访问深度 (浮点型)

          请求数据示例

          {  "begin_date" : "20170313",  "end_date" : "20170313"}

          返回数据示例

          {  "list": [    {      "ref_date": "20170313",      "session_cnt": 142549,      "visit_pv": 472351,      "visit_uv": 55500,      "visit_uv_new": 5464,      "stay_time_session": 0,      "visit_depth": 1.9838    }  ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.analysis.getDailyVisitTrend
          需在 config.json 中配置 analysis.getDailyVisitTrend API 的权限,详情

          请求参数

          属性类型默认值必填说明
          beginDatestring开始日期。格式为 yyyymmdd
          endDatestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          listArray.<Object>数据列表

          list 的结构

          属性类型说明
          refDatestring日期,格式为 yyyymmdd
          sessionCntnumber打开次数
          visitPvnumber访问次数
          visitUvnumber访问人数
          visitUvNewnumber新用户数
          stayTimeUvnumber人均停留时长 (浮点型,单位:秒)
          stayTimeSessionnumber次均停留时长 (浮点型,单位:秒)
          visitDepthnumber平均访问深度 (浮点型)

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getDailyVisitTrend({        beginDate: '20170313',        endDate: '20170313'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "list": [    {      "refDate": "20170313",      "sessionCnt": 142549,      "visitPv": 472351,      "visitUv": 55500,      "visitUvNew": 5464,      "stayTimeSession": 0,      "visitDepth": 1.9838    }  ],  "errMsg": "openapi.analysis.getDailyVisitTrend:ok"}

          analysis.getMonthlyVisitTrend

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取用户访问小程序数据月趋势(能查询到的最新数据为上一个自然月的数据)

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/datacube/getweanalysisappidmonthlyvisittrend?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          begin_datestring开始日期,为自然月第一天。格式为 yyyymmdd
          end_datestring结束日期,为自然月最后一天,限定查询一个月的数据。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          listArray.<Object>数据列表

          list 的结构

          属性类型说明
          ref_datestring时间,格式为 yyyymm,如:"201702"
          session_cntnumber打开次数(自然月内汇总)
          visit_pvnumber访问次数(自然月内汇总)
          visit_uvnumber访问人数(自然月内去重)
          visit_uv_newnumber新用户数(自然月内去重)
          stay_time_uvnumber人均停留时长 (浮点型,单位:秒)
          stay_time_sessionnumber次均停留时长 (浮点型,单位:秒)
          visit_depthnumber平均访问深度 (浮点型)

          访问周期说明

          限定查询一个自然月的数据,时间必须按照自然月的方式输入: 如:20170301, 20170331

          请求数据示例

          {  "begin_date" : "20170301",  "end_date" : "20170331"}

          返回数据示例

          {  "list": [    {      "ref_date": "201703",      "session_cnt": 126513,      "visit_pv": 426113,      "visit_uv": 48659,      "visit_uv_new": 6726,      "stay_time_session": 56.4112,      "visit_depth": 2.0189    }  ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.analysis.getMonthlyVisitTrend
          需在 config.json 中配置 analysis.getMonthlyVisitTrend API 的权限,详情

          请求参数

          属性类型默认值必填说明
          beginDatestring开始日期,为自然月第一天。格式为 yyyymmdd
          endDatestring结束日期,为自然月最后一天,限定查询一个月的数据。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          listArray.<Object>数据列表

          list 的结构

          属性类型说明
          refDatestring时间,格式为 yyyymm,如:"201702"
          sessionCntnumber打开次数(自然月内汇总)
          visitPvnumber访问次数(自然月内汇总)
          visitUvnumber访问人数(自然月内去重)
          visitUvNewnumber新用户数(自然月内去重)
          stayTimeUvnumber人均停留时长 (浮点型,单位:秒)
          stayTimeSessionnumber次均停留时长 (浮点型,单位:秒)
          visitDepthnumber平均访问深度 (浮点型)

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getMonthlyVisitTrend({        beginDate: '20170301',        endDate: '20170331'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "list": [    {      "refDate": "201703",      "sessionCnt": 126513,      "visitPv": 426113,      "visitUv": 48659,      "visitUvNew": 6726,      "stayTimeSession": 56.4112,      "visitDepth": 2.0189    }  ],  "errMsg": "openapi.analysis.getMonthlyVisitTrend:ok"}

          analysis.getWeeklyVisitTrend

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取用户访问小程序数据周趋势

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/datacube/getweanalysisappidweeklyvisittrend?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          begin_datestring开始日期,为周一日期。格式为 yyyymmdd
          end_datestring结束日期,为周日日期,限定查询一周数据。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          listArray.<Object>数据列表

          list 的结构

          属性类型说明
          ref_datestring时间,格式为 yyyymmdd-yyyymmdd,如:"20170306-20170312"
          session_cntnumber打开次数(自然周内汇总)
          visit_pvnumber访问次数(自然周内汇总)
          visit_uvnumber访问人数(自然周内去重)
          visit_uv_newnumber新用户数(自然周内去重)
          stay_time_uvnumber人均停留时长 (浮点型,单位:秒)
          stay_time_sessionnumber次均停留时长 (浮点型,单位:秒)
          visit_depthnumber平均访问深度 (浮点型)

          访问周期说明

          限定查询一个自然周的数据,时间必须按照自然周的方式输入: 如:20170306(周一), 20170312(周日)

          请求数据示例

          {  "begin_date" : "20170306",  "end_date" : "20170312"}

          返回数据示例

          {  "list": [    {      "ref_date": "20170306-20170312",      "session_cnt": 986780,      "visit_pv": 3251840,      "visit_uv": 189405,      "visit_uv_new": 45592,      "stay_time_session": 54.5346,      "visit_depth": 1.9735    }  ]}

          云调用

              是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.analysis.getWeeklyVisitTrend
          需在 config.json 中配置 analysis.getWeeklyVisitTrend API 的权限,详情

          请求参数

          属性类型默认值必填说明
          beginDatestring开始日期,为周一日期。格式为 yyyymmdd
          endDatestring结束日期,为周日日期,限定查询一周数据。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          listArray.<Object>数据列表

          list 的结构

          属性类型说明
          refDatestring时间,格式为 yyyymmdd-yyyymmdd,如:"20170306-20170312"
          sessionCntnumber打开次数(自然周内汇总)
          visitPvnumber访问次数(自然周内汇总)
          visitUvnumber访问人数(自然周内去重)
          visitUvNewnumber新用户数(自然周内去重)
          stayTimeUvnumber人均停留时长 (浮点型,单位:秒)
          stayTimeSessionnumber次均停留时长 (浮点型,单位:秒)
          visitDepthnumber平均访问深度 (浮点型)

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getWeeklyVisitTrend({        beginDate: '20170306',        endDate: '20170312'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "list": [    {      "refDate": "20170306-20170312",      "sessionCnt": 986780,      "visitPv": 3251840,      "visitUv": 189405,      "visitUvNew": 45592,      "stayTimeSession": 54.5346,      "visitDepth": 1.9735    }  ],  "errMsg": "openapi.analysis.getWeeklyVisitTrend:ok"}


          analysis.getUserPortrait

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取小程序新增或活跃用户的画像分布数据。时间范围支持昨天、最近7天、最近30天。其中,新增用户数为时间范围内首次访问小程序的去重用户数,活跃用户数为时间范围内访问过小程序的去重用户数。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/datacube/getweanalysisappiduserportrait?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          begin_datestring开始日期。格式为 yyyymmdd
          end_datestring结束日期,开始日期与结束日期相差的天数限定为0/6/29,分别表示查询最近1/7/30天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          ref_datestring时间范围,如:"20170611-20170617"
          visit_uv_newObject新用户画像
          visit_uvObject活跃用户画像

          visit_uv_new 的结构

          属性类型说明
          indexnumber分布类型
          provinceObject省份,如北京、广东等
          cityObject城市,如北京、广州等
          gendersObject性别,包括男、女、未知
          platformsObject终端类型,包括 iPhone,android,其他
          devicesObject机型,如苹果 iPhone 6,OPPO R9 等
          agesObject年龄,包括17岁以下、18-24岁等区间

          province 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          city 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          genders 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          platforms 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          devices 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          ages 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          visit_uv 的结构

          属性类型说明
          indexnumber分布类型
          provinceObject省份,如北京、广东等
          cityObject城市,如北京、广州等
          gendersObject性别,包括男、女、未知
          platformsObject终端类型,包括 iPhone,android,其他
          devicesObject机型,如苹果 iPhone 6,OPPO R9 等
          agesObject年龄,包括17岁以下、18-24岁等区间

          province 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          city 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          genders 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          platforms 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          devices 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          ages 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          access_source_visit_uvnumber该场景访问uv

          请求数据示例

          {  "begin_date" : "20170611",  "end_date" : "20170617"}

          返回数据示例

          {  "ref_date": "20170611",  "visit_uv_new": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 215      }    ],    "city": [     {        "id": 3102,        "name": "广州",        "value": 78      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 2146      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 27642      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 61      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 151      }    ]  },  "visit_uv": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 1341      }    ],    "city": [     {        "id": 3102,        "name": "广州",        "value": 234      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 14534      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 21750      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 617      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 3156      }    ]  }}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.analysis.getUserPortrait
          需在 config.json 中配置 analysis.getUserPortrait API 的权限,详情

          请求参数

          属性类型默认值必填说明
          beginDatestring开始日期。格式为 yyyymmdd
          endDatestring结束日期,开始日期与结束日期相差的天数限定为0/6/29,分别表示查询最近1/7/30天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          refDatestring时间范围,如:"20170611-20170617"
          visitUvNewObject新用户画像
          visitUvObject活跃用户画像

          visitUvNew 的结构

          属性类型说明
          indexnumber分布类型
          provinceObject省份,如北京、广东等
          cityObject城市,如北京、广州等
          gendersObject性别,包括男、女、未知
          platformsObject终端类型,包括 iPhone,android,其他
          devicesObject机型,如苹果 iPhone 6,OPPO R9 等
          agesObject年龄,包括17岁以下、18-24岁等区间

          province 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          city 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          genders 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          platforms 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          devices 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          ages 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          visitUv 的结构

          属性类型说明
          indexnumber分布类型
          provinceObject省份,如北京、广东等
          cityObject城市,如北京、广州等
          gendersObject性别,包括男、女、未知
          platformsObject终端类型,包括 iPhone,android,其他
          devicesObject机型,如苹果 iPhone 6,OPPO R9 等
          agesObject年龄,包括17岁以下、18-24岁等区间

          province 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          city 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          genders 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          platforms 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          devices 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          ages 的结构

          属性类型说明
          idnumber属性值id
          namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
          accessSourceVisitUvnumber该场景访问uv

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getUserPortrait({        beginDate: '20170611',        endDate: '20170617'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "refDate": "20170611",  "visitUvNew": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 215      }    ],    "city": [      {        "id": 3102,        "name": "广州",        "value": 78      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 2146      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 27642      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 61      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 151      }    ]  },  "visitUv": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 1341      }    ],    "city": [      {        "id": 3102,        "name": "广州",        "value": 234      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 14534      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 21750      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 617      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 3156      }    ]  },  "errMsg": "openapi.analysis.getUserPortrait:ok"}


          analysis.getVisitDistribution

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取用户小程序访问分布数据

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/datacube/getweanalysisappidvisitdistribution?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          begin_datestring开始日期。格式为 yyyymmdd
          end_datestring结束日期,限定查询 1 天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          ref_datestring日期,格式为 yyyymmdd
          listArray.<Object>数据列表

          list 的结构

          属性类型说明
          indexnumber分布类型
          item_listArray.<Object>分布数据列表

          index 的合法值

          说明最低版本
          access_source_session_cnt访问来源分布
          access_staytime_info访问时长分布
          access_depth_info访问深度的分布

          item_list 的结构

          属性类型说明
          keynumber场景 id,定义在各个 index 下不同,具体参见下方表格
          valuenumber该场景 id 访问 pv
          access_source_visit_uvnumber该场景 id 访问 uv

          请求数据示例

          {  "begin_date" : "20170313",  "end_date" : "20170313"}

          返回数据示例

          {  "ref_date": "20170313",  "list": [    {      "index": "access_source_session_cnt",      "item_list": [        {          "key": 10,          "value": 5        },        {          "key": 8,          "value": 687        },        {          "key": 7,          "value": 10740        },        {          "key": 6,          "value": 1961        },        {          "key": 5,          "value": 677        },        {          "key": 4,          "value": 653        },        {          "key": 3,          "value": 1120        },        {          "key": 2,          "value": 10243        },        {          "key": 1,          "value": 116578        }      ]    },    {      "index": "access_staytime_info",      "item_list": [        {          "key": 8,          "value": 16329        },        {          "key": 7,          "value": 19322        },        {          "key": 6,          "value": 21832        },        {          "key": 5,          "value": 19539        },        {          "key": 4,          "value": 29670        },        {          "key": 3,          "value": 19667        },        {          "key": 2,          "value": 11794        },        {          "key": 1,          "value": 4511        }      ]    },    {      "index": "access_depth_info",      "item_list": [        {          "key": 5,          "value": 217        },        {          "key": 4,          "value": 3259        },        {          "key": 3,          "value": 32445        },        {          "key": 2,          "value": 63542        },        {          "key": 1,          "value": 43201        }      ]    }  ]}

          访问来源 key 对应关系(index="access_source_session_cnt"),场景值说明参见 场景值

          key访问来源对应场景值
          1小程序历史列表1001 1002 1004
          2搜索1005 1006 1027 1042 1053 1106 1108 1132
          3会话1007 1008 1044 1093 1094 1096
          4扫一扫二维码1011 1025 1047 1105 1124 1150
          5公众号主页1020
          6聊天顶部1022
          7系统桌面1023 1113 1114 1117
          8小程序主页1024 1135
          9附近的小程序1026 1033 1068
          11模板消息1014 1043 1107 1162
          12客服消息1021
          13公众号菜单1035 1102 1130
          14APP分享1036
          15支付完成页1034 1060 1072 1097 1109 1137 1149
          16长按识别二维码1012 1048 1050 1125
          17相册选取二维码1013 1049 1126
          18公众号文章1058 1091
          19钱包1019 1057 1061 1066 1070 1071
          20卡包1028 1128 1148
          21小程序内卡券1029 1062
          22其他小程序1037
          23其他小程序返回1038
          24卡券适用门店列表1052
          25搜索框快捷入口1054
          26小程序客服消息1073 1081
          27公众号下发1074 1076 1082 1152
          28系统会话菜单1080 1083 1088
          29任务栏-最近使用1089
          30长按小程序菜单圆点1085 1090 1147
          31连wifi成功页1064 1078
          32城市服务1092
          33微信广告1045 1046 1067 1084 1095
          34其他移动应用1065 1069 1111 1140
          35发现入口-我的小程序1003 1103
          36任务栏-我的小程序1104
          37微信圈子1138 1163
          38手机充值1098
          39H51018 1055
          40插件1040 1041 1099
          41大家在用1118 1145
          42发现页1112 1141 1142 1143
          43浮窗1131
          44附近的人1075 1134
          45看一看1115
          46朋友圈1009 1110 1154 1155
          47企业微信1119 1120 1121 1122 1123 1156
          48视频1136 1144
          49收藏1010
          50微信红包1100
          51微信游戏中心1079 1127
          52摇一摇1039 1077
          53公众号导购消息1157
          54识物1153
          55小程序订单1151
          56小程序直播1161
          57群工具1158 1159 1160
          10其他除上述外其余场景值

          访问时长 key 对应关系(index="access_staytime_info")

          key访问时长
          10-2s
          23-5s
          36-10s
          411-20s
          520-30s
          630-50s
          750-100s
          8>100s

          平均访问深度 key 对应关系(index="access_depth_info")

          key访问时长
          11 页
          22 页
          33 页
          44 页
          55 页
          66-10 页
          7>10 页

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.analysis.getVisitDistribution
          需在 config.json 中配置 analysis.getVisitDistribution API 的权限,详情

          请求参数

          属性类型默认值必填说明
          beginDatestring开始日期。格式为 yyyymmdd
          endDatestring结束日期,限定查询 1 天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          refDatestring日期,格式为 yyyymmdd
          listArray.<Object>数据列表

          list 的结构

          属性类型说明
          indexnumber分布类型
          itemListArray.<Object>分布数据列表

          index 的合法值

          说明最低版本
          access_source_session_cnt访问来源分布
          access_staytime_info访问时长分布
          access_depth_info访问深度的分布

          itemList 的结构

          属性类型说明
          keynumber场景 id,定义在各个 index 下不同,具体参见下方表格
          valuenumber该场景 id 访问 pv
          accessSourceVisitUvnumber该场景 id 访问 uv

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getVisitDistribution({        beginDate: '20170313',        endDate: '20170313'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "refDate": "20170313",  "list": [    {      "index": "access_source_session_cnt",      "itemList": [        {          "key": 10,          "value": 5        },        {          "key": 8,          "value": 687        },        {          "key": 7,          "value": 10740        },        {          "key": 6,          "value": 1961        },        {          "key": 5,          "value": 677        },        {          "key": 4,          "value": 653        },        {          "key": 3,          "value": 1120        },        {          "key": 2,          "value": 10243        },        {          "key": 1,          "value": 116578        }      ]    },    {      "index": "access_staytime_info",      "itemList": [        {          "key": 8,          "value": 16329        },        {          "key": 7,          "value": 19322        },        {          "key": 6,          "value": 21832        },        {          "key": 5,          "value": 19539        },        {          "key": 4,          "value": 29670        },        {          "key": 3,          "value": 19667        },        {          "key": 2,          "value": 11794        },        {          "key": 1,          "value": 4511        }      ]    },    {      "index": "access_depth_info",      "itemList": [        {          "key": 5,          "value": 217        },        {          "key": 4,          "value": 3259        },        {          "key": 3,          "value": 32445        },        {          "key": 2,          "value": 63542        },        {          "key": 1,          "value": 43201        }      ]    }  ],  "errMsg": "openapi.analysis.getVisitDistribution:ok"}


          analysis.getVisitPage

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          访问页面。目前只提供按 page_visit_pv 排序的 top200。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/datacube/getweanalysisappidvisitpage?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          begin_datestring开始日期。格式为 yyyymmdd
          end_datestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          page_pathstring页面路径
          page_visit_pvnumber访问次数
          page_visit_uvnumber访问人数
          page_staytime_pvnumber次均停留时长
          entrypage_pvnumber进入页次数
          exitpage_pvnumber退出页次数
          page_share_pvnumber转发次数
          page_share_uvnumber转发人数

          请求数据示例

          {  "begin_date" : "20170313",  "end_date" : "20170313"}

          返回数据示例

          {  "ref_date": "20170313",  "list": [    {      "page_path": "pages/main/main.html",      "page_visit_pv": 213429,      "page_visit_uv": 55423,      "page_staytime_pv": 8.139198,      "entrypage_pv": 117922,      "exitpage_pv": 61304,      "page_share_pv": 180,      "page_share_uv": 166    },    {      "page_path": "pages/linedetail/linedetail.html",      "page_visit_pv": 155030,      "page_visit_uv": 42195,      "page_staytime_pv": 35.462395,      "entrypage_pv": 21101,      "exitpage_pv": 47051,      "page_share_pv": 47,      "page_share_uv": 42    },    {      "page_path": "pages/search/search.html",      "page_visit_pv": 65011,      "page_visit_uv": 24716,      "page_staytime_pv": 6.889634,      "entrypage_pv": 1811,      "exitpage_pv": 3198,      "page_share_pv": 0,      "page_share_uv": 0    },    {      "page_path": "pages/stationdetail/stationdetail.html",      "page_visit_pv": 29953,      "page_visit_uv": 9695,      "page_staytime_pv": 7.558508,      "entrypage_pv": 1386,      "exitpage_pv": 2285,      "page_share_pv": 0,      "page_share_uv": 0    },    {      "page_path": "pages/switch-city/switch-city.html",      "page_visit_pv": 8928,      "page_visit_uv": 4017,      "page_staytime_pv": 9.22659,      "entrypage_pv": 748,      "exitpage_pv": 1613,      "page_share_pv": 0,      "page_share_uv": 0    }  ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.analysis.getVisitPage
          需在 config.json 中配置 analysis.getVisitPage API 的权限,详情

          请求参数

          属性类型默认值必填说明
          beginDatestring开始日期。格式为 yyyymmdd
          endDatestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          pagePathstring页面路径
          pageVisitPvnumber访问次数
          pageVisitUvnumber访问人数
          pageStaytimePvnumber次均停留时长
          entrypagePvnumber进入页次数
          exitpagePvnumber退出页次数
          pageSharePvnumber转发次数
          pageShareUvnumber转发人数

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getVisitPage({        beginDate: '20170313',        endDate: '20170313'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "refDate": "20170313",  "list": [    {      "pagePath": "pages/main/main.html",      "pageVisitPv": 213429,      "pageVisitUv": 55423,      "pageStaytimePv": 8.139198,      "entrypagePv": 117922,      "exitpagePv": 61304,      "pageSharePv": 180,      "pageShareUv": 166    },    {      "pagePath": "pages/linedetail/linedetail.html",      "pageVisitPv": 155030,      "pageVisitUv": 42195,      "pageStaytimePv": 35.462395,      "entrypagePv": 21101,      "exitpagePv": 47051,      "pageSharePv": 47,      "pageShareUv": 42    },    {      "pagePath": "pages/search/search.html",      "pageVisitPv": 65011,      "pageVisitUv": 24716,      "pageStaytimePv": 6.889634,      "entrypagePv": 1811,      "exitpagePv": 3198,      "pageSharePv": 0,      "pageShareUv": 0    },    {      "pagePath": "pages/stationdetail/stationdetail.html",      "pageVisitPv": 29953,      "pageVisitUv": 9695,      "pageStaytimePv": 7.558508,      "entrypagePv": 1386,      "exitpagePv": 2285,      "pageSharePv": 0,      "pageShareUv": 0    },    {      "pagePath": "pages/switch-city/switch-city.html",      "pageVisitPv": 8928,      "pageVisitUv": 4017,      "pageStaytimePv": 9.22659,      "entrypagePv": 748,      "exitpagePv": 1613,      "pageSharePv": 0,      "pageShareUv": 0    }  ],  "errMsg": "openapi.analysis.getVisitPage:ok"}


          customerServiceMessage.getTempMedia

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取客服消息内的临时素材。即下载临时的多媒体文件。目前小程序仅支持下载图片文件。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          media_idstring媒体文件 ID

          返回值

          Buffer

          返回的图片 Buffer

          异常返回

          Object

          JSON

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          40007无效媒体文件 ID

          返回值说明

          如果调用成功,会直接返回图片二进制内容,如果请求失败,会返回 JSON 格式的数据。

          调用示例

          使用 CURL 命令,用 FORM 表单方式上传一个多媒体文件

          curl -I -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.customerServiceMessage.getTempMedia
          需在 config.json 中配置 customerServiceMessage.getTempMedia API 的权限,详情

          请求参数

          属性类型默认值必填说明
          mediaIdstring媒体文件 ID

          返回值

          Object

          包含二进制数据及其数据类型的对象

          属性类型说明
          contentTypeString数据类型 (MIME Type)
          bufferBuffer数据 Buffer

          异常

          Object

          JSON

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.getTempMedia({        mediaId: ''      })    return result  } catch (err) {    return err  }}

          SDK 调用示例

          // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.customerServiceMessage.getTempMedia({  mediaId: 'MEDIA_ID'})

          SDK 调用返回示例

          {  "errCode": 0,  "errMsg": "openapi.customerServiceMessage.getTempMedia:ok",   "contentType": "image/jpeg",   "buffer": Buffer}


          customerServiceMessage.send

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          发送客服消息给用户。详细规则见 发送客服消息

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          touserstring用户的 OpenID
          msgtypestring消息类型
          textObject文本消息,msgtype="text" 时必填
          imageObject图片消息,msgtype="image" 时必填
          linkObject图文链接,msgtype="link" 时必填
          miniprogrampageObject小程序卡片,msgtype="miniprogrampage" 时必填

          msgtype 的合法值

          说明最低版本
          text文本消息
          image图片消息
          link图文链接
          miniprogrampage小程序卡片

          text 的结构

          属性类型默认值必填说明
          contentstring文本消息内容

          image 的结构

          属性类型默认值必填说明
          media_idstring发送的图片的媒体ID,通过 新增素材接口 上传图片文件获得。

          link 的结构

          属性类型默认值必填说明
          titlestring消息标题
          descriptionstring图文链接消息
          urlstring图文链接消息被点击后跳转的链接
          thumb_urlstring图文链接消息的图片链接,支持 JPG、PNG 格式,较好的效果为大图 640 X 320,小图 80 X 80

          miniprogrampage 的结构

          属性类型默认值必填说明
          titlestring消息标题
          pagepathstring小程序的页面路径,跟app.json对齐,支持参数,比如pages/index/index?foo=bar
          thumb_media_idstring小程序消息卡片的封面, image 类型的 media_id,通过 新增素材接口 上传图片文件获得,建议大小为 520*416

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统繁忙,此时请开发者稍候再试
          40001获取 access_token 时 AppSecret 错误,或者 access_token 无效。请开发者认真比对 AppSecret 的正确性,或查看是否正在为恰当的小程序调用接口
          40002不合法的凭证类型
          40003不合法的 OpenID,请开发者确认 OpenID 是否是其他小程序的 OpenID
          45015回复时间超过限制
          45047客服接口下行条数超过上限
          48001API 功能未授权,请确认小程序已获得该接口

          下发消息示例

          发送文本消息

          {  "touser":"OPENID",  "msgtype":"text",  "text":  {    "content":"Hello World"  }}

          发送文本消息时,支持添加可跳转小程序的文字连接

          文本内容...<a href="http://www.qq.com" rel="external nofollow" target="_blank"  rel="external nofollow" target="_blank"  data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>
          说明:
          1. data-miniprogram-appid 项,填写小程序appid,则表示该链接跳转小程序;
          2. data-miniprogram-path项,填写小程序路径,路径与app.json中保持一致,可带参数;
          3. 对于不支持 data-miniprogram-appid 项的客户端版本(6.5.16 以下),如果有 herf 项,则仍然保持跳 href 中的链接;
          4. 小程序发带小程序文字链的文本消息,data-miniprogram-appid必须是该小程序的appid。

          发送图片消息

          {  "touser":"OPENID",  "msgtype":"image",  "image": {    "media_id":"MEDIA_ID"  }}

          发送图文链接

          每次可以发送一个图文链接

          {  "touser": "OPENID",  "msgtype": "link",  "link": {    "title": "Happy Day",    "description": "Is Really A Happy Day",    "url": "URL",    "thumb_url": "THUMB_URL"  }}

          发送小程序卡片

          { "touser":"OPENID", "msgtype":"miniprogrampage", "miniprogrampage": {   "title":"title",   "pagepath":"pagepath",   "thumb_media_id":"thumb_media_id" }}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.customerServiceMessage.send
          需在 config.json 中配置 customerServiceMessage.send API 的权限,详情

          请求参数

          属性类型默认值必填说明
          touserstring用户的 OpenID
          msgtypestring消息类型
          textObject文本消息,msgtype="text" 时必填
          imageObject图片消息,msgtype="image" 时必填
          linkObject图文链接,msgtype="link" 时必填
          miniprogrampageObject小程序卡片,msgtype="miniprogrampage" 时必填

          msgtype 的合法值

          说明最低版本
          text文本消息
          image图片消息
          link图文链接
          miniprogrampage小程序卡片

          text 的结构

          属性类型默认值必填说明
          contentstring文本消息内容

          image 的结构

          属性类型默认值必填说明
          mediaIdstring发送的图片的媒体ID,通过 新增素材接口 上传图片文件获得。

          link 的结构

          属性类型默认值必填说明
          titlestring消息标题
          descriptionstring图文链接消息
          urlstring图文链接消息被点击后跳转的链接
          thumbUrlstring图文链接消息的图片链接,支持 JPG、PNG 格式,较好的效果为大图 640 X 320,小图 80 X 80

          miniprogrampage 的结构

          属性类型默认值必填说明
          titlestring消息标题
          pagepathstring小程序的页面路径,跟app.json对齐,支持参数,比如pages/index/index?foo=bar
          thumbMediaIdstring小程序消息卡片的封面, image 类型的 media_id,通过 新增素材接口 上传图片文件获得,建议大小为 520*416

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          -1系统繁忙,此时请开发者稍候再试
          40001获取 access_token 时 AppSecret 错误,或者 access_token 无效。请开发者认真比对 AppSecret 的正确性,或查看是否正在为恰当的小程序调用接口
          40002不合法的凭证类型
          40003不合法的 OpenID,请开发者确认 OpenID 是否是其他小程序的 OpenID
          45015回复时间超过限制
          45047客服接口下行条数超过上限
          48001API 功能未授权,请确认小程序已获得该接口

          下发消息示例

          发送文本消息

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.send({        touser: 'OPENID',        msgtype: 'text',        text: {          content: 'Hello World'        }      })    return result  } catch (err) {    return err  }}

          发送文本消息时,支持添加可跳转小程序的文字连接

          文本内容...<a href="http://www.qq.com" rel="external nofollow" target="_blank"  rel="external nofollow" target="_blank"  data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>
          说明:
          1. data-miniprogram-appid 项,填写小程序appid,则表示该链接跳转小程序;
          2. data-miniprogram-path项,填写小程序路径,路径与app.json中保持一致,可带参数;
          3. 对于不支持 data-miniprogram-appid 项的客户端版本(6.5.16 以下),如果有 herf 项,则仍然保持跳 href 中的链接;
          4. 小程序发带小程序文字链的文本消息,data-miniprogram-appid必须是该小程序的appid。

          发送图片消息

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.send({        touser: 'OPENID',        msgtype: 'image',        image: {          mediaId: 'MEDIA_ID'        }      })    return result  } catch (err) {    return err  }}

          发送图文链接

          每次可以发送一个图文链接

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.send({        touser: 'OPENID',        msgtype: 'link',        link: {          title: 'Happy Day',          description: 'Is Really A Happy Day',          url: 'URL',          thumbUrl: 'THUMB_URL'        }      })    return result  } catch (err) {    return err  }}

          发送小程序卡片

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.send({        touser: 'OPENID',        msgtype: 'miniprogrampage',        miniprogrampage: {          title: 'title',          pagepath: 'pagepath',          thumbMediaId: 'thumb_media_id'        }      })    return result  } catch (err) {    return err  }}


          customerServiceMessage.setTyping

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          下发客服当前输入状态给用户。详见 客服消息输入状态

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/message/custom/typing?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          touserstring用户的 OpenID
          commandStrign命令

          command 的合法值

          说明最低版本
          Typing对用户下发"正在输入"状态
          CancelTyping取消对用户的"正在输入"状态

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          45072command字段取值不对
          45080下发输入状态,需要之前30秒内跟用户有过消息交互
          45081已经在输入状态,不可重复下发

          请求示例

          {  "touser": "OPENID",  "command": "Typing"   }

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.customerServiceMessage.setTyping
          需在 config.json 中配置 customerServiceMessage.setTyping API 的权限,详情

          请求参数

          属性类型默认值必填说明
          touserstring用户的 OpenID
          commandStrign命令

          command 的合法值

          说明最低版本
          Typing对用户下发"正在输入"状态
          CancelTyping取消对用户的"正在输入"状态

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          45072command字段取值不对
          45080下发输入状态,需要之前30秒内跟用户有过消息交互
          45081已经在输入状态,不可重复下发

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.setTyping({        touser: 'OPENID',        command: 'Typing'      })    return result  } catch (err) {    return err  }}


          customerServiceMessage.uploadTempMedia

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          把媒体文件上传到微信服务器。目前仅支持图片。用于发送客服消息或被动回复用户消息。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          typestring文件类型
          mediaFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息

          type 的合法值

          说明最低版本
          image图片

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          typestring文件类型
          media_idstring媒体文件上传后,获取标识,3天内有效。
          created_atnumber媒体文件上传时间戳

          errcode 的合法值

          说明最低版本
          40004无效媒体文件类型

          type 的合法值

          说明最低版本
          image图片

          调用示例

          使用 CURL 命令,用 FORM 表单方式上传一个多媒体文件

          curl -F media=@test.jpg "https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE"

          返回示例

          {  "errcode": 0,  "errmsg": "ok",  "type": "image",  "media_id": "MEDIA_ID",  "created_at": "xxx"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.customerServiceMessage.uploadTempMedia
          需在 config.json 中配置 customerServiceMessage.uploadTempMedia API 的权限,详情

          请求参数

          属性类型默认值必填说明
          typestring文件类型
          mediaFormData媒体文件数据

          type 的合法值

          说明最低版本
          image图片

          media 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息
          typestring文件类型
          mediaIdstring媒体文件上传后,获取标识,3天内有效。
          createdAtnumber媒体文件上传时间戳

          errCode 的合法值

          说明最低版本
          0成功

          type 的合法值

          说明最低版本
          image图片

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          40004无效媒体文件类型

          返回示例

          {  "errCode": 0,  "errMsg": "openapi.customerServiceMessage.uploadTempMedia:ok",  "type": "image",  "mediaId": "MEDIA_ID",  "createdAt": "xxx"}

          SDK 调用示例

          // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.customerServiceMessage.uploadTempMedia({  type: 'image',  media: {    contentType: 'image/png',    value: Buffer  }})


          uniformMessage.send

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          下发小程序和公众号统一的服务消息

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/message/wxopen/template/uniform_send?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          touserstring用户openid,可以是小程序的openid,也可以是mp_template_msg.appid对应的公众号的openid
          weapp_template_msgObject小程序模板消息相关的信息,可以参考小程序模板消息接口; 有此节点则优先发送小程序模板消息
          mp_template_msgObject公众号模板消息相关的信息,可以参考公众号模板消息接口;有此节点并且没有weapp_template_msg节点时,发送公众号模板消息

          weapp_template_msg 的结构

          属性类型默认值必填说明
          template_idstring小程序模板ID
          pagestring小程序页面路径
          form_idstring小程序模板消息formid
          datastring小程序模板数据
          emphasis_keywordstring小程序模板放大关键词

          mp_template_msg 的结构

          属性类型默认值必填说明
          appidstring公众号appid,要求与小程序有绑定且同主体
          template_idstring公众号模板id
          urlstring公众号模板消息所要跳转的url
          miniprogramstring公众号模板消息所要跳转的小程序,小程序的必须与公众号具有绑定关系
          datastring公众号模板消息的数据

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          错误

          错误码错误信息说明
          40037模板id不正确,weapp_template_msg.template_id或者mp_template_msg.template_id
          41028weapp_template_msg.form_id过期或者不正确
          41029weapp_template_msg.form_id已被使用
          41030weapp_template_msg.page不正确
          45009接口调用超过限额
          40003touser不是正确的openid
          40013appid不正确,或者不符合绑定关系要求

          请求数据示例

          {    "touser":"OPENID",    "weapp_template_msg":{        "template_id":"TEMPLATE_ID",        "page":"page/page/index",        "form_id":"FORMID",        "data":{            "keyword1":{                "value":"339208499"            },            "keyword2":{                "value":"2015年01月05日 12:30"            },            "keyword3":{                "value":"腾讯微信总部"            },            "keyword4":{                "value":"广州市海珠区新港中路397号"            }        },        "emphasis_keyword":"keyword1.DATA"    },    "mp_template_msg":{        "appid":"APPID ",        "template_id":"TEMPLATE_ID",        "url":"http://weixin.qq.com/download",        "miniprogram":{            "appid":"xiaochengxuappid12345",            "pagepath":"index?foo=bar"        },        "data":{            "first":{                "value":"恭喜你购买成功!",                "color":"#173177"            },            "keyword1":{                "value":"巧克力",                "color":"#173177"            },            "keyword2":{                "value":"39.8元",                "color":"#173177"            },            "keyword3":{                "value":"2014年9月22日",                "color":"#173177"            },            "remark":{                "value":"欢迎再次购买!",                "color":"#173177"            }        }    }}

          返回数据示例

          { "errcode": 0, "errmsg": "ok"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.uniformMessage.send
          需在 config.json 中配置 uniformMessage.send API 的权限,详情

          请求参数

          属性类型默认值必填说明
          touserstring用户openid,可以是小程序的openid,也可以是mp_template_msg.appid对应的公众号的openid
          weappTemplateMsgObject小程序模板消息相关的信息,可以参考小程序模板消息接口; 有此节点则优先发送小程序模板消息
          mpTemplateMsgObject公众号模板消息相关的信息,可以参考公众号模板消息接口;有此节点并且没有weapp_template_msg节点时,发送公众号模板消息

          weappTemplateMsg 的结构

          属性类型默认值必填说明
          templateIdstring小程序模板ID
          pagestring小程序页面路径
          formIdstring小程序模板消息formid
          datastring小程序模板数据
          emphasisKeywordstring小程序模板放大关键词

          mpTemplateMsg 的结构

          属性类型默认值必填说明
          appidstring公众号appid,要求与小程序有绑定且同主体
          templateIdstring公众号模板id
          urlstring公众号模板消息所要跳转的url
          miniprogramstring公众号模板消息所要跳转的小程序,小程序的必须与公众号具有绑定关系
          datastring公众号模板消息的数据

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          错误

          错误码错误信息说明
          40037模板id不正确,weapp_template_msg.template_id或者mp_template_msg.template_id
          41028weapp_template_msg.form_id过期或者不正确
          41029weapp_template_msg.form_id已被使用
          41030weapp_template_msg.page不正确
          45009接口调用超过限额
          40003touser不是正确的openid
          40013appid不正确,或者不符合绑定关系要求

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.uniformMessage.send({        touser: 'OPENID',        weappTemplateMsg: {          page: 'page/page/index',          data: {            keyword1: {              value: '339208499'            },            keyword2: {              value: '2015年01月05日 12:30'            },            keyword3: {              value: '腾讯微信总部'            },            keyword4: {              value: '广州市海珠区新港中路397号'            }          },          templateId: 'TEMPLATE_ID',          formId: 'FORMID',          emphasisKeyword: 'keyword1.DATA'        },        mpTemplateMsg: {          appid: 'APPID ',          url: 'http://weixin.qq.com/download',          miniprogram: {            appid: 'xiaochengxuappid12345',            pagepath: 'index?foo=bar'          },          data: {            first: {              value: '恭喜你购买成功!',              color: '#173177'            },            keyword1: {              value: '巧克力',              color: '#173177'            },            keyword2: {              value: '39.8元',              color: '#173177'            },            keyword3: {              value: '2014年9月22日',              color: '#173177'            },            remark: {              value: '欢迎再次购买!',              color: '#173177'            }          },          templateId: 'TEMPLATE_ID'        }      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "errCode": 0,  "errMsg": "openapi.uniformMessage.send:ok"}


          updatableMessage.createActivityId

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          创建被分享动态消息的 activity_id。详见动态消息

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/cgi-bin/message/wxopen/activityid/create?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          activity_idstring动态消息的 ID
          expiration_timenumberactivity_id 的过期时间戳。默认24小时后过期。
          errcodenumber错误码

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统繁忙。此时请开发者稍候再试
          42001access_token 过期

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.updatableMessage.createActivityId
          需在 config.json 中配置 updatableMessage.createActivityId API 的权限,详情

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          activityIdstring动态消息的 ID
          expirationTimenumberactivity_id 的过期时间戳。默认24小时后过期。
          errCodenumber错误码

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码

          errCode 的合法值

          说明最低版本
          -1系统繁忙。此时请开发者稍候再试
          42001access_token 过期


          updatableMessage.setUpdatableMsg

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          修改被分享的动态消息。详见动态消息

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/message/wxopen/updatablemsg/send?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          activity_idstring动态消息的 ID,通过 updatableMessage.createActivityId 接口获取
          target_statenumber动态消息修改后的状态(具体含义见后文)
          template_infoObject动态消息对应的模板信息

          target_state 的合法值

          说明最低版本
          0未开始
          1已开始

          template_info 的结构

          属性类型默认值必填说明
          parameter_listArray.<Object>模板中需要修改的参数

          parameter_list 的结构

          属性类型默认值必填说明
          namestring要修改的参数名
          valuestring修改后的参数值

          name 的合法值

          说明最低版本
          member_counttarget_state = 0 时必填,文字内容模板中 member_count 的值
          room_limittarget_state = 0 时必填,文字内容模板中 room_limit 的值
          pathtarget_state = 1 时必填,点击「进入」启动小程序时使用的路径。
          对于小游戏,没有页面的概念,可以用于传递查询字符串(query),如 "?foo=bar"
          version_typetarget_state = 1 时必填,点击「进入」启动小程序时使用的版本。
          有效参数值为:develop(开发版),trial(体验版),release(正式版)

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgnumber错误信息

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统繁忙。此时请开发者稍候再试
          42001access_token 过期
          44002post 数据为空
          47001post 数据中参数缺失
          47501参数 activity_id 错误
          47502参数 target_state 错误
          47503参数 version_type 错误
          47504activity_id 过期

          消息状态

          消息有两个状态(target_state),分别有其对应的文字内容和颜色。文字内容模板和颜色不支持变更。

          状态文字内容颜色允许转移的状态
          0"成员正在加入,当前 {member_count}/{room_limit} 人"#FA9D390, 1
          1"已开始"#CCCCCC

          活动的默认有效期是 24 小时。活动结束后,消息内容会变成统一的样式:

          • 文字内容:“已结束”
          • 文字颜色:#00ff00

          curl 调用示例

          curl -d '{"activity_id": "966_NGiqxxxxxxxxx...xxxxxxxxE33BlwX", "target_state": 0, "template_info": {"parameter_list": [{"name": "member_count", "value": "2"}, {"name":"room_limit", "value": "5"} ] } }' 'https://api.weixin.qq.com/cgi-bin/message/wxopen/updatablemsg/send?access_token=ACCESS_TOKEN'

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.updatableMessage.setUpdatableMsg
          需在 config.json 中配置 updatableMessage.setUpdatableMsg API 的权限,详情

          请求参数

          属性类型默认值必填说明
          activityIdstring动态消息的 ID,通过 updatableMessage.createActivityId 接口获取
          targetStatenumber动态消息修改后的状态(具体含义见后文)
          templateInfoObject动态消息对应的模板信息

          targetState 的合法值

          说明最低版本
          0未开始
          1已开始

          templateInfo 的结构

          属性类型默认值必填说明
          parameterListArray.<Object>模板中需要修改的参数

          parameterList 的结构

          属性类型默认值必填说明
          namestring要修改的参数名
          valuestring修改后的参数值

          name 的合法值

          说明最低版本
          member_counttarget_state = 0 时必填,文字内容模板中 member_count 的值
          room_limittarget_state = 0 时必填,文字内容模板中 room_limit 的值
          pathtarget_state = 1 时必填,点击「进入」启动小程序时使用的路径。
          对于小游戏,没有页面的概念,可以用于传递查询字符串(query),如 "?foo=bar"
          version_typetarget_state = 1 时必填,点击「进入」启动小程序时使用的版本。
          有效参数值为:develop(开发版),trial(体验版),release(正式版)

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgnumber错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgnumber错误信息

          errCode 的合法值

          说明最低版本
          -1系统繁忙。此时请开发者稍候再试
          42001access_token 过期
          44002post 数据为空
          47001post 数据中参数缺失
          47501参数 activity_id 错误
          47502参数 target_state 错误
          47503参数 version_type 错误
          47504activity_id 过期


          pluginManager.applyPlugin

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          向插件开发者发起使用插件的申请

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/plugin?access_token=TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          actionstring此接口下填写 "apply"
          plugin_appidstring插件 appId
          reasonstring申请使用理由

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          错误

          错误码错误信息说明
          0ok正常
          -1系统错误
          89236该插件不能申请
          89237已经添加该插件
          89238申请或使用的插件已经达到上限
          89239该插件不存在
          89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
          89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
          89242该appid不在申请列表内
          89243“待确认”的申请不可删除
          89044不存在该插件appid

          请求数据示例

          {  "action": "apply",  "plugin_appid": "aaaa",  "reason": "hello"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.pluginManager.applyPlugin
          需在 config.json 中配置 pluginManager.applyPlugin API 的权限,详情

          请求参数

          属性类型默认值必填说明
          actionstring此接口下填写 "apply"
          pluginAppidstring插件 appId
          reasonstring申请使用理由

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          错误

          错误码错误信息说明
          0ok正常
          -1系统错误
          89236该插件不能申请
          89237已经添加该插件
          89238申请或使用的插件已经达到上限
          89239该插件不存在
          89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
          89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
          89242该appid不在申请列表内
          89243“待确认”的申请不可删除
          89044不存在该插件appid

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.applyPlugin({        action: 'apply',        reason: 'hello',        pluginAppid: 'aaaa'      })    return result  } catch (err) {    return err  }}


          pluginManager.getPluginDevApplyList

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取当前所有插件使用方(供插件开发者调用)

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/devplugin?access_token=TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          actionstring此接口下填写 "dev_apply_list"
          pagenumber要拉取第几页的数据
          numnumber每页的记录数

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          apply_listArray.<Object>插件使用方列表

          apply_list 的结构

          属性类型说明
          appidstring使用者的appid
          statusnumber插件状态
          nicknamestring使用者的昵称
          headimgurlstring使用者的头像
          categoriesArray.<Object>使用者的类目
          create_timestring使用者的申请时间
          apply_urlstring使用者的小程序码
          reasonstring使用者的申请说明

          status 的合法值

          说明最低版本
          1申请中
          2申请通过
          3已拒绝
          4已超时

          错误

          错误码错误信息说明
          0ok正常
          -1系统错误
          89236该插件不能申请
          89237已经添加该插件
          89238申请或使用的插件已经达到上限
          89239该插件不存在
          89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
          89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
          89242该appid不在申请列表内
          89243“待确认”的申请不可删除
          89044不存在该插件appid

          请求数据示例

          {  "action":"dev_apply_list",  "page": 1,  "num": 10}

          返回数据示例

          {  "errcode": 0,  "errmsg": "ok",  "apply_list": [{    "appid": "xxxxxxxxxxxxx",    "status": 1,    "nickname": "名称",    "headimgurl": "**********",    "reason": "polo has gone",    "apply_url": "*******",    "create_time": "1536305096",    "categories": [{      "first": "IT科技",      "second": "硬件与设备"    }]  }]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.pluginManager.getPluginDevApplyList
          需在 config.json 中配置 pluginManager.getPluginDevApplyList API 的权限,详情

          请求参数

          属性类型默认值必填说明
          actionstring此接口下填写 "dev_apply_list"
          pagenumber要拉取第几页的数据
          numnumber每页的记录数

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息
          applyListArray.<Object>插件使用方列表

          applyList 的结构

          属性类型说明
          appidstring使用者的appid
          statusnumber插件状态
          nicknamestring使用者的昵称
          headimgurlstring使用者的头像
          categoriesArray.<Object>使用者的类目
          createTimestring使用者的申请时间
          applyUrlstring使用者的小程序码
          reasonstring使用者的申请说明

          status 的合法值

          说明最低版本
          1申请中
          2申请通过
          3已拒绝
          4已超时

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          错误

          错误码错误信息说明
          0ok正常
          -1系统错误
          89236该插件不能申请
          89237已经添加该插件
          89238申请或使用的插件已经达到上限
          89239该插件不存在
          89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
          89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
          89242该appid不在申请列表内
          89243“待确认”的申请不可删除
          89044不存在该插件appid

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.getPluginDevApplyList({        action: 'dev_apply_list',        page: 1,        num: 10      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "errCode": 0,  "errMsg": "openapi.pluginManager.getPluginDevApplyList:ok",  "applyList": [    {      "appid": "xxxxxxxxxxxxx",      "status": 1,      "nickname": "名称",      "headimgurl": "**********",      "reason": "polo has gone",      "categories": [        {          "first": "IT科技",          "second": "硬件与设备"        }      ],      "applyUrl": "*******",      "createTime": "1536305096"    }  ]}


          pluginManager.getPluginList

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          查询已添加的插件

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/plugin?access_token=TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          actionstring此接口下填写 "list"

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          plugin_listArray.<Object>申请或使用中的插件列表

          plugin_list 的结构

          属性类型说明
          appidstring插件 appId
          statusnumber插件状态
          nicknamestring插件昵称
          headimgurlstring插件头像

          status 的合法值

          说明最低版本
          1申请中
          2申请通过
          3已拒绝
          4已超时

          错误

          错误码错误信息说明
          0ok正常
          -1系统错误
          89236该插件不能申请
          89237已经添加该插件
          89238申请或使用的插件已经达到上限
          89239该插件不存在
          89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
          89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
          89242该appid不在申请列表内
          89243“待确认”的申请不可删除
          89044不存在该插件appid

          请求数据示例

          {  "action":"list"}

          返回数据示例

          {  "errcode": 0,  "errmsg": "ok",  "plugin_list": [{    "appid": "aaaa",    "status": 1,    "nickname": "插件昵称",    "headimgurl": "http://plugin.qq.com"  }]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.pluginManager.getPluginList
          需在 config.json 中配置 pluginManager.getPluginList API 的权限,详情

          请求参数

          属性类型默认值必填说明
          actionstring此接口下填写 "list"

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息
          pluginListArray.<Object>申请或使用中的插件列表

          pluginList 的结构

          属性类型说明
          appidstring插件 appId
          statusnumber插件状态
          nicknamestring插件昵称
          headimgurlstring插件头像

          status 的合法值

          说明最低版本
          1申请中
          2申请通过
          3已拒绝
          4已超时

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          错误

          错误码错误信息说明
          0ok正常
          -1系统错误
          89236该插件不能申请
          89237已经添加该插件
          89238申请或使用的插件已经达到上限
          89239该插件不存在
          89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
          89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
          89242该appid不在申请列表内
          89243“待确认”的申请不可删除
          89044不存在该插件appid

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.getPluginList({        action: 'list'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "errCode": 0,  "errMsg": "openapi.pluginManager.getPluginList:ok",  "pluginList": [    {      "appid": "aaaa",      "status": 1,      "nickname": "插件昵称",      "headimgurl": "http://plugin.qq.com"    }  ]}


          pluginManager.setDevPluginApplyStatus

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          修改插件使用申请的状态(供插件开发者调用)

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/devplugin?access_token=TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          actionstring修改操作
          appidstring使用者的 appid。同意申请时填写。
          reasonstring拒绝理由。拒绝申请时填写。

          action 的合法值

          说明最低版本
          dev_agree同意申请
          dev_refuse拒绝申请
          dev_delete删除已拒绝的申请者

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          错误

          错误码错误信息说明
          0ok正常
          -1系统错误
          89236该插件不能申请
          89237已经添加该插件
          89238申请或使用的插件已经达到上限
          89239该插件不存在
          89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
          89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
          89242该appid不在申请列表内
          89243“待确认”的申请不可删除
          89044不存在该插件appid

          请求数据示例

          {  "action": "dev_agree",  "appid": "aaaa"}

          {  "action": "dev_refuse",  "reason": "refuse reason"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.pluginManager.setDevPluginApplyStatus
          需在 config.json 中配置 pluginManager.setDevPluginApplyStatus API 的权限,详情

          请求参数

          属性类型默认值必填说明
          actionstring修改操作
          appidstring使用者的 appid。同意申请时填写。
          reasonstring拒绝理由。拒绝申请时填写。

          action 的合法值

          说明最低版本
          dev_agree同意申请
          dev_refuse拒绝申请
          dev_delete删除已拒绝的申请者

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          错误

          错误码错误信息说明
          0ok正常
          -1系统错误
          89236该插件不能申请
          89237已经添加该插件
          89238申请或使用的插件已经达到上限
          89239该插件不存在
          89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
          89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
          89242该appid不在申请列表内
          89243“待确认”的申请不可删除
          89044不存在该插件appid

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.setDevPluginApplyStatus({        action: 'dev_agree',        appid: 'aaaa'      })    return result  } catch (err) {    return err  }}

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.setDevPluginApplyStatus({        action: 'dev_refuse',        reason: 'refuse reason'      })    return result  } catch (err) {    return err  }}


          pluginManager.unbindPlugin

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          删除已添加的插件

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/plugin?access_token=TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          actionstring此接口下填写 "unbind"
          plugin_appidstring插件 appId

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          错误

          错误码错误信息说明
          0ok正常
          -1系统错误
          89236该插件不能申请
          89237已经添加该插件
          89238申请或使用的插件已经达到上限
          89239该插件不存在
          89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
          89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
          89242该appid不在申请列表内
          89243“待确认”的申请不可删除
          89044不存在该插件appid

          请求数据示例

          {  "action":"unbind",  "plugin_appid":"aaaa"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.pluginManager.unbindPlugin
          需在 config.json 中配置 pluginManager.unbindPlugin API 的权限,详情

          请求参数

          属性类型默认值必填说明
          actionstring此接口下填写 "unbind"
          pluginAppidstring插件 appId

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          错误

          错误码错误信息说明
          0ok正常
          -1系统错误
          89236该插件不能申请
          89237已经添加该插件
          89238申请或使用的插件已经达到上限
          89239该插件不存在
          89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
          89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
          89242该appid不在申请列表内
          89243“待确认”的申请不可删除
          89044不存在该插件appid

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.unbindPlugin({        action: 'unbind',        pluginAppid: 'aaaa'      })    return result  } catch (err) {    return err  }}


          nearbyPoi.add

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          添加地点

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/addnearbypoi?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          is_comm_nearbystring必填,写死为"1"
          pic_liststring门店图片,最多9张,最少1张,上传门店图片如门店外景、环境设施、商品服务等,图片将展示在微信客户端的门店页。图片链接通过文档https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1444738729中的《上传图文消息内的图片获取URL》接口获取。必填,文件格式为bmp、png、jpeg、jpg或gif,大小不超过5M pic_list是字符串,内容是一个json
          service_infosstring必服务标签列表 必填,需要填写
          1、 服务标签ID
          2、 服务类型tpye
          3、 服务名称name
          详细字段格式见下方《服务标签id编号、类型与服务名称表》
          4、 APPID
          5、 对应服务落地页的path路径:path路径页面要与对应的服务标签一致,例如选取外卖服务,path路径应该是小程序的外卖对应的那个页面,path路径获取咨询开发或者到小程序管理后台-工具-生成小程序码页面获取
          6、新增服务描述desc:描述服务内容,例如满减、折扣等优惠信息或新品、爆品等商品信息,仅标准服务都可添加,10个字符以内。
          service_infos是字符串,内容是一个json
          kf_infostring客服信息 选填,可自定义服务头像与昵称,具体填写字段见下方示例kf_info pic_list是字符串,内容是一个json
          store_namestring门店名字 必填,门店名称需按照所选地理位置自动拉取腾讯地图门店名称,不可修改,如需修改请重现选择地图地点或重新创建地点。
          hourstring营业时间,格式11:11-12:12 必填
          addressstring地址 必填
          poi_idstring如果创建新的门店,poi_id字段为空 如果更新门店,poi_id参数则填对应门店的poi_id 选填
          company_namestring主体名字 必填
          contract_phonestring门店电话 必填
          credentialstring资质号 必填, 15位营业执照注册号或9位组织机构代码
          qualification_liststring证明材料 必填 如果company_name和该小程序主体不一致,需要填qualification_list,详细规则见附近的小程序使用指南-如何证明门店的经营主体跟公众号或小程序帐号主体相关http://kf.qq.com/faq/170401MbUnim17040122m2qY.html
          map_poi_idstring对应《在腾讯地图中搜索门店》中的sosomap_poi_uid字段 腾讯地图那边有些数据不一致,如果不填map_poi_id的话,小概率会提交失败!
          注:
          poi_id与map_poi_id关系:
          map_poi_id是腾讯地图对于poi的唯一标识
          poi_id是门店进驻附近后的门店唯一标识
          NearbyPoiError@error

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errmsgstring错误信息
          errcodenumber错误码
          dataobject返回数据

          data 的结构

          属性类型说明
          audit_idstring审核单 ID
          poi_idstring附近地点 ID
          related_credentialstring经营资质证件号

          注:添加门店需要审核,需要1到2个工作日

          服务标签id编号、类型与服务名称表

          IDtypename(服务名称)
          02自定义服务,可自定义名称(10个以内)
          11外送
          21快递
          31充电
          41预约
          51挂号
          61点餐
          71优惠
          81乘车
          91会员
          101买单
          111排队
          121缴费
          131购票
          141到店自提
          151预定

          频率限制说明

          添加请求暂不支持并发调用,建议使用时间隔1s进行串行调用

          请求示例

          {"is_comm_nearby": "1", //值固定"kf_info": "{"open_kf":true,"kf_headimg":"http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITqmP914zSwhajIEJzUPpx40P7R8fRe1QmicneQMhFzpZNhSLjrvU1pIA/0?wx_fmt=jpeg","kf_name":"Harden"}","pic_list": "{"list":["http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITqmP914zSwhajIEJzUPpx40P7R8fRe1QmicneQMhFzpZNhSLjrvU1pIA/0?wx_fmt=jpeg","http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITRneE5FS9uYruXGMmrtmhsBySwddEWUGOibG8Ze2NT5E3Dyt79I0htNg/0?wx_fmt=jpeg"]}","service_infos": "{"service_infos":[{"id":2,"type":1,"name":"快递","appid":"wx1373169e494e0c39","path":"index"},{"id":0,"type":2,"name":"自定义","appid":"wx1373169e494e0c39","path":"index"}]}","store_name": "羊村小马烧烤","contract_phone": "111111111","hour": "00:00-11:11","company_name": "深圳市腾讯计算机系统有限公司","credential": "156718193518281","address": "新疆维吾尔自治区克拉玛依市克拉玛依区碧水路15-1-8号(碧水云天广场)","qualification_list": "3LaLzqiTrQcD20DlX_o-OV1-nlYMu7sdVAL7SV2PrxVyjZFZZmB3O6LPGaYXlZWq","poi_id": ""}

          返回json示例: { "errcode":0, "errmsg":"ok", "data":{ "audit_id":416620525, "poi_id": 112333 } }

          审核状态通知

          审核状态通过事件推送通知,推送数据格式为 XML

          示例数据

          <xml>  <ToUserName><![CDATA[gh_4346ac1514d8]]></ToUserName>  <FromUserName><![CDATA[od1P50M-fNQI5Gcq-trm4a7apsU8]]></FromUserName>  <CreateTime>1488856741</CreateTime>  <MsgType><![CDATA[event]]></MsgType>  <Event><![CDATA[add_nearby_poi_audit_info]]></Event>  <audit_id>11111</audit_id>  <status>3</status>                // 2: 审核失败 3: 审核通过  <reason><![CDATA[xxx]]></reason>  //审核失败的理由  <poi_id>111111</poi_id></xml>

          参数说明

          参数说明
          audit_id审核单id
          status审核状态(3:审核通过,2:审核失败)
          reason如果status为2,会返回审核失败的原因
          poi_idpoi_id

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.nearbyPoi.add
          需在 config.json 中配置 nearbyPoi.add API 的权限,详情

          请求参数

          属性类型默认值必填说明
          isCommNearbystring必填,写死为"1"
          picListstring门店图片,最多9张,最少1张,上传门店图片如门店外景、环境设施、商品服务等,图片将展示在微信客户端的门店页。图片链接通过文档https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1444738729中的《上传图文消息内的图片获取URL》接口获取。必填,文件格式为bmp、png、jpeg、jpg或gif,大小不超过5M pic_list是字符串,内容是一个json
          serviceInfosstring必服务标签列表 必填,需要填写
          1、 服务标签ID
          2、 服务类型tpye
          3、 服务名称name
          详细字段格式见下方《服务标签id编号、类型与服务名称表》
          4、 APPID
          5、 对应服务落地页的path路径:path路径页面要与对应的服务标签一致,例如选取外卖服务,path路径应该是小程序的外卖对应的那个页面,path路径获取咨询开发或者到小程序管理后台-工具-生成小程序码页面获取
          6、新增服务描述desc:描述服务内容,例如满减、折扣等优惠信息或新品、爆品等商品信息,仅标准服务都可添加,10个字符以内。
          service_infos是字符串,内容是一个json
          kfInfostring客服信息 选填,可自定义服务头像与昵称,具体填写字段见下方示例kf_info pic_list是字符串,内容是一个json
          storeNamestring门店名字 必填,门店名称需按照所选地理位置自动拉取腾讯地图门店名称,不可修改,如需修改请重现选择地图地点或重新创建地点。
          hourstring营业时间,格式11:11-12:12 必填
          addressstring地址 必填
          poiIdstring如果创建新的门店,poi_id字段为空 如果更新门店,poi_id参数则填对应门店的poi_id 选填
          companyNamestring主体名字 必填
          contractPhonestring门店电话 必填
          credentialstring资质号 必填, 15位营业执照注册号或9位组织机构代码
          qualificationListstring证明材料 必填 如果company_name和该小程序主体不一致,需要填qualification_list,详细规则见附近的小程序使用指南-如何证明门店的经营主体跟公众号或小程序帐号主体相关http://kf.qq.com/faq/170401MbUnim17040122m2qY.html
          mapPoiIdstring对应《在腾讯地图中搜索门店》中的sosomap_poi_uid字段 腾讯地图那边有些数据不一致,如果不填map_poi_id的话,小概率会提交失败!
          注:
          poi_id与map_poi_id关系:
          map_poi_id是腾讯地图对于poi的唯一标识
          poi_id是门店进驻附近后的门店唯一标识
          NearbyPoiError@error

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errMsgstring错误信息
          errCodenumber错误码
          dataobject返回数据

          data 的结构

          属性类型说明
          auditIdstring审核单 ID
          poiIdstring附近地点 ID
          relatedCredentialstring经营资质证件号

          异常

          Object

          抛出的异常

          属性类型说明
          errMsgstring错误信息
          errCodenumber错误码

          errCode 的合法值

          说明最低版本

          请求示例

          {"is_comm_nearby": "1", //值固定"kf_info": "{"open_kf":true,"kf_headimg":"http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITqmP914zSwhajIEJzUPpx40P7R8fRe1QmicneQMhFzpZNhSLjrvU1pIA/0?wx_fmt=jpeg","kf_name":"Harden"}","pic_list": "{"list":["http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITqmP914zSwhajIEJzUPpx40P7R8fRe1QmicneQMhFzpZNhSLjrvU1pIA/0?wx_fmt=jpeg","http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITRneE5FS9uYruXGMmrtmhsBySwddEWUGOibG8Ze2NT5E3Dyt79I0htNg/0?wx_fmt=jpeg"]}","service_infos": "{"service_infos":[{"id":2,"type":1,"name":"快递","appid":"wx1373169e494e0c39","path":"index"},{"id":0,"type":2,"name":"自定义","appid":"wx1373169e494e0c39","path":"index"}]}","store_name": "羊村小马烧烤","contract_phone": "111111111","hour": "00:00-11:11","company_name": "深圳市腾讯计算机系统有限公司","credential": "156718193518281","address": "新疆维吾尔自治区克拉玛依市克拉玛依区碧水路15-1-8号(碧水云天广场)","qualification_list": "3LaLzqiTrQcD20DlX_o-OV1-nlYMu7sdVAL7SV2PrxVyjZFZZmB3O6LPGaYXlZWq","poi_id": ""}

          返回json示例: { "errcode":0, "errmsg":"ok", "data":{ "audit_id":416620525, "poi_id": 112333 } }


          nearbyPoi.delete

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          删除地点

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/delnearbypoi?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          poi_idstring附近地点 ID

          返回值

          deleteNearbyPoiResponse

          返回的 JSON 数据包

          错误

          错误码错误信息说明
          0ok正常
          47001POST数据json格式错误
          20002POST参数非法
          44002POST数据为空
          92000该经营资质已添加,请勿重复添加
          92002附近地点添加数量达到上线,无法继续添加
          92003地点已被其它小程序占用
          92004附近功能被封禁
          92005地点正在审核中
          92006地点正在展示小程序
          92007地点审核失败
          92008程序未展示在该地点
          93009小程序未上架或不可见
          93010地点不存在
          93011个人类型小程序不可用
          93011个人类型小程序不可用
          93012非普通类型小程序(门店小程序、小店小程序等)不可用
          93013从腾讯地图获取地址详细信息失败
          93014同一资质证件号重复添加

          POST数据示例:

          { "poi_id":"469382092"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.nearbyPoi.delete
          需在 config.json 中配置 nearbyPoi.delete API 的权限,详情

          请求参数

          属性类型默认值必填说明
          poiIdstring附近地点 ID

          返回值

          deleteNearbyPoiResponse

          返回的 JSON 数据包

          错误

          错误码错误信息说明
          0ok正常
          47001POST数据json格式错误
          20002POST参数非法
          44002POST数据为空
          92000该经营资质已添加,请勿重复添加
          92002附近地点添加数量达到上线,无法继续添加
          92003地点已被其它小程序占用
          92004附近功能被封禁
          92005地点正在审核中
          92006地点正在展示小程序
          92007地点审核失败
          92008程序未展示在该地点
          93009小程序未上架或不可见
          93010地点不存在
          93011个人类型小程序不可用
          93011个人类型小程序不可用
          93012非普通类型小程序(门店小程序、小店小程序等)不可用
          93013从腾讯地图获取地址详细信息失败
          93014同一资质证件号重复添加


          nearbyPoi.getList

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          查看地点列表

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/wxa/getnearbypoilist?page=1&page_rows=20&access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          pagenumber起始页id(从1开始计数)
          page_rowsnumber每页展示个数(最多1000个)

          返回值

          Object

          属性类型说明
          errmsgstring错误信息
          errcodenumber错误码
          dataobject返回数据

          data 的结构

          属性类型说明
          left_apply_numnumber剩余可添加地点个数
          max_apply_numnumber最大可添加地点个数
          datastring地址列表的 JSON 格式字符串

          data.data 的结构

          属性类型说明
          poi_listArray.<Object>地址列表

          data.data.poi_list 的结构

          属性类型说明
          poi_idstring附近地点 ID
          qualification_addressstring资质证件地址
          qualification_numstring资质证件证件号
          audit_statusnumber地点审核状态
          display_statusnumber地点展示在附近状态
          refuse_reasonstring审核失败原因,audit_status=4 时返回

          audit_status 的合法值

          说明最低版本
          3审核中
          4审核失败
          5审核通过

          display_status 的合法值

          说明最低版本
          0未展示
          1展示中

          错误

          错误码错误信息说明
          0ok正常
          47001POST数据json格式错误
          20002POST参数非法
          44002POST数据为空
          92000该经营资质已添加,请勿重复添加
          92002附近地点添加数量达到上线,无法继续添加
          92003地点已被其它小程序占用
          92004附近功能被封禁
          92005地点正在审核中
          92006地点正在展示小程序
          92007地点审核失败
          92008程序未展示在该地点
          93009小程序未上架或不可见
          93010地点不存在
          93011个人类型小程序不可用
          93011个人类型小程序不可用
          93012非普通类型小程序(门店小程序、小店小程序等)不可用
          93013从腾讯地图获取地址详细信息失败
          93014同一资质证件号重复添加

          返回数据示例

          {   "errcode": 0,   "errmsg": "",   "data": {      "left_apply_num": 9,      "max_apply_num": 10,      "data": "{"poi_list": [{"poi_id": "123456","qualification_address": "广东省广州市海珠区新港中路123号","qualification_num": "123456789-1","audit_status": 3,"display_status": 0,"refuse_reason": ""}]}"   }}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.nearbyPoi.getList
          需在 config.json 中配置 nearbyPoi.getList API 的权限,详情

          请求参数

          属性类型默认值必填说明
          pagenumber起始页id(从1开始计数)
          pageRowsnumber每页展示个数(最多1000个)

          返回值

          Object

          属性类型说明
          errMsgstring错误信息
          errCodenumber错误码
          dataobject返回数据

          data 的结构

          属性类型说明
          leftApplyNumnumber剩余可添加地点个数
          maxApplyNumnumber最大可添加地点个数
          datastring地址列表的 JSON 格式字符串

          data.data 的结构

          属性类型说明
          poiListArray.<Object>地址列表

          data.data.poiList 的结构

          属性类型说明
          poiIdstring附近地点 ID
          qualificationAddressstring资质证件地址
          qualificationNumstring资质证件证件号
          auditStatusnumber地点审核状态
          displayStatusnumber地点展示在附近状态
          refuseReasonstring审核失败原因,audit_status=4 时返回

          auditStatus 的合法值

          说明最低版本
          3审核中
          4审核失败
          5审核通过

          displayStatus 的合法值

          说明最低版本
          0未展示
          1展示中

          异常

          Object

          抛出的异常

          属性类型说明
          errMsgstring错误信息
          errCodenumber错误码

          errCode 的合法值

          说明最低版本

          错误

          错误码错误信息说明
          0ok正常
          47001POST数据json格式错误
          20002POST参数非法
          44002POST数据为空
          92000该经营资质已添加,请勿重复添加
          92002附近地点添加数量达到上线,无法继续添加
          92003地点已被其它小程序占用
          92004附近功能被封禁
          92005地点正在审核中
          92006地点正在展示小程序
          92007地点审核失败
          92008程序未展示在该地点
          93009小程序未上架或不可见
          93010地点不存在
          93011个人类型小程序不可用
          93011个人类型小程序不可用
          93012非普通类型小程序(门店小程序、小店小程序等)不可用
          93013从腾讯地图获取地址详细信息失败
          93014同一资质证件号重复添加

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.nearbyPoi.getList({        page: '',        pageRows: ''      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "errCode": 0,  "errMsg": "openapi.nearbyPoi.getList:ok",  "data": {    "data": "{"poi_list": [{"poi_id": "123456","qualification_address": "广东省广州市海珠区新港中路123号","qualification_num": "123456789-1","audit_status": 3,"display_status": 0,"refuse_reason": ""}]}",    "leftApplyNum": 9,    "maxApplyNum": 10  }}


          nearbyPoi.setShowStatus

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          展示/取消展示附近小程序

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/setnearbypoishowstatus?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          poi_idstring附近地点 ID
          statusnumber是否展示

          status 的合法值

          说明最低版本
          0不展示
          1展示

          返回值

          Object

          返回的 JSON 数据

          属性类型说明
          errmsgstring错误信息
          errcodenumber错误码

          错误

          错误码错误信息说明
          0ok正常
          47001POST数据json格式错误
          20002POST参数非法
          44002POST数据为空
          92000该经营资质已添加,请勿重复添加
          92002附近地点添加数量达到上线,无法继续添加
          92003地点已被其它小程序占用
          92004附近功能被封禁
          92005地点正在审核中
          92006地点正在展示小程序
          92007地点审核失败
          92008程序未展示在该地点
          93009小程序未上架或不可见
          93010地点不存在
          93011个人类型小程序不可用
          93011个人类型小程序不可用
          93012非普通类型小程序(门店小程序、小店小程序等)不可用
          93013从腾讯地图获取地址详细信息失败
          93014同一资质证件号重复添加

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.nearbyPoi.setShowStatus
          需在 config.json 中配置 nearbyPoi.setShowStatus API 的权限,详情

          请求参数

          属性类型默认值必填说明
          poiIdstring附近地点 ID
          statusnumber是否展示

          status 的合法值

          说明最低版本
          0不展示
          1展示

          返回值

          Object

          返回的 JSON 数据

          属性类型说明
          errMsgstring错误信息
          errCodenumber错误码

          异常

          Object

          抛出的异常

          属性类型说明
          errMsgstring错误信息
          errCodenumber错误码

          errCode 的合法值

          说明最低版本

          错误

          错误码错误信息说明
          0ok正常
          47001POST数据json格式错误
          20002POST参数非法
          44002POST数据为空
          92000该经营资质已添加,请勿重复添加
          92002附近地点添加数量达到上线,无法继续添加
          92003地点已被其它小程序占用
          92004附近功能被封禁
          92005地点正在审核中
          92006地点正在展示小程序
          92007地点审核失败
          92008程序未展示在该地点
          93009小程序未上架或不可见
          93010地点不存在
          93011个人类型小程序不可用
          93011个人类型小程序不可用
          93012非普通类型小程序(门店小程序、小店小程序等)不可用
          93013从腾讯地图获取地址详细信息失败
          93014同一资质证件号重复添加


          wxacode.createQRCode

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取小程序二维码,适用于需要的码数量较少的业务场景。通过该接口生成的小程序码,永久有效,有数量限制,详见获取二维码

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/wxaapp/createwxaqrcode?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          pathstring扫码进入的小程序页面路径,最大长度 128 字节,不能为空;对于小游戏,可以只传入 query 部分,来实现传参效果,如:传入 "?foo=bar",即可在 wx.getLaunchOptionsSync 接口中的 query 参数获取到 {foo:"bar"}
          widthnumber430二维码的宽度,单位 px。最小 280px,最大 1280px

          返回值

          Buffer

          返回的图片 Buffer

          异常返回

          Object

          JSON

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          45029生成码个数总和到达最大个数限制

          返回值说明

          如果调用成功,会直接返回图片二进制内容,如果请求失败,会返回 JSON 格式的数据。

          注意

          • POST 参数需要转成 JSON 字符串,不支持 form 表单提交。
          • 接口只能生成已发布的小程序的二维码。开发版的带参二维码可以在开发者工具预览时生成。
          • 与 wxacode.get 总共生成的码数量限制为 100,000,请谨慎调用。

          示例

          请求

          { "path":"page/index/index", "width":430}

          返回

          { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.wxacode.createQRCode
          需在 config.json 中配置 wxacode.createQRCode API 的权限,详情

          请求参数

          属性类型默认值必填说明
          pathstring扫码进入的小程序页面路径,最大长度 128 字节,不能为空;对于小游戏,可以只传入 query 部分,来实现传参效果,如:传入 "?foo=bar",即可在 wx.getLaunchOptionsSync 接口中的 query 参数获取到 {foo:"bar"}
          widthnumber430二维码的宽度,单位 px。最小 280px,最大 1280px

          返回值

          Object

          包含二进制数据及其数据类型的对象

          属性类型说明
          contentTypeString数据类型 (MIME Type)
          bufferBuffer数据 Buffer

          异常

          Object

          JSON

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          示例

          请求

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.wxacode.createQRCode({        path: 'page/index/index',        width: 430      })    return result  } catch (err) {    return err  }}

          返回

          { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}


          wxacode.get

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取小程序码,适用于需要的码数量较少的业务场景。通过该接口生成的小程序码,永久有效,有数量限制,详见获取二维码

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/getwxacode?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          pathstring扫码进入的小程序页面路径,最大长度 128 字节,不能为空;对于小游戏,可以只传入 query 部分,来实现传参效果,如:传入 "?foo=bar",即可在 wx.getLaunchOptionsSync 接口中的 query 参数获取到 {foo:"bar"}
          widthnumber430二维码的宽度,单位 px。最小 280px,最大 1280px
          auto_colorbooleanfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调
          line_colorObject{"r":0,"g":0,"b":0}auto_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"} 十进制表示
          is_hyalinebooleanfalse是否需要透明底色,为 true 时,生成透明底色的小程序码

          返回值

          Buffer

          返回的图片 Buffer

          异常返回

          Object

          JSON

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          45029生成码个数总和到达最大个数限制

          返回值说明

          如果调用成功,会直接返回图片二进制内容,如果请求失败,会返回 JSON 格式的数据。

          注意

          • POST 参数需要转成 JSON 字符串,不支持 form 表单提交。
          • 接口只能生成已发布的小程序的二维码
          • 与 wxacode.createQRCode 总共生成的码数量限制为 100,000,请谨慎调用。

          示例

          请求

          { "path":"page/index/index", "width":430}

          返回

          { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.wxacode.get
          需在 config.json 中配置 wxacode.get API 的权限,详情

          请求参数

          属性类型默认值必填说明
          pathstring扫码进入的小程序页面路径,最大长度 128 字节,不能为空;对于小游戏,可以只传入 query 部分,来实现传参效果,如:传入 "?foo=bar",即可在 wx.getLaunchOptionsSync 接口中的 query 参数获取到 {foo:"bar"}
          widthnumber430二维码的宽度,单位 px。最小 280px,最大 1280px
          autoColorbooleanfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调
          lineColorObject{"r":0,"g":0,"b":0}auto_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"} 十进制表示
          isHyalinebooleanfalse是否需要透明底色,为 true 时,生成透明底色的小程序码

          返回值

          Object

          包含二进制数据及其数据类型的对象

          属性类型说明
          contentTypeString数据类型 (MIME Type)
          bufferBuffer数据 Buffer

          异常

          Object

          JSON

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          示例

          请求

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.wxacode.get({        path: 'page/index/index',        width: 430      })    return result  } catch (err) {    return err  }}

          返回

          { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}


          wxacode.getUnlimited

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取小程序码,适用于需要的码数量极多的业务场景。通过该接口生成的小程序码,永久有效,数量暂无限制。 更多用法详见 获取二维码

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址 

          POST https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          scenestring最大32个可见字符,只支持数字,大小写英文以及部分特殊字符:!#$&'()*+,/:;=?@-._~,其它字符请自行编码为合法字符(因不支持%,中文无法使用 urlencode 处理,请使用其他编码方式)
          pagestring主页必须是已经发布的小程序存在的页面(否则报错),例如 pages/index/index, 根路径前不要填加 /,不能携带参数(参数请放在scene字段里),如果不填写这个字段,默认跳主页面
          widthnumber430二维码的宽度,单位 px,最小 280px,最大 1280px
          auto_colorbooleanfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调,默认 false
          line_colorObject{"r":0,"g":0,"b":0}auto_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"} 十进制表示
          is_hyalinebooleanfalse是否需要透明底色,为 true 时,生成透明底色的小程序

          返回值

          Buffer

          返回的图片 Buffer

          异常返回

          Object

          JSON

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          45009调用分钟频率受限(目前5000次/分钟,会调整),如需大量小程序码,建议预生成。
          41030所传page页面不存在,或者小程序没有发布

          返回值说明

          如果调用成功,会直接返回图片二进制内容,如果请求失败,会返回 JSON 格式的数据。

          注意

          • POST 参数需要转成 JSON 字符串,不支持 form 表单提交。
          • 接口只能生成已发布的小程序的二维码
          • 调用分钟频率受限(5000次/分钟),如需大量小程序码,建议预生成

          获取 scene 值

          scene 字段的值会作为 query 参数传递给小程序/小游戏。用户扫描该码进入小程序/小游戏后,开发者可以获取到二维码中的 scene 值,再做处理逻辑。

          调试阶段可以使用开发工具的条件编译自定义参数 scene=xxxx 进行模拟,开发工具模拟时的 scene 的参数值需要进行 encodeURIComponent

          小程序

          Page({  onLoad (query) {    // scene 需要使用 decodeURIComponent 才能获取到生成二维码时传入的 scene    const scene = decodeURIComponent(query.scene)  }})

          小游戏

          // 在首次启动时通过 wx.getLaunchOptionsSync 接口获取const {query} = wx.getLaunchOptionsSync()const scene = decodeURIComponent(query.scene)// 或者在 wx.onShow 事件中获取wx.onShow(function ({query}) {  // scene 需要使用 decodeURIComponent 才能获取到生成二维码时传入的 scene  const scene = decodeURIComponent(query.scene)})

          示例

          请求

          { "scene": "a=1"}

          返回

          { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.wxacode.getUnlimited
          需在 config.json 中配置 wxacode.getUnlimited API 的权限,详情

          请求参数

          属性类型默认值必填说明
          scenestring最大32个可见字符,只支持数字,大小写英文以及部分特殊字符:!#$&'()*+,/:;=?@-._~,其它字符请自行编码为合法字符(因不支持%,中文无法使用 urlencode 处理,请使用其他编码方式)
          pagestring主页必须是已经发布的小程序存在的页面(否则报错),例如 pages/index/index, 根路径前不要填加 /,不能携带参数(参数请放在scene字段里),如果不填写这个字段,默认跳主页面
          widthnumber430二维码的宽度,单位 px,最小 280px,最大 1280px
          autoColorbooleanfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调,默认 false
          lineColorObject{"r":0,"g":0,"b":0}auto_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"} 十进制表示
          isHyalinebooleanfalse是否需要透明底色,为 true 时,生成透明底色的小程序

          返回值

          Object

          包含二进制数据及其数据类型的对象

          属性类型说明
          contentTypeString数据类型 (MIME Type)
          bufferBuffer数据 Buffer

          异常

          Object

          JSON

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          示例

          请求

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.wxacode.getUnlimited({        scene: 'a=1'      })    return result  } catch (err) {    return err  }}

          返回

          { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}


          security.imgSecCheck

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          校验一张图片是否含有违法违规内容。

          应用场景举例:

          1. 图片智能鉴黄:涉及拍照的工具类应用(如美拍,识图类应用)用户拍照上传检测;电商类商品上架图片检测;媒体类用户文章里的图片检测等;
          2. 敏感人脸识别:用户头像;媒体类用户文章里的图片检测;社交类用户上传的图片检测等。 频率限制:单个 appId 调用上限为 2000 次/分钟,200,000 次/天*(图片大小限制:1M) *服务市场:**通过服务市场使用可以有更多的能力,文档详情。

          调用方式:

          • HTTPS 调用
          • 云调用
          • 增量调用(加强版)

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/img_sec_check?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          mediaFormData要检测的图片文件,格式支持PNG、JPEG、JPG、GIF,图片尺寸不超过 750px x 1334px

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errMsgstring错误信息

          errcode 的合法值

          说明最低版本
          0内容正常
          87014内容含有违法违规内容

          errMsg 的合法值

          说明最低版本
          "ok"内容正常
          "risky content"内容含有违法违规内容

          调用示例

          curl -F media=@test.jpg 'https://api.weixin.qq.com/wxa/img_sec_check?access_token=ACCESS_TOKEN'

          调用过程中如遇到问题,可在珊瑚安全社区发帖交流。

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.security.imgSecCheck
          需在 config.json 中配置 security.imgSecCheck API 的权限,详情

          请求参数

          属性类型默认值必填说明
          mediaFormData媒体文件数据

          media 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          87014内容含有违法违规内容

          errMsg 的合法值

          说明最低版本
          "ok"内容正常
          "risky content"内容含有违法违规内容

          SDK 调用示例

          // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.security.imgSecCheck({  media: {    contentType: 'image/png',    value: Buffer  }})


          security.mediaCheckAsync

          本接口应在服务器端调用,详细说明参见服务端API

          异步校验图片/音频是否含有违法违规内容。

          应用场景举例:

          1. 语音风险识别:社交类用户发表的语音内容检测;
          2. 图片智能鉴黄:涉及拍照的工具类应用(如美拍,识图类应用)用户拍照上传检测;电商类商品上架图片检测;媒体类用户文章里的图片检测等;
          3. 敏感人脸识别:用户头像;媒体类用户文章里的图片检测;社交类用户上传的图片检测等。 频率限制:单个 appId 调用上限为 2000 次/分钟,200,000 次/天;文件大小限制:单个文件大小不超过10M

          请求地址

          POST https://api.weixin.qq.com/wxa/media_check_async?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          media_urlstring要检测的多媒体url
          media_typenumber1:音频;2:图片

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          trace_idstring任务id,用于匹配异步推送结果
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0检测请求已接收

          Object

          异步检测结果在 30 分钟内会推送到你的消息接收服务器。返回的 JSON 数据包

          属性类型说明
          ToUserNamestring小程序的username
          FromUserNamestring平台推送服务UserName
          CreateTimenumber发送时间
          MsgTypestring默认为:Event
          Eventstring默认为:wxa_media_check
          isriskynumber检测结果,0:暂未检测到风险,1:风险
          extra_info_jsonstring附加信息,默认为空
          appidstring小程序的appid
          trace_idstring任务id
          status_codenumber默认为:0,4294966288(-1008)为链接无法下载

          调用示例

          curl -d '{ "media_url":"https://developers.weixin.qq.com/miniprogram/assets/images/head_global_z_@all.png","media_type":2 }' 'https://api.weixin.qq.com/wxa/media_check_async?access_token=ACCESS_TOKEN'

          注意

          media_type 需要准确填写 url 对应的多媒体类型,media_url 需要保证可以被检测服务器下载

          接口返回示例

          {   "errcode"  : 0,   "errmsg"   : "ok",   "trace_id" : "967e945cd8a3e458f3c74dcb886068e9"}

          异步检测结果推送示例

          {   "ToUserName"      : "gh_38cc49f9733b",   "FromUserName"    : "oH1fu0FdHqpToe2T6gBj0WyB8iS1",   "CreateTime"      : 1552465698,   "MsgType"         : "event",   "Event"           : "wxa_media_check",   "isrisky"         : 0,   "extra_info_json" : "",   "appid"           : "wxd8c59133dfcbfc71",   "trace_id"        : "967e945cd8a3e458f3c74dcb886068e9",   "status_code"     : 0}

          调用过程中如遇到问题,可在珊瑚安全社区发帖交流。


          security.msgSecCheck

          本接口应在服务器端调用,详细说明参见服务端API。
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载),wx-server-sdk >= 0.4.0

          检查一段文本是否含有违法违规内容。

          应用场景举例:

          1. 用户个人资料违规文字检测;
          2. 媒体新闻类用户发表文章,评论内容检测;
          3. 游戏类用户编辑上传的素材(如答题类小游戏用户上传的问题及答案)检测等。 频率限制:单个 appId 调用上限为 4000 次/分钟,2,000,000 次/天* *服务市场:**通过服务市场使用可以有更多的能力,文档详情。

          调用方式:

          • HTTPS 调用
          • 云调用
          • 增量调用(加强版)

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/msg_sec_check?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          contentstring要检测的文本内容,长度不超过 500KB

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errMsgstring错误信息

          errcode 的合法值

          说明最低版本
          0内容正常
          87014内容含有违法违规内容

          errMsg 的合法值

          说明最低版本
          "ok"内容正常
          "riskycontent" 内容含有违法违规内容

          调用示例

          curl -d '{ "content":"hello world!" }' 'https://api.weixin.qq.com/wxa/msg_sec_check?access_token=ACCESS_TOKEN'

          测试用例

          特3456书yuuo莞6543李zxcz蒜7782法fgnv级完2347全dfji试3726测asad感3847知qwez到

          开发者可使用以上两段文本进行测试,若接口errcode返回87014(内容含有违法违规内容),则对接成功。

          调用过程中如遇到问题,可在珊瑚安全社区发帖交流。

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.security.msgSecCheck
          需在 config.json 中配置 security.msgSecCheck API 的权限,详情

          请求参数

          属性类型默认值必填说明
          contentstring要检测的文本内容,长度不超过 500KB

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          87014内容含有违法违规内容

          errMsg 的合法值

          说明最低版本
          "ok"内容正常
          "riskycontent" 内容含有违法违规内容


          logistics.batchGetOrder

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          批量获取运单数据

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/business/order/batchget?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          order_listArray.<Object>订单列表, 最多不能超过100个

          order_list 的结构

          属性类型默认值必填说明
          order_idstring订单ID
          delivery_idstring快递公司ID,参见getAllDelivery
          waybill_idstring运单ID

          返回值

          Object

          属性类型说明
          order_listArray.<Object>运单列表
          order_statusnumber运单状态, 0正常,1取消

          order_list 的结构

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          order_idstring订单ID
          delivery_idstring快递公司ID,参见getAllDelivery
          waybill_idstring运单ID
          print_htmlstring运单 html 的 BASE64 结果
          waybill_dataArray.<Object>运单信息

          order_list.waybill_data 的结构

          属性类型说明
          keystring运单信息 key
          valuestring运单信息 value

          请求数据示例

          {   "order_list": [       {          "order_id": "01234567890123456789",          "delivery_id": "SF",          "waybill_id": "123456789"       },       {          "order_id": "01234567890123456789",          "delivery_id": "SF",          "waybill_id": "123456789"       }   ]}

          返回数据示例

          {   "order_list": [       {          "errcode": 0,          "errmsg": "ok",          "order_id": "01234567890123456789",          "delivery_id": "SF",          "waybill_id": "123456789",          "print_html": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",          "waybill_data": [               {                   "key": "SF_bagAddr",                   "value": "广州"               },               {                  "key": "SF_mark",                  "value": "101- 07-03 509"               }           ],           "order_status": 0       },       {          "errcode": 0,          "errmsg": "ok",          "order_id": "01234567890123456789_2",          "delivery_id": "SF",          "waybill_id": "123456789_2",          "print_html": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",          "waybill_data": [               {                   "key": "SF_bagAddr",                   "value": "广州"               },               {                  "key": "SF_mark",                  "value": "101- 07-03 509"               }           ],           "order_status": 0       }   ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.batchGetOrder
          需在 config.json 中配置 logistics.batchGetOrder API 的权限,详情

          请求参数

          属性类型默认值必填说明
          orderListArray.<Object>订单列表, 最多不能超过100个

          orderList 的结构

          属性类型默认值必填说明
          orderIdstring订单ID
          deliveryIdstring快递公司ID,参见getAllDelivery
          waybillIdstring运单ID

          返回值

          Object

          属性类型说明
          orderListArray.<Object>运单列表
          orderStatusnumber运单状态, 0正常,1取消

          orderList 的结构

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          orderIdstring订单ID
          deliveryIdstring快递公司ID,参见getAllDelivery
          waybillIdstring运单ID
          printHtmlstring运单 html 的 BASE64 结果
          waybillDataArray.<Object>运单信息

          orderList.waybillData 的结构

          属性类型说明
          keystring运单信息 key
          valuestring运单信息 value

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.batchGetOrder({        orderList: [          {            orderId: '01234567890123456789',            deliveryId: 'SF',            waybillId: '123456789'          },          {            orderId: '01234567890123456789',            deliveryId: 'SF',            waybillId: '123456789'          }        ]      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "orderList": [    {      "errcode": 0,      "errmsg": "ok",      "orderId": "01234567890123456789",      "deliveryId": "SF",      "waybillId": "123456789",      "printHtml": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",      "waybillData": [        {          "key": "SF_bagAddr",          "value": "广州"        },        {          "key": "SF_mark",          "value": "101- 07-03 509"        }      ],      "orderStatus": 0    },    {      "errcode": 0,      "errmsg": "ok",      "orderId": "01234567890123456789_2",      "deliveryId": "SF",      "waybillId": "123456789_2",      "printHtml": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",      "waybillData": [        {          "key": "SF_bagAddr",          "value": "广州"        },        {          "key": "SF_mark",          "value": "101- 07-03 509"        }      ],      "orderStatus": 0    }  ],  "errMsg": "openapi.logistics.batchGetOrder:ok"}


          logistics.addOrder

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          生成运单

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/business/order/add?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          add_sourcenumber订单来源,0为小程序订单,2为App或H5订单,填2则不发送物流服务通知
          wx_appidstringApp或H5的appid,add_source=2时必填,需和开通了物流助手的小程序绑定同一open帐号
          order_idstring订单ID,须保证全局唯一,不超过512字节
          openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
          delivery_idstring快递公司ID,参见getAllDelivery
          biz_idstring快递客户编码或者现付编码
          custom_remarkstring快递备注信息,比如"易碎物品",不超过1024字节
          tagidnumber订单标签id,用于平台型小程序区分平台上的入驻方,tagid须与入驻方账号一一对应,非平台型小程序无需填写该字段
          senderObject发件人信息
          receiverObject收件人信息
          cargoObject包裹信息,将传递给快递公司
          shopObject商品信息,会展示到物流服务通知和电子面单中
          insuredObject保价信息
          serviceObject服务类型
          expect_timenumberUnix 时间戳, 单位秒,顺丰必须传。 预期的上门揽件时间,0表示已事先约定取件时间;否则请传预期揽件时间戳,需大于当前时间,收件员会在预期时间附近上门。例如expect_time为“1557989929”,表示希望收件员将在2019年05月16日14:58:49-15:58:49内上门取货。说明:若选择 了预期揽件时间,请不要自己打单,由上门揽件的时候打印。如果是下顺丰散单,则必传此字段,否则不会有收件员上门揽件。

          sender 的结构

          属性类型默认值必填说明
          namestring发件人姓名,不超过64字节
          telstring发件人座机号码,若不填写则必须填写 mobile,不超过32字节
          mobilestring发件人手机号码,若不填写则必须填写 tel,不超过32字节
          companystring发件人公司名称,不超过64字节
          post_codestring发件人邮编,不超过10字节
          countrystring发件人国家,不超过64字节
          provincestring发件人省份,比如:"广东省",不超过64字节
          citystring发件人市/地区,比如:"广州市",不超过64字节
          areastring发件人区/县,比如:"海珠区",不超过64字节
          addressstring发件人详细地址,比如:"XX路XX号XX大厦XX",不超过512字节

          receiver 的结构

          属性类型默认值必填说明
          namestring收件人姓名,不超过64字节
          telstring收件人座机号码,若不填写则必须填写 mobile,不超过32字节
          mobilestring收件人手机号码,若不填写则必须填写 tel,不超过32字节
          companystring收件人公司名,不超过64字节
          post_codestring收件人邮编,不超过10字节
          countrystring收件人所在国家,不超过64字节
          provincestring收件人省份,比如:"广东省",不超过64字节
          citystring收件人地区/市,比如:"广州市",不超过64字节
          areastring收件人区/县,比如:"天河区",不超过64字节
          addressstring收件人详细地址,比如:"XX路XX号XX大厦XX",不超过512字节

          cargo 的结构

          属性类型默认值必填说明
          countnumber包裹数量, 需要和detail_list size保持一致
          weightnumber包裹总重量,单位是千克(kg)
          space_xnumber包裹长度,单位厘米(cm)
          space_ynumber包裹宽度,单位厘米(cm)
          space_znumber包裹高度,单位厘米(cm)
          detail_listArray.<Object>包裹中商品详情列表

          cargo.detail_list 的结构

          属性类型默认值必填说明
          namestring商品名,不超过128字节
          countnumber商品数量

          shop 的结构

          属性类型默认值必填说明
          wxa_pathstring商家小程序的路径,建议为订单页面
          img_urlstring商品缩略图 url
          goods_namestring商品名称, 不超过128字节
          goods_countnumber商品数量

          insured 的结构

          属性类型默认值必填说明
          use_insurednumber是否保价,0 表示不保价,1 表示保价
          insured_valuenumber保价金额,单位是分,比如: 10000 表示 100 元

          service 的结构

          属性类型默认值必填说明
          service_typenumber服务类型ID,详见已经支持的快递公司基本信息
          service_namestring服务名称,详见已经支持的快递公司基本信息

          返回值

          Object

          属性类型说明
          order_idstring订单ID,下单成功时返回
          waybill_idstring运单ID,下单成功时返回
          waybill_dataArray.<Object>运单信息,下单成功时返回
          errcodenumber微信侧错误码,下单失败时返回
          errmsgstring微信侧错误信息,下单失败时返回
          delivery_resultcodenumber快递侧错误码,下单失败时返回
          delivery_resultmsgstring快递侧错误信息,下单失败时返回

          waybill_data 的结构

          属性类型说明
          keystring运单信息 key
          valuestring运单信息 value

          errcode 的合法值

          说明最低版本
          -1系统失败
          47001格式错误
          40003openid无效
          9300502快递公司系统错误
          9300501快递侧逻辑错误,详细原因需要看 delivery_resultcode, 请先确认一下编码方式,python建议 json.dumps(b, ensure_ascii=False),php建议 json_encode($arr, JSON_UNESCAPED_UNICODE)
          9300503delivery_id 不存在
          9300510service_type 不存在
          9300526字段长度不正确
          930561参数错误
          9300525bizid未绑定
          9300534add_source=2时,wx_appid和当前小程序不同主体
          9300535shop字段商品缩略图 url、商品名称为空或者非法,或者商品数量为0
          9300536add_source=2时,wx_appid无效
          9300531bizid无效
          930564沙盒环境调用无配额
          930559沙盒环境openid无效

          请求示例

          {  "add_source": 0,  "order_id": "01234567890123456789",  "openid": "oABC123456",  "delivery_id": "SF",  "biz_id": "xyz",  "custom_remark": "易碎物品",  "sender": {    "name": "张三",    "tel": "020-88888888",    "mobile": "18666666666",    "company": "公司名",    "post_code": "123456",    "country": "中国",    "province": "广东省",    "city": "广州市",    "area": "海珠区",    "address": "XX路XX号XX大厦XX栋XX"  },  "receiver": {    "name": "王小蒙",    "tel": "020-77777777",    "mobile": "18610000000",    "company": "公司名",    "post_code": "654321",    "country": "中国",    "province": "广东省",    "city": "广州市",    "area": "天河区",    "address": "XX路XX号XX大厦XX栋XX"  },  "shop": {    "wxa_path": "/index/index?from=waybill&id=01234567890123456789",    "img_url": "https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640",    "goods_name": "微信气泡狗抱枕&微信气泡狗钥匙扣",    "goods_count": 2  },  "cargo": {    "count": 2,    "weight": 5.5,    "space_x": 30.5,    "space_y": 20,    "space_z": 20,    "detail_list": [      {        "name": "微信气泡狗抱枕",        "count": 1      },      {        "name": "微信气泡狗钥匙扣",        "count": 1      }    ]  },  "insured": {    "use_insured": 1,    "insured_value": 10000  },  "service": {    "service_type": 0,    "service_name": "标准快递"  }}

          返回示例

          下单成功

          {  "order_id": "01234567890123456789",  "waybill_id": "123456789",  "waybill_data": [    {      "key": "SF_bagAddr",      "value": "广州"    },    {      "key": "SF_mark",      "value": "101- 07-03 509"    }  ]}

          下单失败

          {  "errcode": 9300501,  "errmsg": "delivery logic fail",  "delivery_resultcode": 10002,  "delivery_resultmsg": "客户密码不正确"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.addOrder
          需在 config.json 中配置 logistics.addOrder API 的权限,详情

          请求参数

          属性类型默认值必填说明
          addSourcenumber订单来源,0为小程序订单,2为App或H5订单,填2则不发送物流服务通知
          wxAppidstringApp或H5的appid,add_source=2时必填,需和开通了物流助手的小程序绑定同一open帐号
          orderIdstring订单ID,须保证全局唯一,不超过512字节
          openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
          deliveryIdstring快递公司ID,参见getAllDelivery
          bizIdstring快递客户编码或者现付编码
          customRemarkstring快递备注信息,比如"易碎物品",不超过1024字节
          tagidnumber订单标签id,用于平台型小程序区分平台上的入驻方,tagid须与入驻方账号一一对应,非平台型小程序无需填写该字段
          senderObject发件人信息
          receiverObject收件人信息
          cargoObject包裹信息,将传递给快递公司
          shopObject商品信息,会展示到物流服务通知和电子面单中
          insuredObject保价信息
          serviceObject服务类型
          expectTimenumberUnix 时间戳, 单位秒,顺丰必须传。 预期的上门揽件时间,0表示已事先约定取件时间;否则请传预期揽件时间戳,需大于当前时间,收件员会在预期时间附近上门。例如expect_time为“1557989929”,表示希望收件员将在2019年05月16日14:58:49-15:58:49内上门取货。说明:若选择 了预期揽件时间,请不要自己打单,由上门揽件的时候打印。如果是下顺丰散单,则必传此字段,否则不会有收件员上门揽件。

          sender 的结构

          属性类型默认值必填说明
          namestring发件人姓名,不超过64字节
          telstring发件人座机号码,若不填写则必须填写 mobile,不超过32字节
          mobilestring发件人手机号码,若不填写则必须填写 tel,不超过32字节
          companystring发件人公司名称,不超过64字节
          postCodestring发件人邮编,不超过10字节
          countrystring发件人国家,不超过64字节
          provincestring发件人省份,比如:"广东省",不超过64字节
          citystring发件人市/地区,比如:"广州市",不超过64字节
          areastring发件人区/县,比如:"海珠区",不超过64字节
          addressstring发件人详细地址,比如:"XX路XX号XX大厦XX",不超过512字节

          receiver 的结构

          属性类型默认值必填说明
          namestring收件人姓名,不超过64字节
          telstring收件人座机号码,若不填写则必须填写 mobile,不超过32字节
          mobilestring收件人手机号码,若不填写则必须填写 tel,不超过32字节
          companystring收件人公司名,不超过64字节
          postCodestring收件人邮编,不超过10字节
          countrystring收件人所在国家,不超过64字节
          provincestring收件人省份,比如:"广东省",不超过64字节
          citystring收件人地区/市,比如:"广州市",不超过64字节
          areastring收件人区/县,比如:"天河区",不超过64字节
          addressstring收件人详细地址,比如:"XX路XX号XX大厦XX",不超过512字节

          cargo 的结构

          属性类型默认值必填说明
          countnumber包裹数量, 需要和detail_list size保持一致
          weightnumber包裹总重量,单位是千克(kg)
          spaceXnumber包裹长度,单位厘米(cm)
          spaceYnumber包裹宽度,单位厘米(cm)
          spaceZnumber包裹高度,单位厘米(cm)
          detailListArray.<Object>包裹中商品详情列表

          cargo.detailList 的结构

          属性类型默认值必填说明
          namestring商品名,不超过128字节
          countnumber商品数量

          shop 的结构

          属性类型默认值必填说明
          wxaPathstring商家小程序的路径,建议为订单页面
          imgUrlstring商品缩略图 url
          goodsNamestring商品名称, 不超过128字节
          goodsCountnumber商品数量

          insured 的结构

          属性类型默认值必填说明
          useInsurednumber是否保价,0 表示不保价,1 表示保价
          insuredValuenumber保价金额,单位是分,比如: 10000 表示 100 元

          service 的结构

          属性类型默认值必填说明
          serviceTypenumber服务类型ID,详见已经支持的快递公司基本信息
          serviceNamestring服务名称,详见已经支持的快递公司基本信息

          返回值

          Object

          属性类型说明
          orderIdstring订单ID,下单成功时返回
          waybillIdstring运单ID,下单成功时返回
          waybillDataArray.<Object>运单信息,下单成功时返回
          errCodenumber微信侧错误码,下单失败时返回
          errMsgstring微信侧错误信息,下单失败时返回
          deliveryResultcodenumber快递侧错误码,下单失败时返回
          deliveryResultmsgstring快递侧错误信息,下单失败时返回

          waybillData 的结构

          属性类型说明
          keystring运单信息 key
          valuestring运单信息 value

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber微信侧错误码,下单失败时返回
          errMsgstring微信侧错误信息,下单失败时返回

          errCode 的合法值

          说明最低版本
          -1系统失败
          47001格式错误
          40003openid无效
          9300502快递公司系统错误
          9300501快递侧逻辑错误,详细原因需要看 delivery_resultcode, 请先确认一下编码方式,python建议 json.dumps(b, ensure_ascii=False),php建议 json_encode($arr, JSON_UNESCAPED_UNICODE)
          9300503delivery_id 不存在
          9300510service_type 不存在
          9300526字段长度不正确
          930561参数错误
          9300525bizid未绑定
          9300534add_source=2时,wx_appid和当前小程序不同主体
          9300535shop字段商品缩略图 url、商品名称为空或者非法,或者商品数量为0
          9300536add_source=2时,wx_appid无效
          9300531bizid无效
          930564沙盒环境调用无配额
          930559沙盒环境openid无效

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.addOrder({        openid: 'oABC123456',        sender: {          name: '张三',          tel: '020-88888888',          mobile: '18666666666',          company: '公司名',          country: '中国',          province: '广东省',          city: '广州市',          area: '海珠区',          address: 'XX路XX号XX大厦XX栋XX',          postCode: '123456'        },        receiver: {          name: '王小蒙',          tel: '020-77777777',          mobile: '18610000000',          company: '公司名',          country: '中国',          province: '广东省',          city: '广州市',          area: '天河区',          address: 'XX路XX号XX大厦XX栋XX',          postCode: '654321'        },        shop: {          wxaPath: '/index/index?from=waybill&id=01234567890123456789',          imgUrl: 'https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640',          goodsName: '微信气泡狗抱枕&微信气泡狗钥匙扣',          goodsCount: 2        },        cargo: {          count: 2,          weight: 5.5,          spaceX: 30.5,          spaceY: 20,          spaceZ: 20,          detailList: [            {              name: '微信气泡狗抱枕',              count: 1            },            {              name: '微信气泡狗钥匙扣',              count: 1            }          ]        },        insured: {          useInsured: 1,          insuredValue: 10000        },        service: {          serviceType: 0,          serviceName: '标准快递'        },        addSource: 0,        orderId: '01234567890123456789',        deliveryId: 'SF',        bizId: 'xyz',        customRemark: '易碎物品'      })    return result  } catch (err) {    return err  }}

          返回示例

          下单成功

          {  "orderId": "01234567890123456789",  "waybillId": "123456789",  "waybillData": [    {      "key": "SF_bagAddr",      "value": "广州"    },    {      "key": "SF_mark",      "value": "101- 07-03 509"    }  ],  "errMsg": "openapi.logistics.addOrder:ok"}

          下单失败

          {  "errCode": 9300501,  "errMsg": "openapi.logistics.addOrder:fail delivery logic fail",  "deliveryResultcode": 10002,  "deliveryResultmsg": "客户密码不正确"}


          logistics.bindAccount

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          绑定、解绑物流账号

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/business/account/bind?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          typestringbind表示绑定,unbind表示解除绑定
          biz_idstring快递公司客户编码
          delivery_idstring快递公司ID
          passwordstring快递公司客户密码, ems,顺丰,京东非必填
          remark_contentstring备注内容(提交EMS审核需要)

          返回值

          Object

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0成功
          -1系统失败
          9300529账号已绑定过
          9300530解绑的biz_id不存在
          9300531账号或密码错误
          9300532绑定已提交,审核中

          请求数据示例

          {  "type": "bind",  "biz_id": "123456",  "delivery_id": "YUNDA",  "password": "123456789123456789"}

          返回数据示例

          {  "errcode": 0,  "errmsg": "ok"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.bindAccount
          需在 config.json 中配置 logistics.bindAccount API 的权限,详情

          请求参数

          属性类型默认值必填说明
          typestringbind表示绑定,unbind表示解除绑定
          bizIdstring快递公司客户编码
          deliveryIdstring快递公司ID
          passwordstring快递公司客户密码, ems,顺丰,京东非必填
          remarkContentstring备注内容(提交EMS审核需要)

          返回值

          Object

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          -1系统失败
          9300529账号已绑定过
          9300530解绑的biz_id不存在
          9300531账号或密码错误
          9300532绑定已提交,审核中

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.bindAccount({        type: 'bind',        password: '123456789123456789',        bizId: '123456',        deliveryId: 'YUNDA'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "errCode": 0,  "errMsg": "openapi.logistics.bindAccount:ok"}


          logistics.cancelOrder

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载)
          wx-server-sdk >= 0.4.0

          取消运单

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/business/order/cancel?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          order_idstring订单 ID,需保证全局唯一
          openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
          delivery_idstring快递公司ID,参见getAllDelivery
          waybill_idstring运单ID

          返回值

          Object

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          delivery_resultcodenumber运力返回的错误码
          delivery_resultmsgstring运力返回的错误信息

          errcode 的合法值

          说明最低版本
          0成功
          -1系统失败
          40199运单 ID 不存在
          9300503delivery_id不存在
          930563订单不存在
          930561参数错误
          9300506运单 ID 已经存在轨迹,不可取消
          9300524取消订单失败(一般为重复取消订单)
          9300501快递公司逻辑错误,具体错误码见delivery_resultcode

          请求示例

          {  "order_id": "01234567890123456789",  "openid": "oABC123456",  "delivery_id": "SF",  "waybill_id": "123456789"}

          返回示例

          {  "errcode": 0,  "errmsg": "ok",  "delivery_resultcode": 0,  "delivery_resultmsg": ""}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.cancelOrder
          需在 config.json 中配置 logistics.cancelOrder API 的权限,详情

          请求参数

          属性类型默认值必填说明
          orderIdstring订单 ID,需保证全局唯一
          openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
          deliveryIdstring快递公司ID,参见getAllDelivery
          waybillIdstring运单ID

          返回值

          Object

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息
          deliveryResultcodenumber运力返回的错误码
          deliveryResultmsgstring运力返回的错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          -1系统失败
          40199运单 ID 不存在
          9300503delivery_id不存在
          930563订单不存在
          930561参数错误
          9300506运单 ID 已经存在轨迹,不可取消
          9300524取消订单失败(一般为重复取消订单)
          9300501快递公司逻辑错误,具体错误码见delivery_resultcode

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.cancelOrder({        openid: 'oABC123456',        orderId: '01234567890123456789',        deliveryId: 'SF',        waybillId: '123456789'      })    return result  } catch (err) {    return err  }}

          返回示例

          {  "errCode": 0,  "errMsg": "openapi.logistics.cancelOrder:ok",  "deliveryResultcode": 0,  "deliveryResultmsg": ""}


          logistics.getAllAccount

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取所有绑定的物流账号

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/cgi-bin/express/business/account/getall?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回值

          Object

          属性类型说明
          errcodenumber错误码
          errmsgnumber错误信息
          countnumber账号数量
          listArray.<Object>账号列表

          errcode 的合法值

          说明最低版本
          0成功
          -1系统失败

          list 的结构

          属性类型说明
          biz_idstring快递公司客户编码
          delivery_idstring快递公司ID
          create_timenumber账号绑定时间
          update_timenumber账号更新时间
          status_codenumber绑定状态
          aliasstring账号别名
          remark_wrong_msgstring账号绑定失败的错误信息(EMS审核结果)
          remark_contentstring账号绑定时的备注内容(提交EMS审核需要)
          quota_numnumber电子面单余额
          quota_update_timenumber电子面单余额更新时间
          service_typeArray.<Object>该绑定帐号支持的服务类型

          list.status_code 的合法值

          说明最低版本
          0绑定成功
          1审核中
          2绑定失败
          3已解绑

          list.service_type 的结构

          属性类型说明
          service_typenumber服务类型ID
          service_namestring服务类型名称

          返回数据示例

          {       "count": 1,       "list": [           {               "biz_id": "123456789",               "delivery_id": "YUNDA",               "create_time": 1555482786,               "update_time": 1556594799,               "status_code": 0,               "alias": "",               "remark_wrong_msg": "",               "remark_content": "",               "quota_num": 55,               "quota_update_time": 1556594799           }       ]   }

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.getAllAccount
          需在 config.json 中配置 logistics.getAllAccount API 的权限,详情

          返回值

          Object

          属性类型说明
          errCodenumber错误码
          errMsgnumber错误信息
          countnumber账号数量
          listArray.<Object>账号列表

          errCode 的合法值

          说明最低版本
          0成功

          list 的结构

          属性类型说明
          bizIdstring快递公司客户编码
          deliveryIdstring快递公司ID
          createTimenumber账号绑定时间
          updateTimenumber账号更新时间
          statusCodenumber绑定状态
          aliasstring账号别名
          remarkWrongMsgstring账号绑定失败的错误信息(EMS审核结果)
          remarkContentstring账号绑定时的备注内容(提交EMS审核需要)
          quotaNumnumber电子面单余额
          quotaUpdateTimenumber电子面单余额更新时间
          serviceTypeArray.<Object>该绑定帐号支持的服务类型

          list.statusCode 的合法值

          说明最低版本
          0绑定成功
          1审核中
          2绑定失败
          3已解绑

          list.serviceType 的结构

          属性类型说明
          serviceTypenumber服务类型ID
          serviceNamestring服务类型名称

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgnumber错误信息

          errCode 的合法值

          说明最低版本
          -1系统失败

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getAllAccount({})    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "count": 1,  "list": [    {      "alias": "",      "bizId": "123456789",      "deliveryId": "YUNDA",      "createTime": 1555482786,      "updateTime": 1556594799,      "statusCode": 0,      "remarkWrongMsg": "",      "remarkContent": "",      "quotaNum": 55,      "quotaUpdateTime": 1556594799    }  ],  "errMsg": "openapi.logistics.getAllAccount:ok"}


          logistics.getAllDelivery

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取支持的快递公司列表

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/cgi-bin/express/business/delivery/getall?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回值

          Object

          属性类型说明
          countnumber快递公司数量
          dataArray.<Object>快递公司信息列表

          data 的结构

          属性类型说明
          delivery_idstring快递公司 ID
          delivery_namestring快递公司名称
          can_use_cashnumber是否支持散单, 1表示支持
          can_get_quotanumber是否支持查询面单余额, 1表示支持
          cash_biz_idstring散单对应的bizid,当can_use_cash=1时有效
          service_typeArray.<Object>支持的服务类型

          data.service_type 的结构

          属性类型说明
          service_typenumber服务类型ID
          service_namestring服务类型名称

          返回数据示例

          {  "count": 7,  "data": [    {      "delivery_id": "BEST",      "delivery_name": "百世快递"    },    {      "delivery_id": "EMS",      "delivery_name": "中国邮政速递物流"    },    {      "delivery_id": "PJ",      "delivery_name": "品骏物流"    },    {      "delivery_id": "SF",      "delivery_name": "顺丰速运"    },    {      "delivery_id": "YTO",      "delivery_name": "圆通速递"    },    {      "delivery_id": "YUNDA",      "delivery_name": "韵达快递"    },    {      "delivery_id": "ZTO",      "delivery_name": "中通快递"    }  ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.getAllDelivery
          需在 config.json 中配置 logistics.getAllDelivery API 的权限,详情

          返回值

          Object

          属性类型说明
          countnumber快递公司数量
          dataArray.<Object>快递公司信息列表

          data 的结构

          属性类型说明
          deliveryIdstring快递公司 ID
          deliveryNamestring快递公司名称
          canUseCashnumber是否支持散单, 1表示支持
          canGetQuotanumber是否支持查询面单余额, 1表示支持
          cashBizIdstring散单对应的bizid,当can_use_cash=1时有效
          serviceTypeArray.<Object>支持的服务类型

          data.serviceType 的结构

          属性类型说明
          serviceTypenumber服务类型ID
          serviceNamestring服务类型名称

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getAllDelivery({})    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "count": 7,  "data": [    {      "deliveryId": "BEST",      "deliveryName": "百世快递"    },    {      "deliveryId": "EMS",      "deliveryName": "中国邮政速递物流"    },    {      "deliveryId": "PJ",      "deliveryName": "品骏物流"    },    {      "deliveryId": "SF",      "deliveryName": "顺丰速运"    },    {      "deliveryId": "YTO",      "deliveryName": "圆通速递"    },    {      "deliveryId": "YUNDA",      "deliveryName": "韵达快递"    },    {      "deliveryId": "ZTO",      "deliveryName": "中通快递"    }  ],  "errMsg": "openapi.logistics.getAllDelivery:ok"}


          logistics.getOrder

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取运单数据

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/business/order/get?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          order_idstring订单 ID,需保证全局唯一
          openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
          delivery_idstring快递公司ID,参见getAllDelivery, 必须和waybill_id对应
          waybill_idstring运单ID

          返回值

          Object

          属性类型说明
          print_htmlstring运单 html 的 BASE64 结果
          waybill_dataArray.<Object>运单信息
          delivery_idstring快递公司ID
          order_idstring订单ID
          waybill_idstring运单号
          order_statusnumber运单状态, 0正常,1取消

          waybill_data 的结构

          属性类型说明
          keystring运单信息 key
          valuestring运单信息 value

          请求数据示例

          {  "order_id": "01234567890123456789",  "openid": "oABC123456",  "delivery_id": "SF",  "waybill_id": "123456789"}

          返回数据示例

          {  "print_html": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",  "waybill_data": [    {      "key": "SF_bagAddr",      "value": "广州"    },    {      "key": "SF_mark",      "value": "101- 07-03 509"    }  ],  "delivery_id": "SF",  "waybill_id": "123456",  "order_id": "123456",  "order_status": 0}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.getOrder
          需在 config.json 中配置 logistics.getOrder API 的权限,详情

          请求参数

          属性类型默认值必填说明
          orderIdstring订单 ID,需保证全局唯一
          openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
          deliveryIdstring快递公司ID,参见getAllDelivery, 必须和waybill_id对应
          waybillIdstring运单ID

          返回值

          Object

          属性类型说明
          printHtmlstring运单 html 的 BASE64 结果
          waybillDataArray.<Object>运单信息
          deliveryIdstring快递公司ID
          orderIdstring订单ID
          waybillIdstring运单号
          orderStatusnumber运单状态, 0正常,1取消

          waybillData 的结构

          属性类型说明
          keystring运单信息 key
          valuestring运单信息 value

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getOrder({        openid: 'oABC123456',        orderId: '01234567890123456789',        deliveryId: 'SF',        waybillId: '123456789'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "printHtml": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",  "waybillData": [    {      "key": "SF_bagAddr",      "value": "广州"    },    {      "key": "SF_mark",      "value": "101- 07-03 509"    }  ],  "deliveryId": "SF",  "waybillId": "123456",  "orderId": "123456",  "orderStatus": 0,  "errMsg": "openapi.logistics.getOrder:ok"}


          logistics.getPath

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          查询运单轨迹

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/business/path/get?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          order_idstring订单 ID,需保证全局唯一
          openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
          delivery_idstring快递公司ID,参见getAllDelivery
          waybill_idstring运单ID

          返回值

          Object

          属性类型说明
          openidstring用户openid
          delivery_idstring快递公司 ID
          waybill_idstring运单 ID
          path_item_numnumber轨迹节点数量
          path_item_listArray.<Object>轨迹节点列表

          path_item_list 的结构

          属性类型说明
          action_timenumber轨迹节点 Unix 时间戳
          action_typenumber轨迹节点类型
          action_msgstring轨迹节点详情

          action_type 的合法值

          说明最低版本
          100001揽件阶段-揽件成功
          100002揽件阶段-揽件失败
          100003揽件阶段-分配业务员
          200001运输阶段-更新运输轨迹
          300002派送阶段-开始派送
          300003派送阶段-签收成功
          300004派送阶段-签收失败
          400001异常阶段-订单取消
          400002异常阶段-订单滞留

          请求数据示例

          {  "order_id": "01234567890123456789",  "openid": "oABC123456",  "delivery_id": "SF",  "waybill_id": "123456789"}

          返回数据示例

          {  "openid": "OPENID",  "delivery_id": "SF",  "waybill_id": "12345678901234567890",  "path_item_num": 3,  "path_item_list": [    {      "action_time": 1533052800,      "action_type": 100001,      "action_msg": "快递员已成功取件"    },    {      "action_time": 1533062800,      "action_type": 200001,      "action_msg": "快件已到达xxx集散中心,准备发往xxx"    },    {      "action_time": 1533072800,      "action_type": 300001,      "action_msg": "快递员已出发,联系电话xxxxxx"    }  ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.getPath
          需在 config.json 中配置 logistics.getPath API 的权限,详情

          请求参数

          属性类型默认值必填说明
          orderIdstring订单 ID,需保证全局唯一
          openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
          deliveryIdstring快递公司ID,参见getAllDelivery
          waybillIdstring运单ID

          返回值

          Object

          属性类型说明
          openidstring用户openid
          deliveryIdstring快递公司 ID
          waybillIdstring运单 ID
          pathItemNumnumber轨迹节点数量
          pathItemListArray.<Object>轨迹节点列表

          pathItemList 的结构

          属性类型说明
          actionTimenumber轨迹节点 Unix 时间戳
          actionTypenumber轨迹节点类型
          actionMsgstring轨迹节点详情

          actionType 的合法值

          说明最低版本
          100001揽件阶段-揽件成功
          100002揽件阶段-揽件失败
          100003揽件阶段-分配业务员
          200001运输阶段-更新运输轨迹
          300002派送阶段-开始派送
          300003派送阶段-签收成功
          300004派送阶段-签收失败
          400001异常阶段-订单取消
          400002异常阶段-订单滞留

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getPath({        openid: 'oABC123456',        orderId: '01234567890123456789',        deliveryId: 'SF',        waybillId: '123456789'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "openid": "OPENID",  "deliveryId": "SF",  "waybillId": "12345678901234567890",  "pathItemNum": 3,  "pathItemList": [    {      "actionTime": 1533052800,      "actionType": 100001,      "actionMsg": "快递员已成功取件"    },    {      "actionTime": 1533062800,      "actionType": 200001,      "actionMsg": "快件已到达xxx集散中心,准备发往xxx"    },    {      "actionTime": 1533072800,      "actionType": 300001,      "actionMsg": "快递员已出发,联系电话xxxxxx"    }  ],  "errMsg": "openapi.logistics.getPath:ok"}


          logistics.getPrinter

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取打印员。若需要使用微信打单 PC 软件,才需要调用。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/cgi-bin/express/business/printer/getall?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回值

          Object

          返回数据示例

          { "count": 2, "openid": [   "oABC",   "oXYZ" ], "tagid_list": [   "123",   "456" ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.getPrinter
          需在 config.json 中配置 logistics.getPrinter API 的权限,详情

          返回值

          Object

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getPrinter({})    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "count": 2,  "openid": [    "oABC",    "oXYZ"  ],  "tagidList": [    "123",    "456"  ],  "errMsg": "openapi.logistics.getPrinter:ok"}


          logistics.getQuota

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取电子面单余额。仅在使用加盟类快递公司时,才可以调用。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/business/quota/get?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          delivery_idstring快递公司ID,参见getAllDelivery
          biz_idstring快递公司客户编码

          返回值

          Object

          属性类型说明
          quota_numnumber电子面单余额

          请求数据示例

          {  "delivery_id": "YTO",  "biz_id": "xyz"}

          返回数据示例

          {  "quota_num": 210}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.getQuota
          需在 config.json 中配置 logistics.getQuota API 的权限,详情

          请求参数

          属性类型默认值必填说明
          deliveryIdstring快递公司ID,参见getAllDelivery
          bizIdstring快递公司客户编码

          返回值

          Object

          属性类型说明
          quotaNumnumber电子面单余额

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getQuota({        deliveryId: 'YTO',        bizId: 'xyz'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "quotaNum": 210,  "errMsg": "openapi.logistics.getQuota:ok"}


          logistics.onBindResultUpdate

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          绑定商户审核结果更新事件。收到事件之后,回复success或者空串即可。

          消息参数

          OnBindResultUpdateData

          消息数据包示例

          XML 格式

          <xml>  <ToUserName><![CDATA[toUser]]></ToUserName>  <FromUserName><![CDATA[fromUser]]></FromUserName>  <CreateTime>1546924844</CreateTime>  <MsgType><![CDATA[event]]></MsgType>  <Event><![CDATA[update_business_bind_result]]></Event>  <errcode>0</errcode>  <errmsg><![CDATA[ok]]></errmsg>  <delivery_id><![CDATA[EMS]]></delivery_id>  <biz_id><![CDATA[1234567]]></biz_id></xml>

          JSON 格式

          {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1546924844,  "MsgType": "event",  "Event": "update_business_bind_result",  "errcode": 0,  "errmsg": "ok",  "delivery_id": "EMS",  "biz_id": "1234567",}


          logistics.onPathUpdate

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          运单轨迹更新事件。当运单轨迹有更新时,会产生如下数据包。收到事件之后,回复success或者空串即可。

          消息参数

          Object

          属性类型说明
          ToUserNamestring小程序的原始ID
          FromUserNamestring发送者的openid
          CreateTimenumber消息创建时间(整型)
          MsgTypestring固定 event
          Eventstring固定 add_express_path
          DeliveryIDstring快递公司ID
          WayBillIdstring运单ID
          OrderIdstring订单ID
          Versionnumber轨迹版本号(整型)
          Countnumber轨迹节点数(整型)
          ActionsArray.<Object>轨迹列表

          Actions 的结构

          属性类型说明
          ActionTimenumber轨迹节点 Unix 时间戳
          ActionTypenumber轨迹节点类型
          ActionMsgstring轨迹节点详情

          ActionType 的合法值

          说明最低版本
          100001揽件阶段-揽件成功
          100002揽件阶段-揽件失败
          100003揽件阶段-分配业务员
          200001运输阶段-更新运输轨迹
          300002派送阶段-开始派送
          300003派送阶段-签收成功
          300004派送阶段-签收失败
          400001异常阶段-订单取消
          400002异常阶段-订单滞留

          消息数据包示例

          XML 格式

          <xml>  <ToUserName><![CDATA[toUser]]></ToUserName>  <FromUserName><![CDATA[fromUser]]></FromUserName>  <CreateTime>1546924844</CreateTime>  <MsgType><![CDATA[event]]></MsgType>  <Event><![CDATA[add_express_path]]></Event>  <DeliveryID><![CDATA[SF]]></DeliveryID>  <WayBillId><![CDATA[123456789]]></WayBillId>  <OrderId><![CDATA[123456]]></OrderId>  <Version>3</Version>  <Count>3</Count>  <Actions>    <ActionTime>1546924840</ActionTime>    <ActionType>100001</ActionType>    <ActionMsg><![CDATA[小哥A揽件成功]]></ActionMsg>  </Actions>  <Actions>    <ActionTime>1546924841</ActionTime>    <ActionType>200001</ActionType>    <ActionMsg><![CDATA[到达广州集包地]]></ActionMsg>  </Actions>  <Actions>    <ActionTime>1546924842</ActionTime>    <ActionType>200001</ActionType>    <ActionMsg><![CDATA[运往目的地]]></ActionMsg>  </Actions></xml>

          JSON 格式

          {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1546924844,  "MsgType": "event",  "Event": "add_express_path",  "DeliveryID": "SF",  "WayBillId": "123456789",  "OrderId": "123456789",  "Version": 2,  "Count": 3,  "Actions": [    {      "ActionTime": 1546924840,      "ActionType": 100001,      "ActionMsg": "小哥A揽件成功"    },    {      "ActionTime": 1546924841,      "ActionType": 200001,      "ActionMsg": "到达广州集包地"    },    {      "ActionTime": 1546924842,      "ActionType": 200001,      "ActionMsg": "运往目的地"    }  ]}


          logistics.testUpdateOrder

          本接口应在服务器端调用,详细说明参见服务端API

          模拟快递公司更新订单状态, 该接口只能用户测试

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/business/test_update_order?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          biz_idstring商户id,需填test_biz_id
          order_idstring订单号
          delivery_idstring快递公司id,需填TEST
          waybill_idstring运单号
          action_timenumber轨迹变化 Unix 时间戳
          action_typenumber轨迹变化类型
          action_msgstring轨迹变化具体信息说明,使用UTF-8编码

          action_type 的合法值

          说明最低版本
          100001揽件阶段-揽件成功
          100002揽件阶段-揽件失败
          100003揽件阶段-分配业务员
          200001运输阶段-更新运输轨迹
          300002派送阶段-开始派送
          300003派送阶段-签收成功
          300004派送阶段-签收失败
          400001异常阶段-订单取消
          400002异常阶段-订单滞留

          返回值

          Object

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0成功
          -1系统失败

          请求数据示例

          {  "biz_id": "test_biz_id",  "order_id": "xxxxxxxxxxxx",  "delivery_id": "TEST",  "waybill_id": "xxxxxxxxxx",  "action_time": 123456789,  "action_type": 100001,  "action_msg": "揽件阶段"}

          返回数据示例

          {  "errcode": 0,  "errmsg": "ok"}


          logistics.updatePrinter

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          配置面单打印员,可以设置多个,若需要使用微信打单 PC 软件,才需要调用。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/business/printer/update?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          openidstring打印员 openid
          update_typestring更新类型
          tagid_liststring用于平台型小程序设置入驻方的打印员面单打印权限,同一打印员最多支持10个tagid,使用半角逗号分隔,中间不加空格,如填写123,456,表示该打印员可以拉取到tagid为123和456的下的单,非平台型小程序无需填写该字段

          update_type 的合法值

          说明最低版本
          bind绑定
          unbind解除绑定

          返回值

          Object

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0成功
          -1系统失败
          9300517update_type 不正确

          请求数据示例

          {  "openid": "oJ4v0wRAfiXcnIbM3SgGEUkTw3Qw",  "update_type": "bind",  "tagid_list": "123,456"}

          返回数据示例

          {  "errcode": 0,  "errmsg": "ok"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.updatePrinter
          需在 config.json 中配置 logistics.updatePrinter API 的权限,详情

          请求参数

          属性类型默认值必填说明
          openidstring打印员 openid
          updateTypestring更新类型
          tagidListstring用于平台型小程序设置入驻方的打印员面单打印权限,同一打印员最多支持10个tagid,使用半角逗号分隔,中间不加空格,如填写123,456,表示该打印员可以拉取到tagid为123和456的下的单,非平台型小程序无需填写该字段

          updateType 的合法值

          说明最低版本
          bind绑定
          unbind解除绑定

          返回值

          Object

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          -1系统失败
          9300517update_type 不正确

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.updatePrinter({        openid: 'oJ4v0wRAfiXcnIbM3SgGEUkTw3Qw',        updateType: 'bind',        tagidList: '123,456'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "errCode": 0,  "errMsg": "openapi.logistics.updatePrinter:ok"}


          logistics.getContact

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取面单联系人信息

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/delivery/contact/get?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          tokenstring商户侧下单事件中推送的 Token 字段
          waybill_idstring运单 ID

          返回值

          Object

          属性类型说明
          waybill_idstring运单 ID
          senderArray.<Object>发件人信息
          receiverArray.<Object>收件人信息
          errcodenumber错误码
          errmsgstring错误信息

          sender 的结构

          属性类型说明
          addressstring地址,已经将省市区信息合并
          namestring用户姓名
          telstring座机号码
          mobilestring手机号码

          receiver 的结构

          属性类型说明
          addressstring地址,已经将省市区信息合并
          namestring用户姓名
          telstring座机号码
          mobilestring手机号码

          errcode 的合法值

          说明最低版本
          0成功
          -1其他错误
          40199运单 ID 错误,未查到运单
          9300507Token 不正确

          请求数据示例

          {  "token": "TOKEN",  "waybill_id": "12345678901234567890"}

          返回数据示例

          {  "waybill_id": "12345678901234567890",  "sender": {    "address": "广东省广州市海珠区XX路XX号XX大厦XX栋XX",    "name": "张三",    "tel": "020-88888888",    "mobile": "18666666666"  },  "receiver": {    "address": "广东省广州市天河区XX路XX号XX大厦XX栋XX",    "name": "王小蒙",    "tel": "029-77777777",    "mobile": "18610000000"  }}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.getContact
          需在 config.json 中配置 logistics.getContact API 的权限,详情

          请求参数

          属性类型默认值必填说明
          tokenstring商户侧下单事件中推送的 Token 字段
          waybillIdstring运单 ID

          返回值

          Object

          属性类型说明
          waybillIdstring运单 ID
          senderArray.<Object>发件人信息
          receiverArray.<Object>收件人信息
          errCodenumber错误码
          errMsgstring错误信息

          sender 的结构

          属性类型说明
          addressstring地址,已经将省市区信息合并
          namestring用户姓名
          telstring座机号码
          mobilestring手机号码

          receiver 的结构

          属性类型说明
          addressstring地址,已经将省市区信息合并
          namestring用户姓名
          telstring座机号码
          mobilestring手机号码

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          -1其他错误
          40199运单 ID 错误,未查到运单
          9300507Token 不正确

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getContact({        token: 'TOKEN',        waybillId: '12345678901234567890'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "waybillId": "12345678901234567890",  "sender": {    "address": "广东省广州市海珠区XX路XX号XX大厦XX栋XX",    "name": "张三",    "tel": "020-88888888",    "mobile": "18666666666"  },  "receiver": {    "address": "广东省广州市天河区XX路XX号XX大厦XX栋XX",    "name": "王小蒙",    "tel": "029-77777777",    "mobile": "18610000000"  },  "errMsg": "openapi.logistics.getContact:ok"}


          logistics.onAddOrder

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          请求下单事件。

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 add_waybill,不区分大小写
          Tokenstring订单 Token。请保存该 Token,调用logistics.updatePath时需要传入
          OrderIDstring唯一标识订单的 ID,由商户生成。快递需要保证相同的 OrderID 生成相同的运单ID。
          BizIDstring商户 ID,即商户在快递注册的客户编码或月结账户名
          BizPwdstringBizID 对应的密码
          ShopAppIDstring商户的小程序 AppID
          WayBillIDstring运单 ID,从微信号段中生成。若为 0,则表示需要快递来生成运单 ID。
          Remarkstring快递备注,会打印到面单上,比如"易碎物品"
          SenderArray.<Object>发件人信息
          ReceiverArray.<Object>收件人信息
          CargoArray.<Object>包裹信息
          InsuredArray.<Object>保价信息
          ServiceArray.<Object>服务类型

          Sender 的结构

          属性类型说明
          Namestring发件人姓名
          Telstring发件人座机号码
          Mobilestring发件人手机号码
          Companystring发件人公司名
          PostCodestring发件人邮编
          Countrystring发件人所在国家,默认为"中国"
          Provincestring发件人省份,比如"广东省"
          Citystring发件人地区/市,比如"广州市"
          Areastring发件人区/县,比如"海珠区"
          Addressstring发件人详细地址,比如"XX路XX号XX大厦XX"

          Receiver 的结构

          属性类型说明
          Namestring收件人姓名
          Telstring收件人座机号码
          Mobilestring收件人手机号码
          Companystring收件人公司名
          PostCodestring收件人邮编
          Countrystring收件人所在国家,默认为"中国"
          Provincestring收件人省份,比如"广东省"
          Citystring收件人地区/市,比如"广州市"
          Areastring收件人区/县,比如"海珠区"
          Addressstring收件人详细地址,比如"XX路XX号XX大厦XX"

          Cargo 的结构

          属性类型说明
          Weightnumber货物总重量,比如1.2,单位是千克(kg)
          Space_Xnumber货物长度,比如20.5,单位是厘米(cm)
          Space_Ynumber货物宽度,比如15.0,单位是厘米(cm)
          Space_Znumber货物高度,比如10.0,单位是厘米(cm)
          Countnumber货物数量,一般为1

          Insured 的结构

          属性类型说明
          UseInsurednumber是否保价,0 表示不保价,1 表示保价
          InsuredValuenumber保价金额,单位是分,比如: 10000 表示 100 元

          Service 的结构

          属性类型说明
          ServiceTypenumber服务类型ID,详见已经支持的快递公司基本信息
          ServiceNamestring服务名称,详见已经支持的快递公司基本信息

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix 时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 add_waybill
          Tokenstring传入的 Token,原样返回
          OrderIDstring传入的唯一标识订单的 ID,由商户生成,原样返回
          BizIDstring商户 ID,原样返回
          WayBillIDstring运单 ID
          ResultCodenumber处理结果错误码
          ResultMsgstring处理结果的详细信息
          WaybillDatastring集包地、三段码、大头笔等信息,用于生成面单信息。详见后文返回值说明

          ResultCode 的合法值

          说明最低版本
          0下单成功
          -1其他错误
          10001客户编码或者月结账户不存在
          10002客户密码不正确
          20001运单 ID 不正确(仅适用于微信生成运单 ID 的情况)
          20002发件人信息不完整(包括姓名、电话、地址等不完整)
          20003发件人地址不可达或者发货地址不在服务范围
          20004收件人信息不完整(包括姓名、电话、地址等不完整)
          20005收件人地址不可达或者收货地址不在服务范围
          20006货物数量、重量、尺寸不正确或者不合理
          20007商户余额不足,需要充值后再进行下单
          20008保价信息不正确(金额不合理或者快递不支持)
          20009服务信息不正确

          消息参数说明

          • 各字段均为商家提供,不保证完整,不保证正确,需要快递侧做好参数合法性和正确性检查。
          • 当网络环境不稳定时,下单事件可能会重复推送。对于相同的 BizID+OrderID,要返回相同的运单 ID。
          • 不支持子母单、代收货款。

          返回值说明

          WaybillData 字段用于生成面单,结构为##(key##value##)*。key可以写到面单模板中,value是实际值。

          比如样例##ZTO_bagAddr##广州##ZTO_mark##888-666-666##中,"ZTO_markAddr"表示中通的集包地代号,"广州"是实际的集包地值;"ZTO_mark"表示中通三段码代号,"888-666-666"是实际的三段码值。

          消息数据包示例

          XML 格式

          <xml>  <ToUserName><![CDATA[gh_abcdefg]]></ToUserName>  <FromUserName><![CDATA[oABCD]]></FromUserName>  <CreateTime>1533042556</CreateTime>  <MsgType><![CDATA[event]]></MsgType>  <Event><![CDATA[add_waybill]]></Event>  <Token>1234ABC234523451</Token>  <OrderID><![CDATA[012345678901234567890123456789]]></OrderID>  <BizID><![CDATA[xyz]]></BizID>  <BizPwd><![CDATA[xyz123]]></BizPwd>  <ShopAppID><![CDATA[wxABCD]]></ShopAppID>  <WayBillID><![CDATA[123456789]]></WayBillID>  <Remark><![CDATA[易碎物品]]></Remark>  <Sender>      <Name><![CDATA[张三]]></Name>      <Tel><![CDATA[020-88888888]]></Tel>      <Mobile><![CDATA[18666666666]]></Mobile>      <Company><![CDATA[公司名]]></Company>      <PostCode><![CDATA[123456]]></PostCode>      <Country><![CDATA[中国]]></Country>      <Province><![CDATA[广东省]]></Province>      <City><![CDATA[广州市]]></City>      <Area><![CDATA[海珠区]]></Area>      <Address><![CDATA[XX路XX号XX大厦XX栋XX]]></Address>  </Sender>  <Receiver>      <Name><![CDATA[王小蒙]]></Name>      <Tel><![CDATA[029-77777777]]></Tel>      <Mobile><![CDATA[18610000000]]></Mobile>      <Company><![CDATA[公司名]]></Company>      <PostCode><![CDATA[654321]]></PostCode>      <Country><![CDATA[中国]]></Country>      <Province><![CDATA[广东省]]></Province>      <City><![CDATA[广州市]]></City>      <Area><![CDATA[天河区]]></Area>      <Address><![CDATA[XX路XX号XX大厦XX栋XX]]></Address>  </Receiver>  <Cargo>      <Weight>1.2</Weight>      <Space_X>20.5</Space_X>      <Space_Y>15.0</Space_Y>      <Space_Z>10.0</Space_Z>      <Count>2</Count>      <DetailList>          <Name><![CDATA[一千零一夜钻石包]]></Name>          <Count>1</Count>      </DetailList>      <DetailList>          <Name><![CDATA[爱马仕柏金钻石包]]></Name>          <Count>1</Count>      </DetailList>  </Cargo>  <Insured>      <UseInsured>1</UseInsured>      <InsuredValue>10000</InsuredValue>  </Insured>  <Service>      <ServiceType>0</ServiceType>      <ServiceName><![CDATA[标准快递]]></ServiceName>  </Service></xml>

          JSON 格式

          {  "ToUserName": "gh_abcdefg",  "FromUserName": "oABCD",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "add_waybill",  "Token": "1234ABC234523451",  "OrderID": "012345678901234567890123456789",  "BizID": "xyz",  "BizPwd": "xyz123",  "ShopAppID": "wxABCD",  "WayBillID": "123456789",  "Remark": "易碎物品",  "Sender": {    "Name": "张三",    "Tel": "020-88888888",    "Mobile": "18666666666",    "Company": "公司名",    "PostCode": "123456",    "Country": "中国",    "Province": "广东省",    "City": "广州市",    "Area": "海珠区",    "Address": "XX路XX号XX大厦XX栋XX"  },  "Receiver": {    "Name": "王小蒙",    "Tel": "029-77777777",    "Mobile": "18610000000",    "Company": "公司名",    "PostCode": "654321",    "Country": "中国",    "Province": "广东省",    "City": "广州市",    "Area": "天河区",    "Address": "XX路XX号XX大厦XX栋XX"  },  "Cargo": {    "Weight": 1.2,    "Space_X": 20.5,    "Space_Y": 15,    "Space_Z": 10,    "Count": 2,    "DetailList": [      {        "Name": "一千零一夜钻石包",        "Count": 1      },      {        "Name": "爱马仕柏金钻石包",        "Count": 1      }    ]  },  "Insured": {    "UseInsured": 1,    "InsuredValue": 10000  },  "Service": {    "ServiceType": 0,    "ServiceName": "标准快递"  }}

          返回数据包示例

          XML 格式

          <xml>    <ToUserName><![CDATA[oABCD]]></ToUserName>    <FromUserName><![CDATA[gh_abcdefg]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[add_waybill]]></Event>    <Token>1234ABC234523451</Token>    <OrderID><![CDATA[012345678901234567890123456789]]></OrderID>    <BizID><![CDATA[xyz]]></BizID>    <WayBillID><![CDATA[123456789]]></WayBillID>    <ResultCode>0</ResultCode>    <ResultMsg><![CDATA[success]]></ResultMsg>    <WaybillData><![CDATA[##ZTO_bagAddr##广州##ZTO_mark##888-666-666##]]></WaybillData></xml>

          JSON 格式

          {  "ToUserName": "oABCD",  "FromUserName": "gh_abcdefg",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "add_waybill",  "Token": "1234ABC234523451",  "OrderID": "012345678901234567890123456789",  "BizID": "xyz",  "WayBillID": "123456789",  "ResultCode": 0,  "ResultMsg": "success",  "WaybillData": "##ZTO_bagAddr##广州##ZTO_mark##888-666-666##"}


          logistics.onCancelOrder

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          取消订单事件。

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring下单用户的 OpenID
          CreateTimenumber事件时间,Unix 时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 cancel_waybill
          OrderIDstring唯一标识订单的 ID,由商户生成
          BizIDstring商户 ID
          BizPwdstring商户密码
          ShopAppIDstring商户的小程序 AppID
          WayBillIDstring运单 ID,从微信号段中生成

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix 时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 cancel_waybill,不区分大小写
          BizIDstring商户ID,请原样返回
          OrderIDstring唯一标识订单的ID,由商户生成。请原样返回
          WayBillIDstring运单ID,请原样返回
          ResultCodenumber处理结果错误码
          ResultMsgstring处理结果详情

          ResultCode 的合法值

          说明最低版本
          0取消成功
          -1其他错误
          30001参数错误(BizID、OrderID、WayBillID不存在)
          30002已经揽收,不可取消
          30003无效单(如已经取消过、或签收超过一定时间),不可取消
          30004快递不支持取消运单

          消息数据包示例

          XML 格式

          <xml>    <ToUserName><![CDATA[gh_abcdefg]]></ToUserName>    <FromUserName><![CDATA[oABCD]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[cancel_waybill]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <BizPwd><![CDATA[xyz123]]></BizPwd>    <ShopAppID><![CDATA[wxABCD]]></ShopAppID>    <OrderID><![CDATA[012345678901234567890123456789]]></OrderID>    <WayBillID><![CDATA[123456789]]></WayBillID></xml>

          JSON 格式

          {  "ToUserName": "gh_abcdefg",  "FromUserName": "oABCD",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "cancel_waybill",  "BizID": "xyz",  "BizPwd": "xyz123",  "ShopAppID": "wxABCD",  "OrderID": "012345678901234567890123456789",  "WayBillID": "123456789"}

          返回数据包示例

          XML 格式

          <xml>    <ToUserName><![CDATA[oABCD]]></ToUserName>    <FromUserName><![CDATA[gh_abcdefg]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[cancel_waybill]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <OrderID><![CDATA[012345678901234567890123456789]]></OrderID>    <WayBillID><![CDATA[123456789]]></WayBillID>    <ResultCode>0</ResultCode>    <ResultMsg><![CDATA[success]]></ResultMsg></xml>

          JSON 格式

          {  "ToUserName": "oABCD",  "FromUserName": "gh_abcdefg",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "cancel_waybill",  "BizID": "xyz",  "OrderID": "012345678901234567890123456789",  "WayBillID": "123456789",  "ResultCode": 0,  "ResultMsg": "success"}


          logistics.onCheckBusiness

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          审核商户事件。

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix 时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 check_biz,不区分大小写
          BizIDstring商户ID,即商户在快递注册的客户编码或月结账户名
          BizPwdstringBizID 对应的密码
          ShopAppIDstring商户的小程序 AppID
          ShopNamestring商户名称,即小程序昵称(仅EMS可用)
          ShopTelphonestring商户联系电话(仅EMS可用)
          ShopContactstring商户联系人姓名(仅EMS可用)
          ServiceNamestring预开通的服务类型名称(仅EMS可用)
          SenderAddressstring商户发货地址(仅EMS可用)
          SenderProvincestring商户发货省份(仅EMS可用)
          SenderCitystring商户发货城市(仅EMS可用)
          SenderAreastring商户发货区域(仅EMS可用)

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为event
          Eventstring事件类型,固定为check_biz,不区分大小写
          BizIDstring商户ID
          ResultCodenumber处理结果错误码
          ResultMsgstring处理结果详情
          Quotanumber商户可用余额,0 表示无可用余额

          ResultCode 的合法值

          说明最低版本
          0审核通过
          -1其他错误
          10001客户编码或者月结账户不存在
          10002客户密码不正确

          消息数据包示例

          XML 格式

          <xml>    <ToUserName><![CDATA[gh_abcdefg]]></ToUserName>    <FromUserName><![CDATA[oABCD]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[check_biz]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <BizPwd><![CDATA[xyz123]]></BizPwd>    <ShopAppID><![CDATA[wxABCD]]></ShopAppID>    <ShopName><![CDATA[商户名称]]></ShopName>    <ShopTelphone><![CDATA[18677778888]]></ShopTelphone>    <ShopContact><![CDATA[村正]]></ShopContact>    <ServiceName><![CDATA[标准快递]]></ServiceName>    <SenderProvince><![CDATA[广东省]]></SenderProvince>    <SenderCity><![CDATA[广州市]]></SenderCity>    <SenderArea><![CDATA[海珠区]]></SenderArea>    <SenderAddress><![CDATA[新港中路397号]]></SenderAddress></xml>

          JSON 格式

          {  "ToUserName": "gh_abcdefg",  "FromUserName": "oABCD",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "check_biz",  "BizID": "xyz",  "BizPwd": "xyz123",  "ShopAppID": "wxABCD",  "ShopName": "商户名称",  "ShopTelphone": "18677778888",  "ShopContact": "村正",  "ServiceName": "标准快递",  "SenderProvince": "广东省"  "SenderCity": "广州市"  "SenderArea": "海珠区"  "SenderAddress": "新港中路397号"}

          返回数据包示例

          XML 格式

          <xml>    <ToUserName><![CDATA[oABCD]]></ToUserName>    <FromUserName><![CDATA[gh_abcdefg]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[check_biz]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <ResultCode>0</ResultCode>    <ResultMsg><![CDATA[success]]></ResultMsg></xml>

          JSON 格式

          {  "ToUserName": "oABCD",  "FromUserName": "gh_abcdefg",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "check_biz",  "BizID": "xyz",  "ResultCode": 0,  "ResultMsg": "success"}


          logistics.onGetQuota

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          查询商户余额事件。

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 get_quota,不区分大小写
          BizIDstring商户ID,即商户在快递注册的客户编码或月结账户名
          BizPwdstringBizID 对应的密码
          ShopAppIDstring商户小程序的 AppID

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为event
          Eventstring事件类型,固定为get_quota,不区分大小写
          BizIDstring商户ID
          ResultCodenumber处理结果错误码
          ResultMsgstring处理结果详情
          Quotanumber商户可用余额,0 表示无可用余额

          ResultCode 的合法值

          说明最低版本
          0查询成功
          -1其他错误
          10001客户编码或者月结账户不存在
          10002客户密码不正确

          消息数据包示例

          XML 格式

          <xml>    <ToUserName><![CDATA[gh_abcdefg]]></ToUserName>    <FromUserName><![CDATA[oABCD]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[get_quota]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <BizPwd><![CDATA[xyz123]]></BizPwd>    <ShopAppID><![CDATA[wxABCD]]></ShopAppID></xml>

          JSON 格式

          {  "ToUserName": "gh_abcdefg",  "FromUserName": "oABCD",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "get_quota",  "BizID": "xyz",  "BizPwd": "xyz123",  "ShopAppID": "wxABCD"}

          返回数据包示例

          XML 格式

          <xml>    <ToUserName><![CDATA[oABCD]]></ToUserName>    <FromUserName><![CDATA[gh_abcdefg]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[get_quota]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <ResultCode>0</ResultCode>    <ResultMsg><![CDATA[success]]></ResultMsg>    <Quota>0</Quota></xml>

          JSON 格式

          {  "ToUserName": "oABCD",  "FromUserName": "gh_abcdefg",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "get_quota",  "BizID": "xyz",  "ResultCode": 0,  "ResultMsg": "success",  "Quota": 0}


          logistics.previewTemplate

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          预览面单模板。用于调试面单模板使用。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/delivery/template/preview?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          waybill_idstring运单 ID
          waybill_templatestring面单 HTML 模板内容(需经 Base64 编码)
          waybill_datastring面单数据。详情参考下单事件返回值中的 WaybillData
          customObject商户下单数据,格式是商户侧下单 API 中的请求体

          返回值

          Object

          属性类型说明
          waybill_idstring运单 ID
          rendered_waybill_templatestring渲染后的面单 HTML 文件(已经过 Base64 编码)
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0成功
          -1其他错误
          40199运单 ID 错误,未查到运单
          9300507Token 不正确
          9300502预览模板中出现该错误,一般是waybill_data数据错误
          9300512模板格式错误,渲染失败

          请求数据示例

          {  "waybill_id": "1234567890123",  "waybill_data": "##ZTO_mark##11-22-33##ZTO_bagAddr##广州##",  "waybill_template": "PGh0bWw+dGVzdDwvaHRtbD4=",  "custom": {    "order_id": "012345678901234567890123456789",    "openid": "oABC123456",    "delivery_id": "ZTO",    "biz_id": "xyz",    "custom_remark": "易碎物品",    "sender": {      "name": "张三",      "tel": "18666666666",      "mobile": "020-88888888",      "company": "公司名",      "post_code": "123456",      "country": "中国",      "province": "广东省",      "city": "广州市",      "area": "海珠区",      "address": "XX路XX号XX大厦XX栋XX"    },    "receiver": {      "name": "王小蒙",      "tel": "18610000000",      "mobile": "020-77777777",      "company": "公司名",      "post_code": "654321",      "country": "中国",      "province": "广东省",      "city": "广州市",      "area": "天河区",      "address": "XX路XX号XX大厦XX栋XX"    },    "shop": {      "wxa_path": "/index/index?from=waybill",      "img_url": "https://mmbiz.qpic.cn/mmbiz_png/KfrZwACMrmwbPGicysN6kibW0ibXwzmA3mtTwgSsdw4Uicabduu2pfbfwdKicQ8n0v91kRAUX6SDESQypl5tlRwHUPA/640",      "goods_name": "一千零一夜钻石包&爱马仕柏金钻石包",      "goods_count": 2    },    "cargo": {      "count": 2,      "weight": 5.5,      "space_x": 30.5,      "space_y": 20,      "space_z": 20,      "detail_list": [        {          "name": "一千零一夜钻石包",          "count": 1        },        {          "name": "爱马仕柏金钻石包",          "count": 1        }      ]    },    "insured": {      "use_insured": 1,      "insured_value": 10000    },    "service": {      "service_type": 0,      "service_name": "标准快递"    }  }}

          返回数据示例

          {  "waybill_id": "1234567890123",  "rendered_waybill_template": "PGh0bWw+dGVzdDwvaHRtbD4="}

          模板渲染语法

          1. 所有渲染语法由##开始,可参考示例。
          2. ##VAR(key) 用参数key对应的值填充。支持的参数如下表格所示
          keyvalue
          sys.waybillid运单 ID
          sys.wxaappid商户小程序 APPID
          waybilldata.*下单事件返回中的WaybillData,快递侧自定义的数据
          custom.*是商户侧下单 API 中传入的字段
          custom.order_id唯一标识订单的 ID,由商户传入
          custom.custom_remark快递备注,会打印到面单的自定义区,比如"易碎物品"
          custom.sender.name发件人名字
          custom.sender.tel发件人座机号码
          custom.sender.mobile发件人手机号码
          custom.sender.company发件人公司名
          custom.sender.post_code发件人邮编
          custom.sender.country发件人所在国家
          custom.sender.province发件人省份
          custom.sender.city发件人地区/市
          custom.sender.area发件人区/县
          custom.sender.address发件人详细地址
          custom.receiver.name收件人名字
          custom.receiver.tel收件人座机号码
          custom.receiver.mobile收件人手机号码
          custom.receiver.company收件人公司名
          custom.receiver.post_code收件人邮编
          custom.receiver.country收件人所在国家
          custom.receiver.province收件人省份
          custom.receiver.city收件人地区/市
          custom.receiver.area收件人区/县
          custom.receiver.address收件人详细地址
          custom.cargo.count包裹数量
          custom.cargo.weight包裹总重量,单位是千克(kg)
          custom.cargo.space_x包裹长度,单位是厘米(cm)
          custom.cargo.space_y包裹宽度,单位是厘米(cm)
          custom.cargo.space_z包裹高度,单位是厘米(cm)
          custom.shop.goods_name商品名称
          custom.shop.goods_count商品数量
          custom.insured.use_insured是否使用保价
          custom.insured.insured_value报价金额,单位是分
          custom.service.service_type服务类型 ID
          custom.service.service_name服务名称
          1. ##TIME(DATE) 用日期填充当前位置,格式为%Y/%m/%d,比如2018/11/22。
          2. ##TIME(TIME) 用时间填充当前位置,格式为%H:%M:%S,比如17:54:06。
          3. ##TIME(FULL) 用日期时间填充当前位置,格式为%Y/%m/%d %H:%M:%S,比如2018/11/22 17:54:06。
          4. ##STRBLOAT(VAR(sys.waybillid)) 获取运单 ID,然后在每个字符间填充空格。
          5. ##CODE128(VAR(sys.waybillid)) 获取运单 ID,然后转换成CODE128条码,图片为base64编码。
          6. ##QRCODE(VAR(sys.waybillid)) 获取运单 ID,然后转换为二维码,图片为base64编码。
          7. ##WXASUNCODE(VAR(sys.wxaappid)) 获取商户的小程序码,图片为base64编码。
          举例,如果想在面单上打印一个集包地信息的条形码,可以在面单中增加:
          <img src="data:image/jpeg;base64, ##CODE128(VAR(waybilldata.ZTO_bagAddr))" class="block_5__barCode">

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.previewTemplate
          需在 config.json 中配置 logistics.previewTemplate API 的权限,详情

          请求参数

          属性类型默认值必填说明
          waybillIdstring运单 ID
          waybillTemplatestring面单 HTML 模板内容(需经 Base64 编码)
          waybillDatastring面单数据。详情参考下单事件返回值中的 WaybillData
          customObject商户下单数据,格式是商户侧下单 API 中的请求体

          返回值

          Object

          属性类型说明
          waybillIdstring运单 ID
          renderedWaybillTemplatestring渲染后的面单 HTML 文件(已经过 Base64 编码)
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          -1其他错误
          40199运单 ID 错误,未查到运单
          9300507Token 不正确
          9300502预览模板中出现该错误,一般是waybill_data数据错误
          9300512模板格式错误,渲染失败

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.previewTemplate({        custom: {          openid: 'oABC123456',          sender: {            name: '张三',            tel: '18666666666',            mobile: '020-88888888',            company: '公司名',            country: '中国',            province: '广东省',            city: '广州市',            area: '海珠区',            address: 'XX路XX号XX大厦XX栋XX',            postCode: '123456'          },          receiver: {            name: '王小蒙',            tel: '18610000000',            mobile: '020-77777777',            company: '公司名',            country: '中国',            province: '广东省',            city: '广州市',            area: '天河区',            address: 'XX路XX号XX大厦XX栋XX',            postCode: '654321'          },          shop: {            wxaPath: '/index/index?from=waybill',            imgUrl: 'https://mmbiz.qpic.cn/mmbiz_png/KfrZwACMrmwbPGicysN6kibW0ibXwzmA3mtTwgSsdw4Uicabduu2pfbfwdKicQ8n0v91kRAUX6SDESQypl5tlRwHUPA/640',            goodsName: '一千零一夜钻石包&爱马仕柏金钻石包',            goodsCount: 2          },          cargo: {            count: 2,            weight: 5.5,            spaceX: 30.5,            spaceY: 20,            spaceZ: 20,            detailList: [              {                name: '一千零一夜钻石包',                count: 1              },              {                name: '爱马仕柏金钻石包',                count: 1              }            ]          },          insured: {            useInsured: 1,            insuredValue: 10000          },          service: {            serviceType: 0,            serviceName: '标准快递'          },          orderId: '012345678901234567890123456789',          deliveryId: 'ZTO',          bizId: 'xyz',          customRemark: '易碎物品'        },        waybillId: '1234567890123',        waybillData: '##ZTO_mark##11-22-33##ZTO_bagAddr##广州##',        waybillTemplate: 'PGh0bWw+dGVzdDwvaHRtbD4='      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "waybillId": "1234567890123",  "renderedWaybillTemplate": "PGh0bWw+dGVzdDwvaHRtbD4=",  "errMsg": "openapi.logistics.previewTemplate:ok"}


          logistics.updateBusiness

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          更新商户审核结果

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/delivery/service/business/update?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          shop_app_idstring商户的小程序AppID,即审核商户事件中的 ShopAppID
          biz_idstring商户账户
          result_codenumber审核结果,0 表示审核通过,其他表示审核失败
          result_msgstring审核错误原因,仅 result_code 不等于 0 时需要设置

          返回值

          Object

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0成功
          -1其他错误
          40013非法的商户小程序 AppID
          9300525商户未申请过审核

          请求数据示例

          {  "shop_app_id": "wxABCD",  "biz_id": "xyz",  "result_code": 0,  "result_msg": "审核通过"}

          返回数据示例

          {  "errcode": 0,  "errmsg": "ok"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.updateBusiness
          需在 config.json 中配置 logistics.updateBusiness API 的权限,详情

          请求参数

          属性类型默认值必填说明
          shopAppIdstring商户的小程序AppID,即审核商户事件中的 ShopAppID
          bizIdstring商户账户
          resultCodenumber审核结果,0 表示审核通过,其他表示审核失败
          resultMsgstring审核错误原因,仅 result_code 不等于 0 时需要设置

          返回值

          Object

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          -1其他错误
          40013非法的商户小程序 AppID
          9300525商户未申请过审核

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.updateBusiness({        shopAppId: 'wxABCD',        bizId: 'xyz',        resultCode: 0,        resultMsg: '审核通过'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "errCode": 0,  "errMsg": "openapi.logistics.updateBusiness:ok"}


          logistics.updatePath

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          更新运单轨迹

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/delivery/path/update?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          tokenstring商户侧下单事件中推送的 Token 字段
          waybill_idstring运单 ID
          action_timenumber轨迹变化 Unix 时间戳
          action_typenumber轨迹变化类型
          action_msgstring轨迹变化具体信息说明,展示在快递轨迹详情页中。若有手机号码,则直接写11位手机号码。使用UTF-8编码。

          action_type 的合法值

          说明最低版本
          100001揽件阶段-揽件成功
          100002揽件阶段-揽件失败
          100003揽件阶段-分配业务员
          200001运输阶段-更新运输轨迹
          300002派送阶段-开始派送
          300003派送阶段-签收成功
          300004派送阶段-签收失败
          400001异常阶段-订单取消
          400002异常阶段-订单滞留

          返回值

          Object

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0成功
          -1系统失败
          40199运单 ID 错误,未查到运单
          9300507Token 不正确

          请求数据示例

          {  "token": "TOKEN",  "waybill_id": "12345678901234567890",  "action_time": 1533052800,  "action_type": 300002,  "action_msg": "丽影邓丽君【18666666666】正在派件"}

          返回数据示例

          {  "errcode": 0,  "errmsg": "ok"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.logistics.updatePath
          需在 config.json 中配置 logistics.updatePath API 的权限,详情

          请求参数

          属性类型默认值必填说明
          tokenstring商户侧下单事件中推送的 Token 字段
          waybillIdstring运单 ID
          actionTimenumber轨迹变化 Unix 时间戳
          actionTypenumber轨迹变化类型
          actionMsgstring轨迹变化具体信息说明,展示在快递轨迹详情页中。若有手机号码,则直接写11位手机号码。使用UTF-8编码。

          actionType 的合法值

          说明最低版本
          100001揽件阶段-揽件成功
          100002揽件阶段-揽件失败
          100003揽件阶段-分配业务员
          200001运输阶段-更新运输轨迹
          300002派送阶段-开始派送
          300003派送阶段-签收成功
          300004派送阶段-签收失败
          400001异常阶段-订单取消
          400002异常阶段-订单滞留

          返回值

          Object

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          -1系统失败
          40199运单 ID 错误,未查到运单
          9300507Token 不正确

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.updatePath({        token: 'TOKEN',        waybillId: '12345678901234567890',        actionTime: 1533052800,        actionType: 300002,        actionMsg: '丽影邓丽君【18666666666】正在派件'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "errCode": 0,  "errMsg": "openapi.logistics.updatePath:ok"}


          ad.getUserActionSets

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          广告数据源查询

          说明

          微信广告文档:https://ad.weixin.qq.com/guide/457

          对应接口 https://api.weixin.qq.com/marketing/user_action_sets/get

          云调用使用说明

          外链文档中可能只有 HTTP 形式的定义,对云调用方式,调用时参数与 HTTP 需求的参数一致,但是无需传入 access_token,同时所有的参数无论 get/post 都只需作为接口参数 JS 对象中的一个字段传入即可。

          而对于 FormData 的请求,如果一个参数的类型是 Buffer,则其字段应传入有如下字段的对象:

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          示例

          假设外链文档要求是 POST 方法,要求传入如下参数

          属性类型位置说明
          xxxstringURL 参数...
          yyynumberJSON body...

          则调用示例如下:

          cloud.openapi.ad.getUserActionSets({  xxx: '字符串',  yyy: 100,})

          假设外链文档要求是 POST FormData,要求传入如下参数

          属性类型位置说明
          xxxstringURL 参数...
          mediabufferFormData图片 buffer

          则调用示例如下:

          cloud.openapi.ad.getUserActionSets({  xxx: '字符串',  media: {    contentType: 'image/png',    value: Buffer  },})


          ad.addUserActionSet

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          广告创建数据源

          说明

          微信广告文档:https://ad.weixin.qq.com/guide/457

          对应接口 https://api.weixin.qq.com/marketing/user_action_sets/add

          云调用使用说明

          外链文档中可能只有 HTTP 形式的定义,对云调用方式,调用时参数与 HTTP 需求的参数一致,但是无需传入 access_token,同时所有的参数无论 get/post 都只需作为接口参数 JS 对象中的一个字段传入即可。

          而对于 FormData 的请求,如果一个参数的类型是 Buffer,则其字段应传入有如下字段的对象:

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          示例

          假设外链文档要求是 POST 方法,要求传入如下参数

          属性类型位置说明
          xxxstringURL 参数...
          yyynumberJSON body...

          则调用示例如下:

          cloud.openapi.ad.addUserActionSet({  xxx: '字符串',  yyy: 100,})

          假设外链文档要求是 POST FormData,要求传入如下参数

          属性类型位置说明
          xxxstringURL 参数...
          mediabufferFormData图片 buffer

          则调用示例如下:

          cloud.openapi.ad.addUserActionSet({  xxx: '字符串',  media: {    contentType: 'image/png',    value: Buffer  },})


          ad.addUserAction

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          回传广告数据

          说明

          微信广告文档:https://ad.weixin.qq.com/guide/457

          对应接口 https://api.weixin.qq.com/marketing/user_actions/add

          云调用使用说明

          外链文档中可能只有 HTTP 形式的定义,对云调用方式,调用时参数与 HTTP 需求的参数一致,但是无需传入 access_token,同时所有的参数无论 get/post 都只需作为接口参数 JS 对象中的一个字段传入即可。

          而对于 FormData 的请求,如果一个参数的类型是 Buffer,则其字段应传入有如下字段的对象:

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          示例

          假设外链文档要求是 POST 方法,要求传入如下参数

          属性类型位置说明
          xxxstringURL 参数...
          yyynumberJSON body...

          则调用示例如下:

          cloud.openapi.ad.addUserAction({  xxx: '字符串',  yyy: 100,})

          假设外链文档要求是 POST FormData,要求传入如下参数

          属性类型位置说明
          xxxstringURL 参数...
          mediabufferFormData图片 buffer

          则调用示例如下:

          cloud.openapi.ad.addUserAction({  xxx: '字符串',  media: {    contentType: 'image/png',    value: Buffer  },})


          ad.getUserActionSetReports

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          广告数据源报表查询

          说明

          微信广告文档:https://ad.weixin.qq.com/guide/457

          对应接口 https://api.weixin.qq.com/marketing/user_action_set_reports/get

          云调用使用说明

          外链文档中可能只有 HTTP 形式的定义,对云调用方式,调用时参数与 HTTP 需求的参数一致,但是无需传入 access_token,同时所有的参数无论 get/post 都只需作为接口参数 JS 对象中的一个字段传入即可。

          而对于 FormData 的请求,如果一个参数的类型是 Buffer,则其字段应传入有如下字段的对象:

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          示例

          假设外链文档要求是 POST 方法,要求传入如下参数

          属性类型位置说明
          xxxstringURL 参数...
          yyynumberJSON body...

          则调用示例如下:

          cloud.openapi.ad.getUserActionSetReports({  xxx: '字符串',  yyy: 100,})

          假设外链文档要求是 POST FormData,要求传入如下参数

          属性类型位置说明
          xxxstringURL 参数...
          mediabufferFormData图片 buffer

          则调用示例如下:

          cloud.openapi.ad.getUserActionSetReports({  xxx: '字符串',  media: {    contentType: 'image/png',    value: Buffer  },})


          img.aiCrop

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          本接口提供基于小程序的图片智能裁剪能力。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cv/img/aicrop?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          img_urlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息

          使用说明

          说明 文件大小限制:小于2M 图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 ratios参数为可选,如果为空,则算法自动裁剪最佳宽高比;如果提供多个宽高比,请以英文逗号“,”分隔,最多支持5个宽高比

          请求数据示例

          示例1:

          curl -F 'ratios=1,2.35' "http://api.weixin.qq.com/cv/img/aicrop?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN"

          示例2:

          curl -F 'img=@test.jpg' -F 'ratios=1,2.35' 'http://api.weixin.qq.com/cv/img/aicrop?access_token=ACCESS_TOCKEN'

          返回数据示例

          {   "errcode": 0,   "errmsg": "ok",   "results": [ //智能裁剪结果   {       "crop_left": 112,       "crop_top": 0,       "crop_right": 839,       "crop_bottom": 727   },   {       "crop_left": 0,       "crop_top": 205,       "crop_right": 965,       "crop_bottom": 615   }   ],   "img_size": { //图片大小       "w": 966,       "h": 728   }}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.img.aiCrop
          需在 config.json 中配置 img.aiCrop API 的权限,详情

          请求参数

          属性类型默认值必填说明
          imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          img 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          使用说明

          说明 文件大小限制:小于2M 图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 ratios参数为可选,如果为空,则算法自动裁剪最佳宽高比;如果提供多个宽高比,请以英文逗号“,”分隔,最多支持5个宽高比

          返回数据示例

          {   "errcode": 0,   "errmsg": "ok",   "results": [ //智能裁剪结果   {       "crop_left": 112,       "crop_top": 0,       "crop_right": 839,       "crop_bottom": 727   },   {       "crop_left": 0,       "crop_top": 205,       "crop_right": 965,       "crop_bottom": 615   }   ],   "img_size": { //图片大小       "w": 966,       "h": 728   }}


          img.scanQRCode

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          本接口提供基于小程序的条码/二维码识别的API。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cv/img/qrcode?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          img_urlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息

          使用说明

          图片说明 文件大小限制:小于2M

          二维码说明 支持条码、二维码、DataMatrix和PDF417的识别。 二维码、DataMatrix会返回位置坐标,条码和PDF417暂不返回位置坐标。

          请求数据示例

          示例1:

          curl https://api.weixin.qq.com/cv/img/qrcode?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          示例2:

          curl -F 'img=@test.jpg' 'https://api.weixin.qq.com/cv/img/qrcode?access_token=ACCESS_TOCKEN'

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "code_results": [        {            "type_name": "QR_CODE",            "data": "http://www.qq.com",            "pos": {                "left_top": {                    "x": 585,                    "y": 378                },                "right_top": {                    "x": 828,                    "y": 378                },                "right_bottom": {                    "x": 828,                    "y": 618                },                "left_bottom": {                    "x": 585,                    "y": 618                }            }        },        {            "type_name": "QR_CODE",            "data": "https://mp.weixin.qq.com",            "pos": {                "left_top": {                    "x": 185,                    "y": 142                },                "right_top": {                    "x": 396,                    "y": 142                },                "right_bottom": {                    "x": 396,                    "y": 353                },                "left_bottom": {                    "x": 185,                    "y": 353                }            }        },        {            "type_name": "EAN_13",            "data": "5906789678957"        },        {            "type_name": "CODE_128",            "data": "50090500019191"        }    ],    "img_size": {        "w": 1000,        "h": 900    }}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.img.scanQRCode
          需在 config.json 中配置 img.scanQRCode API 的权限,详情

          请求参数

          属性类型默认值必填说明
          imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          img 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          使用说明

          图片说明 文件大小限制:小于2M

          二维码说明 支持条码、二维码、DataMatrix和PDF417的识别。 二维码、DataMatrix会返回位置坐标,条码和PDF417暂不返回位置坐标。

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "code_results": [        {            "type_name": "QR_CODE",            "data": "http://www.qq.com",            "pos": {                "left_top": {                    "x": 585,                    "y": 378                },                "right_top": {                    "x": 828,                    "y": 378                },                "right_bottom": {                    "x": 828,                    "y": 618                },                "left_bottom": {                    "x": 585,                    "y": 618                }            }        },        {            "type_name": "QR_CODE",            "data": "https://mp.weixin.qq.com",            "pos": {                "left_top": {                    "x": 185,                    "y": 142                },                "right_top": {                    "x": 396,                    "y": 142                },                "right_bottom": {                    "x": 396,                    "y": 353                },                "left_bottom": {                    "x": 185,                    "y": 353                }            }        },        {            "type_name": "EAN_13",            "data": "5906789678957"        },        {            "type_name": "CODE_128",            "data": "50090500019191"        }    ],    "img_size": {        "w": 1000,        "h": 900    }}


          img.superresolution

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          本接口提供基于小程序的图片高清化能力。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cv/img/superresolution?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          img_urlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息

          使用说明

          说明 文件大小限制:小于2M 图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 目前支持将图片超分辨率高清化2倍,即生成图片分辨率为原图2倍大小

          请求数据示例

          示例1:

          curl 'https://api.weixin.qq.com/cv/img/superresolution?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN'

          示例2:

          curl -F 'img=@test.jpg' 'https://api.weixin.qq.com/cv/img/superresolution?access_token=ACCESS_TOCKEN'

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "media_id": "6WXsIXkG7lXuDLspD9xfm5dsvHzb0EFl0li6ySxi92ap8Vl3zZoD9DpOyNudeJGB"}

          说明

          返回的media_id有效期为3天,期间可以通过“获取临时素材”接口获取图片二进制,示例:

          curl "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID" -o "output.jpg"

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.img.superresolution
          需在 config.json 中配置 img.superresolution API 的权限,详情

          请求参数

          属性类型默认值必填说明
          imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          img 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          使用说明

          说明 文件大小限制:小于2M 图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 目前支持将图片超分辨率高清化2倍,即生成图片分辨率为原图2倍大小

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "media_id": "6WXsIXkG7lXuDLspD9xfm5dsvHzb0EFl0li6ySxi92ap8Vl3zZoD9DpOyNudeJGB"}


          immediateDelivery.abnormalConfirm

          本接口应在服务器端调用,详细说明参见服务端API

          异常件退回商家商家确认收货接口

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/confirm_return?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          shopidstring商家id,由配送公司分配的appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号,在配送公司登记,闪送必填,值为店铺id
          delivery_signstring用配送公司提供的appSecret加密的校验串说明
          waybill_idstring配送单id
          remarkstring备注

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述

          使用场景

          当订单配送异常,骑手把货物退还给商家,商家收货以后调用本接口返回确认收货。

          请求示例

          {   "shopid": "123456",   "shop_order_id": "123456",   "shop_no": "shop_no_111"   "waybill_id": "123456",   "remark": "remark",   "delivery_sign": "123456"}

          返回数据示例

          {  "resultcode": 0,  "resultmsg": "ok"}


          immediateDelivery.addOrder

          本接口应在服务器端调用,详细说明参见服务端API

          下配送单接口

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/add?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          delivery_tokenstring预下单接口返回的参数,配送公司可保证在一段时间内运费不变
          shopidstring商家id,由配送公司分配的appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成, 不超过128字节
          shop_nostring商家门店编号,在配送公司登记,如果只有一个门店,美团闪送必填, 值为店铺id
          delivery_signstring用配送公司提供的appSecret加密的校验串说明
          delivery_idstring配送公司ID
          openidstring下单用户的openid
          senderObject发件人信息,顺丰同城急送必须填写,美团配送、达达、闪送,若传了shop_no的值可不填该字段
          receiverObject收件人信息
          cargoObject货物信息
          order_infoObject订单信息
          shopObject商品信息,会展示到物流通知消息中
          sub_biz_idstring子商户id,区分小程序内部多个子商户

          sender 的结构

          属性类型默认值必填说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          receiver 的结构

          属性类型默认值必填说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          cargo 的结构

          属性类型默认值必填说明
          goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
          goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
          goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
          goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_detailObject货物详情,最长不超过10240个字符
          goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
          goods_delivery_infostring货物交付信息,最长不超过100个字符
          cargo_first_classstring品类一级类目, 详见品类表
          cargo_second_classstring品类二级类目

          goods_detail 的结构

          属性类型默认值必填说明
          goodsArray.<Object>货物列表

          goods 的结构

          属性类型默认值必填说明
          good_countnumber货物数量
          good_namestring货品名称
          good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
          good_unitstring货品单位,最长不超过20个字符

          order_info 的结构

          属性类型默认值必填说明
          delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
          order_typenumber0订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
          expected_delivery_timenumber0期望派单时间(达达支持,表示达达系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
          expected_finish_timenumber0期望送达时间(美团、顺丰同城急送支持),unix-timestamp, 比如1586342180
          expected_pick_timenumber0期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
          poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
          notestring备注,最长不超过200个字符
          order_timenumber用户下单付款时间, 顺丰必填, 比如1555220757
          is_insurednumber0是否保价,0,非保价,1.保价
          declared_valuenumber保价金额,单位为元,精确到分
          tipsnumber小费,单位为元, 下单一般不加小费
          is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
          cash_on_deliverynumber骑手应付金额,单位为元,精确到分
          cash_on_pickupnumber骑手应收金额,单位为元,精确到分
          rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
          is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
          is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

          shop 的结构

          属性类型默认值必填说明
          wxa_pathstring商家小程序的路径,建议为订单页面
          img_urlstring商品缩略图 url
          goods_namestring商品名称
          goods_countnumber商品数量
          wxa_appidstring若结算方式为:第三方向配送公司统一结算,商户后续和第三方结算,则该参数必填;在该结算模式下,第三方用自己的开发小程序替授权商户发起下单,并将授权小程序的appid给平台,后续配送通知中可回流授权商户小程序。

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述
          feenumber实际运费(单位:元),运费减去优惠券费用
          deliverfeenumber运费(单位:元)
          couponfeenumber优惠券费用(单位:元)
          tipsnumber小费(单位:元)
          insurancefeenumber保价费(单位:元)
          distancenumber配送距离(整数单位:米)
          waybill_idstring配送单号
          order_statusnumber配送状态
          finish_codenumber收货码
          pickup_codenumber取货码
          dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0

          使用场景

          商家可调用本接口向配送公司请求下配送单,配送公司会返回这一单的配送单号、配送费、预计骑手接单时间等信息。如遇下单错误,请先确认一下编码方式,python建议 json.dumps(b, ensure_ascii=False),php建议 json_encode($arr, JSON_UNESCAPED_UNICODE) 可预约时间:达达:72小时内,闪送2小时以后,48小时以内

          请求示例

          {   "cargo": {       "cargo_first_class": "美食夜宵",       "cargo_second_class": "零食小吃",       "goods_detail": {           "goods": [               {                   "good_count": 1,                   "good_name": "水果",                   "good_price": 10,                   "good_unit": "元"               },               {                   "good_count": 2,                   "good_name": "蔬菜",                   "good_price": 20,                   "good_unit": "元"               }           ]       },       "goods_height": 1,       "goods_length": 3,       "goods_value": 5,       "goods_weight": 1,       "goods_width": 2   },   "delivery_id": "SFTC",   "delivery_sign": "01234567890123456789",   "openid": "oABC123456",   "order_info": {       "delivery_service_code": "",       "expected_delivery_time": 0,       "is_direct_delivery": 0,       "is_finish_code_needed": 1,       "is_insured": 0,       "is_pickup_code_needed": 1,       "note": "test_note",       "order_time": 1555220757,       "order_type": 0,       "poi_seq": "1111",       "tips": 0   },   "receiver": {       "address": "xxx地铁站",       "address_detail": "2号楼202",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.1529600000,       "lng": 116.5060300000,       "name": "老王",       "phone": "18512345678"   },   "sender": {       "address": "xx大厦",       "address_detail": "1号楼101",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.4486120000,       "lng": 116.3830750000,       "name": "刘一",       "phone": "13712345678"   },   "shop": {       "goods_count": 2,       "goods_name": "宝贝",       "img_url": "https://mmbiz.qpic.cn/mmbiz_png/xxxxxxxxx/0?wx_fmt=png",       "wxa_path": "/page/index/index"   },   "shop_no": "12345678",   "sub_biz_id": "sub_biz_id_1",   "shop_order_id": "SFTC_001",   "shopid": "122222222",   "delivery_token": "xxxxxxxx"}

          返回示例

          下单成功

          {  "resultcode": 0,  "resultmsg": "ok",  "fee": 10,  "deliverfee": 10,  "couponfee": 0,  "tips": 0,  "insurancfee": 0,  "distance": 1000,  "waybill_id": "123456789",  "order_status": 101,  "finish_code": 1024,  "pickup_code": 2048,  "dispatch_duration": 300}

          下单失败

          {  "resultcode": 1010,  "resultmsg": "收件人信息不正确"}


          immediateDelivery.addTip

          本接口应在服务器端调用,详细说明参见服务端API

          可以对待接单状态的订单增加小费。需要注意:订单的小费,以最新一次加小费动作的金额为准,故下一次增加小费额必须大于上一次小费额

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/addtips?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          shopidstring商家id, 由配送公司分配的appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号,在配送公司登记,如果只有一个门店,闪送shop_no必填,值为店铺id
          delivery_signstring用配送公司提供的appSecret加密的校验串说明
          waybill_idstring配送单id
          openidstring下单用户的openid
          tipsnumber小费金额(单位:元) 各家配送公司最大值不同
          remarkstring备注

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述

          使用场景

          调用本接口,可以给待接单状态的订单增加小费,各家配送公司增加消费的规则如下:

          配送公司加小费规则
          顺丰同城急送支持加小费,小费规则:骑手接单前可加小费,上限10次,200元封顶
          闪送支持加小费,小费规则:骑手接单前可加小费,需按固定档位加小费,档位为2、3、5、10、15、20、50、100
          美团配送不支持加小费
          达达配送支持加小费,小费规则:骑手接单前可加小费,小费金额以最新一次为准,同一单新增的小费额须大于上一次的小费额,小费不可以超过货值,上限30元

          请求示例

          {   "shopid": "123456",   "shop_order_id": "123456",   "waybill_id": "123456",   "tips": 5,   "remark": "gogogo",   "delivery_sign": "123456",   "shop_no": "shop_no_111"}

          返回数据示例

          {  "resultcode": 0,  "resultmsg": "ok"}


          immediateDelivery.bindAccount

          本接口应在服务器端调用,详细说明参见服务端API

          第三方代商户发起绑定配送公司帐号的请求

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/shop/add?access_token=COMPNENT_ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          delivery_idstring配送公司ID

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述

          errcode 的合法值

          说明最低版本
          0成功
          86000不是第三方的调用
          930561delivery_id无效

          使用场景

          1. 只能由第三方服务商调用此接口
          2. 服务商可通过本接口代开发的小程序发起绑定配送公司帐号的操作,当调用成功,小程序管理员将收到模版消息,点击详情进入配送公司网站进行绑定操作

          返回数据示例

          {  "resultcode": 0,  "resultmsg": "ok",}


          immediateDelivery.cancelOrder

          本接口应在服务器端调用,详细说明参见服务端API

          取消配送单接口

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/cancel?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          shopidstring商家id, 由配送公司分配的appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号,如果只有一个门店,闪送shop_no必填,值为店铺id
          delivery_signstring用配送公司提供的appSecret加密的校验串说明
          delivery_idstring快递公司ID
          waybill_idstring配送单id
          cancel_reason_idnumber取消原因Id
          cancel_reasonstring取消原因

          cancel_reason_id 的合法值

          说明最低版本
          1暂时不需要邮寄
          2价格不合适
          3订单信息有误,重新下单
          4骑手取货不及时
          5骑手配送不及时
          6其他原因( 如果选择6,需要填写取消原因,否则不需要填写 )

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述
          deduct_feenumber扣除的违约金(单位:元),精确到分
          descstring说明

          使用场景

          调用本接口可向配送公司请求取消配送单,各家取消规则如下:

          配送公司取消规则
          顺丰同城急送配送完成前任意节点可取消配送单
          闪送配送完成前任意节点可取消配送单
          美团配送配送完成前任意节点可取消配送单
          达达骑手取货之前可取消配送单

          请求示例

          {   "shopid": "123456",   "shop_order_id": "123456",   "waybill_id": "123456",   "delivery_id": "123456",   "cancel_reason_id": 1,   "cancel_reason": "",   "delivery_sign": "123456",   "shop_no": "shop_no_111"}

          返回数据示例

          {  "resultcode": 0,  "resultmsg": "ok",  "deduct_fee": 5,  "desc": "blabla"}


          immediateDelivery.getAllImmeDelivery

          本接口应在服务器端调用,详细说明参见服务端API

          获取已支持的配送公司列表接口

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/delivery/getall?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述
          listArray.<Object>配送公司列表

          list 的结构

          属性类型说明
          delivery_idstring配送公司Id
          delivery_namestring配送公司名称

          使用场景

          查询即时配送接口已支持的配送公司和delivery_id

          返回数据示例

          {  "resultcode": 0,  "resultmsg": "ok",  "list": [     {         "delivery_id": "SFTC",         "delivery_name": "顺发同城"     },     {         "delivery_id": "MTPS",         "delivery_name": "美团配送"     }  ]}


          immediateDelivery.getBindAccount

          本接口应在服务器端调用,详细说明参见服务端API

          拉取已绑定账号

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/shop/get?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述
          shop_listArray.<Object>绑定的商家签约账号列表

          shop_list 的结构

          属性类型说明
          delivery_idstring配送公司Id
          shopidstring商家id
          audit_resultnumber审核状态

          audit_result 的合法值

          说明最低版本
          0审核通过
          1审核中
          2审核不通过

          使用场景

          1. 商家可通过本接口查询自己已经在小程序后台绑定的和配送公司签约的账号;
          2. 服务商可通过本接口查询代开发的小程序在小程序后台绑定的和配送公司签约的账号,为其完成后续的接口代开发业务。

          返回数据示例

          {  "resultcode": 0,  "resultmsg": "ok",  "shop_list": [      {       "delivery_id": "SFTC",       "shopid": "123456",       "audit_result": 0      },      {       "delivery_id": "MTPS",       "shopid": "123456",       "audit_result": 0      }  ]}


          immediateDelivery.getOrder

          本接口应在服务器端调用,详细说明参见服务端API

          拉取配送单信息

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/get?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          shopidstring商家id, 由配送公司分配的appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司登记,如果只有一个门店,可以不填
          delivery_signstring用配送公司提供的appSecret加密的校验串说明

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述
          order_statusnumber配送状态,枚举值
          waybill_idstring配送单号
          rider_namestring骑手姓名
          rider_phonestring骑手电话
          rider_lngnumber骑手位置经度, 配送中时返回
          rider_latnumber骑手位置纬度, 配送中时返回
          reach_timenumber预计还剩多久送达时间, 配送中时返回,单位秒, 已取货配送中需返回,比如5分钟后送达,填300

          使用场景

          商家可使用本接口查询某一配送单的配送状态,便于商家掌握配送情况。


          immediateDelivery.mockUpdateOrder

          本接口应在服务器端调用,详细说明参见服务端API

          模拟配送公司更新配送单状态, 该接口只用于沙盒环境,即订单并没有真实流转到运力方

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/test_update_order?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          shopidstring商家id, 必须是 "test_shop_id"
          shop_order_idstring唯一标识订单的 ID,由商户生成
          action_timenumber状态变更时间点,Unix秒级时间戳
          order_statusnumber配送状态,枚举值
          action_msgstring附加信息

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述

          使用场景

          该接口只能用于测试

          请求示例

          {   "shopid": "test_shop_id",   "shop_order_id": "xxxxxxxxxxx",   "waybill_id": "xxxxxxxxxxxxx",   "action_time": 12345678,   "order_status": 101,   "action_msg": "",}

          返回数据示例

          {  "resultcode": 0,  "resultmsg": "ok"}


          immediateDelivery.onOrderStatus

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          配送单配送状态更新通知接口

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 update_waybill_status,不区分大小写
          shopidstring商家id, 由配送公司分配的appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司侧登记
          waybill_idstring配送单id
          action_timenumberUnix时间戳
          order_statusnumber配送状态,枚举值
          action_msgstring附加信息
          agentObject骑手信息

          agent 的结构

          属性类型说明
          namestring骑手姓名
          phonestring骑手电话
          reach_timenumber预计送达时间戳, 配送中返回

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 update_waybill_status,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述

          使用场景

          当配送公司更新订单配送状态时,微信会通过本接口同步通知商户

          消息数据包示例

          JSON 格式

          {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1546924844,  "MsgType": "event",  "Event": "update_waybill_status",  "shopid": "123456",  "shop_order_id": "123456",  "waybill_id": "123456",  "action_time": 1546924844,  "order_status": 102,  "action_msg": "",  "shop_no": "123456",  "agent": {     "name": "xxx",     "phone": "1234567"  }}


          immediateDelivery.openDelivery

          本接口应在服务器端调用,详细说明参见服务端API

          第三方代商户发起开通即时配送权限

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/open?access_token=COMPNENT_ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述

          errcode 的合法值

          说明最低版本
          0成功
          43016小程序未认证
          86000不是第三方的调用
          930568不支持个人类型小程序
          930569已经开通不需要再开通
          930571该商户没有内测权限

          使用场景

          1. 只能由第三方服务商调用此接口
          2. 服务商可通过本接口代开发的小程序发起开通即时配送接口权限的操作,当调用成功,小程序管理员将收到模版消息,进行开通操作

          返回数据示例

          {  "resultcode": 0,  "resultmsg": "ok",}


          immediateDelivery.preAddOrder

          本接口应在服务器端调用,详细说明参见服务端API

          预下配送单接口

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/pre_add?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          shopidstring商家id, 由配送公司分配的appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成, 不超过128字节
          shop_nostring商家门店编号,在配送公司登记,美团、闪送必填
          delivery_signstring用配送公司提供的appSecret加密的校验串说明
          delivery_idstring配送公司ID
          openidstring下单用户的openid
          senderObject发件人信息,闪送、顺丰同城急送必须填写,美团配送、达达,若传了shop_no的值可不填该字段
          receiverObject收件人信息
          cargoObject货物信息
          order_infoObject订单信息
          shopObject商品信息,会展示到物流通知消息中
          sub_biz_idstring子商户id,区分小程序内部多个子商户

          sender 的结构

          属性类型默认值必填说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          receiver 的结构

          属性类型默认值必填说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          cargo 的结构

          属性类型默认值必填说明
          goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
          goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
          goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
          goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_detailObject货物详情,最长不超过10240个字符
          goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
          goods_delivery_infostring货物交付信息,最长不超过100个字符
          cargo_first_classstring品类一级类目, 详见品类表
          cargo_second_classstring品类二级类目

          goods_detail 的结构

          属性类型默认值必填说明
          goodsArray.<Object>货物列表

          goods 的结构

          属性类型默认值必填说明
          good_countnumber货物数量
          good_namestring货品名称
          good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
          good_unitstring货品单位,最长不超过20个字符

          order_info 的结构

          属性类型默认值必填说明
          delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
          order_typenumber0订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
          expected_delivery_timenumber0期望派单时间(美团、达达支持,美团表示商家发单时间,达达表示系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
          expected_finish_timenumber0期望送达时间(顺丰同城急送支持),unix-timestamp, 比如1586342180
          expected_pick_timenumber0期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
          poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
          notestring备注,最长不超过200个字符
          order_timenumber用户下单付款时间, 比如1555220757
          is_insurednumber0是否保价,0,非保价,1.保价
          declared_valuenumber保价金额,单位为元,精确到分
          tipsnumber小费,单位为元, 下单一般不加小费
          is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
          cash_on_deliverynumber骑手应付金额,单位为元,精确到分
          cash_on_pickupnumber骑手应收金额,单位为元,精确到分
          rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
          is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
          is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

          shop 的结构

          属性类型默认值必填说明
          wxa_pathstring商家小程序的路径,建议为订单页面
          img_urlstring商品缩略图 url
          goods_namestring商品名称
          goods_countnumber商品数量
          wxa_appidstring若结算方式为:第三方向配送公司统一结算,商户后续和第三方结算,则该参数必填;在该结算模式下,第三方用自己的开发小程序替授权商户发起下单,并将授权小程序的appid给平台,后续配送通知中可回流授权商户小程序。

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述
          feenumber实际运费(单位:元),运费减去优惠券费用
          deliverfeenumber运费(单位:元)
          couponfeenumber优惠券费用(单位:元)
          tipsnumber小费(单位:元)
          insurancefeenumber保价费(单位:元)
          distancenumber配送距离(单位:米)
          dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0
          delivery_tokenstring配送公司可以返回此字段,当用户下单时候带上这个字段,保证在一段时间内运费不变

          使用场景

          1. 在用户提交外卖订单时,商家可调用本接口查询配送公司是否可接单、预计多久接单、运费预估等。预估运费可作为展示给用户的运费参考值。
          2. 举个例子:商家通过预下配送单接口返回的预估运费是8元,商家可决定前端顾客下外卖单时展示给顾客看的运费是真实的8元,还是其他商家指定的金额。
          3. 说明:本接口非必须调用接口,若不需要获取配送公司是否可接单、预计多久接单、运费预估等,也可不调用本接口,直接下配送单。
          4. 顺丰同城可返回配送费用、配送距离、预计骑手接单时间,不支持返回delivery_token。
          5. 闪送可返回配送费用、配送距离、预计骑手接单时间,不支持返回delivery_token。
          6. 美团配送返回0时表示校验通过,不支持返回配送费用、配送距离、预计骑手接单时间和delivery_token。
          7. 达达支持预下单查询配送费用、配送距离、预计骑手接单时间和delivery_token(有效期3分钟)。

          请求示例

          {   "cargo": {       "cargo_first_class": "美食夜宵",       "cargo_second_class": "零食小吃",       "goods_detail": {           "goods": [               {                   "good_count": 1,                   "good_name": "水果",                   "good_price": 10,                   "good_unit": "元"               },               {                   "good_count": 2,                   "good_name": "蔬菜",                   "good_price": 20,                   "good_unit": "元"               }           ]       },       "goods_height": 1,       "goods_length": 3,       "goods_value": 5,       "goods_weight": 1,       "goods_width": 2   },   "delivery_id": "SFTC",   "delivery_sign": "01234567890123456789",   "openid": "oABC123456",   "order_info": {       "delivery_service_code": "",       "expected_delivery_time": 0,       "is_direct_delivery": 0,       "is_finish_code_needed": 1,       "is_insured": 0,       "is_pickup_code_needed": 1,       "note": "test_note",       "order_time": 1555220757,       "order_type": 0,       "poi_seq": "1111",       "tips": 0   },   "receiver": {       "address": "xxx地铁站",       "address_detail": "2号楼202",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.1529600000,       "lng": 116.5060300000,       "name": "老王",       "phone": "18512345678"   },   "sender": {       "address": "xx大厦",       "address_detail": "1号楼101",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.4486120000,       "lng": 116.3830750000,       "name": "刘一",       "phone": "13712345678"   },   "shop": {       "goods_count": 2,       "goods_name": "宝贝",       "img_url": "https://mmbiz.qpic.cn/mmbiz_png/xxxxxxxxx/0?wx_fmt=png",       "wxa_path": "/page/index/index"   },   "shop_no": "12345678",   "sub_biz_id": "sub_biz_id_1",   "shop_order_id": "SFTC_001",   "shopid": "122222222",}

          返回示例

          下单成功

          {  "resultcode": 0,  "resultmsg": "ok",  "fee": 10,  "deliverfee": 10,  "couponfee": 0,  "tips": 0,  "insurancfee": 0,  "distance": 1000,  "dispatch_duration": 300,  "delivery_token": "1111111"}

          下单失败

          {  "resultcode": 1010,  "resultmsg": "收件人信息不正确"}


          immediateDelivery.preCancelOrder

          本接口应在服务器端调用,详细说明参见服务端API

          预取消配送单接口

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/precancel?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          shopidstring商家id, 由配送公司分配的appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号,在配送公司登记,闪送shop_no必填,值为店铺id
          delivery_signstring用配送公司提供的appSecret加密的校验串说明
          delivery_idstring快递公司ID
          waybill_idstring配送单id
          cancel_reason_idnumber取消原因Id
          cancel_reasonstring取消原因

          cancel_reason_id 的合法值

          说明最低版本
          1暂时不需要邮寄
          2价格不合适
          3订单信息有误,重新下单
          4骑手取货不及时
          5骑手配送不及时
          6其他原因( 如果选择6,需要填写取消原因,否则不需要填写 )

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述
          deduct_feenumber预计扣除的违约金(单位:元),精确到分
          descstring说明

          使用场景

          在正式取消配送单前,商家可调用本接口查询该订单是否可以取消,取消订单配送公司需要扣除的费用是多少。各家取消规则如下:

          配送公司取消规则
          顺丰同城急送配送完成前任意节点可取消配送单
          闪送配送完成前任意节点可取消配送单
          美团配送配送完成前任意节点可取消配送单
          达达骑手取货之前可取消配送单

          请求示例

          {   "shopid": "123456",   "shop_order_id": "123456",   "waybill_id": "123456",   "delivery_id": "123456",   "cancel_reason_id": 1,   "cancel_reason": "",   "delivery_sign": "123456",   "shop_no": "shop_no_111"}

          返回数据示例

          {  "resultcode": 0,  "resultmsg": "ok",  "deduct_fee": 5,  "desc": "blabla"}


          immediateDelivery.realMockUpdateOrder

          本接口应在服务器端调用,详细说明参见服务端API

          模拟配送公司更新配送单状态, 该接口用于测试账户下的单,将请求转发到运力测试环境

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/realmock_update_order?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          shopidstring商家id
          shop_order_idstring唯一标识订单的 ID,由商户生成
          action_timenumber状态变更时间点,Unix秒级时间戳
          order_statusnumber配送状态,枚举值
          action_msgstring附加信息
          delivery_signstring用配送公司提供的appSecret加密的校验串说明

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述

          使用场景

          该接口只能用于测试,请求会转发到运力测试环境, 目前支持顺丰同城和达达

          1. 顺丰同城测试号
          • shopid: 1534713176
          • appsecret: d80400f91e156f63b38886e616d84590
          • shopno: 3243279847393
          • 支持变更状态: 102 202 202 302
          1. 达达测试号
          • shopid: dadaaee18818d97e236
          • appsecret: 1c6f40492d6d89caaad80b85f7d31670
          • shopno: 77071-47913
          • 支持变更状态: 102 201 202 301 302 304 305

          请求示例

          {   "shopid": "xxxxxxx",   "shop_order_id": "xxxxxxxxxxx",   "action_time": 1584145981,   "order_status": 101,   "action_msg": "",   "delivery_sign": "xxxxxxx",}

          返回数据示例

          {  "resultcode": 0,  "resultmsg": "ok"}


          immediateDelivery.reOrder

          本接口应在服务器端调用,详细说明参见服务端API

          重新下单

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/readd?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          delivery_tokenstring预下单接口返回的参数,配送公司可保证在一段时间内运费不变
          shopidstring商家id, 由配送公司分配的appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成, 不超过128字节
          shop_nostring商家门店编号,在配送公司登记,如果只有一个门店,闪送shop_no必填,值为店铺id
          delivery_signstring用配送公司提供的appSecret加密的校验串说明
          delivery_idstring配送公司ID
          openidstring下单用户的openid
          senderObject发件人信息,顺丰同城急送必须填写,美团配送、达达、闪送,若传了shop_no的值可不填该字段
          receiverObject收件人信息
          cargoObject货物信息
          order_infoObject订单信息
          shopObject商品信息,会展示到物流通知消息中
          sub_biz_idstring子商户id,区分小程序内部多个子商户

          sender 的结构

          属性类型默认值必填说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          receiver 的结构

          属性类型默认值必填说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          cargo 的结构

          属性类型默认值必填说明
          goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
          goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
          goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
          goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_detailObject货物详情,最长不超过10240个字符
          goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
          goods_delivery_infostring货物交付信息,最长不超过100个字符
          cargo_first_classstring品类一级类目, 详见品类表
          cargo_second_classstring品类二级类目

          goods_detail 的结构

          属性类型默认值必填说明
          goodsArray.<Object>货物列表

          goods 的结构

          属性类型默认值必填说明
          good_countnumber货物数量
          good_namestring货品名称
          good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
          good_unitstring货品单位,最长不超过20个字符

          order_info 的结构

          属性类型默认值必填说明
          delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
          order_typenumber0订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
          expected_delivery_timenumber0期望派单时间(美团、达达支持,美团表示商家发单时间,达达表示系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
          expected_finish_timenumber0期望送达时间(顺丰同城急送支持),unix-timestamp, 比如1586342180
          expected_pick_timenumber0期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
          poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
          notestring备注,最长不超过200个字符
          order_timenumber用户下单付款时间, 比如1555220757
          is_insurednumber0是否保价,0,非保价,1.保价
          declared_valuenumber保价金额,单位为元,精确到分
          tipsnumber小费,单位为元, 下单一般不加小费
          is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
          cash_on_deliverynumber骑手应付金额,单位为元,精确到分
          cash_on_pickupnumber骑手应收金额,单位为元,精确到分
          rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
          is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
          is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

          shop 的结构

          属性类型默认值必填说明
          wxa_pathstring商家小程序的路径,建议为订单页面
          img_urlstring商品缩略图 url
          goods_namestring商品名称
          goods_countnumber商品数量
          wxa_appidstring若结算方式为:第三方向配送公司统一结算,商户后续和第三方结算,则该参数必填;在该结算模式下,第三方用自己的开发小程序替授权商户发起下单,并将授权小程序的appid给平台,后续配送通知中可回流授权商户小程序。

          返回值

          Object

          属性类型说明
          errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
          errmsgstring错误描述
          resultcodenumber运力返回的错误码
          resultmsgstring运力返回的错误描述
          feenumber实际运费(单位:元),运费减去优惠券费用
          deliverfeenumber运费(单位:元)
          couponfeenumber优惠券费用(单位:元)
          tipsnumber小费(单位:元)
          insurancefeenumber保价费(单位:元)
          distancenumber配送距离(单位:米)
          waybill_idstring配送单号
          order_statusnumber配送状态
          finish_codenumber收货码
          pickup_codenumber取货码
          dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0

          使用场景

          在调用下配送单接口、订单被取消、过期或者投递异常的情况下,可调用此接口,重新下单,需要保持orderid一致。 备注:美团不支持重新下单接口,如果订单被取消商家需要重新下单,请修改orderid之后,调用下配送单接口下单。

          请求示例

          {   "cargo": {       "cargo_first_class": "美食夜宵",       "cargo_second_class": "零食小吃",       "goods_detail": {           "goods": [               {                   "good_count": 1,                   "good_name": "水果",                   "good_price": 10,                   "good_unit": "元"               },               {                   "good_count": 2,                   "good_name": "蔬菜",                   "good_price": 20,                   "good_unit": "元"               }           ]       },       "goods_height": 1,       "goods_length": 3,       "goods_value": 5,       "goods_weight": 1,       "goods_width": 2   },   "delivery_id": "SFTC",   "delivery_sign": "01234567890123456789",   "openid": "oABC123456",   "order_info": {       "delivery_service_code": "",       "expected_delivery_time": 0,       "is_direct_delivery": 0,       "is_finish_code_needed": 1,       "is_insured": 0,       "is_pickup_code_needed": 1,       "note": "test_note",       "order_time": 1555220757,       "order_type": 0,       "poi_seq": "1111",       "tips": 0   },   "receiver": {       "address": "xxx地铁站",       "address_detail": "2号楼202",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.1529600000,       "lng": 116.5060300000,       "name": "老王",       "phone": "18512345678"   },   "sender": {       "address": "xx大厦",       "address_detail": "1号楼101",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.4486120000,       "lng": 116.3830750000,       "name": "刘一",       "phone": "13712345678"   },   "shop": {       "goods_count": 2,       "goods_name": "宝贝",       "img_url": "https://mmbiz.qpic.cn/mmbiz_png/xxxxxxxxx/0?wx_fmt=png",       "wxa_path": "/page/index/index"   },   "shop_no": "12345678",   "sub_biz_id": "sub_biz_id_1",   "shop_order_id": "SFTC_001",   "shopid": "122222222",   "delivery_token": "xxxxxxxx"}

          返回示例

          下单成功

          {  "resultcode": 0,  "resultmsg": "ok",  "fee": 10,  "deliverfee": 10,  "couponfee": 0,  "tips": 0,  "insurancfee": 0,  "distance": 1000,  "waybill_id": "123456789",  "order_status": 101,  "finish_code": 1024,  "pickup_code": 2048,  "dispatch_duration": 300}

          下单失败

          {  "resultcode": 1010,  "resultmsg": "收件人信息不正确"}


          immediateDelivery.onAgentPosQuery

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          查询骑手当前位置信息

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_get_agent_pos,不区分大小写
          shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司侧登记
          waybill_idstring配送单id

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_get_agent_pos,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述
          lngnumber经度,火星坐标,精确到小数点后6位
          latnumber纬度,火星坐标,精确到小数点后6位
          distancenumber和目的地距离,已取货配送中需返回,单位米
          reach_timenumber预计还剩多久送达时间, 单位秒, 已取货配送中需返回,比如5分钟后送达,填300


          immediateDelivery.onAuthInfoGet

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          使用授权码拉取授权信息

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 get_auth_info,不区分大小写
          wx_appidstring发起授权的商户小程序appid
          codestring授权码

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 get_auth_info,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述
          appkeystring配送公司分配的appkey,对应shopid
          accountstring帐号名称
          account_typenumber帐号类型:0.不确定,1.预充值,2,月结,3,其它


          immediateDelivery.onCancelAuth

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          取消授权帐号

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 cancel_auth_account,不区分大小写
          shopidstring商家id, 配送公司唯一标识
          wx_appidstring发起授权的商户小程序appid

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 cancel_auth_account,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述


          immediateDelivery.onMockUpdateOrder

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          模拟更新订单状态接口

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 mock_update_order_status,不区分大小写
          shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司侧登记
          waybill_idstring配送单id
          delivery_signstring用配送公司侧提供的appSecret加密的校验串
          order_statusnumber订单状态,见之前order_status 枚举值
          action_timenumber状态变更时间点,Unix秒级时间戳
          action_msgstring附加信息(选填)

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 mock_update_order_status,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述


          immediateDelivery.onOrderAdd

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          真实发起下单任务

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_add_order,不区分大小写
          wx_tokenstring微信订单 Token。请保存该Token,调用更新配送单状态接口(updateOrder)时需要传入
          delivery_tokenstring配送公司侧在预下单时候返回的token,用于保证运费不变
          shopidstring商家id, 由配送公司分配的appkey
          shop_nostring商家门店编号, 在配送公司侧登记
          shop_order_idstring唯一标识订单的 ID,由商户生成
          delivery_signstring用配送公司侧提供的appSecret加密的校验串
          senderObject发件人信息,如果配送公司能从shopid+shop_no对应到门店地址,则不需要填写,否则需填写
          receiverObject收件人信息
          cargoObject货物信息
          order_infoObject订单信息

          sender 的结构

          属性类型说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          receiver 的结构

          属性类型说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          cargo 的结构

          属性类型说明
          goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
          goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
          goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
          goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_detailObject货物详情,最长不超过10240个字符
          goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
          goods_delivery_infostring货物交付信息,最长不超过100个字符
          cargo_first_classstring品类一级类目, 详见品类表
          cargo_second_classstring品类二级类目

          goods_detail 的结构

          属性类型说明
          goodsArray.<Object>货物列表

          goods 的结构

          属性类型说明
          good_countnumber货物数量
          good_namestring货品名称
          good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
          good_unitstring货品单位,最长不超过20个字符

          order_info 的结构

          属性类型说明
          delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
          order_typenumber订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
          expected_delivery_timenumber期望派单时间(达达支持,表示达达系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
          expected_finish_timenumber期望送达时间(美团、顺丰同城急送支持),unix-timestamp, 比如1586342180
          expected_pick_timenumber期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
          poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
          notestring备注,最长不超过200个字符
          order_timenumber用户下单付款时间, 顺丰必填, 比如1555220757
          is_insurednumber是否保价,0,非保价,1.保价
          declared_valuenumber保价金额,单位为元,精确到分
          tipsnumber小费,单位为元, 下单一般不加小费
          is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
          cash_on_deliverynumber骑手应付金额,单位为元,精确到分
          cash_on_pickupnumber骑手应收金额,单位为元,精确到分
          rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
          is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
          is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_add_order,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述
          feenumber实际运费(单位:元),运费减去优惠券费用
          deliverfeenumber运费(单位:元)
          couponfeenumber优惠券费用(单位:元)
          tipsnumber小费(单位:元)
          insurancefeenumber保价费(单位:元)
          distancenumber配送距离(整数,单位:米)
          waybill_idstring配送单号, 可以在API1更新配送单状态异步返回
          order_statusnumber配送单状态
          finish_codenumber收货码
          pickup_codenumber取货码
          dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0
          sender_lngnumber发货方经度,火星坐标,精确到小数点后6位, 用于消息通知,如果下单请求里有发货人信息则不需要
          sender_latnumber发货方纬度,火星坐标,精确到小数点后6位, 用于消息通知,如果下单请求里有发货人信息则不需要


          immediateDelivery.onOrderAddTips

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          可以对待接单状态的订单增加小费。需注意:各家小费规则不一致,请参考配送公司信息表小费规则说明来添加。

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_add_tips,不区分大小写
          shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司侧登记
          waybill_idstring配送单id
          delivery_signstring用配送公司侧提供的appSecret加密的校验串
          tipsnumber小费金额(单位:元)
          remarkstring备注

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_add_tips,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述


          immediateDelivery.onOrderCancel

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          取消订单操作,取消逻辑参照各配送公司取消规则)

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_cancel_order,不区分大小写
          shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司侧登记
          waybill_idstring配送单id
          delivery_signstring用配送公司侧提供的appSecret加密的校验串
          cancel_reason_idnumber取消原因id
          cancel_reasonstring取消原因

          cancel_reason_id 的合法值

          说明最低版本
          1暂时不需要邮寄
          2价格不合适
          3订单信息有误,重新下单
          4骑手取货不及时
          5骑手配送不及时
          6其他原因( 如果选择6,需要填写取消原因,否则不需要填写 )

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_cancel_order,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述
          deduct_feenumber扣除的违约金(单位:元),可能没有
          descstring扣费说明


          immediateDelivery.onOrderConfirmReturn

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          异常妥投商户收货确认(达达、闪送、人人快送支持)

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_confirm_return_to_biz,不区分大小写
          shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司侧登记
          waybill_idstring配送单id
          delivery_signstring用配送公司侧提供的appSecret加密的校验串

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_confirm_return_to_biz,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述


          immediateDelivery.onOrderPreAdd

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          并非真正发单,用来验证是否配送公司是否可以接单,并在成功时返回时效、计价等信息,也可用来验证地址以及时间是否在配送范围内。注意:预下单和下单时候由于时间差或者配送公司策略问题,返回的运费可能不一致,如果配送公司返回delivery_token,商家真正下单时候带上delivery_token,配送公司需保证在这一段时间内运费不变

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_precreate_order,不区分大小写
          shopidstring商家id, 由配送公司分配的appkey
          shop_nostring商家门店编号, 在配送公司侧登记
          shop_order_idstring唯一标识订单的 ID,由商户生成
          delivery_signstring用配送公司侧提供的appSecret加密的校验串
          senderObject发件人信息,如果配送公司能从shopid+shop_no对应到门店地址,则不需要填写,否则需填写
          receiverObject收件人信息
          cargoObject货物信息
          order_infoObject订单信息

          sender 的结构

          属性类型说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          receiver 的结构

          属性类型说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          cargo 的结构

          属性类型说明
          goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
          goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
          goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
          goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_detailObject货物详情,最长不超过10240个字符
          goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
          goods_delivery_infostring货物交付信息,最长不超过100个字符
          cargo_first_classstring品类一级类目, 详见品类表
          cargo_second_classstring品类二级类目

          goods_detail 的结构

          属性类型说明
          goodsArray.<Object>货物列表

          goods 的结构

          属性类型说明
          good_countnumber货物数量
          good_namestring货品名称
          good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
          good_unitstring货品单位,最长不超过20个字符

          order_info 的结构

          属性类型说明
          delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
          order_typenumber订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
          expected_delivery_timenumber期望派单时间(美团、达达支持,美团表示商家发单时间,达达表示系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
          expected_finish_timenumber期望送达时间(顺丰同城急送支持),unix-timestamp, 比如1586342180
          expected_pick_timenumber期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
          poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
          notestring备注,最长不超过200个字符
          order_timenumber用户下单付款时间, 比如1555220757
          is_insurednumber是否保价,0,非保价,1.保价
          declared_valuenumber保价金额,单位为元,精确到分
          tipsnumber小费,单位为元, 下单一般不加小费
          is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
          cash_on_deliverynumber骑手应付金额,单位为元,精确到分
          cash_on_pickupnumber骑手应收金额,单位为元,精确到分
          rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
          is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
          is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_precreate_order,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述
          feenumber实际运费(单位:元),运费减去优惠券费用
          deliverfeenumber运费(单位:元)
          couponfeenumber优惠券费用(单位:元)
          tipsnumber小费(单位:元)
          insurancefeenumber保价费(单位:元)
          distancenumber配送距离(单位:米)
          dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0
          delivery_tokenstring配送公司可以返回此字段,当用户下单时候带上这个字段,配送公司可保证在一段时间内运费不变


          immediateDelivery.onOrderPreCancel

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          预取消订单操作,用于在取消订单前查询是否可以取消以及取消扣除的违约金(非必须)

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_precancel_order,不区分大小写
          shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司侧登记
          waybill_idstring配送单id
          delivery_signstring用配送公司侧提供的appSecret加密的校验串
          cancel_reason_idnumber取消原因id
          cancel_reasonstring取消原因

          cancel_reason_id 的合法值

          说明最低版本
          1暂时不需要邮寄
          2价格不合适
          3订单信息有误,重新下单
          4骑手取货不及时
          5骑手配送不及时
          6其他原因( 如果选择6,需要填写取消原因,否则不需要填写 )

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_precancel_order,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述
          deduct_feenumber预计扣除的违约金(单位:元),可能没有
          descstring扣费说明


          immediateDelivery.onOrderQuery

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          查询订单状态

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_query_order_status,不区分大小写
          shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司侧登记
          waybill_idstring配送单id
          delivery_signstring用配送公司侧提供的appSecret加密的校验串

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_query_order_status,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述
          order_statusnumber当前订单状态,枚举值
          action_msgstring附加信息
          waybill_idstring配送单id


          immediateDelivery.onOrderReAdd

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          在调用下单接口后,订单被取消或者投递异常的情况下,调用此接口重新下单

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_readd_order,不区分大小写
          wx_tokenstring微信订单 Token。请保存该Token,调用更新配送单状态接口(updateOrder)时需要传入
          delivery_tokenstring配送公司侧在预下单时候返回的token,用于保证运费不变
          shopidstring商家id, 由配送公司分配的appkey
          shop_nostring商家门店编号, 在配送公司侧登记
          shop_order_idstring唯一标识订单的 ID,由商户生成
          delivery_signstring用配送公司侧提供的appSecret加密的校验串
          senderObject发件人信息,如果配送公司能从shopid+shop_no对应到门店地址,则不需要填写,否则需填写
          receiverObject收件人信息
          cargoObject货物信息
          order_infoObject订单信息

          sender 的结构

          属性类型说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          receiver 的结构

          属性类型说明
          namestring姓名,最长不超过256个字符
          citystring城市名称,如广州市
          addressstring地址(街道、小区、大厦等,用于定位)
          address_detailstring地址详情(楼号、单元号、层号)
          phonestring电话/手机号,最长不超过64个字符
          lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
          latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
          coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

          cargo 的结构

          属性类型说明
          goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
          goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
          goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
          goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
          goods_detailObject货物详情,最长不超过10240个字符
          goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
          goods_delivery_infostring货物交付信息,最长不超过100个字符
          cargo_first_classstring品类一级类目, 详见品类表
          cargo_second_classstring品类二级类目

          goods_detail 的结构

          属性类型说明
          goodsArray.<Object>货物列表

          goods 的结构

          属性类型说明
          good_countnumber货物数量
          good_namestring货品名称
          good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
          good_unitstring货品单位,最长不超过20个字符

          order_info 的结构

          属性类型说明
          delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
          order_typenumber订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
          expected_delivery_timenumber期望派单时间(达达支持,表示达达系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
          expected_finish_timenumber期望送达时间(美团、顺丰同城急送支持),unix-timestamp, 比如1586342180
          expected_pick_timenumber期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
          poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
          notestring备注,最长不超过200个字符
          order_timenumber用户下单付款时间, 顺丰必填, 比如1555220757
          is_insurednumber是否保价,0,非保价,1.保价
          declared_valuenumber保价金额,单位为元,精确到分
          tipsnumber小费,单位为元, 下单一般不加小费
          is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
          cash_on_deliverynumber骑手应付金额,单位为元,精确到分
          cash_on_pickupnumber骑手应收金额,单位为元,精确到分
          rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
          is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
          is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_readd_order,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述
          feenumber实际运费(单位:元),运费减去优惠券费用
          deliverfeenumber运费(单位:元)
          couponfeenumber优惠券费用(单位:元)
          tipsnumber小费(单位:元)
          insurancefeenumber保价费(单位:元)
          distancenumber配送距离(单位:米)
          waybill_idstring配送单号, 可以在API1更新配送单状态异步返回
          order_statusnumber配送单状态
          finish_codenumber收货码
          pickup_codenumber取货码
          dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0
          sender_lngnumber发货方经度,火星坐标,精确到小数点后6位, 用于消息通知,如果下单请求里有发货人信息则不需要
          sender_latnumber发货方纬度,火星坐标,精确到小数点后6位, 用于消息通知,如果下单请求里有发货人信息则不需要


          immediateDelivery.onPreAuthCodeGet

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          获取预授权码

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 get_pre_auth_code,不区分大小写
          wx_appidstring发起授权的商户小程序appid

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 get_pre_auth_code,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述
          pre_auth_codestring预授权码


          immediateDelivery.onRiderScoreSet

          本文档描述服务器端接收的消息或事件,详细说明参见消息推送

          给骑手评分

          消息参数

          Object

          属性类型说明
          ToUserNamestring快递公司小程序 UserName
          FromUserNamestring微信团队的 OpenID (固定值)
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_set_rider_score,不区分大小写
          shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司侧登记
          waybill_idstring配送单id
          delivery_ontime_scorenumber配送准时分数,范围 1 - 5
          cargo_intact_scorenumber货物完整分数,范围1-5
          attitude_scorenumber服务态度分数 范围1-5

          消息返回

          属性类型默认值必填说明
          ToUserNamestring原样返回请求中的 FromUserName
          FromUserNamestring快递公司小程序 UserName
          CreateTimenumber事件时间,Unix时间戳
          MsgTypestring消息类型,固定为 event
          Eventstring事件类型,固定为 transport_set_rider_score,不区分大小写
          resultcodenumber错误码
          resultmsgstring错误描述


          immediateDelivery.updateOrder

          本接口应在服务器端调用,详细说明参见服务端API

          配送公司更新配送单状态

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/express/local/delivery/update_order?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          wx_tokenstring下单事件中推送的wx_token字段
          shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
          shop_order_idstring唯一标识订单的 ID,由商户生成
          shop_nostring商家门店编号, 在配送公司侧登记
          waybill_idstring配送单id
          action_timenumber状态变更时间点,Unix秒级时间戳
          order_statusnumber订单状态,枚举值,下附枚举值列表及说明
          action_msgstring附加信息
          wxa_pathstring配送公司小程序跳转路径,用于用户收到消息会间接跳转到这个页面
          agentObject骑手信息, 骑手接单时需返回
          expected_delivery_timenumber预计送达时间戳, 骑手接单时需返回

          agent 的结构

          属性类型默认值必填说明
          namestring骑手姓名
          phonestring骑手电话
          is_phone_encryptednumber0电话是否加密

          返回值

          Object

          属性类型说明
          resultcodenumber错误码
          resultmsgstring错误描述



          ocr.bankcard

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          本接口提供基于小程序的银行卡 OCR 识别

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cv/ocr/bankcard?type=MODE&img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          img_urlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息
          numberstring银行卡号

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

          拍摄图片样例

          请求数据示例

          示例1:

          curl "https://api.weixin.qq.com/cv/ocr/bankcard?img_url= ENCODE_URL&access_token=ACCESS_TOCKEN"

          示例2:

          curl -F ‘img=@test.jpg’ “https://api.weixin.qq.com/cv/ocr/bankcard?access_token=ACCESS_TOCKEN”

          返回数据示例

          {  "errcode": "0",  "errmsg": "ok",  "id": "622213XXXXXXXXX"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.ocr.bankcard
          需在 config.json 中配置 ocr.bankcard API 的权限,详情

          请求参数

          属性类型默认值必填说明
          imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          img 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息
          numberstring银行卡号

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

          拍摄图片样例

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.bankcard({        type: 'photo',        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

          // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.bankcard({  type: 'photo',  img: {    contentType: 'image/png',    value: Buffer  }})

          返回数据示例

          {  "errcode": "0",  "errmsg": "ok",  "id": "622213XXXXXXXXX"}


          ocr.businessLicense

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          本接口提供基于小程序的营业执照 OCR 识别

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cv/ocr/bizlicense?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          img_urlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息
          reg_numstring注册号
          serialstring编号
          legal_representativestring法定代表人姓名
          enterprise_namestring企业名称
          type_of_organizationstring组成形式
          addressstring经营场所/企业住所
          type_of_enterprisestring公司类型
          business_scopestring经营范围
          registered_capitalstring注册资本
          paid_in_capitalstring实收资本
          valid_periodstring营业期限
          registered_datestring注册日期/成立日期
          cert_positionstring营业执照位置
          img_sizestring图片大小

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          返回字段仅包含当前营业执照图片中存在的字段,若对应字段不存在则不返回

          拍摄图片样例

          请求数据示例

          示例1:

          curl https://api.weixin.qq.com/cv/ocr/bizlicense?img_url= ENCODE_URL&access_token=ACCESS_TOCKEN

          示例2:

          curl -F ‘img=@test.jpg’“https://api.weixin.qq.com/cv/ocr/bizlicense?access_token=ACCESS_TOCKEN”

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "reg_num": "123123",                                                     //注册号    "serial": "123123",                                                      //编号    "legal_representative": "张三",                                          //法定代表人姓名    "enterprise_name": "XX饮食店",                                           //企业名称    "type_of_organization": "个人经营",                                      //组成形式    "address": "XX市XX区XX路XX号",                                           //经营场所/企业住所    "type_of_enterprise": "xxx",                                             //公司类型    "business_scope": "中型餐馆(不含凉菜、不含裱花蛋糕,不含生食海产品)。",  //经营范围    "registered_capital": "200万",                                           //注册资本    "paid_in_capital": "200万",                                              //实收资本    "valid_period": "2019年1月1日",                                          //营业期限    "registered_date": "2018年1月1日",                                       //注册日期/成立日期    "cert_position": {                                                       //营业执照位置        "pos": {            "left_top": {                "x": 155,                "y": 191            },            "right_top": {                "x": 725,                "y": 157            },            "right_bottom": {                "x": 743,                "y": 512            },            "left_bottom": {                "x": 164,                "y": 525            }        }    },    "img_size": {                                                            //图片大小        "w": 966,        "h": 728    }}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.ocr.businessLicense
          需在 config.json 中配置 ocr.businessLicense API 的权限,详情

          请求参数

          属性类型默认值必填说明
          imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          img 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息
          regNumstring注册号
          serialstring编号
          legalRepresentativestring法定代表人姓名
          enterpriseNamestring企业名称
          typeOfOrganizationstring组成形式
          addressstring经营场所/企业住所
          typeOfEnterprisestring公司类型
          businessScopestring经营范围
          registeredCapitalstring注册资本
          paidInCapitalstring实收资本
          validPeriodstring营业期限
          registeredDatestring注册日期/成立日期
          certPositionstring营业执照位置
          imgSizestring图片大小

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          返回字段仅包含当前营业执照图片中存在的字段,若对应字段不存在则不返回

          拍摄图片样例

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.businessLicense({        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

          // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.businessLicense({  img: {    contentType: 'image/png',    value: Buffer  }})

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "reg_num": "123123",                                                     //注册号    "serial": "123123",                                                      //编号    "legal_representative": "张三",                                          //法定代表人姓名    "enterprise_name": "XX饮食店",                                           //企业名称    "type_of_organization": "个人经营",                                      //组成形式    "address": "XX市XX区XX路XX号",                                           //经营场所/企业住所    "type_of_enterprise": "xxx",                                             //公司类型    "business_scope": "中型餐馆(不含凉菜、不含裱花蛋糕,不含生食海产品)。",  //经营范围    "registered_capital": "200万",                                           //注册资本    "paid_in_capital": "200万",                                              //实收资本    "valid_period": "2019年1月1日",                                          //营业期限    "registered_date": "2018年1月1日",                                       //注册日期/成立日期    "cert_position": {                                                       //营业执照位置        "pos": {            "left_top": {                "x": 155,                "y": 191            },            "right_top": {                "x": 725,                "y": 157            },            "right_bottom": {                "x": 743,                "y": 512            },            "left_bottom": {                "x": 164,                "y": 525            }        }    },    "img_size": {                                                            //图片大小        "w": 966,        "h": 728    }}


          ocr.driverLicense

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          本接口提供基于小程序的驾驶证 OCR 识别

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cv/ocr/drivinglicense?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          img_urlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息
          id_numstring证号
          namestring姓名
          sexstring性别
          namestring姓名
          addressstring地址
          birth_datestring出生日期
          issue_datestring初次领证日期
          car_classstring准驾车型
          valid_fromstring有效期限起始日
          valid_tostring有效期限终止日
          official_sealstring印章文构

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

          拍摄图片样例

          请求数据示例

          示例1:

          curl http://api.weixin.qq.com/cv/ocr/drivinglicense?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          示例2:

          curl -F ‘img=@test.jpg’“http://api.weixin.qq.com/cv/ocr/drivinglicense?access_token=ACCESS_TOCKEN”

          返回数据示例

          { "errcode": 0, "errmsg": "ok", "id_num": "660601xxxxxxxx1234", "name": "张三", "sex": "男", "nationality": "中国", "address": "广东省东莞市xxxxx号", "birth_date": "1990-12-21", "issue_date": "2012-12-21", "car_class": "C1", "valid_from": "2018-07-06", "valid_to": "2020-07-01", "official_seal": "xx市公安局公安交通管理局"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.ocr.driverLicense
          需在 config.json 中配置 ocr.driverLicense API 的权限,详情

          请求参数

          属性类型默认值必填说明
          imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          img 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息
          idNumstring证号
          namestring姓名
          sexstring性别
          namestring姓名
          addressstring地址
          birthDatestring出生日期
          issueDatestring初次领证日期
          carClassstring准驾车型
          validFromstring有效期限起始日
          validTostring有效期限终止日
          officialSealstring印章文构

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

          拍摄图片样例

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.driverLicense({        type: 'photo',        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

          // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.driverLicense({  type: 'photo',  img: {    contentType: 'image/png',    value: Buffer  }})

          返回数据示例

          { "errcode": 0, "errmsg": "ok", "id_num": "660601xxxxxxxx1234", "name": "张三", "sex": "男", "nationality": "中国", "address": "广东省东莞市xxxxx号", "birth_date": "1990-12-21", "issue_date": "2012-12-21", "car_class": "C1", "valid_from": "2018-07-06", "valid_to": "2020-07-01", "official_seal": "xx市公安局公安交通管理局"}


          ocr.idcard

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          本接口提供基于小程序的身份证 OCR 识别

          调用方式:

          • HTTPS 调用
          • 云调用
          • 增量调用(加强版)

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cv/ocr/idcard?type=MODE&img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          img_urlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息
          typestring正面或背面,Front / Back
          valid_datestring有效期

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。更强的能力需求,可以走服务市场调用。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

          拍摄图片样例

          photo:拍照模型,带背景的图片(示例如下)

          scan:扫描模式,不带背景的图片(示例如下)

          请求数据示例

          示例1:

          curl https://api.weixin.qq.com/cv/ocr/idcard?type=photo&img_url= ENCODE_URL&access_token=ACCESS_TOCKEN

          示例2:

          curl -F ‘img=@test.jpg’“https://api.weixin.qq.com/cv/ocr/idcard?type=photo&access_token=ACCESS_TOCKEN”

          返回数据示例

          正面返回

          {  "errcode": "0",  "errmsg": "ok",  "type": "Front",  "name": "张三",  "id": "123456789012345678",  "addr": "广东省广州市",  "gender": "男",  "nationality": "汉"}

          背面返回

          { "errcode": 0, "errmsg": "ok", "type": "Back", "valid_date": "20070105-20270105"}

          常见错误码

          错误码errmsg说明
          -1system error系统错误,请稍后重试
          101000invalid image url图片URL错误或拉取URL图像错误
          101001certificate not found图片中无法找到证件
          101002invalid image data图片数据无效

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.ocr.idcard
          需在 config.json 中配置 ocr.idcard API 的权限,详情

          请求参数

          属性类型默认值必填说明
          imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          img 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息
          typestring正面或背面,Front / Back
          validDatestring有效期

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。更强的能力需求,可以走服务市场调用。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

          拍摄图片样例

          photo:拍照模型,带背景的图片(示例如下)

          scan:扫描模式,不带背景的图片(示例如下)

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.idcard({        type: 'photo',        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

          // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.idcard({  type: 'photo',  img: {    contentType: 'image/png',    value: Buffer  }})

          返回数据示例

          正面返回

          {  "errCode": 0,  "errMsg": "openapi.ocr.idcard:ok",  "type": "Front",  "name": "张三",  "id": "123456789012345678",  "addr": "广东省广州市",  "gender": "男",  "nationality": "汉"}

          背面返回

          {  "errCode": 0,  "errMsg": "openapi.ocr.idcard:ok",  "type": "Back",  "validDate": "20070105-20270105"}


          ocr.printedText

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          本接口提供基于小程序的通用印刷体 OCR 识别

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cv/ocr/comm?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          img_urlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息
          itemsstring识别结果
          img_sizestring图片大小

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 通用印刷体OCR适用于屏幕截图、印刷体照片等场景

          请求数据示例

          示例1:

          curl http://api.weixin.qq.com/cv/ocr/comm?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          示例2:

          curl -F ‘img=@test.jpg’“http://api.weixin.qq.com/cv/ocr/comm?access_token=ACCESS_TOCKEN”

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "items": [ //识别结果        {            "text": "腾讯",            "pos": {                "left_top": {                    "x": 575,                    "y": 519                },                "right_top": {                    "x": 744,                    "y": 519                },                "right_bottom": {                    "x": 744,                    "y": 532                },                "left_bottom": {                    "x": 573,                    "y": 532                }            }        },        {            "text": "微信团队",            "pos": {                "left_top": {                    "x": 670,                    "y": 516                },                "right_top": {                    "x": 762,                    "y": 517                },                "right_bottom": {                    "x": 762,                    "y": 532                },                "left_bottom": {                    "x": 670,                    "y": 531                }            }        }    ],    "img_size": { //图片大小        "w": 1280,        "h": 720    }}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.ocr.printedText
          需在 config.json 中配置 ocr.printedText API 的权限,详情

          请求参数

          属性类型默认值必填说明
          imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          img 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息
          itemsstring识别结果
          imgSizestring图片大小

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 通用印刷体OCR适用于屏幕截图、印刷体照片等场景

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.printedText({        type: 'photo',        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

          // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.printedText({  type: 'photo',  img: {    contentType: 'image/png',    value: Buffer  }})

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "items": [ //识别结果        {            "text": "腾讯",            "pos": {                "left_top": {                    "x": 575,                    "y": 519                },                "right_top": {                    "x": 744,                    "y": 519                },                "right_bottom": {                    "x": 744,                    "y": 532                },                "left_bottom": {                    "x": 573,                    "y": 532                }            }        },        {            "text": "微信团队",            "pos": {                "left_top": {                    "x": 670,                    "y": 516                },                "right_top": {                    "x": 762,                    "y": 517                },                "right_bottom": {                    "x": 762,                    "y": 532                },                "left_bottom": {                    "x": 670,                    "y": 531                }            }        }    ],    "img_size": { //图片大小        "w": 1280,        "h": 720    }}


          ocr.vehicleLicense

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          本接口提供基于小程序的行驶证 OCR 识别

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cv/ocr/driving?type=MODE&img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          typestring图片识别模式,photo(拍照模式)或 scan(扫描模式)
          img_urlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息
          vehicle_typestring车辆类型
          ownerstring所有人
          addrstring住址
          use_characterstring使用性质
          modelstring品牌型号
          vinstring车辆识别代
          engine_numstring发动机号码
          register_datestring注册日期
          issue_datestring发证日期
          plate_num_bstring车牌号码
          recordstring号牌
          passengers_numstring核定载人数
          total_qualitystring总质量
          totalprepare_quality_qualitystring整备质量

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

          拍摄图片样例

          请求数据示例

          示例1:

          curl https://api.weixin.qq.com/cv/ocr/driving?type=photo&img_url= ENCODE_URL&access_token=ACCESS_TOCKEN

          示例2:

          curl -F ‘img=@test.jpg’“https://api.weixin.qq.com/cv/ocr/driving?type=photo&access_token=ACCESS_TOCKEN”

          返回数据示例

          {"vhicle_type": "小型普通客⻋","owner": "东莞市xxxxx机械厂","addr": "广东省东莞市xxxxx号","use_character": "非营运","model": "江淮牌HFCxxxxxxx","vin": "LJ166xxxxxxxx51","engine_num": "J3xxxxx3","register_date": "2018-07-06","issue_date": "2018-07-01","plate_num_b": "粤xxxxx","record": "441xxxxxx3","passengers_num": "7人","total_quality": "2700kg","prepare_quality": "1995kg"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.ocr.vehicleLicense
          需在 config.json 中配置 ocr.vehicleLicense API 的权限,详情

          请求参数

          属性类型默认值必填说明
          typestring图片识别模式,photo(拍照模式)或 scan(扫描模式)
          imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
          imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

          img 的结构

          属性类型默认值必填说明
          contentTypestring数据类型,传入 MIME Type
          valueBuffer文件 Buffer

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息
          vehicleTypestring车辆类型
          ownerstring所有人
          addrstring住址
          useCharacterstring使用性质
          modelstring品牌型号
          vinstring车辆识别代
          engineNumstring发动机号码
          registerDatestring注册日期
          issueDatestring发证日期
          plateNumBstring车牌号码
          recordstring号牌
          passengersNumstring核定载人数
          totalQualitystring总质量
          totalprepareQualityQualitystring整备质量

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          使用说明

          接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

          使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

          图片说明 文件大小限制:小于2M

          图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

          拍摄图片样例

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.vehicleLicense({        type: 'photo',        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

          // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.vehicleLicense({  type: 'photo',  img: {    contentType: 'image/png',    value: Buffer  }})

          返回数据示例

          {"vhicle_type": "小型普通客⻋","owner": "东莞市xxxxx机械厂","addr": "广东省东莞市xxxxx号","use_character": "非营运","model": "江淮牌HFCxxxxxxx","vin": "LJ166xxxxxxxx51","engine_num": "J3xxxxx3","register_date": "2018-07-06","issue_date": "2018-07-01","plate_num_b": "粤xxxxx","record": "441xxxxxx3","passengers_num": "7人","total_quality": "2700kg","prepare_quality": "1995kg"}


          operation.getFeedback

          本接口应在服务器端调用,详细说明参见服务端API

          获取用户反馈列表

          请求地址

          GET https://api.weixin.qq.com/wxaapi/feedback/list?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          typenumber反馈的类型,默认拉取全部类型,详细定义见下面
          pagenumber分页的页数,从1开始
          numnumber分页拉取的数据数量

          请求示例

          {  "page":1,  "num":10}

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          listArray.<Object>反馈列表
          total_numnumber总条数

          反馈类型type的定义

          说明
          1无法打开小程序
          2小程序闪退
          3卡顿
          4黑屏白屏
          5死机
          6界面错位
          7界面加载慢
          8其他异常

          响应示例

          {  "list": [      {          "record_id": 1,          "create_time": 1587571200,          "content": "白屏了",          "phone": 18800000000,          "openid": "openidxxxxxx",          "nickname": "反馈用户昵称",          "head_url": "反馈用户头像",          "type": 1,          "systemInfo": "{}"      }  ],  "total_num": 100,  "errcode": 0}


          operation.getJsErrSearch

          本接口应在服务器端调用,详细说明参见服务端API

          错误查询

          请求地址

          POST https://api.weixin.qq.com/wxaapi/log/jserr_search?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          errmsg_keywordstring错误关键字
          typenumber查询类型,1 为客户端, 2为服务直达
          client_versionstring客户端版本,可以通过 getVersionList 接口拉取, 不传或者传空代表所有版本
          start_timenumber开始时间
          end_timenumber结束时间
          startnumber分页起始值
          limitnumber一次拉取最大值

          请求示例

          {  "errmsg_keyword":"",  "type":1,  "client_version": "",  "start_time": 1587021734,  "end_time": 1587626534,  "start": 1,  "limit": 1  "sceneDesc": "测试数据"}

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          resultsArray.<Object>错误列表
          totalnumber总条数

          响应示例

          {  "results": [      {          "time": 1587571200,          "client_version": "7.0.14",          "app_version": "2.8.21",          "version_error_cnt": 1,          "total_error_cnt": 1,          "errmsg": "setBackgroundAudioState:fail:src is null
          Error: setBackgroundAudioState:fail:src is null
              at fail (https://lib/WASubContext.js:2:876609)
              at Object.fail (https://lib/WASubContext.js:2:115688)
              at b (https://lib/WASubContext.js:2:431732)
              at https://lib/WASubContext.js:2:432886
          "      }  ],  "total": 91,  "errcode": 0}


          operation.getPerformance

          本接口应在服务器端调用,详细说明参见服务端API

          性能监控

          请求地址

          POST https://api.weixin.qq.com/wxaapi/log/get_performance?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          cost_time_typenumber可选值 1(启动总耗时), 2(下载耗时),3(初次渲染耗时)
          default_start_timenumber查询开始时间
          default_end_timenumber查询结束时间
          devicestring系统平台,可选值 "@_all:"(全部),1(IOS), 2(android)
          is_download_codestring是否下载代码包,当 type 为 1 的时候才生效,可选值 "@_all:"(全部),1(是), 2(否)
          scenestring访问来源,当 type 为 1 或者 2 的时候才生效,通过 getSceneList 接口获取
          networktypestring网络环境, 当 type 为 2 的时候才生效,可选值 "@_all:",wifi, 4g, 3g, 2g

          请求示例

          {  "cost_time_type": 2,  "default_start_time": 1572339403,  "default_end_time": 1574931403,  "device": "@_all",  "networktype": "@_all",  "scene": "@_all",  "is_download_code": "@_all"}

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          default_time_datastring错误查询数据(json字符串,结构如下所述的 strbody)
          compare_time_datastring比较数据

          strbody 的结构

          属性类型说明
          ref_datestring日期
          cost_time_typenumber意思同参数里面的 cost_time_type
          cost_timenumber耗时(毫秒)

          响应示例

          {  "default_time_data": "{"list":[{"ref_date":"20191029","cost_time_type":2,"cost_time":1533},{"ref_date":"20191030","cost_time_type":2,"cost_time":1682}]}",  "compare_time_data": "",  "errcode": 0}


          operation.getSceneList

          本接口应在服务器端调用,详细说明参见服务端API

          获取访问来源

          请求地址

          GET https://api.weixin.qq.com/wxaapi/log/get_scene?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          sceneArray.<Object>访问来源

          scene 的结构

          属性类型说明
          namestring来源中文名
          valuestring}number

          响应示例

          {   "errcode": 0,   "errmsg": "ok",   "scene": [      {          "name": "全部",          "value": "@_all"      },      {          "name": "小程序历史列表"          "value": 1      }   ]}


          operation.getVersionList

          本接口应在服务器端调用,详细说明参见服务端API

          获取客户端版本

          请求地址

          GET https://api.weixin.qq.com/wxaapi/log/get_client_version?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          cvlistArray.<Object>版本列表

          cvlist 的结构

          属性类型说明
          typenumber查询类型 1 代表客户端,2 代表服务直达
          client_version_listArray.<String>版本列表

          响应示例

          {   "errcode": 0,   "errmsg": "ok",   "cvlist": [      {          "type": 1,          "client_version_list": []      },      {          "type": 2,          "client_version_list": []      }   ]}


          operation.realtimelogSearch

          本接口应在服务器端调用,详细说明参见服务端API

          实时日志查询

          请求地址

          GET https://api.weixin.qq.com/wxaapi/userlog/userlog_search?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          datestringYYYYMMDD格式的日期,仅支持最近7天
          begintimenumber开始时间,必须是date指定日期的时间
          endtimenumber结束时间,必须是date指定日期的时间
          startnumber0开始返回的数据下标,用作分页,默认为0
          limitnumber20返回的数据条数,用作分页,默认为20
          traceIdstring小程序启动的唯一ID,按TraceId查询会展示该次小程序启动过程的所有页面的日志。
          urlstring小程序页面路径,例如pages/index/index
          idstring用户微信号或者OpenId
          filterMsgstring开发者通过setFileterMsg/addFilterMsg指定的filterMsg字段
          levelnumber日志等级,返回大于等于level等级的日志,level的定义为2(Info)、4(Warn)、8(Error),如果指定为4,则返回大于等于4的日志,即返回Warn和Error日志。

          返回值

          Object

          属性类型说明
          dataObject返回的日志数据和日志条数总量
          listArray.<Object>返回的日志数据列表
          errcodenumber微信侧错误码,下单失败时返回
          errmsgstring微信侧错误信息,下单失败时返回

          list 的结构

          属性类型说明
          levelnumber日志等级,是msg数组里面的所有level字段的或操作得到的结果。例如msg数组里有两条日志,Info(值为2)和Warn(值为4),则level值为6
          libraryVersionstring基础库版本
          clientVersionstring客户端版本
          idstring微信用户OpenID
          timestampnumber打日志的Unix时间戳
          platformnumber1 安卓 2 IOS
          urlstring小程序页面链接
          msgArray.<Object>日志内容数组,log.info等的内容存在这里
          traceidstring小程序启动的唯一ID,按TraceId查询会展示该次小程序启动过程的所有页面的日志。
          filterMsgstring微信用户OpenID

          list.msg 的结构

          属性类型说明
          timenumberlog.info调用的时间
          msgArray.<string>log.info调用的内容,每个参数分别是数组的一项
          levelnumberlog.info调用的日志等级

          errcode 的合法值

          说明最低版本
          -1系统失败
          200002参数错误,date、begintime、endtime必填。date只能是最近三天的日期,endtime必须大于begintime
          200010操作过于频繁,目前限制每分钟50次
          200007无权限

          返回示例

          查询成功 { "errcode": 0, "errmsg": "", "data": { "list": [{ "level": 6, "platform": 1, "libraryVersion": "2.8.3", "clientVersion": "7.0.7", "id": "oXu034-Kl5Et2U0vsexKDsFaon0Q", "timestamp": 1570852796, "msg": [{ "time": 1570852795, "msg": ["hello world"], "level": 2 }, { "time": 1570852795, "msg": ["get msg list mig 10006"], "level": 4 }], "url": "pages/chat/chat", "traceid": "oXu03410akoNqfsrMMswk6Zwwl1U_1570852656", "filterMsg": "NetworkExceed08 ReportTimeTotal" }], "total": 1000 } }


          search.imageSearch

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          本接口提供基于小程序的站内搜商品图片搜索能力

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/imagesearch?access_token=TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          imgArray.<FormData>form-data中媒体文件标识,有filename、filelength、content-type等信息

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息
          itemsArray.<Object>搜索结果列表

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统繁忙,此时请开发者稍候再试
          41005获取图片数据失败,请检查图片数据格式

          items 的结构

          属性类型说明
          titlestring小程序商品页面标题
          img_urlstring小程序商品页面主图url
          pricestring小程序商品页面价格
          pathstring小程序商品页面地址

          请求示例

          curl -F 'img=@test.jpg' "https://api.weixin.qq.com/wxa/imagesearch?access_token=TOKEN"

          云调用请求示例

          // javascript// cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.search.imageSearch({  img: {     contentType: 'image/png',     value: Buffer  }})

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.search.imageSearch
          需在 config.json 中配置 search.imageSearch API 的权限,详情

          请求参数

          属性类型默认值必填说明
          imgArray.<FormData>form-data中媒体文件标识,有filename、filelength、content-type等信息

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息
          itemsArray.<Object>搜索结果列表

          errCode 的合法值

          说明最低版本
          0成功

          items 的结构

          属性类型说明
          titlestring小程序商品页面标题
          imgUrlstring小程序商品页面主图url
          pricestring小程序商品页面价格
          pathstring小程序商品页面地址

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值


          说明最低版本
          -1系统繁忙,此时请开发者稍候再试
          41005获取图片数据失败,请检查图片数据格式


          search.siteSearch

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          小程序内部搜索API提供针对页面的查询能力,小程序开发者输入搜索词后,将返回自身小程序和搜索词相关的页面。因此,利用该接口,开发者可以查看指定内容的页面被微信平台的收录情况;同时,该接口也可供开发者在小程序内应用,给小程序用户提供搜索能力。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/sitesearch?access_token=TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          keywordstring关键词
          next_page_infostring请求下一页的参数,开发者无需理解。为空时查询的是第一页内容,如需查询下一页,把返回参数的next_page_info填充到这里即可

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息
          itemsArray.<Object>搜索结果列表
          has_next_pageboolean是否有下一页
          next_page_infostring请求下一页的参数,开发者无需理解,如需查询下一页结果,把该参数填充到下页请求参数中的next_page_info即可
          hit_countnumber估算索引文档数

          errcode 的合法值

          说明最低版本
          -1系统繁忙,此时请开发者稍候再试
          47101搜索结果总数超过了1000条
          47102next_page_info参数错误

          items 的结构

          属性类型说明
          titlestring小程序页面标题
          descriptionstring小程序页面摘要
          imagestring小程序页面代表图
          pathstring小程序页面路径

          使用示例

          curl -d '{    "query": "微信",    "next_page_info": ""}' https://api.weixin.qq.com/wxa/sitesearch?access_token=TOKEN

          调用成功时的返回示例

          {    "errcode":0,    "errmsg":"ok",    "items": [        {            "title": "<em class="highlight">微信</em>版本更新!",            "description": "...今日,<em class="highlight">微信</em>官方发布<em class="highlight">微信</em>X.Y.Z版本...",            "image": "http://image.weixin.qq.com/1.jpeg",            "path": "pages/normal/index?id=20191210A0C29X00"        },        {            "title": "<em class="highlight">微信</em>小程序发布新功能!",            "description": "<em class="highlight">微信</em>小程序发布了XXX功能...",            "image": "http://image.weixin.qq.com/2.jpeg",            "path": "pages/normal/index?id=20191210A0C29X11"        },    ],    "has_next_page": 1,    "hit_count": 100,    "next_page_info":"eyJwYWdlX3BhcmFtIjpbeyJzdWJzeXNfdHlwZSI6MTAsInNlcnZlcl9vZmZzZXQiOjAsInNlcnZlcl9saW1pdCI6MTIwLCJpbmRleF9zdGVwIjoyMCwiaW5kZXhfb2Zmc2V0IjoyMH1dLCJjbGllbnRfb2Zmc2V0IjowLCJjbGllbnRfbGltaXQiOjEwfQ=="}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.search.siteSearch
          需在 config.json 中配置 search.siteSearch API 的权限,详情

          请求参数

          属性类型默认值必填说明
          keywordstring关键词
          nextPageInfostring请求下一页的参数,开发者无需理解。为空时查询的是第一页内容,如需查询下一页,把返回参数的next_page_info填充到这里即可

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息
          itemsArray.<Object>搜索结果列表
          hasNextPageboolean是否有下一页
          nextPageInfostring请求下一页的参数,开发者无需理解,如需查询下一页结果,把该参数填充到下页请求参数中的next_page_info即可
          hitCountnumber估算索引文档数

          errCode 的合法值

          说明最低版本
          0成功

          items 的结构

          属性类型说明
          titlestring小程序页面标题
          descriptionstring小程序页面摘要
          imagestring小程序页面代表图
          pathstring小程序页面路径

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值


          说明最低版本
          -1系统繁忙,此时请开发者稍候再试
          47101搜索结果总数超过了1000条
          47102next_page_info参数错误


          search.submitPages

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          小程序开发者可以通过本接口提交小程序页面url及参数信息,让微信可以更及时的收录到小程序的页面信息,开发者提交的页面信息将可能被用于小程序搜索结果展示。

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/search/wxaapi_submitpages?access_token=TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          pagesArray.<Object>小程序页面信息列表

          pages 的结构

          属性类型默认值必填说明
          pathstring页面路径
          querystring页面参数

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodestring错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          -1系统繁忙,此时请开发者稍候再试
          0请求成功
          40066递交的页面被sitemap标记为拦截,具体查看errmsg提示。
          40210pages 中的path参数不存在或为空
          40212paegs 当中存在不合法的query,query格式遵循URL标准,即k1=v1&k2=v2
          40219pages不存在或者参数为空
          47001http请求包不是合法的JSON
          47004每次提交的页面数超过1000(备注:每次提交页面数应小于或等于1000)
          47006当天提交页面数达到了配额上限,请明天再试
          85091小程序的搜索开关被关闭。请访问设置页面打开开关再重试
          85083小程序的搜索功能被禁用

          请求示例

          curl -d '{    "pages": [        {            "path": "pages/index/index",            "query": "userName=wechat_user"        },        {            "path": "pages/video/index",            "query": "vid=123"        }    ]}' https://api.weixin.qq.com/wxa/search/wxaapi_submitpages?access_token=TOKEN

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.search.submitPages
          需在 config.json 中配置 search.submitPages API 的权限,详情

          请求参数

          属性类型默认值必填说明
          pagesArray.<Object>小程序页面信息列表

          pages 的结构

          属性类型默认值必填说明
          pathstring页面路径
          querystring页面参数

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodestring错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          -1系统繁忙,此时请开发者稍候再试
          40066递交的页面被sitemap标记为拦截,具体查看errmsg提示。
          40210pages 中的path参数不存在或为空
          40212paegs 当中存在不合法的query,query格式遵循URL标准,即k1=v1&k2=v2
          40219pages不存在或者参数为空
          47001http请求包不是合法的JSON
          47004每次提交的页面数超过1000(备注:每次提交页面数应小于或等于1000)
          47006当天提交页面数达到了配额上限,请明天再试
          85091小程序的搜索开关被关闭。请访问设置页面打开开关再重试
          85083小程序的搜索功能被禁用


          serviceMarket.invokeService

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          调用服务平台提供的服务

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxa/servicemarket?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          servicestring服务 ID
          apistring接口名
          datastring服务提供方接口定义的 JSON 格式的数据
          client_msg_idstring随机字符串 ID,调用方请求的唯一标识

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          template_idstring添加至帐号下的模板id,发送小程序模板消息时所需

          请求数据示例

          {  "service" : "wx79ac3de8be320b71",  "api" : "OcrAllInOne",  "data" : {    "img_url": "http://mmbiz.qpic.cn/mmbiz_jpg/7UFjuNbYxibu66xSqsQqKcuoGBZM77HIyibdiczeWibdMeA2XMt5oibWVQMgDibriazJSOibLqZxcO6DVVcZMxDKgeAtbQ/0",    "data_type": 3,    "ocr_type": 1  },  "client_msg_id" : "id123"}

          返回数据示例

          { "errcode": 0, "errmsg": "ok", "data": "{"idcard_res":{"type":0,"name":{"text":"abc","pos"…0312500}}},"image_width":480,"image_height":304}}"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.serviceMarket.invokeService
          需在 config.json 中配置 serviceMarket.invokeService API 的权限,详情

          请求参数

          属性类型默认值必填说明
          servicestring服务 ID
          apistring接口名
          datastring服务提供方接口定义的 JSON 格式的数据
          clientMsgIdstring随机字符串 ID,调用方请求的唯一标识

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息
          templateIdstring添加至帐号下的模板id,发送小程序模板消息时所需

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          请求数据示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.serviceMarket.invokeService({        service: 'wx79ac3de8be320b71',        api: 'OcrAllInOne',        data: {          imgUrl: 'http://mmbiz.qpic.cn/mmbiz_jpg/7UFjuNbYxibu66xSqsQqKcuoGBZM77HIyibdiczeWibdMeA2XMt5oibWVQMgDibriazJSOibLqZxcO6DVVcZMxDKgeAtbQ/0',          dataType: 3,          ocrType: 1        },        clientMsgId: 'id123'      })    return result  } catch (err) {    return err  }}

          返回数据示例

          {  "errCode": 0,  "errMsg": "openapi.serviceMarket.invokeService:ok",  "data": "{"idcardRes":{"type":0,"name":{"text":"abc","pos"…0312500}}},"imageWidth":480,"imageHeight":304}}"}


          soter.verifySignature

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          SOTER 生物认证秘钥签名验证

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/soter/verify_signature?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          openidstring用户 openid
          json_stringstring通过 wx.startSoterAuthentication 成功回调获得的 resultJSON 字段
          json_signaturestring通过 wx.startSoterAuthentication 成功回调获得的 resultJSONSignature 字段

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errmsgstring错误信息
          errcodenumber错误码
          is_okboolean验证结果

          请求示例

          {  "openid": "$openid",  "json_string": "$resultJSON",  "json_signature": "$resultJSONSignature"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.soter.verifySignature
          需在 config.json 中配置 soter.verifySignature API 的权限,详情

          请求参数

          属性类型默认值必填说明
          openidstring用户 openid
          jsonStringstring通过 wx.startSoterAuthentication 成功回调获得的 resultJSON 字段
          jsonSignaturestring通过 wx.startSoterAuthentication 成功回调获得的 resultJSONSignature 字段

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errMsgstring错误信息
          errCodenumber错误码
          isOkboolean验证结果

          异常

          Object

          抛出的异常

          属性类型说明
          errMsgstring错误信息
          errCodenumber错误码

          errCode 的合法值

          说明最低版本

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.soter.verifySignature({        openid: '$openid',        jsonString: '$resultJSON',        jsonSignature: '$resultJSONSignature'      })    return result  } catch (err) {    return err  }}


          subscribeMessage.addTemplate

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          组合模板并添加至帐号下的个人模板库

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxaapi/newtmpl/addtemplate?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          tidstring模板标题 id,可通过接口获取,也可登录小程序后台查看获取
          kidListArray.<number>开发者自行组合好的模板关键词列表,关键词顺序可以自由搭配(例如 [3,5,4] 或 [4,5,3]),最多支持5个,最少2个关键词组合
          sceneDescstring服务场景描述,15个字以内

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          priTmplIdstring添加至帐号下的模板id,发送小程序订阅消息时所需

          errcode 的合法值

          说明最低版本
          200014模版 tid 参数错误
          200020关键词列表 kidList 参数错误
          200021场景描述 sceneDesc 参数错误
          200011此账号已被封禁,无法操作
          200013此模版已被封禁,无法选用
          200012个人模版数已达上限,上限25个

          请求示例

          content-type: application/json;

          {  "tid":"401",  "kidList":[1,2],  "sceneDesc": "测试数据"}

          响应示例

          {  "errmsg": "ok",  "errcode": 0,  "priTmplId": "9Aw5ZV1j9xdWTFEkqCpZ7jWySL7aGN6rQom4gXINfJs"}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.subscribeMessage.addTemplate
          需在 config.json 中配置 subscribeMessage.addTemplate API 的权限,详情

          请求参数

          属性类型默认值必填说明
          tidstring模板标题 id,可通过接口获取,也可登录小程序后台查看获取
          kidListArray.<number>开发者自行组合好的模板关键词列表,关键词顺序可以自由搭配(例如 [3,5,4] 或 [4,5,3]),最多支持5个,最少2个关键词组合
          sceneDescstring服务场景描述,15个字以内

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息
          priTmplIdstring添加至帐号下的模板id,发送小程序订阅消息时所需

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          200014模版 tid 参数错误
          200020关键词列表 kidList 参数错误
          200021场景描述 sceneDesc 参数错误
          200011此账号已被封禁,无法操作
          200013此模版已被封禁,无法选用
          200012个人模版数已达上限,上限25个

          请求示例

          content-type: application/json;

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.addTemplate({        tid: '401',        kidList: [          1,          2        ],        sceneDesc: '测试数据'      })    return result  } catch (err) {    return err  }}

          响应示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.addTemplate({        errmsg: 'ok',        errcode: 0,        priTmplId: '9Aw5ZV1j9xdWTFEkqCpZ7jWySL7aGN6rQom4gXINfJs'      })    return result  } catch (err) {    return err  }}


          subscribeMessage.deleteTemplate

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          删除帐号下的个人模板

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/wxaapi/newtmpl/deltemplate?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          priTmplIdstring要删除的模板id

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          请求示例

          content-type: application/json;

          {  "priTmplId": "wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc"}

          响应示例

          {  "errmsg": "ok",  "errcode": 0}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.subscribeMessage.deleteTemplate
          需在 config.json 中配置 subscribeMessage.deleteTemplate API 的权限,详情

          请求参数

          属性类型默认值必填说明
          priTmplIdstring要删除的模板id

          请求示例

          content-type: application/json;

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.deleteTemplate({        priTmplId: 'wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc'      })    return result  } catch (err) {    return err  }}

          响应示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.deleteTemplate({        errmsg: 'ok',        errcode: 0      })    return result  } catch (err) {    return err  }}


          subscribeMessage.getCategory

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取小程序账号的类目

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/wxaapi/newtmpl/getcategory?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          dataArray.<Object>类目列表

          data 的结构

          属性类型说明
          idnumber类目id,查询公共库模版时需要
          namestring类目的中文名

          响应示例

          {   "errcode": 0,   "errmsg": "ok",   "data": [       {           "id": 616,           "name": "公交"       }   ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.subscribeMessage.getCategory
          需在 config.json 中配置 subscribeMessage.getCategory API 的权限,详情

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getCategory({})    return result  } catch (err) {    return err  }}

          响应示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getCategory({        errcode: 0,        errmsg: 'ok',        data: [          {            id: 616,            name: '公交'          }        ]      })    return result  } catch (err) {    return err  }}


          subscribeMessage.getPubTemplateKeyWordsById

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取模板标题下的关键词列表

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatekeywords?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          tidstring模板标题 id,可通过接口获取

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          countnumber模版标题列表总数
          dataArray.<Object>关键词列表

          data 的结构

          属性类型说明
          kidnumber关键词 id,选用模板时需要
          namestring关键词内容
          examplestring关键词内容对应的示例
          rulestring参数类型

          请求示例

          {  "tid": "99"}

          响应示例

          {   "errcode": 0,   "errmsg": "ok",   "data": [       {           "kid": 1,           "name": "物品名称",           "example": "名称",           "rule": "thing"       }   ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.subscribeMessage.getPubTemplateKeyWordsById
          需在 config.json 中配置 subscribeMessage.getPubTemplateKeyWordsById API 的权限,详情

          请求参数

          属性类型默认值必填说明
          tidstring模板标题 id,可通过接口获取

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息
          countnumber模版标题列表总数
          dataArray.<Object>关键词列表

          data 的结构

          属性类型说明
          kidnumber关键词 id,选用模板时需要
          namestring关键词内容
          examplestring关键词内容对应的示例
          rulestring参数类型

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getPubTemplateKeyWordsById({        tid: ''      })    return result  } catch (err) {    return err  }}

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getPubTemplateKeyWordsById({        tid: '99'      })    return result  } catch (err) {    return err  }}

          响应示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getPubTemplateKeyWordsById({        errcode: 0,        errmsg: 'ok',        data: [          {            kid: 1,            name: '物品名称',            example: '名称',            rule: 'thing'          }        ]      })    return result  } catch (err) {    return err  }}


          subscribeMessage.getPubTemplateTitleList

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取帐号所属类目下的公共模板标题

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatetitles?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          idsstring类目 id,多个用逗号隔开
          startnumber用于分页,表示从 start 开始。从 0 开始计数。
          limitnumber用于分页,表示拉取 limit 条记录。最大为 30。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          countnumber模版标题列表总数
          dataArray.<Object>模板标题列表

          errcode 的合法值

          说明最低版本
          200016start 参数错误
          200017limit 参数错误
          200018类目 ids 缺失
          200019类目 ids 不合法

          data 的结构

          属性类型说明
          tidnumber模版标题 id
          titlestring模版标题
          typenumber模版类型,2 为一次性订阅,3 为长期订阅
          categoryIdnumber模版所属类目 id

          请求示例

          {  "ids": "2,616",  "start": 0,  "limit": 1}

          响应示例

          {   "errcode": 0,   "errmsg": "ok",   "count": 55,   "data": [       {           "tid": 99,           "title": "付款成功通知",           "type": 2,           "categoryId": "616"       }   ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.subscribeMessage.getPubTemplateTitleList
          需在 config.json 中配置 subscribeMessage.getPubTemplateTitleList API 的权限,详情

          请求参数

          属性类型默认值必填说明
          idsstring类目 id,多个用逗号隔开
          startnumber用于分页,表示从 start 开始。从 0 开始计数。
          limitnumber用于分页,表示拉取 limit 条记录。最大为 30。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息
          countnumber模版标题列表总数
          dataArray.<Object>模板标题列表

          errCode 的合法值

          说明最低版本
          0成功

          data 的结构

          属性类型说明
          tidnumber模版标题 id
          titlestring模版标题
          typenumber模版类型,2 为一次性订阅,3 为长期订阅
          categoryIdnumber模版所属类目 id

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          200016start 参数错误
          200017limit 参数错误
          200018类目 ids 缺失
          200019类目 ids 不合法

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getPubTemplateTitleList({        ids: '',        start: '',        limit: ''      })    return result  } catch (err) {    return err  }}

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getPubTemplateTitleList({        ids: '2,616',        start: 0,        limit: 1      })    return result  } catch (err) {    return err  }}

          响应示例

          {  "errCode": 0,  "errMsg": "openapi.subscribeMessage.getPubTemplateTitleList:ok",  "count": 55,  "data": [    {      "tid": 99,      "title": "付款成功通知",      "type": 2,      "categoryId": "616"    }  ]}


          subscribeMessage.getTemplateList

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          获取当前帐号下的个人模板列表

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          GET https://api.weixin.qq.com/wxaapi/newtmpl/gettemplate?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          dataArray.<Object>个人模板列表

          data 的结构

          属性类型说明
          priTmplIdstring添加至帐号下的模板 id,发送小程序订阅消息时所需
          titlestring模版标题
          contentstring模版内容
          examplestring模板内容示例
          typenumber模版类型,2 为一次性订阅,3 为长期订阅

          响应示例

          {   "errcode": 0,   "errmsg": "ok",   "data": [       {          "priTmplId": "9Aw5ZV1j9xdWTFEkqCpZ7mIBbSC34khK55OtzUPl0rU",          "title": "报名结果通知",          "content": "会议时间:{{date2.DATA}}
          会议地点:{{thing1.DATA}}
          ",          "example": "会议时间:2016年8月8日
          会议地点:TIT会议室
          ",          "type": 2       }   ]}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.subscribeMessage.getTemplateList
          需在 config.json 中配置 subscribeMessage.getTemplateList API 的权限,详情

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息
          dataArray.<Object>个人模板列表

          data 的结构

          属性类型说明
          priTmplIdstring添加至帐号下的模板 id,发送小程序订阅消息时所需
          titlestring模版标题
          contentstring模版内容
          examplestring模板内容示例
          typenumber模版类型,2 为一次性订阅,3 为长期订阅

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getTemplateList({})    return result  } catch (err) {    return err  }}

          响应示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getTemplateList({        errcode: 0,        errmsg: 'ok',        data: [          {            priTmplId: '9Aw5ZV1j9xdWTFEkqCpZ7mIBbSC34khK55OtzUPl0rU',            title: '报名结果通知',            content: '会议时间:{{date2.DATA}}
          会议地点:{{thing1.DATA}}
          ',            example: '会议时间:2016年8月8日
          会议地点:TIT会议室
          ',            type: 2          }        ]      })    return result  } catch (err) {    return err  }}


          subscribeMessage.send

          本接口应在服务器端调用,详细说明参见服务端API
          本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
          wx-server-sdk >= 0.4.0

          发送订阅消息

          调用方式:

          • HTTPS 调用
          • 云调用

          HTTPS 调用

          请求地址

          POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          touserstring接收者(用户)的 openid
          template_idstring所需下发的订阅模板id
          pagestring点击模板卡片后的跳转页面,仅限本小程序内的页面。支持带参数,(示例index?foo=bar)。该字段不填则模板无跳转。
          dataObject模板内容,格式形如 { "key1": { "value": any }, "key2": { "value": any } }
          miniprogram_statestring跳转小程序类型:developer为开发版;trial为体验版;formal为正式版;默认为正式版
          langstring进入小程序查看”的语言类型,支持zh_CN(简体中文)、en_US(英文)、zh_HK(繁体中文)、zh_TW(繁体中文),默认为zh_CN

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          40003touser字段openid为空或者不正确
          40037订阅模板id为空不正确
          43101用户拒绝接受消息,如果用户之前曾经订阅过,则表示用户取消了订阅关系
          47003模板参数不准确,可能为空或者不满足规则,errmsg会提示具体是哪个字段出错
          41030page路径不正确,需要保证在现网版本小程序中存在,与app.json保持一致

          接口限制

          次数限制:开通支付能力的是3kw/日,没开通的是1kw/日。

          请求示例

          {  "touser": "OPENID",  "template_id": "TEMPLATE_ID",  "page": "index",  "miniprogram_state":"developer",  "lang":"zh_CN",  "data": {      "number01": {          "value": "339208499"      },      "date01": {          "value": "2015年01月05日"      },      "site01": {          "value": "TIT创意园"      } ,      "site02": {          "value": "广州市新港中路397号"      }  }}

          订阅消息参数值内容限制说明

          参数类别参数说明参数值限制说明
          thing.DATA事物20个以内字符可汉字、数字、字母或符号组合
          number.DATA数字32位以内数字只能数字,可带小数
          letter.DATA字母32位以内字母只能字母
          symbol.DATA符号5位以内符号只能符号
          character_string.DATA字符串32位以内数字、字母或符号可数字、字母或符号组合
          time.DATA时间24小时制时间格式(支持+年月日),支持填时间段,两个时间点之间用“~”符号连接例如:15:01,或:2019年10月1日 15:01
          date.DATA日期年月日格式(支持+24小时制时间),支持填时间段,两个时间点之间用“~”符号连接例如:2019年10月1日,或:2019年10月1日 15:01
          amount.DATA金额1个币种符号+10位以内纯数字,可带小数,结尾可带“元”可带小数
          phone_number.DATA电话17位以内,数字、符号电话号码,例:+86-0766-66888866
          car_number.DATA车牌8位以内,第一位与最后一位可为汉字,其余为字母或数字车牌号码:粤A8Z888挂
          name.DATA姓名10个以内纯汉字或20个以内纯字母或符号中文名10个汉字内;纯英文名20个字母内;中文和字母混合按中文名算,10个字内
          phrase.DATA汉字5个以内汉字5个以内纯汉字,例如:配送中

          符号表示除中文、英文、数字外的常见符号,不能带有换行等控制字符。 时间格式支持HH:MM:SS或者HH:MM。 日期包含年月日,为y年m月d日,y年m月、m月d日格式,或者用‘-’、‘/’、‘.’符号连接,如2018-01-01,2018/01/01,2018.01.01,2018-01,01-01。 每个模板参数都会以类型为前缀,例如第一个数字模板参数为number01.DATA,第二个为number02.DATA

          例如,模板的内容为

          姓名: {{name01.DATA}}金额: {{amount01.DATA}}行程: {{thing01.DATA}}日期: {{date01.DATA}}

          则对应的json为

          {  "touser": "OPENID",  "template_id": "TEMPLATE_ID",  "page": "index",  "data": {      "name01": {          "value": "某某"      },      "amount01": {          "value": "¥100"      },      "thing01": {          "value": "广州至北京"      } ,      "date01": {          "value": "2018-01-01"      }  }}

          云调用

          云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

          接口方法

          openapi.subscribeMessage.send
          需在 config.json 中配置 subscribeMessage.send API 的权限,详情

          请求参数

          属性类型默认值必填说明
          touserstring接收者(用户)的 openid
          templateIdstring所需下发的订阅模板id
          pagestring点击模板卡片后的跳转页面,仅限本小程序内的页面。支持带参数,(示例index?foo=bar)。该字段不填则模板无跳转。
          dataObject模板内容,格式形如 { "key1": { "value": any }, "key2": { "value": any } }
          miniprogramStatestring跳转小程序类型:developer为开发版;trial为体验版;formal为正式版;默认为正式版
          langstring进入小程序查看”的语言类型,支持zh_CN(简体中文)、en_US(英文)、zh_HK(繁体中文)、zh_TW(繁体中文),默认为zh_CN

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          0成功

          异常

          Object

          抛出的异常

          属性类型说明
          errCodenumber错误码
          errMsgstring错误信息

          errCode 的合法值

          说明最低版本
          40003touser字段openid为空或者不正确
          40037订阅模板id为空不正确
          43101用户拒绝接受消息,如果用户之前曾经订阅过,则表示用户取消了订阅关系
          47003模板参数不准确,可能为空或者不满足规则,errmsg会提示具体是哪个字段出错
          41030page路径不正确,需要保证在现网版本小程序中存在,与app.json保持一致

          请求示例

          const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.send({        touser: 'OPENID',        page: 'index',        lang: 'zh_CN',        data: {          number01: {            value: '339208499'          },          date01: {            value: '2015年01月05日'          },          site01: {            value: 'TIT创意园'          },          site02: {            value: '广州市新港中路397号'          }        },        templateId: 'TEMPLATE_ID',        miniprogramState: 'developer'      })    return result  } catch (err) {    return err  }}


          为了帮助开发者简单和高效地开发微信小程序,我们推出了全新的开发者工具,集成了开发调试、代码编辑及程序发布等功能。

          devtools

          扫码登录


          启动工具时,开发者需要使用已在后台绑定成功的微信号扫描二维码登录,后续所有的操作都会基于这个微信帐号

          启动页

          登录页

          在登录页,可以使用微信扫码登陆开发者工具,开发者工具将使用这个微信帐号的信息进行小程序的开发和调试。

          login

          项目列表

          登录成功后,会看到已经存在的项目列表和代码片段列表,
          在项目列表可以选择公众号网页调试,进入到公众号网页调试模式
          projectlist

          新建项目

          当符合以下条件时,可以在本地创建一个小程序项目

          1. 需要一个小程序的 AppID;如没有 AppID,可以选择申请使用测试号。
          2. 登录的微信号需要是该 AppID 的开发者;
          3. 需要选择一个空目录,或者选择的非空目录下存在 app.json 或者 project.config.json。当选择空目录时,可以选择是否在该目录下生成一个简单的项目。

          addproject

          多开项目

          工具支持同时打开多个项目,每次打开项目时会从新窗口打开,入口有以下几种:

          1. 从项目选择页打开项目,处于项目窗口时可以从菜单栏的项目 -> 查看所有项目打开项目选择页
          2. 从菜单栏的最近打开项目列表中打开的项目会从新窗口打开
          3. 新建项目
          4. 命令行或 HTTP 调用工具打开项目

          管理项目

          对本地项目进行删除和批量删除

          projectmanage


          主界面

          开发者工具主界面,从上到下,从左到右,分别为:菜单栏、工具栏、模拟器、编辑器、调试器 五大部分。

          parts

          菜单栏

          微信web开发者工具

          切换帐号:快速切换登录用户关于:关于开发者工具检查更新:检查版本更新开发者论坛:前往开发者论坛开发者文档:前往开发者文档调试:调试开发者工具、调试编辑器;如果遇到疑似开发者工具或者编辑器的 bug,可以打开调试工具查看是否有出错日志,欢迎在论坛上反馈相关问题更换开发模式:快速切换公众号网页调试和小程序调试退出:退出开发者工具

          项目

          新建项目:快速新建项目打开最近:可以查看最近打开的项目列表,并选择是否进入对应项目查看所有项目:新窗口打开启动页的项目列表页关闭当前项目:关闭当前项目,回到启动页的项目列表页

          文件

          新建文件保存保存所有关闭文件

          编辑:可以查看编辑相关的操作和快捷键

          工具

          编译:编译当前小程序项目刷新:与编译的功能一致,由于历史原因保留对应的快捷键 ctrl(⌘) + R编译配置:可以选择普通编译或自定义编译条件前后台切换:模拟客户端小程序进入后台运行和返回前台的操作清除缓存:清除文件缓存、数据缓存、以及授权数据

          界面:控制主界面窗口模块的显示与隐藏

          设置:

          外观设置:控制编辑器的配色主题、字体、字号、行距编辑设置:控制文件保存的行为,编辑器的表现代理设置:选择直连网络、系统代理和手动设置代理通知设置:设置是否接受某种类型的通知

          工具栏

          点击用户头像可以打开个人中心,在这里可以便捷的切换用户和查看开发者工具收到的消息。

          noticecenter

          用户头像右侧是控制主界面模块显示/隐藏的按钮。至少需要有一个模块显示。

          showandhide

          工具栏中间,可以选择普通编译,也可以新建并选择自定义条件进行编译和预览。

          通过切后台按钮,可以模拟小程序进入后台的情况

          background

          工具栏上提供了清缓存的快速入口。可以便捷的清除工具上的文件缓存、数据缓存、还有后台的授权数据,方便开发者调试。

          工具栏右侧是开发辅助功能的区域,在这里可以上传代码、申请测试、上传腾讯云、查看项目信息

          righttools

          工具栏管理

          在工具栏上点击鼠标右键,可以打开工具栏管理

          toolbarmanager

          模拟器

          模拟器可以模拟小程序在微信客户端的表现。小程序的代码通过编译后可以在模拟器上直接运行。

          开发者可以选择不同的设备,也可以添加自定义设备来调试小程序在不同尺寸机型上的适配问题。

          device

          在模拟器底部的状态栏,可以直观地看到当前运行小程序的场景值,页面路径及页面参数

          独立窗口

          点击 模拟器/调试器 右上角的按钮可以使用独立窗口显示 模拟器/调试器

          popup

          poped


          项目页卡主要有三大功能:


          显示当前项目细节

          包括图标、AppID、第三方平台名(只有第三方平台的开发小程序才会显示)、目录信息、上次提交代码的时间以及代码包大小。


          基础库版本切换

          开发者可以在此选择任意基础库版本,用于开发和调试旧版本兼容问题。

          clientlib


          项目配置

          ES6 转 ES5

          在 0.10.101000 以及之后版本的开发工具中,会默认使用babel将开发者代码ES6语法转换为三端都能很好支持的ES5的代码,帮助开发者解决环境不同所带来的开发问题。开发者可以在项目设置中关闭这个功能。详情

          需要注意的是:

          • 为了提高代码质量,在开启ES6转换功能的情况下,默认启用 javasctipt 严格模式,请参考 "use strict"

          压缩代码

          开启此选项,开发工具在上传代码时候将会帮助开发者压缩javascript代码,减小代码包体积。

          样式补全

          开启此选项,开发工具会自动检测并补全缺失样式,保证在低版本系统上的正常显示。尽管可以规避大部分的问题 ,还是建议开发者需要在 iOS 和 Android 上分别检查小程序的真实表现。

          代码保护

          开启此选项,开发者工具会尝试对项目代码进行保护,主要是对文件进行扁平化处理并替换 require 引用的文件名,以下情况不适合使用此功能

          1. 对于小程序只有简单页面的情况下,开启此功能效果不佳
          2. 有文件超过 500kb,且其中有使用 require 引用项目中的文件的情况,在运行时可能会报文件没有找到
          3. 动态引用的情况,如 var a = 'somefile.js'; require(a);
          4. 将 require 函数赋值给其他变量的情况,如 var a = require; a('somefile.js');
          5. 将 require 作为二元运算符的参数的情况,如 require + 1;
          6. 使用 ... 运算符且未开启 ES6 转 ES5 的情况

          不校验请求域名及 TLS 版本

          正式发布的小程序的网络请求是需要校验合法域名以及域名的 TLS 版本,可以在 mp 管理后台进行配置。 在开发过程中可以开启此选项,开发工具将不会校验安全域名,以及 TLS 版本,帮助在开发过程中更方便的完成调试工作。

          启用多核心编译

          在四核及以上的电脑上此选项可见。启用此选项,会充分利用 CPU 资源来编译项目的 JS 代码,提高编译的效率。可以选择关闭此选项。


          域名信息

          将显示小程序的安全域名信息,合法域名可在 mp 管理后台进行设置。

          host


          设置页提供对编辑器(外观和代码编辑)、代理和通知的配置。菜单栏上点击设置,或者使用快捷键 ctrl(⌘) + , 可以打开设置页。

          入口

          菜单栏上点击设置可以打开设置页。设置页侧边栏分别是编辑器、代理和通知的配置。

          settings_main

          编辑器配置

          编辑器支持配置外观和代码编辑器习惯和风格。

          编辑器外观配置

          • 主题:白色、深色、黑色
          • 字体
          • 字号
          • 行距 

          编辑配置支持

          • 修改文件时自动保存
          • 编译时自动保存所有文件
          • 文件保存时自动编译小程序
          • 自动折行
          • 用空格代替 Tab
          • 代码缩略图
          • 总是在新标签页打开文件
          • Git 比较文件内容时,忽略 Windows 风格回车符
          • Tab 大小

          如果选中了 “总是在新标签页打开文件”,则在编辑器目录树点击文件时,总是会在一个新标签页中打开此文件,而非在临时标签页中打开。

              


          代理配置

          可以配置不使用代理,或使用系统代理,或使用自定义代理。   


          通知配置

          可以配置系统消息和开发者社区消息通知。

          settings_bbs

          快捷键

          本节介绍一些快捷键的使用。

          Mac OS 快捷键Windows 快捷键说明
          ⌘ + Q退出开发者工具
          ⇧ + ⌘ + Nshift + ctrl + N新建项目
          ⇧ + ⌘ + Wshift + ctrl + W关闭当前项目

          文件
          ⌘ + Nctrl + N新建文件
          ⌘ + Sctrl + S保存文件
          ⇧ + ⌘ + Sshift + ctrl + S保存所有文件
          ⌘ + Wctrl + W关闭当前文件

          编辑
          ⌘ + Zctrl + Z撤销
          ⇧ + ⌘ + Zshift + ctrl + Z重做
          ⌘ + Cctrl + C复制
          ⌘ + Xctrl + X剪切
          ⌘ + Vctrl + V粘贴
          ⌘ + [ctrl + [代码左缩进
          ⌘ + ]ctrl + ]代码右缩进
          ⇧ + ⌥ + Fshift + alt + F格式化代码
          ⌥ + ⬆alt + ⬆代码上移一行
          ⌥ + ⬇alt + ⬆代码上移一行
          ⇧ + ⌥ + ⬆shift + alt + ⬆复制并向上粘贴
          ⇧ + ⌥ + ⬇shift + alt + ⬆复制并向下粘贴
          ⌘ + Pctrl + P跳到文件
          ⌘ + Ectrl + E跳到最近文件
          ⌘ + ⌥ + ⬅ctrl + alt + ⬅打开当前文件编辑器左边的文件
          ⌘ + ⌥ + ➡ctrl + alt + ➡打开当前文件编辑器右边的文件
          ⌘ + Fctrl + F文件内搜索
          ⇧ + ⌘ + Fshift + ctrl + F项目内搜索
          ⇧ + ⌘ + Rshift + ctrl + R焦点在编辑器内,表示替换

          工具
          ⌘ + Bctrl + B编译项目
          ⌘ + Rctrl + R焦点在编辑器外,编译项目
          ⇧ + ⌘ + Pshift + ctrl + P预览代码
          ⇧ + ⌘ + Ushift + ctrl + U上传代码

          界面
          ⌘ + ,ctrl + ,打开设置窗口

          编辑区可以对当前项目进行代码编写和文件的添加、删除以及重命名等基本操作。


          文件格式

          因 iOS 下仅支持 UTF8 编码格式,最新版本的开发者工具会在上传代码时候对代码文件做一次编码格式校验。


          文件支持

          工具目前提供了5种文件的编辑:wxmlwxssjsjson、wxs以及图片文件的预览。


          文件操作

          新建页面有两种方式

          1. 在目录树上右键,选择新建 Page,将自动生成页面所需要的 wxml、wxss、js、json
          2. 在 app.json 的 pages 字段,添加需要新建的页面的路径,将会自动生成该页面所需要的文件

          自动保存

          编辑代码后,工具会自动帮助用户保存当前的代码编辑状态,直接关闭工具或者切换到别的项目,并不会丢失已经编辑的文件状态,但需要注意的是,只有用户主动保存文件,修改内容才会真实的写到硬盘上。

          如果设置中开启了 “修改文件时自动保存”(设置-编辑设置-修改文件自动保存),工具在修改文件时会自动保存到硬盘中,无需手动保存的效果。

          设置中开启 “编译时自动保存所有文件”(设置-编译设置-编译时自动保存所有文件),在点击编译时自动保存所有文件的效果。

          实时预览


          如果设置中开启了“文件保存时自动编译小程序”(位置在:设置 - 编辑 - 文件保存时自动编译小程序),那么当 js, json, wxml 或 wxss 文件修改时,可以通过模拟器实时预览编辑的情况:

          实时预览

          自动补全

          同大部分编辑器一样,我们提供了完善的自动补全

          • js 文件编辑会帮助开发补全所有的 API 及相关的注释解释,并提供代码模板支持
          • wxml 文件编辑会帮助开发者直接写出相关的标签和标签中的属性
          • json 文件编辑会帮助开发者补全相关的配置,并给出实时的提示

          js 补全

          edit1_1

          代码模板支持

          edit1_2 

          json 补全

          edit3 

          wxml 补全

          edit4 


          TypeScript 支持

          如果项目需要使用 TypeScript 语言开发,开发者工具在创建项目选择快速启动模板时,提供了使用 TypeScript 语言的 QuickStart 项目,可以选择创建此项目并进行后续开发。

          要构建并使用 TypeScript 项目,可能需要安装 npm。通过自定义预处理,可以实现在编译前运行 tsc 以将其编译到 js 文件。

          如需配置 TypeScript 编译选项,请参考 tsconfig.json 的配置。

          注:小程序仅支持运行 JS 文件,因此所有的 TS 文件都默认不会被打包上传。

          Git 状态展示

          如果所在的小程序工程目录(project.config.json 所在目录)存在 Git 仓库,编辑器可以展示目前的 Git 状态。

          目录树

          如图所示,当某些文件存在变动时,目录树的文件右侧将展示相应的图标来表明这一状态。当某一处于收起状态的目录下存在有变动的文件时,此目录的右侧亦会展示一个圆点图标表明此情况。

          文件图标状态的含义如下:

          图标含义
          U文件未追踪(Untracked)
          A新文件(Added, Staged)
          M文件有修改(Modified)
          +M文件有修改(Modified, Staged)
          C文件有冲突(Conflict)
          D文件被删除(Deleted)

          文件夹目录图标状态的含义如下:

          图标含义
          小红点目录下至少存在一个删除状态的文件
          小橙点目录下至少存在一个冲突状态的文件
          小蓝点目录下至少存在一个未追踪状态的文件
          小绿点目录下至少存在一个修改状态的文件

          如果某一文件存在修改(Modified),可以右键点击此文件,并选择 “与上一版本比较”,则可以查看当前工作区文件与 HEAD 版本的比较。

          文件编辑

          存在 Git 仓库时,状态栏会展示此 Git 仓库目前的分支信息。例如,下图表明目前 Git 仓库处于 v2 分支。

          同时,编辑文件内容时,将会在所编辑代码左侧实时显示相对于上一版本内容的比较。

          样式说明如下:

          文件夹目录图标状态的含义如下:

          样式含义
          蓝色线条此处的代码有变动
          绿色线条此处的代码是新增的
          红色三角箭头此处有代码被删除

          Windows 风格回车设置

          如需忽略 Windows 风格的回车符,可以前往 “设置” - “编辑”,并勾选 “Git 比较文件内容时,忽略 Windows 风格回车符”。

          勾选后,在编辑文件进行内容比较时,所有 Windows 风格的回车符将被当作 Unix 风格的回车符对待。


          项目配置文件

          可以在项目根目录使用 project.config.json 文件对项目进行配置。

          字段名类型说明
          miniprogramRootPath String指定小程序源码的目录(需为相对路径)
          qcloudRootPath String指定腾讯云项目的目录(需为相对路径)
          pluginRootPath String指定插件项目的目录(需为相对路径)
          compileTypeString编译类型
          settingObject项目设置
          libVersionString基础库版本
          appidString项目的 appid,只在新建项目时读取
          projectnameString项目名字,只在新建项目时读取
          packOptionsObject打包配置选项
          debugOptionsObject调试配置选项
          scriptsObject自定义预处理

          compileType 有效值

          名字说明
          miniprogram当前为普通小程序项目
          plugin当前为小程序插件项目

          setting 中可以指定以下设置

          字段名类型说明
          es6Boolean是否启用 es6 转 es5
          postcssBoolean上传代码时样式是否自动补全
          minifiedBoolean上传代码时是否自动压缩
          urlCheckBoolean是否检查安全域名和 TLS 版本
          uglifyFileNameBoolean是否进行代码保护

          scripts 中指定自定义预处理的命令

          名字说明
          beforeCompile编译前预处理命令
          beforePreview预览前预处理命令
          beforeUpload上传前预处理命令

          packOptions

          packOptions 用以配置项目在打包过程中的选项。打包是预览、上传时对项目进行的必须步骤。

          目前可以指定 packOptions.ignore 字段,用以配置打包时对符合指定规则的文件或文件夹进行忽略,以跳过打包的过程,这些文件或文件夹将不会出现在预览或上传的结果内。

          packOptions.ignore 为一对象数组,对象元素类型如下:

          字段名类型说明
          valuestring路径1或取值
          typestring类型

          其中,type 可以取的值为 folder、file、suffix、prefix、regexp2、glob2,分别对应文件夹、文件、后缀、前缀、正则表达式、Glob 规则。所有规则值都会自动忽略大小写。

          注 1: value 字段的值若表示文件或文件夹路径,以小程序目录 (miniprogramRoot) 为根目录。

          注 2: regexp、glob 仅 1.02.1809260 及以上版本工具支持。

          示例配置如下。

          {  "packOptions": {    "ignore": [{      "type": "file",      "value": "test/test.js"    }, {      "type": "folder",      "value": "test"    }, {      "type": "suffix",      "value": ".webp"    }, {      "type": "prefix",      "value": "test-"    }, {      "type": "glob",      "value": "test/**/*.js"    }, {      "type": "regexp",      "value": ".jsx$"    }]  }}

          注: 这部分设置的更改可能需要重新打开项目才能生效。

          debugOptions

          debugOptions 用以配置在对项目代码进行调试时的选项。

          目前可以指定 debugOptions.hidedInDevtools 字段,用以配置调试时于调试器 Sources 面板隐藏源代码的文件。

          hidedInDevtools 的配置规则和 packOptions.ignore 是一致的。

          当某个 js 文件符合此规则时,调试器 Sources 面板中此文件源代码正文内容将被隐藏,显示为:

          // xxx.js has been hided by project.config.json
          注:配置此规则后,可能需要关闭并重新打开项目才能看到效果。

          项目配置示例:

          {  "miniprogramRoot": "./src",  "qcloudRoot": "./svr",  "setting": {    "postcss": true,    "es6": true,    "minified": true,    "urlCheck": false  },  "packOptions": {    "ignore": []  },  "debugOptions": {}}

          快捷键

          见工具菜单栏

          程序调试主要有三大功能区:模拟器调试工具小程序操作区

          模拟器

          模拟器模拟微信小程序在客户端真实的逻辑表现,对于绝大部分的 API 均能够在模拟器上呈现出正确的状态。

          模拟器

          编译代码

          点击工具左下角的编译按钮或者使用快捷键 Ctrl(Command) + B,可以编译当前代码,并自动刷新模拟器。

          同时为了帮助开发者调试具体页面或者进入的场景值,如同,开发者可以选择自定义编译模式。

          wxml


          自定义预处理

          projectsetting

          在项目设置页卡,我们提供了以下几个默认的预处理,可以解决大部分的代码文件预处理的问题

          1. ES6 转 ES5(可以应用于编译、预览、上传),使用 "babel-core": "^6.26.0"
          2. 上传代码时样式自动补全,使用 "postcss": "^6.0.1"
          3. 上传代码时自动压缩,使用 "uglify-js": "3.0.27"

          对于高级开发者来说,完全可以自己编写自动化构建脚本对代码文件进行预处理,所以我们提供了 启用自定义处理命令 选项 开发者可以指定 编译前/预览前/上传前 需要预处理的命令 开发者工具使用 shell 的方式运行指定的命令,并在控制台中输出命令的执行日志

          预处理命令的执行顺序

          1. 自定义预处理命令
          2. 默认预处理命令
          3. 编译/预览/上传

          注:

          1. 编译前预处理命令,需要手动点击 "编译" 按钮,或者使用快捷键编译才能触发。文件修改无法触发该命令。
          2. Mac 版本的开发者工具无法复用 bash 中的 Path 环境变量。可能需要手动设置系统的 Path 环境变量,才能正常执行命令。

          调试工具

          调试工具分为 7 大功能模块:Wxml、Console、Sources、Network、Appdata、Storage、Sensor

          Wxml Panel

          Wxml Panel 用于帮助开发者开发 Wxml 转化后的界面。在这里可以看到真实的页面结构以及结构对应的 wxss 属性,同时可以通过修改对应 wxss 属性,在模拟器中实时看到修改的情况。通过调试模块左上角的选择器,还可以快速找到页面中组件对应的 wxml 代码。

          wxml

          Sources panel

          Sources panel 用于显示当前项目的脚本文件,同浏览器开发不同,微信小程序框架会对脚本文件进行编译的工作,所以在 Sources panel 中开发者看到的文件是经过处理之后的脚本文件,开发者的代码都会被包裹在 define 函数中,并且对于 Page 代码,在尾部会有 require 的主动调用。

          sources

          Network panel

          Netwrok Pannle 用于观察和显示 request 和 socket 的请求情况

          network

          注:uploadFile 和 downloadFile 暂时不支持在 Network Panel 中查看

          Appdata panel

          Appdata panel 用于显示当前项目当前时刻 appdata 具体数据,实时地反馈项目数据情况,可以在此处编辑数据,并及时地反馈到界面上。

          appdata

          Storage panel

          Storage panel 用于显示当前项目的使用 wx.setStorage 或者 wx.setStorageSync 后的数据存储情况。

          storage


          Console Pannel

          Console Pannel 有两大功能:

          • 开发者可以在此输入和调试代码

            console1

          • 小程序的错误输出,会显示在此处

            4

          Sensor panel

          Sensor panel 有两大功能:

          • 开发者可以在这里选择模拟地理位置

            location

          • 开发可以在这里模拟移动设备表现,用于调试重力感应 API

            accelerometerchange



          小程序操作区

          小程序操作区帮助开发者模拟一些客户端的环境操作。例如当用户从小程序中回到聊天窗口,会触发一个小程序被设置为后台的api。

          5

          当小程序使用到多窗口的时候,可以在顶部操作区进行页面切换,需要注意的是这个操作只是为了方便开发者才存在的,在真实的微信客户端中是不会有的。

          7


          自定义数据上报

          开发者工具上可以编辑和调试自定义分析的数据上报功能,点击菜单栏中的 “工具 - 自定义分析” 即可弹窗打开自定义分析:

          event_list

          在页面中可以新建、查看或修改事件,在修改事件的页面中编辑完毕后,点击底部的保存并测试按钮将保存当前配置,同时工具将在调试器上提示收到最新配置,并展示配置信息,展示的内容包括事件的 ID 和名称,以及每个动作的触发条件和上报数据:

          begin_test

          接着可以在模拟器中操作和触发事件。在模拟器中刷新小程序也将获取该测试配置,除非窗口被关闭。窗口关闭后模拟器不会再收到配置。当事件被触发上报时,工具上会展示上报信息,包括事件 ID、触发页面、触发方式、触发时动作、以及上报的字段值和数据:

          report_ide

          同时可以在窗口中点击 “同步结果” 会同步显示上报的数据:

          report_mp

          关闭窗口后,配置将全部失效,模拟器不再收到配置并不再触发上报(小程序中使用 wx.reportAnalytics API 进行的数据上报仍会在工具中输出)。 测试成功后,可到小程序后台发布事件配置,即可正式生效收集所定义的事件数据。


          自动预览

          自动预览可以实现编写小程序时快速预览,免去了每次查看小程序效果时都要扫码或者使用小程序开发助手的麻烦。只需按下快捷键,保持前台运行的微信即可自动唤出或刷新小程序。

          要使用自动预览功能,需要配合 6.6.7 及以上的微信客户端版本。


          要开始使用 “自动预览” 功能,可以在打开预览二维码的时候,点击 “自动预览” 标签以切换到自动预览模式。切换到自动预览模式后,只需按下预览快捷键,或者点击浮窗上的 “编译并预览” 按钮,即可触发自动预览。此时工具会上传代码,保持前台运行的微信客户端会自动刷新当前开发的小程序。

          当自动预览成功时,工具栏上的预览图标会显示为一个绿勾。如果预览出错,则会显示为一个红色惊叹号,可以点击查看详情。

          注意,自动预览功能仅限与登陆开发者工具的同帐号微信使用。如需换回普通预览模式,只需要点击 “扫描二维码预览” 标签即可。

          用户可以在快捷键设置里自定义预览快捷键。

          13


          特殊场景调试

          小程序开发者工具是对微信客户端的模拟,受限于桌面设备同移动设备的差异,以及微信的一些特有数据,同时考虑到开发的便捷性,部分 API 在工具和微信中有所不同。

          扫码接口

          同手机端直接调用摄像头来扫码不同,在 PC 或者 Mac 上调用摄像头来扫码完成调试是一个低效的行为,所以在开发工具上调用二维码扫码 API 后,开发者可以选择一个本地的图片来进行后续的逻辑调试,而不是真正的启用摄像头来扫码,流程有所不同,但是接口的输入和输出是一致的。

          微信支付

          最新版本的开发者工具已经支持微信支付的调试,但是为了兼顾到安全,同手机上直接调用微信支付有所不同:

          • 新绑定的开发者需要 24 小时后才有权限进行微信支付的调试
          • 开发者在工具上调用微信支付的 API 后,开发工具会出现一个二维码,开发者必须使用当前开发所使用的微信号扫码后在手机上完成支付的流程
          • 工具会同步移动端微信支付的回包到工具中,开发者自行进行后续的操作

          使用的交互有所不同,但是接口的输入输出工具同客户端是保持一致的。

          启动使用自定义参数

          在日常使用中,用户可以通过扫码、分享打开一个小程序,这时候会依据设置的启动页面:path 跳转到对应的小程序页面(不一定是首页)并且可以携带参数:query。在开发者工具中,开发者同样可以通过自定义编译条件的方式来达到调试不同启动页面和启动参数的目的。

          例如下图是选择进入页面是 page/API/index,参数 是 name=can

          args

          进入场景值

          在微信客户端中,用户可能在各个场景下打开小程序 详情 ,然而在开发者工具中是没有真实的环境去模拟这些场景的。开发者可以通过条件编译的方式来达到调试不同场景的目的。

          sence

          普通的转发

          开发者工具上调用转发是一个模拟的行为,并不会真实的转发给用户,开发可以通过这个模拟行为判断是否正确的调用了转发 API。

          带 shareTicket 的转发

          带 shareTicket 的转发可以获取到更多的转发信息,例如群聊的名称以及群的标识 openGId。在小程序开发者工具上,开发者可以通过以下方式来调试带 shareTicket 的转发。

          调用 wx.showShareMenu 的参数 withShareTicket 为 true 时,点击模拟器右上角菜单后出现的转发按钮,会出现一个测试群列表,如图:

          withShareTicket

          开发者点击选取任何一个群,可以通过接口的回包获取到 shareTicket ,通过调用 wx.getShareInfo 可以获取到相关转发的信息

          当开发者需要调试从某一个群点开,并且带有 shareTicket 的场景时,可以使用自定义编译中的 1044:群聊会话中的小程序消息卡片(带 shareTicket) 同时可以选择任一模拟测试群,如图

          withShareTicket

          预览使用自定义编译条件

          同 启动使用自定义参数 相同,提交预览时,开发者可以通过自定义预览的方式来达到在移动设备上调试不同启动页面和启动参数 的目的。我们可以选择已经创建好的自定义编译条件进行预览。

          跳转小程序调试支持

          小程序跳转开发调试可以分为两个部分

          调试小程序是否能够正确的跳转

          出于小程序代码的安全考虑,在工具上调用 wx.navigateToMiniProgram 的时候,开发者工具不会真实的打开和跳转到另外的小程序,但是工具会判断当前小程序与需要跳转的小程序之间的绑定关系,输出相关信息给到开发者。开发者可以根据成功或者失败的回调函数来判断调用是否成功。

          调试被打开的小程序时候正确的接收参数

          选择 自定义编译 进入场景选择 1037 从小程序进入 可以调试小程序被打开时候是否接收到了正确的参数并做了相关处理。

          navigateToMiniProgram

          选择 自定义编译 进入场景选择 1038 从小程序返回 可以调试小程序返回时候是否接收到了正确的参数并做了相关处理。

          navigateToMiniProgram


          真机调试

          真机远程调试功能可以实现直接利用开发者工具,通过网络连接,对手机上运行的小程序进行调试,帮助开发者更好的定位和查找在手机上出现的问题。

          调试流程

          要发起一个真机远程调试流程,需要先点击开发者工具的工具栏上 “远程调试” 按钮。


          此时,工具会将本地代码进行处理打包并上传,就绪之后,使用手机客户端扫描二维码即可弹出调试窗口,开始远程调试。

          远程调试窗口

          使用手机扫描此二维码,即可开始远程调试。

          要结束调试,直接关闭此调试窗口,或点击右下角 “结束调试” 按钮即可。


          远程调试窗口分为两部分,分别是左侧的调试器视图、右侧的信息视图。开发者可以在调试器里直接进行代码的调试,并查看 Storage 情况;信息视图则可以查看目前与手机和服务器的连接情况,以及发生的错误信息等。

          调试器

          在远程调试的调试器里,开发者可以在 Console 面板里对代码进行调试,在 Sources 面板里查看小程序的源代码并进行断点单步调试,在 Storage 面板里查看小程序的 Storage 使用情况等。


          注意,要在 Console 里对小程序进行调试,需要将调试的上下文切换到 VM Context 1,如图所示。


          在 Sources 面板查看源代码时,开发者所有的文件路径都是以 weapp:// 开头的。


          除了可以在调试器进行单步调试,开发者还能在代码中手动插入 debugger; 语句进行断点调试。因此,如果想要在小程序启动的尽早时刻断点,可以在进入远程调试之前,编辑代码手动在需要断点处的代码插入 debugger; 语句来实现。

          WXML、AppData、Storage 面板的操作和开发者工具调试模拟器时的操作一致。注意,如果在右侧信息视图取消勾选了 “使用工具端的 Storage”,则所有的 Storage 数据将被存储在手机上,将不再出现 Storage 面板。




          信息视图

          右侧的信息视图展示了手机、网络连接的信息。手机信息展示手机的型号、系统、名称、微信版本等信息,以及通信延时。通信延时越小,与手机的通信越流畅。

          在 “连接信息” 里,展示了工具与服务器的连接信息,包括了连接状态、服务器状态等,当连接故障、服务器阻塞影响到调试的过程和流畅度时,此处将展示这一状态。当连接状态为 “已结束” 时,表明调试已被终止。

          “警告和错误” 展示了最近发生的错误和警告信息。如果网络连接断开,此处将会询问开发者是否需要重新连接。

          手机端展示

          调试过程中的手机端展示如下所示。

          当手机无网络或者进入了断点状态时,将会出现一个浮层提示并阻止进一步的操作。

          小游戏远程调试

          目前仅支持 1.02.1809260 及以上版本工具, iOS 11.2 ~ 11.4.1 系统 6.7.2 及以上版本微信客户端,以及 Android 系统 6.7.3 及以上版本微信客户端。

          与小程序不同的是,在调试窗口的右侧可能会出现 “Contexts” 栏,可以点选希望调试的不同的 JavaScript 上下文。

          默认情况下,为了方便调试,工具会上传带有完整源代码的 Source Map。如果不希望上传,或者出现代码行列数映射错乱的情况,可以在右下侧选项中关闭这个选项,并取消勾选项目详情中的 “上传代码时自动压缩混淆” 选项。

          注:目前尚不支持 Storage 面板。


          多账号调试

          开发者工具需要使用微信号登录,我们以此帐号作为所有打开的项目的主帐号,当登录的帐号改变时,其登录态将同步到所有已打开的项目窗口; 当小程序/小游戏需要多个微信号才能共同完成一项工作的话,我们提供了多帐号调试的功能。

          功能入口

          通过 菜单 - 工具 - 多帐号调试 可以使用多帐号调试功能

          如何使用


          使用不同于主帐号的微信扫描二维码可以添加一个测试帐号,如果该测试帐号登录了其他开发者工具客户端,登录态将失效

          点击 ‘+’、‘-’ 我们可以添加多个测试号,或者删除已添加的测试号;按住 ‘ctrl’ 键,鼠标可以多选


          我们可以同时勾选多个帐号,打开多个调试窗口来调试同一个项目;调试窗口与项目主窗口不同,只有模拟器和调试器;对项目代码编辑还是需要在项目主窗口进行,代码保存后,各个调试窗口可以同步执行最新的代码



          小程序开发者工具是对微信客户端的模拟,受限于桌面设备同移动设备不同,以及微信的一些特有数据,同时考虑到开发的便捷性,那么有部分 API 在工具和微信中是有所不同的。

          扫码接口

          同手机端直接调用摄像头来扫码不同,在 PC 或者 Mac 上调用摄像头来扫码完成调试是一个低效的行为,所以在开发工具上调用二维码扫码 API 后,开发者可以选择一个本地的图片来进行后续的逻辑调试,而不是真正的启用摄像头来扫码,流程有所不同,但是接口的输入和输出是一致的。

          微信支付

          最新版本的开发者工具已经支持微信支付的调试,但是为了兼顾到安全,同手机上直接调用微信支付有所不同:

          • 新绑定的开发者需要 24 小时后才有权限进行微信支付的调试
          • 开发者在工具上调用微信支付的 API 后,开发工具会出现一个二维码,开发者必须使用当前开发所使用的微信号扫码后在手机上完成支付的流程
          • 工具会同步移动端微信支付的回包到工具中,开发者自行进行后续的操作

          使用的交互有所不同,但是接口的输入输出工具同客户端是保持一致的。

          普通的转发

          开发者工具上调用转发是一个模拟的行为,并不会真实的转发给用户,开发可以通过这个模拟行为判断是否正确的调用了转发 API。

          带 shareTicket 的转发

          带 shareTicket 的转发可以获取到更多的转发信息,例如群聊的名称以及群的标识 openGId。在小程序开发者工具上,开发者可以通过以下方式来调试带 shareTicket 的转发。

          调用 wx.showShareMenu 的参数 withShareTicket 为 true 时,点击模拟器右上角菜单后出现的转发按钮,会出现一个测试群列表,如图:


          开发者点击选取任何一个群,可以通过接口的回包获取到 shareTicket ,通过调用 wx.getShareInfo 可以获取到相关转发的信息

          当开发者需要调试从某一个群点开,并且带有 shareTicket 的场景时,可以使用自定义编译中的 1044:群聊会话中的小程序消息卡片(带 shareTicket) 同时可以选择任一模拟测试群,如图


          进入场景值

          在微信客户端中,用户可能在各个场景下打开小程序 详情 然而在开发者工具中是没有真实的环境去模拟这些场景的。开发者可以通过条件编译的方式来达到调试不同场景的目的。


          启动使用自定义参数

          在日常使用中,用户可以打开一个小程序,并且依据传入的 path 跳转到对应的小程序页面而非启动页面,或者可以通过 参数 使得小程序区别默认开打状态,开发者工具中,开发者同样可以通过条件编译的方式来达到调试不同 path 和 参数 的目的。

          例如下图是选择进入页面是 pages/name/name 参数 是 name=linchao


          预览使用自定义参数

          同 启动使用自定义参数 相同,提交预览时,开发者可以通过自定义预览的方式来达到在移动设备上调试不同 path 和 参数 的目的。

          例如下图是选择进入页面是 pages/name/name 参数 是 name=linchao


          小程序跳转的调试支持

          小程序跳转开发调试可以分为两个部分

          调试小程序是否能够正确的跳转

          出于小程序代码的安全考虑,在工具上调用 wx.navigateToMiniProgram 的时候,开发者工具不会真实的打开和跳转到另外的小程序,但是工具会判断当前小程序与需要跳转的小程序之间的绑定关系,输出相关信息给到开发者。开发者可以根据成功或者失败的回调函数来判断调用是否成功。

          调试被打开的小程序时候正确的接收参数

          选择 自定义编译 进入场景选择 1037 从小程序进入 可以调试小程序被打开时候是否接收到了正确的参数并做了相关处理。


          选择 自定义编译 进入场景选择 1038 从小程序返回 可以调试小程序返回时候是否接收到了正确的参数并做了相关处理。


          开发者工具提供了命令行与 HTTP 服务两种接口供外部调用,开发者可以通过命令行或 HTTP 请求指示工具进行登录、预览、上传等操作。

          命令行

          通过命令行调用安装完成的工具可执行文件,完成登录、预览、上传、自动化测试等操作。调用返回码为 0 时代表正常,为 -1 时错误。

          命令行工具所在位置:

          macOS: <安装路径>/Contents/Resources/app.nw/bin/cli

          Windows: <安装路径>/cli.bat

          1. 命令行启动工具

          -o, --open [projectpath]: 打开工具,如果不带 projectpath,只是打开工具。如果带 project path,则打开路径中的项目,每次执行都会自动编译刷新,并且自动打开模拟器和调试器。projectpath 不能是相对路径。项目路径中必须含正确格式的 project.config.json 且其中有 appid 和 projectname 字段。

          示例:

          # 打开工具cli -o# 打开路径 /Users/username/demo 下的项目cli -o base64@/Users/username/demo

          2. 命令行登录

          命令行提供两种登录方式:一是将登录二维码转成 base64 给用户,让用户自己集成到自己系统中使用;二是将二维码打印在命令行中。

          -l, --login: 启动登录逻辑。

          --login-qr-output [format[@path]]: 指定二维码输出形式,format 可选值包括 terminal(命令行输出), base64, image。如果有填 path,表示结果输出到指定路径的文件中。如果没填 path,表示将结果输出到命令行。不使用此选项或使用了但没有填 format 的话则默认为命令行打印。

          示例:

          # 登录,在终端中打印登录二维码cli -l# 登录,在终端中打印登录 base64 形式的二维码cli -l --login-qr-output base64# 登录,二维码转成 base64 并存到文件 /Users/username/code.txt cli -l --login-qr-output base64@/Users/username/code.txt

          3. 命令行提交预览

          预览时必须处于登录状态,如果没有登录,会提示需先登录。预览的二维码可命令行打印也可以转成 base64。ES6 等项目配置从 project.config.json 读。

          -p, --preview <project_root>: 预览代码,project_root 指定项目根路径。

          --preview-qr-output [format[@path]]: 指定二维码输出形式,语义同登录用的选项 --login-qr-output。

          示例:

          # 预览,在终端中打印登录二维码cli -p /Users/username/demo# 预览,二维码转成 base64 并存到文件 /Users/username/code.txtcli -p /Users/username/demo --preview-qr-output base64@/Users/username/code.txt

          4. 命令行上传代码

          上传代码时必须处于登录状态,如果没有登录,会提示需先登录。

          上传代码需要的信息包括项目根目录、版本号、以及可选的版本备注。

          -u, --upload <version@project_root>: 上传代码,version 指定版本号,project_root 指定项目根路径。

          --upload-desc <desc>: 上传代码时的备注。

          示例:

          # 上传路径 /Users/username/demo 下的项目,指定版本号为 1.0.0,版本备注为 initial releasecli -u 1.0.0@/Users/username/demo --upload-desc 'initial release'

          5. 支持自动化测试

          -t, --test <project_root>: 提交自动化测试,project_root 指定项目根路径。

          示例:

          # 提交测试路径 /Users/username/demo 下的项目cli -t /Users/username/demo

          开发者工具提供了命令行与 HTTP 服务两种接口供外部调用,开发者可以通过命令行或 HTTP 请求指示工具进行登录、预览、上传等操作。

          HTTP

          http 服务在工具启动后自动开启,HTTP 服务端口号在用户目录下记录,可通过检查用户目录、检查用户目录下是否有端口文件及尝试连接来判断工具是否安装/启动。

          端口号文件位置:

          macOS : ~/Library/Application Support/微信web开发者工具/Default/.ide

          Windows : ~/AppData/Local/微信web开发者工具/User Data/Default/.ide

          1. 打开工具或指定项目

          接口定义:

          URL: /open

          HTTP 方法: GET

          URL 参数必填说明
          projectpath打开指定路径中的项目。如项目已打开,自动刷新项目。如项目未创建,自动创建并打开项目

          示例:

          # 打开工具http://127.0.0.1:端口号/open# 打开/刷新项目http://127.0.0.1:端口号/open?projectpath=项目全路径

          注意:

          • 项目路径中必须含正确格式的 project.config.json 且其中有 appid 和 projectname 字段。
          • 项目路径需经 URL encode

          2. 登录

          接口定义:

          URL:/login

          HTTP 方法:GET

          URL 参数必填说明
          format指定登录二维码返回格式,可选值有 image、base64、terminal,默认 image。图片格式为 png
          qroutput指定文件路径,在文件写入二维码数据。如指定,二维码将被写入指定路径的文件内,如未指定,二维码将作为请求相应体返回

          示例:

          # 登录,返回图片格式的二维码http://127.0.0.1:端口号/login# 登录,取 base64 格式二维码http://127.0.0.1:端口号/login?format=base64# 登录,取 base64 格式二维码,并写入 /Users/username/logincode.txthttp://127.0.0.1:端口号/login?format=base64&qroutput=%2FUsers%2Fusername%2Flogincode.txt

          3. 预览

          接口定义:

          URL:/preview

          HTTP 方法:GET

          URL 参数必填说明
          projectpath预览指定路径中的项目。如项目已打开,自动刷新项目。如项目未创建,自动创建并预览项目
          format指定登录二维码返回格式,可选值有 image、base64、terminal,默认 image。图片格式为 png
          qroutput指定文件路径,在文件中写入二维码数据。如指定,二维码将被写入指定路径的文件内,如未指定,二维码将作为请求相应体返回

          示例:

          # 预览路径为 /Users/username/demo 的项目,返回图片格式的二维码http://127.0.0.1:端口号/preview?projectpath=%2FUsers%2Fusername%2Fdemo# 预览路径为 /Users/username/demo 的项目,返回 base64 格式的二维码http://127.0.0.1:端口号/preview?projectpath=%2FUsers%2Fusername%2Fdemo&format=base64# 预览路径为 /Users/username/demo 的项目,返回 base64 格式的二维码,并写入 /Users/username/logincode.txthttp://127.0.0.1:端口号/preview?projectpath=%2FUsers%2Fusername%2Fdemo&format=base64&qroutput=%2FUsers%2Fusername%2Flogincode.txt

          4. 上传

          接口定义:

          URL:/upload

          HTTP 方法:GET

          URL 参数必填说明
          projectpath上传指定路径中的项目
          version版本号
          desc本次上传的版本备注

          示例:

          # 上传路径为 /Users/username/demo 的项目,指定版本号为 v1.0.0http://127.0.0.1:端口号/upload?projectpath=%2FUsers%2Fusername%2Fdemo&version=v1.0.0# 上传路径为 /Users/username/demo 的项目,指定版本号为 v1.0.0,并带上备注http://127.0.0.1:端口号/upload?projectpath=%2FUsers%2Fusername%2Fdemo&version=v1.0.0&desc=test

          5. 自动化测试

          接口定义:

          URL:/test

          HTTP 方法:GET

          URL 参数必填说明
          projectpath测试指定路径中的项目

          示例:

          # 提交路径为 /Users/username/demo 的项目进行测试http://127.0.0.1:端口号/test?projectpath=%2FUsers%2Fusername%2Fdemo

          请求响应

          正常情况下 HTTP 相应状态码为 200,错误时 400,返回如下格式的 JSON 字符串:

          {  "code": 40000,  "error": "原因"}

          代码片段是一种可分享的小项目,可用于分享小程序和小游戏的开发经验、展示组件和 API 的使用、复现开发问题等等。分享代码片段会得到一个链接,所有拥有此分享链接的人可以在工具中导入此代码片段。如果网页可点击的链接指向的是分享链接,那么点击链接也会自动打开工具进入代码片段导入页。使用最新版的开发者工具可以点此体验导入代码片段

          创建代码片段


          在工具选择项目的界面中,右侧可以选择代码片段页卡,查看所有本地代码片段,在右下角可以点击创建代码片段。

          select-project

          创建代码片段需要填入代码片段名称、本地存放目录。AppID 不是必填项,如果需要演示依赖 AppID 的操作则需填写。如果存放目录是空目录,则可在下方选择小程序、小游戏等的快速启动模板。

          create-minicode

          信息填写正确后,点击创建即可完成创建并打开代码片段。

          代码片段主界面


          代码片段的主界面与普通项目主要有以下几点区别:

          1. 没有上传、腾讯云和申请测试报告等功能
          2. 详情页中会展示上次分享的链接,并可以一键复制
          3. 代码片段的快速启动模板与普通项目的快速启动模板不同,体积更小,功能更精简

          project

          分享代码片段


          在工具栏上点击分享按钮即可开启分享代码片段的流程,在分享信息中需要填写以下内容:

          • 项目描述:简要介绍此代码片段的功能和目的
          • 是否需要 AppID:如果是,开发者导入代码片段时会建议其填入 AppID 以完整运行代码片段
          • 最低库版本:开发者打开导入的代码片段时详情页的调试基础库不会低于指定的版本

          分享的小程序代码片段最大大小为 100KB,小游戏代码片段最大为 200KB。

          share

          分享成功后会展示分享链接,可复制分享给其他开发者,其他开发者在工具中选择导入代码片段并粘贴链接即可导入。

          share-success

          分享的链接除了可以粘贴到导入页导入外,还可以设置为可点击的链接。如果 html <a> 标签的 href 属性设置为分享的链接,如 <a href="wechatide://minicode/76b799966b6ead1837edac517cc02e02" rel="external nofollow" target="_blank" >代码片段示例</a>,则用户点击此链接时会自动打开工具进入代码片段导入页,最后点击导入即可完成导入。在开发者社区发帖时,如果想要提供 demo 示例,如果想要提供 demo 示例,可以插入一个链接为代码片段分享链接的超链接。

          share-bbs

          导入代码片段


          在选择代码片段的页面的右下角可以点击导入进入导入页,或者点击菜单栏上的项目选项卡下的导入代码片段来打开导入页。导入时需要填写分享链接或代码片段 ID。链接的最后一部分即是代码片段的 ID,如 wechatide://minicode/76b799966b6ead1837edac517cc02e02 的 ID 为 76b799966b6ead1837edac517cc02e02。

          import-minicode

          导入时可选择存放目录和 AppID。存放目录默认是在临时文件夹。

          import-minicode-info

          概述

          同开发普通的小程序不同,开发第三方平台小程序具有一定的复杂性,首先需要确认三个概念

          • open3rd:第三方平台,是小程序官方认可的第三方开发商 详情
          • 3rdMiniProgramAppid:第三方平台申请的并绑定在该平台上的小程序,用于开发小程序模板
          • extAppid:授权给第三方平台的小程序

          因为以上的这些不同,第三方平台相关的小程序开发需要做一些特殊的处理

          • 小程序模板的开发
          • 小程序模板结合 extAppid 的开发调试

          最新版本的开发工具支持第三方平台小程序的开发和预览。

          创建项目

          与开发普通小程序一致,第三方平台开发者填入相关的 3rdMiniProgramAppid ,设定项目名称和选择项目目录即可创建项目。

          对于第三方平台小程序,可以在项目页卡查看到相关的 open3rd 信息以及当前的第三方的 3rdMiniProgramAppid ,如若项目配置了相关的 extAppid ,那么项目页卡中也会有相关信息。

          ext1

          小程序模板开发

          与开发普通小程序一致,开发者在开发工具上开发好相关的业务逻辑之后,在项目页卡中提交预览既可以在微信中查看小程序的真实表现,

          有所不同的是,第三方平台小程序的提交上传是上传至该第三方平台的 open 帐号下的模板草稿箱中,该平台的管理员需要自行对该模板进行相应的设置,更多请参考 open平台的文档 。

          extAppid 的开发调试

          为了方便第三方平台的开发者引入 extAppid 的开发调试工作,需要引入ext.json的概念。

          ext.json是一个配置文件,放置在小程序项目的根目录下。

          以下是一个包含了所有配置选项的ext.json

          {  "extEnable": true,  "extAppid": "wxf9c4501a76931b33",  "ext": {    "name": "wechat",    "attr": {      "host": "open.weixin.qq.com",      "users": [        "user_1",        "user_2"      ]    }  },  "extPages": {    "pages/logs/logs": {      "navigationBarTitleText": "logs"    }  },  "window":{    "backgroundTextStyle":"light",    "navigationBarBackgroundColor": "#fff",    "navigationBarTitleText": "Demo",    "navigationBarTextStyle":"black"  },  "tabBar": {    "list": [{      "pagePath": "pages/index/index",      "text": "首页"    }, {      "pagePath": "pages/logs/logs",      "text": "日志"    }]  },  "networkTimeout": {    "request": 10000,    "downloadFile": 10000  }}

          ext.json中的配置字段分为两种

          • 特有的字段
          • app.json相同的字段

          特有的字段

          属性类型必填描述
          extEnableBoolean配置 ext.json 是否生效
          extAppidString配置 extAppid
          extObject开发自定义的数据字段
          extPagesString Array单独设置每个页面的 json

          extEnable

          extEnable是一个Boolean类型的字段,用于规定当前的ext.json文件是否生效,开发者可以通过修改这个字段来开启和关闭 extAppid 的结合开发。


          extAppid

          extAppid是授权调试的AppID,例如开发者在此处填写的是wxf9c4501a76931b33那么在extEnable为真的情况下,后续的开发逻辑都会基于wxf9c4501a76931b33来运行。


          ext

          ext字段是开发自定义的数据字段,在小程序中可以通过 wx.getExtConfigSync 或者 wx.getExtConfig 获取到这些配置信息。

          例如上面的例子中,通过wx.getExtConfigSync就可以获得ext字段的所有配置

          {  "name": "wechat",  "attr": {    "host": "open.weixin.qq.com",    "users": [      "user_1",      "user_2"    ]  }}


          extPages

          extPages是一个对象,对象中的每个key应该是该小程序模板app.json中定义的页面,每个key对应的value是 page.json 中所规定的各项配置。

          当开发者设置这个配置以后,小程序框架会对应的修改相对应的page的配置信息。

          app.json相同的字段

          ext.json中的字段同app.json中一致时,ext.json的字段会覆盖app.json中的对应字段,例如以下的ext.json

          {  ········  "window":{    "backgroundTextStyle":"light",    "navigationBarBackgroundColor": "#fff",    "navigationBarTitleText": "ext navigationBarTitleText",    "navigationBarTextStyle":"black"  }}

          那么该小程序最终的navigationBarTitleText应该是ext navigationBarTitleText

          创建插件项目


          小程序的 AppID 可以创建小程序插件项目,插件是独立于小程序之外的,但是 AppID 是公用的,所以不要使用原有的小程序项目进行插件开发。 在创建项目页面,选择一个空文件夹作为项目路径,可以选择创建小程序插件快速启动模板

          快速启动模板说明:

          1. miniprogram 文件夹是一个普通小程序项目,用来编写小程序插件的使用 Demo,上传插件代码时这个 Demo 会一起上传,并作为小程序插件的发布的审核依据.
          2. plugin 文件就是小程序插件项目,用来编写小程序插件的代码。
          3. project.config.json 需要关注 compileType 字段,compileType == 'plugin' 时才能正常的使用插件项目。详情

          打开已存在的插件项目


          如果是之前创建的插件项目,可以在项目列表中直接打开;

          如果重新创建项目,选择一个非空目录,那么这个非空目录中需要有 project.config.json 详情,确保这个文件中有以下字段:

          {  "miniprogramRoot": "./miniprogram",  "pluginRoot": "./plugin",  "compileType": "plugin"}

          在项目开发期间,可以手动修改 project.config.json 文件的 compileType 字段来切换项目的编译类型。

          插件上传


          上传插件代码前,需要指定版本号,格式为 数字.数字.数字 ,每个数字最大为 999。

          每次提交版本号需要递增,插件使用者会用到这个版本号,请谨慎填写。

          上传插件时,同时会将 project.config.json 中 miniprogramRoot 指定的目录的内容作为插件使用 Demo 一起上传,这个 Demo 需要覆盖到插件的所有使用场景,便于插件的审核

          插件使用


          在小程序项目的 app.json 的 plugins 字段中可以声明使用插件。如果当前的编译类型为小程序时,需要指定已发布的插件的版本号,开发者工具会根据版本号去拉取对应版本的插件进行编译。

          只有在 project.config.json 的 compileType == 'plugin' 时,插件的版本号才能为 'dev'

          名词解释

          Git:是一个免费开源的分布式版本控制系统。我们可以使用 Git 管理我们的小程序代码。

          TGit:是腾讯云提供的基于 Git 的在线代码托管服务。


          TGit开通及配置流程

          1.开通TGit

          开发者可登录小程序管理后台,在 “设置-开发者工具” 内开通 TGit 功能。

          2.配置项目信息、管理员信息

          填写小程序项目名称。小程序管理员将作为 TGit 项目管理员,可自定义管理员的用户名和密码。

          用户名配置完成后,会生成完整的 TGit 用户名,用于在 TGit 内验证身份,可在权限控制页面查看完整用户名。

          提交后,查看完整的 TGit 用户名,TGit 内验证身份需要填写完整用户名。

          3.开通后,进入“查看权限”,可查看和配置 TGit 项目成员信息

          4.添加 TGit 项目成员

          (1)选择成员:通过微信号搜索,选择小程序的一个开发者添加到项目中。

          (2)填写 TGit 用户名

          填写用户名,注意:在添加成员后,可在成员配置页面查看成员完整的用户名,使用 git clone 命令时需要使用完整的用户名进行验证。

          注:开通 TGit,添加项目成员操作耗时较久,请耐心等待


          微信开发者工具

          在微信开发者工具的工具栏上可以通过 “代码仓库” 按钮快速进入 TGit 管理后台


          如何使用

          1. 下载并安装 Git,https://git-scm.com/downloads
          2. 熟悉 Git 使用方法,详情
          3. 使用 Git 命令或者 Git 可视化工具将代码提交到 TGit
          4. 使用 TGit 进行代码托管和多人协作

          素材管理


          素材管理将为你一键开通腾讯云的 "对象存储(COS)" 和 "内容分发网络(CDN)" 的产品功能:

          • 支持从 微信开发者工具 上传素材到腾讯云;
          • 提供临时域名供你在开发过程中调试;
          • 提供简单页面管理和上传你的素材资源;
          • 赠送一定免费的额度供开发和调试;

          名词解释

          • 对象存储(COS):是腾讯云为企业和个人开发者们提供的一种能够存储海量数据的分布式存储服务,用户可随时通过互联网对您的大量数据进行批量存储和处理。
          • 内容分发网络(CDN):是腾讯云针对门户网站、电子商务、UGC 社区等业务场景,提供的静态内容(如网页样式、图片、小文件)加速分发处理能力,极大地缩减了站点响应时间,实现复杂内容秒级加载,显著提升了网页用户的体验。
          • 外网下行流量:指直接通过对象域名链接下载对象或通过静态网站地址浏览对象产生的流量
          • CDN 回源流量:指将存储在 COS 上的文件,分发同步到 CDN 的流量,整个同步过程由系统自动完成。
          • 加速域名: 在开启 CDN 加速后,腾讯云会默认生成一条 CDN 加速域名供开发者使用,通过该域名可以直接访问开发者上传的素材文件,若需要领用开通后前 6 个月每个月 50GB免费流量,需要开发者绑定自己备案的域名。

          免费额度

          • 对象存储(COS): 每月提供免费资源包括: 50 GB 存储空间,10 GB 外网下行流量,10 GB 腾讯云 CDN 回源流量, 100 万次 读请求, 100 万次 写请求,点击 了解详情
          • 内容分发网络(CDN): 新开通 CDN 的用户在开通后的 6 个月内每月收到腾讯云赠送的 50GB 流量包,此外接入加速域名后用户每月均可享受 10GB 免费流量包,自接入加速域名后于每月1号发放至您的账户。点击 了解详情

          收费情况

          对象存储(COS)和 内容分发网络(CDN)都属于后付费的产品,开通本服务后,意味着用户同意在不中断服务的情况下,使用付费的服务。当赠送的流量在过期/快用尽的时候系统将统一通知,请留意用量和系统推送的消息,避免在不知情的情况下产生费用。

          相关收费情况,请查看下面的文档:

          产品介绍

          1. 对象存储(COS)点击 了解详情
          2. 内容分发网络(CDN)点击 了解详情

          开通步骤

          一、通过微信公众平台授权登录腾讯云

          未将小程序授权给腾讯云需要进行前往 微信公众平台 注册并登录小程序,按如下步骤操作:

          • 单击左侧菜单栏中的【设置】
          • 单击右侧 Tab 栏中的【开发者工具】
          • 单击【腾讯云】,进入腾讯云工具页面,单击【开通】
          • 使用小程序绑定的微信扫码即可将小程序授权给腾讯云,开通之后会自动进去腾讯云微信小程序控制台,显示开发环境已开通,此时可以进行后续操作

          进入微信公众平台后台

          开通腾讯云

          二、前往腾讯云开通 素材管理 服务

          单击后台管理按钮

          开通素材管理服务

          注:小程序管理员在 mp 管理后台跳转到腾讯云管理界面后,浏览器中输入 https://console.cloud.tencent.com/lagame 跳转到开通页面

          Windows 仅支持 Windows 7 及以上版本

          稳定版 Stable Build (1.05.2103190)

          测试版缺陷收敛后转为稳定版

          Windows 64Windows 32macOS

          预发布版 RC Build (1.05.2103051)

          预发布版,包含大的特性;通过内部测试,稳定性尚可

          Windows 64Windows 32macOS

          开发版 Nightly Build (1.05.2103262)

          日常构建版本(基于 NW.js 0.49.3) ,用于尽快修复缺陷和敏捷上线小的特性;开发自测验证,稳定性欠佳,

          Windows 64Windows 32macOS


          javascript && wxss


          微信小程序运行在三端:iOS、Android 和 用于调试的开发者工具。

          三端的脚本执行环境聚以及用于渲染非原生组件的环境是各不相同的:

          • 在 iOS 上,小程序的 javascript 代码是运行在 JavaScriptCore 中,是由 WKWebView 来渲染的,环境有 iOS8、iOS9、iOS10
          • 在 Android 上,小程序的 javascript 代码是通过 X5 JSCore来解析,是由 X5 基于 Mobile Chrome 37 内核来渲染的
          • 在 开发工具上, 小程序的 javascript 代码是运行在 nwjs 中,是由 Chrome Webview 来渲染的

          尽管三端的环境是十分相似的,但是还是有些许区别:

          • ES6语法支持不一致,语法上开发者可以通过开启ES6ES5的功能来规避。详情

          • wxss渲染表现不一致,尽管可以通过开启样式补全来规避大部分的问题 详情,还是建议开发者需要在 iOS 和 Android 上检查小程序的真实表现。


          客户端可信域名校验


          开发者使用手机扫码调试的场景下,打开调试模式之后,最新版的客户端将不检查可信域名。


          代码文件必须 UTF8 编码

          iOS下仅支持 UTF8 编码格式,最新版本的开发者工具会在上传代码时候对代码文件做一次编码格式校验。

          ES6 APi 支持情况

          微信小程序已经支持了绝大部分的 ES6 API 具体表格如下:

          1. tip: TBS 3.0 是指微信小程序 Android 运行环境
          2. tipArray.values不支持
          3. tipProxy不支持
          StringiOS8iOS9iOS10TBS3.0
          codePointAt    
          normalize    
          includes    
          startsWith    
          endsWith    
          repeat    
          String.fromCodePoint    
          ArrayiOS8iOS9iOS10TBS3.0
          copyWithin    
          find    
          findIndex    
          fill    
          entries    
          keys    
          values  
          includes    
          Array.from    
          Array.of    
          NumberiOS8iOS9iOS10TBS3.0
          isFinite    
          isNaN    
          parseInt    
          parseFloat    
          isInteger    
          EPSILON    
          isSafeInteger    
          MathiOS8iOS9iOS10TBS3.0
          trunc    
          sign    
          cbrt    
          clz32    
          imul    
          fround    
          hypot    
          expm1    
          log1p    
          log10    
          log2    
          sinh    
          cosh    
          tanh    
          asinh    
          acosh    
          atanh    
          ObjectiOS8iOS9iOS10TBS3.0
          is    
          assign    
          getOwnPropertyDescriptor    
          keys    
          getOwnPropertyNames    
          getOwnPropertySymbols    
          OtheriOS8iOS9iOS10 TBS3.0
          Symbol     
          Set     
          Map     
          Proxy  
          Reflect     
          Promise     

          同 正式 版本不同,本页面提供的是开发者工具测试版本的下载,我们将修复 bug 和一些新的特性以 beta 方式先发布。

          小程序新版工具内测


          新版本的小程序开发工具优化了以下几个方面

          • 重构了工具的整体架构和逻辑,编译和启动速度有 100% 以上的提升
          • 优化了整体交互,预览以及上传代码等高频操作会更加便捷
          • 重构了视觉呈现

          除外,全新提供了两大功能

          • 腾讯云服务:开发者提供免费的云端开发能力以及环境 详情
          • 自动化测试:为小程序提供真机测试报告

          Tips: 新版工具的安装不会覆盖旧版本,两个版本可以同时存在

          下载地址


          windows 64 、 windows 32 、 mac

          2017.08.24 更新日志

          1. A: 新增 自定义设备宽高的添加和删除
          2. F: 修复 WXS 中使用 console 只打印第一个参数的问题。
          3. F: 修复 编辑器 wxss、wxml 无法格式化的问题
          4. F: 修复 编辑器 当前选中文件没有高亮的问题
          5. F: 修复 编辑器 代码无法折叠的问题
          6. F: 修复 编辑器 无法自动匹配的问题
          7. F: 修复 wxml panel 无法显示 dataset 的问题
          8. F: 修复 wx.openLocation、wx.chooseLocation 调用失败的问题
          9. F: 修复 从浏览器拖动图片到开发者工具会加载该图片导致工具无法使用的问题
          10. F: 修复 公众号调试模式下快捷键缺失的问题
          11. U: 优化 公众号调试模式下模拟器可以缩放
          12. U: 优化 编译条件选择场景值的交互
          13. U: 优化 上传腾讯云的交互
          14. U: 优化 小屏幕工具栏的显示

          2017.08.22 更新日志


          1. F: 修复 wxml panel 没有显示样式源文件,无法点击跳转到源文件的问题
          2. F: 修复 wxml panel 勾选、取消勾选样式时不生效的问题
          3. F: 修复 wxml panel 没有显示 element.style 的问题
          4. F: 修复 APIwx.navigateToMiniProgram、wx.navigateBackMiniProgram、wx.exitMiniProgram、wx.startPullDownRefresh、wx.openWeRunSetting、wx.chooseInvoiceTitle 缺失的问题
          5. F: 修复 page.json 不生效的问题
          6. F: 修复 ctrl/command + r 编译快捷键丢失的问题
          7. F: 修复 同时勾选 "编译时自动保存所有文件" 和 "保存时自动编译小程序" 时会出现无法正常编译的问题
          8. A: 新增 WXS 功能

          Git 版本管理

          为了方便开发者更简单快捷地进行代码版本管理,简化一些常用的 Git 操作,以及降低代码版本管理使用的学习成本,开发者工具集成了 Git 版本管理面板。

          开发者可以在打开的项目窗口里,点击工具栏上的 “版本管理” 按钮进入 Git 版本管理界面。

          提交工作区更改

          在 “工作区” 可以查看到目前工作目录的变更及对比,并直接通过勾选文件前面的复选框将其添加到暂存区。右键点击工作区或者此文件,可以丢弃修改。输入提交标题和详情,点击提交按钮即可以提交本次的变更。在标题栏上点击右键可以使用常用的 Gitmoji 符号。

          查看历史

          点击历史或者某个分支,可以查看到当前分支的最新提交记录。每个提交记录都可以看到变更的内容以及目录树详情。展开目录树后,在文件上右键点击,可以保存该提交版本的文件完整内容,或者检出该版本的文件。

          查看文件修改历史

          在提交记录的目录树文件上右键点击,可以查看到某个文件截至该提交的所有变更记录,并可直接查看文件内容,方便排查问题。

          检出和创建分支

          要检出某分支,直接在分支上点击右键选择 “检出” 即可。要创建分支,可以在要创建的提交记录或者分支名上右键,选择 “创建分支” 即可。

          拉取,推送和抓取

          通过工具栏上的拉取,推送和抓取按钮,可以很方便地对远程仓库执行各种操作。某些远程仓库可能需要身份验证或者网络代理配置,可以在 “设置” 页中 “网络和认证” 中配置这些信息。


          网络和认证设置

          如果连接远程仓库需要代理或者用户身份验证的设置,可以在设置 “网络和认证” 中配置。

          用户设置

          在设置页面可以对用户名进行配置。配置完成后,下次提交时,将会使用此用户名和邮箱进行提交。

          子模块

          如果项目包含子模块 (Submodule),可以在子模块列表下查看到子模块的信息。目前不支持对子模块进行更多的操作。

          初始化 Git 仓库

          如果所在的项目文件夹下没有找到 Git 仓库,可以根据提示初始化一个仓库,并可选择是否立即提交所有文件,以及自动生成一个 .gitignore 文件模板。

          体验评分是一项给小程序的体验好坏打分的功能,它会在小程序运行过程中实时检查,分析出一些可能导致体验不好的地方,并且定位出哪里有问题,以及给出一些优化建议。

          运行环境要求

          • 下载并安装 1.02.1808300 或以上版本的开发者工具,下载地址
          • 基础库需要切到 2.2.0 或以上版本。

          使用流程

          1. 打开开发者工具,在详情里切换基础库到 2.2.0 或以上版本。 

          2. 在调试器区域切换到 Audits 面板。 

          3. 点击”开始“按钮,然后自行操作小程序界面,运行过的页面就会被“体验评分”检测到。

          图片描述

          4. 点击 “停止" 则结束检测,在当前面板显示相应的检测报告,开发者可根据报告中的建议对相应功能进行优化。 

          5. 如需再次运行体验评分,可点击报告上方的“清空体验评分”恢复初始状态。请注意,目前系统不提供报告存储服务,一旦清空体验评分,将无法再查看本次评分结果。

          图片描述

          自动运行

          为了方便开发者能够及时发现小程序的体验问题,从开发者工具 1.02.1811150 版本起支持体验评分的 “自动运行” 功能。

          该功能会在开发调试小程序时,实时检查,一旦发现体验分数低于 70 分时,系统会在 console 面板打印一个 warning 信息提示开发者,此时开发者可以切到 Audits 面板查看详情。

          开发者在工具的右上角 “详情” 面板的 本地设置 中勾选 “自动运行体验评分” 选项即可开启。

          图片描述

          评分规则

          具体的评分细则和详情的规则说明可参考下列文档:


          npm 支持

          从小程序基础库版本 2.2.1 或以上、及开发者工具 1.02.1808300 或以上开始,小程序支持使用 npm 安装第三方包。

          此文档要求开发者们对 npm 有一定的了解,因此不会再去介绍 npm 的基本功能。如若之前未接触过 npm,请翻阅官方 npm 文档进行学习。

          使用 npm 包

          1. 在小程序中执行命令安装 npm 包:
          npm install --production

          此处并没有强制要求 node_modules 必须在小程序根目录下(即 project.config.js 中的 miniprogramRoot 字段),也可以存在于小程序根目录下的各个子目录中。但是不允许 node_modules 在小程序根目录外。

          PS:此处请务必使用--production选项,可以减少安装一些业务无关的 npm 包,从而减少整个小程序包的大小。
          1. 点击开发者工具中的菜单栏:工具 --> 构建 npm 
            construction
          2. 勾选“使用 npm 模块”选项: 
            use npm
          3. 构建完成后即可使用 npm 包。

          js 中引入 npm 包:

          const package = require('packageName')const packageOther = require('packageName/other')

          使用 npm 包中的自定义组件:

          {  "usingComponents": {    "package": "packageName",    "package-other": "packageName/other"  }}
          PS:此处使用 npm 包时如果只引入包名,则默认寻找包名下的 index.js 文件或者 index 组件。

          发布 npm 包

          发布小程序 npm 包的约束

          这里要发布的 npm 包是特指专为小程序定制的 npm 包(下称小程序 npm 包)。因为小程序自定义组件的特殊性,原有的 npm 包机制无法满足我们的需求,所以这里需要对小程序 npm 包做一些约束:

          1. 小程序 npm 包要求根目录下必须有构建文件生成目录(默认为 miniprogram_dist 目录),此目录可以通过在 package.json 文件中新增一个 miniprogram 字段来指定,比如:
          {  "name": "miniprogram-custom-component",  "version": "1.0.0",  "description": "",  "miniprogram": "dist",  "devDependencies": {},  "dependencies": {}}
          1. 小程序 npm 包里只有构建文件生成目录会被算入小程序包的占用空间,上传小程序代码时也只会上传该目录的代码。如果小程序 npm 包有一些测试、构建相关的代码请放到构建文件生成目录外。另外也可以使用.npmignore文件来避免将一些非业务代码文件发布到 npm 中。
          2. 测试、构建相关的依赖请放入 devDependencies 字段中避免被一起打包到小程序包中。

          发布其他 npm 包的约束

          如果是已经发布过的一些 npm 包,因为一些原因无法改造成小程序 npm 包的结构的话,也可以通过微调后被使用,但是请确保遵循以下几点:

          1. 只支持纯 js 包,不支持自定义组件。
          2. 必须有入口文件,即需要保证 package.json 中的 main 字段是指向一个正确的入口,如果 package.json 中没有 main 字段,则以 npm 包根目录下的 index.js 作为入口文件。
          3. 测试、构建相关的依赖请放入 devDependencies 字段中避免被一起打包到小程序包中,这一点和小程序 npm 包的要求相同。
          4. 不支持依赖 c++ addon,不支持依赖 nodejs 的内置库:
          const addon = require('./addon.node'); // 不支持!const http = require('http'); // 不支持!
          1. 使用 require 依赖的时候下列几种方式也是不允许的:
          // 不允许将 require 赋值给其他变量后再使用,以下代码不会去解析出具体依赖let r;r = require;r('testa');let r2 = require;r2('testa');// 不允许 require 一个变量,以下代码依赖运行时,无法解析出具体依赖let m = 'testa';require(m);
          1. 小程序环境比较特殊,一些全局变量(如 window 对象)和构造器(如 Function 构造器)是无法使用的。

          发布流程

          发布 npm 包的流程简述如下:

          1. 如果还没有 npm 帐号,可以到 npm 官网注册一个 npm 帐号。
          2. 在本地登录 npm 帐号,在本地执行:
          npm adduser

          或者

          npm login
          1. 在已完成编写的 npm 包根目录下执行:
          npm publish

          到此,npm 包就成功发布到 npm 平台了。

          PS:一些开发者在开发过程中可能修改过 npm 的源,所以当进行登录或发布时需要注意要将源切回 npm 的源。

          原理介绍

          为了帮助大家更好的理解发布 npm 包中提到的各种要求,这里简单介绍一下原理:

          1. 首先 node_modules 目录不会参与编译、上传和打包中,所以小程序想要使用 npm 包必须走一遍“构建 npm”的过程,在最外层的 node_modules 的同级目录下会生成一个 miniprogram_npm 目录,里面会存放构建打包后的 npm 包,也就是小程序真正使用的 npm 包。
          2. 构建打包分为两种:小程序 npm 包会直接拷贝构建文件生成目录下的所有文件到 miniprogram_npm 中;其他 npm 包则会从入口 js 文件开始走一遍依赖分析和打包过程(类似 webpack)。
          3. 寻找 npm 包的过程和 npm 的实现类似,从依赖 npm 包的文件所在目录开始逐层往外找,直到找到可用的 npm 包或是小程序根目录为止。 下面简单介绍下构建打包前后的目录情况,构建之前的结构:
          |--node_modules|    |--testComp // 小程序 npm 包|    |    |--package.json|    |    |--src|    |    |--miniprogram_dist|    |         |-index.js|    |         |-index.json|    |         |-index.wxss|    |         |-index.wxml|    |--testa // 其他 npm 包|         |--package.json|         |--lib|         |    |--entry.js|         |--node_modules|              |--testb|                   |--package.json|                   |--main.js|--pages|--app.js|--app.wxss|--app.json|--project.config.js

          构建之后的结构:

          |--node_modules|--miniprogram_npm|    |--testComp // 小程序 npm 包|    |    |-index.js|    |    |-index.json|    |    |-index.wxss|    |    |-index.wxml|    |--testa // 其他 npm 包|         |--index.js // 打包后的文件|         |--miniprogram_npm|              |--testb|                   |--index.js // 打包后的文件|                   |--index.js.map|--pages|--app.js|--app.wxss|--app.json|--project.config.js
          PS:打包生成的代码在同级目录下会生成 source map 文件,方便进行逆向调试。

          js 模块示例

          以下为官方提供的 js 模块,可以参考并使用:

          自定义组件相关示例

          请查阅开发第三方自定义组件文档。

          稳定版 Stable Build 更新日志

          1.05.2103190 Windows 64Windows 32macOS

          2021.03.19

          1. A 新增 云函数本地调试支持模拟环境变量
          2. A 新增 云开发云托管消息推送
          3. A 新增 公众号网页开发支持音频标签
          4. A 新增 公众号网页调试支持横屏
          5. A 新增 wx.request 支持使用 enableHttp2 参数
          6. A 新增 可视化编辑增加组件面板
          7. A 新增 调试菜单增加打开工具调试相关文件快捷操作
          8. A 新增 支持 getUserProfile 接口的交互
          9. U 优化 公众号网页调试窗口支持自定义标题栏
          10. U 优化 二次编译 JSON 文件的速度
          11. U 优化 新建云开发项目体验优化
          12. U 优化 sitemap 文件的检测方式
          13. U 优化 背景音频支持倍速设置 playbackRate
          14. U 优化 调试器 js context appservice 展示改为非红色
          15. U 优化 调试器 sources 面板默认自动展开当前 instanceframe 内的代码目录
          16. U 优化 10MB以上代码包采用异步方式上传
          17. U 优化 模拟器更多功能半屏弹窗,横屏时对齐客户端样式
          18. F 修复 分包插件页无法引用分包组件的问题
          19. F 修复 小游戏模拟器分离窗口显示不全的问题
          20. F 修复 调试器 sensor 面板重力模拟无法使用的问题
          21. F 修复 WeappApplication 目录下 Temp 文件占满磁盘问题
          22. F 修复 二维码编译打不开的问题
          23. F 修复 无手机号小程序无法开通云开发的问题
          24. F 修复 多项目窗口切换登录用户后没有同步头像等状态
          25. F 修复 代码片段分享失败的问题
          26. F 修复 模拟器网络设为 offline,WebSocket 依然能通信的问题
          27. F 修复 showToast icon 为 error 展示不正确的问题
          28. F 修复 <web-view /> 中 safe-area-inset-bottom 可能失效的问题
          29. F 修复 小游戏开发模式下读取非 game.json 的 json 文件时,控制台会输出警告的问题
          30. F 修复 第三方平台开发模式下,真机调试获取不到 ext.json 内容的 bug
          31. F 修复 导入项目不能选择云开发的问题
          32. F 修复 部分机器调试器白屏问题
          33. F 修复 编译条件参数为空时 onLoad 方法获取的 options 为 {"": ""} 的问题

          2021.02.01

          1. A 新增 支持调试用微信内素材打开小程序的场景
          2. A 新增 代码静态依赖分析支持小游戏类型
          3. A 新增 sourceMap 匹配调试插件
          4. A 新增 小程序可视化编辑面板
          5. A 新增 支持小程序复制链接的调试
          6. A 新增 支持在微信开发者工具中,以仅代码编辑器的形式打开其他类型的项目或文件夹
          7. A 新增 将编译条件单独配置到 project.private.config.json 
          8. A 新增 支持公众号调试订阅消息
          9. U 优化 优化云开发开通界面流程,支持同时开通云开发和创建环境
          10. U 优化 云开发云托管编辑器支持
          11. F 修复 暗黑模式下工具启动调试器会白屏的问题
          12. F 修复 小游戏项目 signature.json 可能校验失败的问题
          13. F 修复 使用 kbone 项目报错的问题
          14. F 修复 横屏时 safe-area-inset-bottom 数值不对的问题
          15. F 修复 部分场景使用体验评分导致工具闪退的问题 
          16. F 修复 云开发腾讯云弹窗白屏的问题
          17. F 修复 修复第三方平台在cli预览时参数不正确的问题
          18. F 修复 WXML 面板自定义组件 class 重复显示的问题
          19. F 修复 1.05版本工具小游戏真机调试加载失败的问题
          20. F 修复 真机调试 Network 面板显示请求数不正确的问题 
          21. F 修复 project.config.json 中的 projectname 未同步的问题
          22. F 修复 调试器弹出空白的问题
          23. F 修复 wx.request返回值类型错误的问题 
          24. F 修复 点击云开发控制台可能无反应的问题 
          25. F 修复 胶囊位置与客户端保持一致
          26. F 修复 小程序 webview 组件打开公众号网页出现无效签名报错的问题
          27. F 修复 开启热重载时修改 js 文件报错的问题
          28. F 修复 使用2.14.0及以下版本基础库时,配置防盗链的资源可能无法正常使用的问题
          29. F 修复 使用 weui 拓展库出现 getApp() 返回 undefined 的问题
          30. F 修复 小程序 tabbar 在刘海屏机型表现和真机不一致的问题
          31. F 修复 fs.unlink 不为异步的问题
          32. F 修复 WXML 面板 shadowRoot 子节点不正确的问题
          33. F 修复 wx.uploadFile 失败的问题 
          34. F 修复 调用 wx.vibrateLong() 时模拟器会震出屏幕的问题
          35. F 修复 uniapp 框架生成的小程序 sourcemap 问题 
          36. F 修复 小程序导航条是黑色时无法看到 home 按钮的问题
          37. F 修复 小游戏开发模式下读取非 game.json 的 json 文件时,控制台会输出警告的问题
          38. F 修复 公众号网页调试授权信息缺失的问题
          39. F 修复 wxml 编译错误显示缺失的问题 
          40. F 修复 调试器显示 __wxConfig.xxx is deprecated 的问题
          41. F 修复 showToast 弹窗 icon 为 error 的时候展示不对的问题
          42. F 修复 Android 模拟器 胶囊有重影的问题
          43. F 修复 小游戏 downloadFile API 没有自动解压 unzip 返回包的问题

          2021.01.15

          1. F 修复 工具一直处于加载中的问题 
          2. F 修复 多次编译导致工具闪退问题 

          2021.01.04

          1. A 新增 小程序插件开发支持打开功能页
          2. A 新增 wx.getVideoInfo 支持
          3. A 新增 wx.compressVideo 支持
          4. A 新增 <wxs/> src 支持使用绝对路径
          5. A 新增 云开发支持内容管理
          6. A 新增 云函数本地调试支持快速安装 npm 依赖
          7. A 新增 快捷键缩放模拟器区域
          8. A 新增 代码静态依赖分析
          9. A 新增 env(safe-area-inset-bottom) 支持
          10. U 优化 iphone 刘海屏机型的模拟器
          11. U 优化 windows 版本的部分样式
          12. U 优化 多账号调试窗口的菜单栏
          13. U 优化 首次打开项目时编译 JSON 耗时过长的问题
          14. U 优化 首次打开项目文件列表获取异步化
          15. F 修复 wx.downloadFile 无法下载 200M 大小的文件的问题
          16. F 修复 WXML 面板中自定义组件数据无法编辑的问题
          17. F 修复 模拟器区域过小时无法分离模拟器窗口的问题 
          18. F 修复 项目列表窗口会自动弹出来的问题
          19. F 修复 调试器 Network 面板无法显示云函数请求大于 1M 的回包请求
          20. F 修复 wx.getSystemInfo 返回的 safeArea 与真机不一致的问题
          21. F 修复 1.03.2011120 部分视频无法播放的问题

          2020.11.26

          1. A 新增 支持设置插件页面为自定义编译条件的启动页面
          2. A 新增 第三方平台小程序支持使用企业微信模拟器进行调试
          3. A 新增 保留上次预览的二维码
          4. A 新增 云开发控制台文件存储配置
          5. A 新增 修改 appid 时支持下拉选取最近使用的appid
          6. A 新增 体验评分支持导出报告
          7. A 新增 支持切后台后可以获取用户位置
          8. A 新增 云开发静态网站托管支持自定义域名
          9. A 新增 静态网站和云存储支持上传文件夹
          10. A 新增 云开发支持云托管
          11. A 新增 预览时报错通过弹框提供错误信息
          12. U 优化 云开发拓展功能入口优化
          13. U 优化 新建项目流程
          14. U 优化 安装包体积
          15. F 修复 调试器在模拟器右侧时,选择机型会导致调试器错位
          16. F 修复 公众号网页调试模式下调试器白屏
          17. F 修复 项目列表页,删除项目时的弹框无法纵向滚动
          18. F 修复 工具导入代码片段会直接新建一个新的代码片段
          19. F 修复 WXML面板节点元素无法选中
          20. F 修复 新的编译模块在win7系统预览报错的问题
          21. F 修复 udp onClose与客户端表现不一致
          22. F 修复 打开工具全屏的问题
          23. F 修复 多账号调试,编译一直使用缓存
          24. F 修复 2.13.0以上基础库,无法触发 onPageNotFound 
          25. F 修复 非系统菜单栏 Mac 下左上角的放大无法按住option最大化 
          26. F 修复 关闭所有项目窗口后,不能从菜单里打开项目选择界面
          27. F 修复 重复CSS样式没有warning提示
          28. F 修复 cli使用 --appid参数时错误
          29. F 修复 downloadFile接口三端表现不一致
          30. F 修复 openSetting中有三个权限一直关不掉
          31. F 修复 工具上临时文件能被unlink删除的问题
          32. F 修复 MacOS Big Sur 频繁崩溃的问题
          33. F 修复 调试器跟随模拟器一起弹出时编辑器部分区域无法触发点击的问题
          34. F 修复 删除项目后,重启工具,已删除的项目又重新出现的问题
          35. F 修复 休眠后重新打开会出现项目列表窗口的问题

          2020.10.27

          1. A 新增 支持通过打开文件的方式打开项目
          2. A 新增 云开发支持
          3. A 新增 项目详情-本地设置-上传时自动压缩样式
          4. A 新增 MediaTrack.slice 接口支持切割视频
          5. A 新增 自动化测试支持设置机型
          6. A 新增 公众号网页调试支持调试开放标签(支持标签渲染和触发 launch 生命周期)
          7. A 新增 公众号网页调试支持云开发登录 
          8. A 新增 小程序支持 wasm 文件上传
          9. A 新增 模拟 wx.navigateToMiniProgram 小程序跳转的交互
          10. A 新增 wx.getGroupEnterInfo 调试支持
          11. A 新增 关闭项目前提示是否保存已修改的文件
          12. A 新增 cli 支持清除缓存操作
          13. A 新增 预览/真机调试新增代码包信息展示
          14. A 新增 worker 内支持网络、文件、音频等 API
          15. U 优化 小程序表单快速填写交互
          16. U 优化 增加 WXML 代码补全的 catch 事件
          17. U 优化 变更自定义编译条件时不会改动到 project.config.json
          18. U 优化 云开发相同的数据库索引建议只提示一次 
          19. U 优化 内存空间中基础库缓存、工具插件缓存、预览的缓存残余
          20. U 优化 预览/上传时 miniprogramRoot 目录下有过大的 node_modules 目录时的对比文件耗时
          21. U 优化 小程序内用 console 打印日志时在控制台显示的日志一级锚点的跳转位置
          22. F 修复 使用新文件监听模块 Windows 7 部分系统版本保存文件编译无效的问题
          23. F 修复 win 版无法访问网络位置的项目的问题 
          24. F 修复 工具栏隐藏后会挡住部分操作区域的问题 
          25. F 修复 开发小游戏插件无法预览的问题
          26. F 修复 快捷键设置,需要点击空白处才能修改的问题 
          27. F 修复 1.03.2006090 版本通过 cli 预览小游戏项目时提示 app.json 找不到的问题 
          28. F 修复 Kbone 项目 Promise 没有 resolve 的问题 
          29. F 修复 调试器可能会白屏的问题 
          30. F 修复 设置了预览时保存文件,使用快捷键预览未能保存文件的问题 
          31. F 修复 云开发开通无法自动刷新的问题
          32. F 修复 云开发共享环境报错的问题
          33. F 修复 云开发配额显示异常的问题
          34. F 修复 未开通云开发的账户无法使用环境共享的问题
          35. F 修复 云开发部分环境无法加载文件目录的问题 
          36. F 修复 WXML 面板样式编辑时 calc 中带 rpx 出错的问题 
          37. F 修复 WXML 面板空白的问题
          38. F 修复 Windows 版本打开安全设置白屏问题
          39. F 修复 页面中的 video 在 navigateTo 下个页面还播放声音的问题
          40. F 修复 WXML 代码注释方式可能错误的问题
          41. F 修复 win 版双击应用程序图标无法打开项目列表页的问题 
          42. F 修复 1.03.2009301 RC cli 调用 build-npm 无效的问题 
          43. F 修复 控制台中输出非用户定义的字段内容的问题
          44. F 修复 win 版因 filesystem.readFile 接口没有关闭文件句柄导致清除文件缓存失败的问题
          45. F 修复 wx.downloadFile 返回的 downloadTask 无法 abort 的问题
          46. F 修复 WXML 面板中 shadow-root 下 scroll-view 里没有节点的问题 
          47. F 修复 WXML 文件中因存在 <wxs /> 单闭合标签时代码着色、注释和格式化异常的问题 
          48. F 修复 第三方平台小程序因 app.json 过大,且存在大量 page.json 时编译卡顿的问题

          2020.09.15 更新说明

          1. F 修复 提示 Converting circular structure to JSON 的报错的问题 
          2. F 修复 onLaunch 里无法断点且网络请求无法显示的问题 
          3. F 修复 模拟器区域不居中的问题 
          4. F 修复 合并编译模式下,修改 js 文件无效的问题 
          5. F 修复 推出动画异常导致模拟器显示白屏的问题 
          6. F 修复 模拟器显示比例 50%,靠边阈值与展开宽度不理想的问题 
          7. F 修复 自定义 tabBar 会挡住页面底部的问题 
          8. F 修复 切换编译条件后不生效的问题 
          9. F 修复 图片不能在网络面板中预览的问题
          10. F 修复 命中断点后点击编译无效的问题
          11. F 修复 wx.getExtConfig 只有 complete 回调的问题 
          12. F 修复 弹出模拟器后 wxml 面板不可用的问题
          13. F 修复 自动化脚本无法使用自动真机调试的问题
          14. F 修复 wx.showTabBar 无效的问题 

          2020.08.31

          1. A 新增 设置调试器显示位置
          2. A 新增 双击模拟器空白处可以隐藏模拟器交互
          3. A 新增 记录项目窗口的显示大小
          4. A 新增 wxml/wxss/js 文件修改热重载
          5. A 新增 云控制台权限控制
          6. A 新增 云控制台静态网站托管配置
          7. A 新增 模拟器显示和隐藏切换时的表现设置
          8. A 新增 使用快捷键退出工具时提醒,防止误操作
          9. A 新增 登录后触发编译
          10. A 新增 插件权限校验
          11. A 新增 微信字体大小设置
          12. A 新增 支持代码按需注入lazyload
          13. A 新增 云开发数据库自动查询分析与索引提示
          14. A 新增 自动化支持获取体验评分报告
          15. A 新增 提供新的构建 npm 能力
          16. A 修复 旧app.json包含有index页面的情况下,删除app.json,重新建一个有index页面的app.json的时候,不会新增index页面
          17. A 新增 支持直接在自动预览界面切换推送到手机/桌面端微信
          18. A 新增 支持直接在自动真机调试界面切换推送到手机/桌面端微信
          19. A 新增 getPerformance 部分性能指标
          20. U 优化 MockApi 面板参数支持全匹配配置
          21. U 优化 AppData 面板焦点跳动问题
          22. U 优化 WXML 调试体验
          23. U 优化 真机调试文件准备速度
          24. U 优化 小程序模拟器的加载逻辑
          25. U 优化 公众号网页调试 URL 收藏后,hover 显示全部信息
          26. U 优化 创建代码片段时显示“请输入导入链接”等错误提示
          27. U 优化 安装模拟器插件后,需要手动重启才能使用
          28. U 优化 添加模拟器插件/调试器插件后,无须重启工具可正常运行
          29. U 优化 预览和真机调试的界面交互
          30. F 修复 macOS 10.15 无法获取摄像头授权导致 组件无法使用的问题
          31. F 修复 无法加载独立分包的问题 
          32. F 修复 小程序插件中有 app.wxss 文件,其内容会覆盖掉小程序的样式的问题
          33. F 修复 新建小程序云开发项目,第一次启动会报 sitemap.json 未找到的问题
          34. F 修复 无法在 Network 面板看到 wx.uploadFile 的 Response 内容的问题
          35. F 修复 调试器面板 mock 右键菜单失效的问题 
          36. F 修复 使用 wasm 重新编译项目存在内存泄漏
          37. F 修复 自动预览tsc 失败一次后,再次预览无响应
          38. F 修复 模拟器在 Tabbar 设置为 top 时样式错乱的问题 
          39. F 修复 游戏引擎弹窗分包逻辑失效
          40. F 修复 小游戏模拟器白屏,控制台提示__virtualDOM__未定义
          41. F 修复 FileSystemManager.stat 工具和真机返回的path格式不一致
          42. F 修复 小游戏开放数据域使用增强编译异常的问题
          43. F 修复 windows 项目列表界面,底部工具栏丢失的问题 
          44. F 修复 自定义 tabbar 文字展示不完整问题
          45. F 修复 wx.compressImage 返回 tmpFilePath 多了 undefined 
          46. F 修复 Windows 下最大化可能遮挡任务栏的问题 
          47. F 修复 wx.compressImage 返回错误 
          48. F 修复 首次编译 wx.getLaunchOptionsSync 结果可能错误的问题
          49. F 修复 WXML/WXSS 压缩错误问题
          50. F 修复 从网页点击导入代码片段会导致工具卡死
          51. F 修复 windows 关闭新版文件监听模块后,保存project.config.json时会报错
          52. F 修复 修改 project.config.json 里的 appid 不生效的问题 
          53. F 修复 导入链接项目已被删除时能够打开的问题
          54. F 修复 模拟器底部有可能闪现白条的问题 
          55. F 修复 WXML 面板伪类无法调试的问题
          56. F 修复 切换企业微信模拟器插件失败的问题
          57. F 修复 Mac版开发者工具在扫码登录页无法设置代理的问题
          58. F 修复 切换模拟器网络状态时报错的问题

          2020.06.19

          1. A 新增 终端面板
          2. A 新增 查看并管理开发者工具相关进程
          3. A 新增 云开发静态资源托管 
          4. A 新增 小程序设置页面中增加订阅消息开关
          5. A 新增 小程序强制更新调试支持
          6. A 新增 小程序/小游戏 收藏事件调试 
          7. A 新增 通用设置-项目关闭时,控制项目关闭时是否直接打开项目列表窗口
          8. A 新增 通用设置-快速打开文件,控制模拟器区域底部状态栏点击页面路径时打开的文件类型
          9. A 新增 搜索回调调试插件
          10. A 新增 小游戏脚本录制插件
          11. A 新增 模拟器-模拟操作-事件模拟-内存警告
          12. A 新增 支持音视频合成调试 详情
          13. A 新增 代码上传后可以下载对应的 sourcemap 文件
          14. F 修复 编辑器 WXML 文件格式化快捷键失效的问题
          15. F 修复 调试器位置顺序无法拖动排序的问题
          16. F 修复 打开快捷键设置后,编辑器 ctrl/cmd + f 快捷键无法触发文件内搜索的问题 
          17. F 修复 cli 命令行当项目路径有中文的情况下无法正常启动的问题
          18. F 修复 新建代码片段时生成多个 sitemap.json 的问题 
          19. F 修复 mac 版无法读取系统设置的 PATH 环境变量的问题
          20. F 修复 云函数本地调试没有日志的问题 
          21. F 修复 API 代码自动补全时按字母序排序不友好的问题 
          22. F 修复 版本更新通知时,如未选择更新,后续手动检查更新时一直提示正在下载的问题
          23. F 修复 win 版通知中心顶部操作按钮被遮挡的问题 
          24. F 修复 小游戏 video 缺少 onVideoProgress 事件回调的问题
          25. F 修复 1.03.2005140 终止模拟器导致工具奔溃的问题 
          26. F 修复 1.03.2005140 多帐号调试窗口编译会导致主项目窗口模拟器崩溃的问题 
          27. F 修复 1.03.2005140 激励视频广告自动显示并无法关闭的问题
          28. F 修复 独立分包代码被执行两遍的问题 
          29. F 修复 菜单栏新建或导入项目可能没反应的问题
          30. F 修复 模拟器在 Tabbar 设置为 top 时样式错乱的问题
          31. F 修复 Mock 的规则无法删除的问题
          32. F 修复 自定义预览前预处理命令失败后,再次预览无响应的问题 
          33. F 修复 新创建的小游戏项目第一次编译可能提示 __virtualDOM__ is not defined 的问题
          34. F 修复 project.config.json 内容不正确时,无法新建自定义编译条件的问题
          35. F 修复 project.config.json 中 watchOptions.ignore 删除部分配置后,重启工具无法生效的问题

          2020.05.25

          1. A 新增 云函数灰度功能
          2. A 新增 云控制台支持微信支付
          3. A 新增 导入代码片段时,若无填写 appid,默认使用测试号
          4. A 新增 接入 miniprogram-ci 编译模块
          5. A 新增 wxml 面板 支持 delete/backspace 进行节点删除操作
          6. A 新增 支持安装在不同路径下并能够同时使用
          7. A 新增 小程序插件的版本 version 字段支持 "latest"
          8. A 新增 云控制台直接开通按量付费功能
          9. A 新增 去掉小程序跳转小程序的限制
          10. U 优化 设置页面
          11. U 优化 win 版的标题栏视觉、交互
          12. U 优化 模拟器胶囊菜单视觉、交互
          13. U 优化 项目窗口默认在屏幕居中打开,避免窗口在屏幕外导致无法显示窗口的表现
          14. U 优化 小程序页面跳转速度
          15. U 优化 可以选择关闭当前网络使用非安全代理的提示
          16. U 优化 快速回退功能只保留最近三个版本 
          17. F 修复 wxml 面板 rpx 计算错误的问题
          18. F 修复 小窗口时无法显示多帐号选择窗口的确定按钮的问题
          19. F 修复 模拟器静音对视频无效的问题
          20. F 修复 wxml 文件中有 wxs 语法错误无法正常提示的问题
          21. F 修复 使用新版编译模块小游戏开放数据域无法使用的问题
          22. F 修复 console 面板中快速申请点击无效的问题
          23. F 修复 小游戏模拟器弹出时顶部有白条的问题
          24. F 修复 无法更改字体设置的问题 
          25. F 修复 project.config.json 中有 pluginRoot 字段时,会导致小程序页面样式丢失的问题
          26. F 修复 自定义预处理命令的输入体验问题 
          27. F 修复 模拟器静音时会有报错的问题 
          28. F 修复 wxml 面板 componentData 页卡 boolean 字段无法显示的问题 
          29. F 修复 wxml 面板无法显示动态传入的图片 src 的问题
          30. F 修复 项目多开时,当一个项目打开真机调试的情况下直接关闭项目,另一个项目无法启动真机调试的问题
          31. F 修复 项目重命名后,通过菜单无法重新打开该项目的问题
          32. F 修复 network 面板云开发请求中文乱码的问题
          33. F 修复 PC 端模拟 touchend 缺少 changedTouches 的问题
          34. F 修复 开发者工具打开项目时突然报错 illegal operation on a directory 的问题 

          2020.04.02

          1. F 修复 32 位系统无法编译小程序、提示重启耗时过久的问题
          2. F 修复 某些第三方工具不对中文进行转译导致项目打开失败的问题 
          3. F 修复 ts 项目编译前命令无限执行的问题

          2020.03.25

          1. A 新增 云开发控制台支持开通按量付费
          2. A 新增 云开发支持数据库备份与回档(还原)
          3. A 新增 支持小程序自动化多帐号调试
          4. A 新增 显示灰度中的基础库以及基础库支持的客户端版本 
          5. A 新增 下发测试基础库 
          6. A 新增 支持模拟 API 的返回内容 
          7. A 新增 支持同时重命名多个同名的文件
          8. A 新增 真机调试出现异常时,可手动操作重试
          9. A 新增 增加工具加载 loading 展示
          10. A 新增 模拟器支持终止
          11. A 新增 支持小游戏代码补全
          12. U 优化 模拟器工具栏及状态栏界面
          13. U 优化 云开发控制台监控图表展示
          14. U 优化 模拟器添加边框
          15. U 优化 更新命令行和 HTTP v2 版本
          16. F 修复 修改 cloudFunctionRoot 会出现文件找不到的问题 
          17. F 修复 不能正确打开已被删除文件夹的项目的问题
          18. F 修复 点击菜单工具栏管理无反应的问题
          19. F 修复 工具外修改项目配置 cli 上传不生效的问题
          20. F 修复 工具预览/上传提示文件已经存在的问题
          21. F 修复 调试器放大会导致 inspect 按钮样式异常的问题
          22. F 修复 模拟器工具栏样式异常
          23. F 修复 wx.addPhoneContact时顶部按钮显示错误的问题 
          24. F 修复 标题栏文字过长覆盖胶囊按钮的问题
          25. F 修复 文件系统读取代码包内文件规则与真机不一致的问题
          26. F 修复 关闭多帐号调试窗口 tabbar 内的 icon 无法加载的问题
          27. F 修复 预览上传错误提示无效的 json 文件
          28. F 修复 使用非等宽字体时光标可能错位的问题
          29. F 修复 某些项目可能出现 wxml not found 的问题
          30. F 修复 真机调试 Appdata 和 WXML 面板可能显示空白的问题
          31. F 修复 弹出模拟器时 getMenuButtonBoundingClient 调用结果为空的问题
          32. A 新增 支持小程序自动化截图功能
          33. A 新增 编辑器面包屑导航条支持自定义快捷导航
          34. A 新增 模拟小程序进程销毁重启
          35. A 新增 编辑器行内错误和警告提示
          36. A 新增 Mac 和 Windows 微信的模拟器类型
          37. U 优化 1.02.1912261 的安装包结构
          38. U 优化 MacOS 版关闭项目窗口时,显示项目列表窗口
          39. U 优化 插件开发模式下 miniprogramRoot 下 app.json 中插件 provider 与项目 appid 一致时,version 必须为 "dev"
          40. F 修复 1.02.1912261 引入的多帐号调试 tabBar 图标无法加载的问题
          41. F 修复 1.02.1912261 引入的 jsserverRoot 目录右键菜单缺失部分选项的问题
          42. F 修复 公众号网页调试中,Base64 图片无法通过调试器打开的问题
          43. F 修复 cli 调用自动预览无法使用自定义编辑条件的问题
          44. F 修复 Windows 版无法使用录音功能的问题
          45. F 修复 插件开发模式下,插件页面配置不生效的问题
          46. F 修复 小游戏开放数据域使用增强编译报错的问题
          47. F 修复 Windows 版某些情况下无法显示项目窗口的问题
          48. F 修复 切换 cloudfunctionsRoot 无法同步云函数的问题 
          49. F 修复 Wxml 面板丢失 text 标签子节点的问题
          50. F 修复 上传时文件体积大小提示错误问题 
          51. F 修复 使用非等宽字体时光标可能错位的问题
          52. F 修复 文件系统 api 读取代码包内文件规则与真机不一致的问题
          53. A 新增 编辑器全局替换
          54. A 新增 编辑器分栏
          55. A 新增 编辑器文件多选操作和拖动到文件夹
          56. A 新增 编辑器多选操作和拖动到文件夹
          57. A 新增 编辑器代码大纲
          58. A 新增 编辑器文件对比
          59. A 新增 选取 android 设备上的 profile 文件进行分析
          60. A 新增 WXML 面板支持自定义组件数据查看与实时修改
          61. A 新增 WXML 面板支持使用键盘 (上下左右) navigate the DOM tree
          62. A 新增 WXML 面板支持右键操作 Hide element/Delete element/Scroll Into View/Collapse children/Expand recursively
          63. A 新增 云控制台数据库高级查询支持聚合操作 
          64. A 新增 云控制台支持自定义告警
          65. A 新增 云控制台用户访问 DAU 图表
          66. A 新增 云控制台自定义数据库读写权限
          67. A 新增 PC 微信小程序调试支持
          68. A 新增 wx.getSystemInfo 返回 deviceOrientation 信息
          69. A 新增 page meta 支持
          70. A 新增 支持小程序拓展包
          71. A 新增 清除订阅消息授权数据
          72. U 优化 编辑器
          73. U 优化 大型项目目录结构缓存优化
          74. U 优化 <web-view /> 组件页面的调试入口位置
          75. F 修复 小游戏 wx.getMenuButtonBoundingClientRect 返回异常的问题
          76. F 修复 插件页面配置不生效的问题
          77. F 修复 App.onLaunch 执行两次的问题 
          78. F 修复 项目列表丢失的问题
          79. F 修复 onPageNotFound 没有触发的问题
          80. F 修复  云函数请求大量并发时可能会在小程序 network 面板漏展示的问题
          81. F 修复 调试器中开启 disableCache 对渲染层无效的问题
          82. F 修复 模拟器录音不触发 onFrameRecorded 回调的问题
          83. F 修复 小游戏 wx.onKeyboardComplete 回调没有触发的问题 
          84. F 修复 页面跳转后触发 onShow 时场景值为 null 的问题
          85. F 修复 app.json 使用 usingComponents 导致工具卡死的问题

          2019.12.02

          1. A 新增 文档搜索
          2. A 新增 支持引用小程序开发版插件
          3. A 新增 云控制台高级日志功能
          4. A 新增 公众号网页调试收藏地址允许删除
          5. A 新增 小程序快速启动模板默认使用新的组件样式 
          6. A 新增 小游戏支持 loadFont 接口
          7. A 新增 在控制台中显示当前页面 scope-data 校验出错信息
          8. A 新增 云函数本地调试支持 Network 面板
          9. A 新增 支持主包页面直接跳转到分包内的插件页面
          10. A 新增 project.config.json 中增加 watchOptions 字段支持忽略部分文件的监听
          11. F 修复 WXML 代码中没有引号闭合时没有报错的问题
          12. F 修复 使用 npm sval 模块时异常的问题
          13. F 修复 CLI/HTTP 调用上传操作因超时导致报错 Error: socket hang up 的问题
          14. F 修复 工具自动更新后使用 CLI 启动工具时路径错误的问题
          15. F 修复 云开发控制台中无法删除 _id 为数字的记录
          16. F 修复 使用 packOptions.ignore 了自定义组件,小程序运行时还是会报对应组件未找到的问题
          17. F 修复 某些情况下上传代码会报 cannot read property true_true_true_false_production of undefined 的问题
          18. F 修复 有大量 js 文件的小程序项目在点击预览后工具无法响应的问题
          19. F 修复 设置 storage 后立即关闭工具并重启,之前设置的数据无法生效的问题
          20. F 修复 主进程中无法收到 worker 的消息的问题
          21. F 修复 增强编译在 ios8 下计算属性名语法错误的问题 
          22. F 修复 将小游戏项目的 appid 直接修改成小程序的 appid 会导致模拟器消失的问题
          23. F 修复 Page 实例上 getOpenerEventChannel 方法丢失的问题 
          24. F 修复 小程序插件开发时,修改插件的 json 文件无法生效的问题

          2019.10.21

          1. A 新增 云开发新增 19 个付费套餐 
          2. A 新增 导航条中新增小程序返回首页功能
          3. A 新增 wx.chooseLocation 支持传入指定地点
          4. A 新增 云控制台告警设置支持关闭相应告警渠道
          5. A 新增 真机调试支持直接触发客户端周期性更新 
          6. A 新增 通用设置增加“使用新版文件监听模块”的设置(默认勾选)
          7. A 新增 新建项目页面增加测试号文档介绍入口
          8. A 新增 记录代码上传的更新类型
          9. A 新增 支持导入二维码创建自定义编译条件时
          10. A 新增 通用设置调试器最大日志行数
          11. A 新增 公众号网页调试增加清除全部缓存按钮
          12. A 新增 本地编译时使用合并编译
          13. A 新增 WXML 面板 scopeData 校验提示
          14. A 新增 PC 微信开发版小程序自动预览
          15. A 新增 自动真机调试
          16. A 新增 多帐号调试默认测试帐号
          17. A 新增 周期性更新调试支持
          18. A 新增 云开发控制台代金券支付
          19. A 新增 多线程 worker 支持单步调试
          20. A 新增 公众号网页调试中新增 url 收藏夹
          21. A 新增 wx.compressImage 调试
          22. A 新增 小游戏关系链互动数据开发支持
          23. A 新增 支持小游戏 JSServer
          24. A 新增 小游戏节点审查插件
          25. A 新增 云开发环境中的存储桶被删除时,支持在云控制台中创建存储桶
          26. A 新增 新建 Page 失败后会给出失败提示
          27. A 新增 JSServer 支持文件 diff
          28. A 新增 不再存储 project.config.json 里自定义编译条件的 current 值
          29. A 新增 云控制台支持全局开启/关闭云函数消息推送
          30. A 新增 项目重命名功能 
          31. A 新增 编译模式记录通过二维码编译的条件
          32. U 优化 再次打开项目时的首次编译速度
          33. U 优化 GPU 加速默认打开
          34. U 优化 增加 navigationBarBackgroundColor 是否为合法颜色值的监测提示
          35. U 优化 只有未授权时直接调用 wx.getUserInfo 才会出现升级提示
          36. U 优化 wx.downloadFile() 指定路径时增加检测文件大小
          37. U 优化 下线云真机测试功能
          38. U 优化 小程序插件的版本不正确的时候的提示
          39. U 提升了真机调试的稳定性
          40. F 修复 ` 组件在基础库 2.8.2 报错的问题 
          41. F 修复 播放临时文件时连续获取播放时间导致工具卡死的问题 
          42. F 修复 miniprogramRoot 为 "/" 时编译报错的问题
          43. F 修复 代码保护异常时没有报错的问题 
          44. F 修复 npm 构建时 Uncaught TypeError: Cannot redefine property 错误
          45. F 修复 真机调试可能报错模块损坏的问题
          46. F 修复 文件修改后编译不生效的问题
          47. F 修复 展开文件夹时,目录树焦点不正确的问题
          48. F 修复 预览时报文件已经存在的问题 
          49. F 修复 删除用户数据目录后开发者工具启动不了的问题
          50. F 修复 未使用体验评分时存在内存泄漏的情况
          51. F 修复 切换页面偶现 WXML 面板内容丢失问题 
          52. F 修复 调试 WXML 面板 rpx 计算错误导致样式错乱的问题 
          53. F 修复 WXML 面板三目运算符不会更新的问题
          54. F 修复 修改页面文本节点 WXML 面板没有同步的问题
          55. F 修复 project.config.jsonpackOptions.ignore 规则命中的文件夹中存在 __ 开头和结尾的文件夹时无法预览的问题
          56. F 修复 状态栏一直在 loading 的问题 
          57. F 修复 wx.downloadFile 下载文件后缀名存在不正确的问题 
          58. F 修复 云控制台不能删除文件名中含 emoji 的文件
          59. F 修复 UDP 不能发送 ArrayBuffer 的问题 
          60. F 修复 1.02.1909051 引入的上传时进行代码保护异常的问题
          61. F 修复 因基础库中引用的文件网络请求超时导致模拟器加载小程序慢的问题 
          62. F 修复 PC 意外断电导致代码文件乱码的问题 
          63. F 修复 <web-view/> 返回异常的问题
          64. F 修复 小游戏出现 Uncaught TypeError: Illegal invocation 的问题 
          65. F 修复 打开任意文件然后删除该文件再重新建立该文件时,不能立即进行编辑的问题
          66. F 修复 小程序插件开发时,修改 plugin.json 中 publicComponents 无法立即生效的问题
          67. F 修复 小程序内webview页面返回上一级原生页面需要点击两次才能返回的问题
          68. F 修复 WXML 面板编辑 style 时失焦的问题 
          69. F 修复 wx.setBackgroundColor 不生效的问题
          70. F 修复 编辑器删除某文件再创建该文件后不能立即编辑的问题
          71. F 修复 多帐号时删除 log 文件失败的问题
          72. F 修复 减少编辑器保存代码时发生异常情况(如突然断电)后代码变成乱码的概率
          73. F 修复 公众号网页调试网址栏在特定情况下无法删除 URL 的 bug
          74. F 修复 增强编译下使用类装饰器语法编译报错的问题
          75. F 修复 打开项目后立即执行预览/真机调试时报错的问题
          76. F 修复 Wxml 面板调试 CSS 时注释无效重复样式
          77. F 修复 小程序的 WebView 里无法调用 wx.chooseImage 的问题
          78. F 修复 云控制台在深色主题下,欢迎页文本颜色变白的问题
          79. F 修复 小游戏模拟器鼠标移开模拟器区域后有时会报错的问题
          80. F 修复 编辑器保存时有概率滚回顶部的问题
          81. F 修复 覆盖安装时 Wxml 面板调试 CSS 时注释无效重复样式 bug 依然存在的问题
          82. F 修复打开多个项目窗口时,云开发控制台可能打不开的问题
          83. F 修复 小程序插件开发修改 plugin.json 不生效的问题
          84. F 修复项目多开时,某些机型顶部会出现黑条的问题
          85. F 修复 在特定缩放模式下工具栏抖动的问题
          86. F 修复 增强编译下多线程 worker 提示 loadBabelMod is not define 的问题
          87. F 修复 多帐号调试窗口无法复制粘贴的问题
          88. F 修复 在某些情况下自定义分析页面点不了的问题
          89. F 修复 setData 回调函数中出错没有提示的问题
          90. F 修复 WXML 面板编辑时失去焦点的问题
          91. F 修复 编辑器目录展开或关闭时会自动定位到当前 tab 的问题
          92. F 修复 工具项目窗口全屏下点击窗口关闭按钮会出黑屏的问题 
          93. F 修复 未写在 app.json pages 中的页面文件会被主动注册的问题
          94. F 修复 设置快捷键在其他项目窗口失效的问题
          95. F 修复 选择视频时,视频声音自动播放的问题
          96. F 修复 自定义导航栏在页面切换时渲染错误

          2019.08.13

          1. A 新增 小程序支持自动化测试
          2. A 新增 预览当前页面
          3. A 增加 云控制台中监控图表的数据总和显示
          4. A 新增 setTabBarItem 支持临时文件和网络路径
          5. A 新增 公众号调试网址栏下拉菜单点击URL路径后自动跳转
          6. A 新增 通用设置——使用GPU加速模式(默认关闭)
          7. A 新增 云开发控制台支持黑色主题
          8. A 新增 云开发控制台支持购买和变更套餐
          9. A 新增 版本管理支持直接 checkout 远程分支
          10. U 优化 文件监听模块
          11. U 优化 体验评分 UI
          12. U 优化 非 miniprogramRoot 目录下文件的修改不会触发编译
          13. F 修改 Wxml 的 text 标签内容后页面不能同步更新
          14. F 修复 调试器点击临时文件地址打不开的问题
          15. F 修复 1.02.1907160 版本小游戏分包加载异常的问题
          16. F 修复 小游戏 websocket 连接期间切换 offline 无效的问题
          17. F 修复 调整模拟器窗口大小操作时鼠标指针在模拟器窗口内释放后会失效的问题
          18. F 修复 backgroundColorTop/Bottom 只因在 iOS 模拟时生效
          19. F 修复 使用 componentGenerics 导致编译错误的问题
          20. F 修复 顶部按钮返回首页时首页无法正常渲染加载的问题
          21. F 修复 wxml 面板多个选择器共用样式时调试不了样式的问题
          22. F 修复 1.02.1907232 版可能导致 bindtap 失效的问题
          23. F 修复 1.02.1907242 引入的 npm 自定义组件模块引用不到的问题
          24. F 修复 修改语言重启后不生效的问题
          25. F 修复 页面返回 wxml 面板伪类信息丢失的问题
          26. F 修复 wxml 面板伪类信息匹配错误的问题
          27. F 修复 控制台数据库点击数字id的记录没有展示的问题
          28. F 修复 顶部按钮返回首页时首页无法正常渲染加载的问题
          29. F 修复 调整模拟器窗口大小操作时鼠标指针在模拟器窗口内释放后会失效的问题

          2019.07.16

          1. A 新增 云控制台支持执行数据库脚本/CRUD 高级操作
          2. A 新增 云控制台全局设置
          3. A 新增 云控制台支持消息推送配置
          4. A 新增 云控制台配额展示
          5. A 新增 云控制台监控图表
          6. A 新增 云控制台查看云函数详情
          7. A 新增 云函数支持单文件更新
          8. A 新增 Network 面板显示云调用信息
          9. A 新增 内置 ES6+ 语言转义能力增强
          10. A 新增 任务通知中心
          11. A 新增 上传时版本号推荐
          12. A 新增 云开发云调用快速启动模板
          13. A 新增 素材管理,不再维护的提示
          14. A 新增 工具联动 sitemap,控制台显示当前页面是否索引
          15. A 新增 project.config.json 中新增设置 uploadWithSourceMap 
          16. A 新增 增加设置是否工具启动默认打开项目
          17. A 新增 小程序 cover-view 支持
          18. A 新增 cover-view 支持全屏
          19. A 新增 小程序插件还原原始 sourcemap
          20. A 新增 小程序 network 展示图片
          21. A 新增 nightly 的快速更新机制
          22. A 新增 版本管理支持删除远程仓库
          23. A 新增 版本管理支持删除 Tag
          24. A 新增 自定义编译条件增加过滤
          25. A 新增 编辑设置——上传前保存所有文件
          26. A 新增 增加通用设置
          27. A 新增 通用设置——修改默认项目路径
          28. A 新增 非第三方小程序存在 ext.json 时出 warning 提示
          29. A 新增 快速体验开发版菜单项
          30. A 新增 新建编译模式时,自动命名模式名称
          31. A 新增 cli 自动预览支持自定义编译条件
          32. A 新增 cli 指定开发者工具启动时监听的服务端口号
          33. A 新增 wx.getSystemInfo 返回 safeArea
          34. A 新增 FileSystemManager.stat 支持 recursive 参数
          35. A 新增 iPhone XS Max 尺寸
          36. A 新增 体验评分支持小游戏
          37. A 新增 体验评分支持 “iPhone X兼容” 检验规则
          38. A 新增 小程序插件快速申请
          39. A 新增 控制台新增命令 cleanAppCache
          40. U 更新 Win 版升级 nwjs 到 0.37.5
          41. U 更新 Mac 版升级 nwjs 到 0.38.5
          42. U 更新 wxml 属性自动补全采用双引号
          43. U 优化 项目详情的交互
          44. U 优化 云函数代码上传
          45. U 优化 上传时的备注详情可以多行输入
          46. U 优化 移除菜单栏界面左 / 右移模拟器选项
          47. U 优化 任务进度框和通知中心的文本应可以复制
          48. U 优化 视觉调整,弹出模拟器/调试器,界面上不需要有个收回的,关闭窗口即是收回
          49. U 优化 模拟器的最小边距改小
          50. U 优化 任务状态栏展示优化
          51. F 修复 分包中使用自定义组件时出现渲染层错误 cannot read property "length" of undefined 的问题
          52. F 修复 app.json 中应用全局 npm 组件报错 
          53. F 修复 小游戏 wx.shareAppMessage 不带 imageUrl 参数无法调用的问题
          54. F 修复 cli 调用登录时未使用工具代理设置的问题
          55. F 修复 云函数本地调试时环境变量中有中文时云函数发起调用失败的问题
          56. F 修复 1.02.1906141 引入的真机调试无法查看网络请求的返回包的问题
          57. F 修复 上传时使用代码保护导致 workers 报错的问题
          58. F 修复 npm 构建后 module.exports 动态设置的变量获取不到的问题
          59. F 修复 公众号网页调试接口调用没有回调的问题
          60. F 修复 在分包目录下新建 page 时异常的问题
          61. F 修复 公众号网页调试 wx.checkJsApi 返回格式错误的问题
          62. F 修复 <camera /> 组件无法使用的问题
          63. F 修复 当小游戏断点时,点击编译按钮没有效果的问题
          64. F 修复 分包页面如果没有 json 文件时该页面无法使用全局组件的问题
          65. F 修复 多开项目时项目之间的断点会互相影响的问题
          66. F 修复 mac 版开发者工具无法显示项目窗口的问题 
          67. F 修复 独立分包使用增强编译异常的问题
          68. F 修复 Wxml 修改样式时自动失去焦点的问题 
          69. F 修复 Wxml 面板样式无法选择的问题
          70. F 修复 Wxml 面板样式权重计算错误的问题
          71. F 修复 Network 面板耗时显示异常的问题
          72. F 修复 编辑器提示区域丢失文档说明的问题
          73. F 修复 安全设置面板端口号无法选中的问题
          74. F 修复 getMenuButtonBoundingClientRect 返回错误值的问题
          75. F 修复 第三方小程序出现企业微信小程序模式的问题
          76. F 修复 调试器没有弹出按钮的问题
          77. F 修复 代码只启用压缩混淆时报错的问题 
          78. F 修复 插件 md 文档点击预览白屏的问题
          79. F 修复 页面跳转导致界面无法选择的问题
          80. F 修复 进入网页调试后再导入项目报错的问题
          81. F 修复 wxml 面板样式文件路径不显示的问题
          82. F 修复 切换网络模拟时调试器报错的问题
          83. F 修复 增强编译 ignore 功能在预览上传时不生效的问题
          84. F 修复 extAppid 不合法时禁止上传代码
          85. F 修复 工具自动添加不必要 wxss 文件的问题
          86. F 修复 packoption.ignore 配置后的异常不应输出堆栈
          87. F 修复 fs.appendFile 不支持传入 ArrayBuffer 的问题
          88. F 修复 小程序项目中有 sitemap.json 但是 app.json 中没有指定 sitemapLocation 时 sitemap.json 会被覆盖掉
          89. F 修复 偶现 appLaunch with an already exist webviewId 错误
          90. F 修复 小游戏模拟器弹出时,wx.showKeyboard 会一闪而过的问题
          91. F 修复 提交版本的 "项目备注" 历史缓存没了的问题
          92. F 修复 wx.downloadFile 由于代理问题下载不到文件时,会导致逻辑层卡顿的问题
          93. F 修复 开发者工具中 backgroundAudioManager 背景音频获取不到 duration 的问题
          94. F 修复 模拟器第一次弹出,devtools 没有 reload 的问题
          95. F 修复 模拟器 TabBar 多次点击后空白的问题
          96. F 修复 企业微信小程序模式,compileType 错误的问题
          97. F 修复 手动修改 project.config.json 把 appid 变成空字符串会出现项目列表重复的问题
          98. F 修复 切换开发模式,状态栏一直显示某个文件编译中的问题
          99. F 修复 工程文件多编译很慢时,系统错误不会报的问题
          100. F 修复 windows 真机调试,配置了 functionpages 的小程序会报错的问题
          101. F 修复 分包调试时,app.js 初始化两次的问题
          102. F 修复 开发者工具下 makeDirSync 不支持递归创建目录的问题
          103. F 修复 windows nightly 小包更新会项目报错的问题
          104. F 修复 真机调试未读取 packOptions 中的 ignore 的问题
          105. F 修复 大小超过代码包最大限制没有提示代码包大小是多少的问题
          106. F 修复 设置中启动打开最后一次修改项目未生效的问题
          107. F 修复 预览和上传时没有提示超出大小
          108. F 修复 调用 downloadFile 接口没有跳过域名校验
          109. F 修复 网页调试模式有 home 和返回按钮的问题
          110. F 修复 代理设置输入失败问题
          111. F 修复 横竖屏切换,多操作几次会出现无法重排页面问题
          112. F 修复 项目详情切换 AppID 后同步云环境列表失败的问题
          113. F 修复 路径中包含「'」的项目无法打开的问题
          114. F 修复 BackgroundAudioManager.onPlay 运行时机应比 onCanPlay 晚的问题
          115. F 修复 工具旧版本基础库新发布线上插件报找不到 vd_version_info 错误的问题
          116. F 修复 app.json 中的 usingComponents 不应扩散到独立分包内的问题
          117. F 修复 app.json 中 plugins 字段删除后,仍保留了插件引用信息的问题
          118. F 修复 模拟 offline 断网时没有同时阻止一些请求的问题
          119. F 修复 模拟器旋转之后没有自动变大小的问题

          2019.04.17

          1.02.1904090 Windows 64Windows 32macOS

          1. A 新增 云函数本地调试
          2. A 新增 企业微信模拟器插件
          3. A 新增 CLI/HTTP 调用关闭项目窗口、关闭开发者工具
          4. A 新增 小程序支持 pageOrientation: "landscape"
          5. A 新增 分包配置中新增的页面配置会自动生成对应的页面结构
          6. A 新增 真机调试支持调试 functionalPage
          7. A 新增 云控制台支持地理位置索引
          8. U 优化 大型的小程序项目编译卡顿的问题
          9. U 优化 TS 版快速开始的代码结构
          10. U 优化 背景音频的交互体验
          11. F 修复 HTTP 调用无法上传的问题
          12. F 修复 tabBar 字体颜色支持 rgb 格式与客户端不一致的问题
          13. F 修复 tabBar 被蒙层遮住的问题
          14. F 修复 wx.getBackgroundAudioManager 实现与客户端不一致的问题 
          15. F 修复 navigationStyle: custom 有 web-view 组件的页面没有顶部导航栏的问题
          16. F 修复 命令行调用上传时 --upload-desc 会截断空格后内容的问题
          17. F 修复 代理设置本地代理,失去焦点会自动在文字前加空格的问题
          18. F 修复 基础库占比只在第一次预览之后才显示的问题
          19. F 修复 wx.connectSocket 超时时最大连接数控制异常的问题
          20. F 修复 wx.connectSocket 在无法建立连接的情况下没有错误回调的问题
          21. F 修复 web-view 横屏时无法显示全部的问题
          22. F 修复 wxss 中使用非数字开头的自定义属性报错的问题
          23. F 修复 自定义 tabBar 中调用 wx.getSystemInfo 返回的 windowHeight 不正确的问题
          24. F 修复 自定义分析测试功能失效的问题
          25. F 修复 没有开通云开发的 appid 选择云开发启动模板新建项目后会弹下拉提示的问题
          26. F 修复 弹出的模拟器,打开设置授权会出现两个状态栏的问题
          27. F 修复 wx.chooseMessageFile 在 tabBar 切换后失效的问题
          28. F 修复 wxss 文件中 keyframe 后有注释会导致 wxml 面板无法解析样式的问题 
          29. F 修复 弹出模拟器之后 wx.getMenuButtonBoundingClient 异常的问题
          30. F 修复 wxs 无法显示相同日志的问题
          31. F 修复 wxs 报错信息没有显示的问题
          32. F 修复 tabBar 调整会先显示其他 tabBar 页面的问题
          33. F 修复 npm 构建 mqtt 包会报错的问题
          34. F 修复 项目列表窗口大小异常的问题
          35. F 修复 上传时间显示错误的问题

          2019.02.01

          1.02.1902010 Windows 64

          开发者可以使用云开发开发微信小程序、小游戏,无需搭建服务器,即可使用云端能力。

          云开发为开发者提供完整的原生云端支持和微信服务支持,弱化后端和运维概念,无需搭建服务器,使用平台提供的 API 进行核心业务开发,即可实现快速上线和迭代,同时这一能力,同开发者已经使用的云服务相互兼容,并不互斥。

          云开发提供了几大基础能力支持:

          能力作用说明
          云函数无需自建服务器在云端运行的代码,微信私有协议天然鉴权,开发者只需编写自身业务逻辑代码
          数据库无需自建数据库一个既可在小程序前端操作,也能在云函数中读写的 JSON 数据库
          存储无需自建存储和 CDN在小程序前端直接上传/下载云端文件,在云开发控制台可视化管理
          云调用原生微信服务集成基于云函数免鉴权使用小程序开放接口的能力,包括服务端调用、获取开放数据等能力


          可以按如下步骤快速开始使用云开发。

          1. 新建云开发模板
          2. 开通云开发
          3. 体验小程序
          4. 查看控制台

          1. 新建云开发模板

          也可以省略此步骤,直接在已有项目上开通和使用云开发。

          新建项目选择一个空目录,填入 AppID(使用云开发能力必须填写 AppID),勾选创建 “云开发 QuickStart 项目”,点击创建即可得到一个展示云开发基础能力的示例小程序。该小程序与普通 QuickStart 小程序有以下不同需注意:

          • 无游客模式、也不可以使用 测试号
          • project.config.json 中增加了字段 cloudfunctionRoot 用于指定存放云函数的目录
          • cloudfunctionRoot 指定的目录有特殊的图标
          • 云开发能力从基础库 2.2.3 开始支持(覆盖率 97.3%,查看兼容性问题)

          从基础库 2.4.1 开始,在小程序插件中可以使用云开发,插件中使用云开发时,使用的是插件方的云资源而非宿主的云资源,在使用方式上与在小程序中使用无异。

          2. 开通云开发、创建环境

          创建了第一个云开发小程序后,在使用云开发能力之前需要先开通云开发。在开发者工具工具栏左侧,点击 “云开发” 按钮即可打开云控制台、根据提示开通云开发、创建云环境。默认配额下可以创建两个环境,各个环境相互隔离,每个环境都包含独立的数据库实例、存储空间、云函数配置等资源。每个环境都有唯一的环境 ID 标识,初始创建的环境自动成为默认环境。

          注:AppID 首次开通云环境后,需等待大约 10 分钟方可正常使用云 API,在此期间官方后台服务正在做准备服务,如尝试在小程序中调用云 API 则会报 cloud init error:{ errMsg: "invalid scope" } 的错误

          3. 体验小程序

          开通创建环境后,即可以开始在模拟器上操作小程序体验云开发提供的部分基础能力演示。

          4. 查看控制台

          云开发控制台是管理云开发资源的地方,控制台提供以下能力:

          • 运营分析:查看云开发监控、配额使用量、用户访问情况
          • 数据库:管理数据库,可查看、增加、更新、查找、删除数据、管理索引、管理数据库访问权限等
          • 存储管理:查看和管理存储空间
          • 云函数:查看云函数列表、配置、日志

          云开发控制台

          5. 销毁环境

          如需销毁环境,开发者可通过工单联系我们。具体工单提交方式请参考文档《小程序·云开发工单》。


          小程序·云开发提供了多个基础能力,以下对各个主要能力介绍。

          数据库

          云开发提供了一个 JSON 数据库,顾名思义,数据库中的每条记录都是一个 JSON 格式的对象。一个数据库可以有多个集合(相当于关系型数据中的表),集合可看做一个 JSON 数组,数组中的每个对象就是一条记录,记录的格式是 JSON 对象。

          关系型数据库和 JSON 数据库的概念对应关系如下表:

          关系型文档型
          数据库 database数据库 database
          表 table集合 collection
          行 row记录 record / doc
          列 column字段 field

          以下是一个示例的集合数据,假设我们有一个 books 集合存放了图书记录,其中有两本书:

          [  {    "_id": "Wzh76lk5_O_dt0vO",    "title": "The Catcher in the Rye",    "author": "J. D. Salinger",    "characters": [      "Holden Caulfield",      "Stradlater",      "Mr. Antolini"    ],    "publishInfo": {      "year": 1951,      "country": "United States"    }  },  {    "_id": "Wzia0lk5_O_dt0vR",    "_openid": "ohl4L0Rnhq7vmmbT_DaNQa4ePaz0",    "title": "The Lady of the Camellias",    "author": "Alexandre Dumas fils",    "characters": [      "Marguerite Gautier",      "Armand Duval",      "Prudence",      "Count de Varville"    ],    "publishInfo": {      "year": 1848,      "country": "France"    }  }]

          在图书信息中,我们用 title, author 来记录图书标题和作者,用 characters 数组来记录书中的主要人物,用 publishInfo 来记录图书的出版信息。在其中我们可以看到,字段既可以是字符串或数字,还可以是对象或数组,就是一个 JSON 对象。

          每条记录都有一个 _id 字段用以唯一标志一条记录、一个 _openid 字段用以标志记录的创建者,即小程序的用户。需要特别注意的是,在管理端(控制台和云函数)中创建的不会有 _openid 字段,因为这是属于管理员创建的记录。开发者可以自定义 _id,但不可自定义和修改 _openid 。_openid 是在文档创建时由系统根据小程序用户默认创建的,开发者可使用其来标识和定位文档。

          数据库 API 分为小程序端和服务端两部分,小程序端 API 拥有严格的调用权限控制,开发者可在小程序内直接调用 API 进行非敏感数据的操作。对于有更高安全要求的数据,可在云函数内通过服务端 API 进行操作。云函数的环境是与客户端完全隔离的,在云函数上可以私密且安全的操作数据库。

          数据库 API 包含增删改查的能力,使用 API 操作数据库只需三步:获取数据库引用、构造查询/更新条件、发出请求。以下是一个在小程序中查询数据库的发表于美国的图书记录的例子:

          // 1. 获取数据库引用const db = wx.cloud.database()// 2. 构造查询语句// collection 方法获取一个集合的引用// where 方法传入一个对象,数据库返回集合中字段等于指定值的 JSON 文档。API 也支持高级的查询条件(比如大于、小于、in 等),具体见文档查看支持列表// get 方法会触发网络请求,往数据库取数据db.collection('books').where({  publishInfo: {    country: 'United States'  }}).get({  success: function(res) {  // 输出 [{ "title": "The Catcher in the Rye", ... }]  console.log(res) }})

          更多的数据库的 API 的使用和数据库管理,可以参考数据库指引章节。

          存储

          云开发提供了一块存储空间,提供了上传文件到云端、带权限管理的云端下载能力,开发者可以在小程序端和云函数端通过 API 使用云存储功能。

          在小程序端可以分别调用 wx.cloud.uploadFile 和 wx.cloud.downloadFile 完成上传和下载云文件操作。下面简单的几行代码,即可实现在小程序内让用户选择一张图片,然后上传到云端管理的功能:

          // 让用户选择一张图片wx.chooseImage({  success: chooseResult => {    // 将图片上传至云存储空间    wx.cloud.uploadFile({      // 指定上传到的云路径      cloudPath: 'my-photo.png',      // 指定要上传的文件的小程序临时文件路径      filePath: chooseResult.tempFilePaths[0],      // 成功回调      success: res => {        console.log('上传成功', res)      },    })  },})

          上传完成后可在控制台中看到刚上传的图片。

          更多的存储 API 和管理,可以参考存储指引章节。

          云函数

          云函数是一段运行在云端的代码,无需管理服务器,在开发工具内编写、一键上传部署即可运行后端代码。

          小程序内提供了专门用于云函数调用的 API。开发者可以在云函数内使用 wx-server-sdk 提供的 getWXContext 方法获取到每次调用的上下文(appid、openid 等),无需维护复杂的鉴权机制,即可获取天然可信任的用户登录态(openid)。

          比如我们如下定义一个云函数,命名为 add ,功能是将传入的两个参数 a 和 b 相加:

          // index.js 是入口文件,云函数被调用时会执行该文件导出的 main 方法// event 包含了调用端(小程序端)调用该函数时传过来的参数,同时还包含了可以通过 getWXContext 方法获取的用户登录态 `openId` 和小程序 `appId` 信息const cloud = require('wx-server-sdk')exports.main = (event, context) => {  let { userInfo, a, b} = event  let { OPENID, APPID } = cloud.getWXContext() // 这里获取到的 openId 和 appId 是可信的  let sum = a + b  return {    OPENID,    APPID,    sum  }}

          在开发者工具中上传部署云函数后,我们在小程序中可以这么调用:

          除了部署云函数进行调用外,我们还支持云函数本地调试,可以不用部署云函数即可测试
          wx.cloud.callFunction({  // 需调用的云函数名  name: 'add',  // 传给云函数的参数  data: {    a: 12,    b: 19,  },  // 成功回调  complete: console.log})// 当然 promise 方式也是支持的wx.cloud.callFunction({  name: 'add',  data: {    a: 12,    b: 19  }}).then(console.log)

          如需在云函数中操作数据库、管理云文件、调用其他云函数等操作,可使用官方提供的 npm 包 wx-server-sdk 进行操作。

          更多的云函数管理和 API,可以参考云函数指引章节。

          云调用

          云调用是云开发提供的基于云函数使用小程序开放接口的能力,支持在云函数调用服务端开放接口,如发送模板消息、获取小程序码等操作都可以在云函数中完成,详情可见具体开发指引。

          HTTP API

          云开发资源也可以通过 HTTP 接口访问,即在小程序外访问,接口见HTTP API 文档。

          通过这个章节,我们已经了解了云开发是什么,提供了哪些能力,能做什么,接下来跟着我们一起进入开发指引的章节,看看如何上手开发吧!


          重要概念

          在此提供云开发的一些重要概念解释,掌握这些概念对理解云开发和其开发模式非常重要:

          1.资源环境

          一个环境对应一整套独立的云开发资源,包括数据库、存储空间、云函数等资源。各个环境是相互独立的,用户开通云开发后即创建了一个环境,默认可拥有最多两个环境。在实际开发中,建议每一个正式环境都搭配一个测试环境,所有功能先在测试环境测试完毕后再上到正式环境。以初始可创建的两个环境为例,建议一个创建为 test 测试环境,一个创建为 release 正式环境。

          为了方便开发者调试,从开发者工具 1.02.1905302 及基础库 2.7.1 起,在 wx.cloud.init 后会在调试器中输出 SDK 中所使用的默认环境:

          devtools-network-cloud-init

          同时,在 Network 面板中会输出各个云开发操作的请求详情,其中包括该调用所请求的环境 ID:

          devtools-network-env


          2.配额说明

          资源配额

          以下为云开发各类资源配额指标,由腾讯云 TCB 提供存储和计算服务。 用户可通过下载最新的微信开发者工具使用该功能。 资源配额可分为三类:资源均衡型、CDN 资源消耗型、云函数资源消耗型、数据库资源消耗型。

          资源均衡型

          分类参数基础版 1基础版 2专业版 1专业版 2专业版 3旗舰版 1旗舰版 2旗舰版 3企业版 1
          存储容量5GB10GB50GB100GB300GB500GB700GB1000GB1300GB
          下载操作次数150万/月200万/月750万/月1500万/月2500万/月3750万/月4500万/月5000万/月6000万/月
          上传操作次数60万/月100万/月300万/月600万/月1000万/月1500万/月2000万/月2500万/月3000万/月
          CDN回源流量15GB/月10GB/月50GB/月150GB/月300GB/月500GB/月600GB/月800GB/月1000GB/月
          CDNCDN流量5GB/月25GB/月50GB/月150GB/月300GB/月500GB/月1000GB/月2000GB/月4000GB/月
          云函数资源使用量GBs34万/月20万/月40万/月150万/月300万/月400万/月1500万/月3000万/月4000万/月
          外网出流量1GB/月3GB/月5GB/月10GB/月20GB/月25GB/月100GB/月200GB/月400GB/月
          数据库容量2GB3GB5GB10GB20GB10GB50GB100GB200GB
          同时连接数42050100200300400500500500
          读操作数5万/天25万/天50万/天150万/天300万/天500万/天1000万/天2000万/天5000万/天
          写操作数3万/天15万/天30万/天100万/天200万/天300万/天500万/天1000万/天3000万/天
          集合限制100个150个200个300个400个400个500个600个800个
          总价免费30 元/月104 元/月390 元/月690 元/月860 元/月2,499 元/月4,699 元/月8,999 元/月

          CDN 资源消耗型

          分类参数CDN 版 1CDN 版 2CDN 版 3
          存储容量50GB100GB500GB
          下载操作次750万/月1500万/月3750万/月
          上传操作次数300万/月600万/月1500万/月
          CDN回源流量50GB/月150GB/月500GB/月
          CDNCDN流量500GB/月3072GB/月10240GB/月
          云函数资源使用量GBs20万/月50万/月150万/月
          外网出流量3GB/月5GB/月10GB/月
          数据库容量3GB5GB10GB
          同时连接数50100200
          读操作数25万/天50万/天150万/天
          写操作数15万/天30万/天100万/天
          集合限制150个200个300个
          总价149 元/月690 元/月2,199 元/月

          云函数资源消耗型

          分类参数云函数版 1云函数版 2云函数版 3
          存储容量5GB10GB50GB
          下载操作次数150万/月200万/月750 万/月
          上传操作次数60万/月100 万/月300万/月
          CDN回源流量5GB/月10GB/月50GB/月
          CDNCDN流量5GB/月25GB/月150GB/月
          云函数资源使用量GBs40万/月400万/月1500万/月
          外网出流量5GB/月25GB/月100GB/月
          数据库容量3GB10GB20GB
          同时连接数50200300
          读操作数25万/天150万/天300万/天
          写操作数15万/天100万/天200万/天
          集合限制150个300个400个
          总价79 元/月390 元/月1,299 元/月

          数据库资源消耗型

          分类参数数据库版 1数据库版 2数据库版 3
          存储容量5GB10GB50GB
          下载操作次数150万/月200万/月750 万/月
          上传操作次数60万/月100 万/月300万/月
          CDN回源流量5GB/月10GB/月50GB/月
          CDNCDN流量5GB/月25GB/月50GB/月
          云函数资源使用量GBs20万/月150万/月400万/月
          外网出流量3GB/月10GB/月25GB/月
          数据库容量5GB50GB200GB
          同时连接数100400500
          读操作数50万/天500万/天5000万/天
          写操作数30万/天300万/天3000万/天
          集合限制200个400个800个
          总价69 元/月590 元/月1,799 元/月

          除以上配额参数外,小程序·云开发资源还包括以下系统参数限制(所有版本配额都遵守相同的系统参数限制):

          • 云函数(单次运行)运行内存:256M5
          • 云函数数量:50个
          • 云函数并发数:10006
          • 数据库流量:单次出包大小为16M
          • 数据库单集合索引限制:20个
          • 单个小程序的小程序端请求频率限制:100 万次/分钟

          注:

          1. CDN回源流量:指开启了 CDN 加速后,CDN 回源存储时产生的流量。
          2. 云函数调用次数:已放开调用次数限制,现所有套餐均改为无限调用次数
          3. 云函数资源使用量 GBs:资源使用量 = 函数配置内存 X 运行计费时长。用户资源使用量,是由函数配置内存,乘以函数运行时的计费时长得出,其中配置内存转换为 GB 单位,计费时长由毫秒(ms)转换为秒(s)单位,因此,资源使用量的计算单位为 GBs(GB-秒)。例如,配置为 256MB 的函数,单次运行了 1760 ms,计费时长为 1800 ms,则单次运行的资源使用量为 (256/1024)*(1800/1000) = 0.45 GBs。针对函数的每次运行,均会计算资源使用量,并按月汇总求和,作为当月的资源使用量。
          4. 数据库同时连接数 :数据库请求并发数量,如同时有三十个数据库操作请求,则有二十个会同时执行,剩下十个返回超出并发错误;一次数据库请求(无论小程序端发起还是云函数端发起)将耗费一个连接;每个云环境分别有一个同时连接数限制、独立计数。假如数据库查询平均耗时 10ms,那么一个连接可以支持 100qps(1000ms/10ms=100),20个连接可以支持到 2000qps。
          5. 云函数(单次运行)运行内存:云函数运行时最大可用内存为 256 MB。在云函数运行日志中展示的运行内存信息,为当次运行时的实际使用内存。实际使用内存可能低于最大可用内存,计费时按配置内存即 256 MB 计算。
          6. 云函数同时连接数:已放开同时连接数限制,现所有套餐均改为统一的最大上限 1000

          服务等级协议

          小程序·云开发由腾讯云 TCB 提供存储和计算服务,因此小程序·云开发遵循《腾讯云云开发服务等级协议(SLA)》中的相关规定。

          对于已购买云开发套餐并已产生费用的客户,如服务可用性低于标准,开发者有权根据服务等级协议中的赔偿方案,通过相应账户的 工单 申请赔付。具体可用性计算规则、赔偿标准和申请方式遵循《腾讯云云开发服务等级协议(SLA)》中的规定。

          特别说明

          • 自付费功能上线起,将不再受理通过邮箱申请的小程序·云开发配额调整申请。
          • 对于截止2019-06-21日前申请调整的配额的截止日期统一延长至2019-08-31。


          小程序插件中使用云开发

          从基础库 2.4.1 开始,在小程序插件中可以使用云开发,插件中使用云开发时,使用的是插件方的云资源而非宿主的云资源,在使用方式上与在小程序中使用无异。


          开发指引

          云开发提供了一整套云服务及简单、易用的 API 和管理界面,以尽可能降低后端开发成本,让开发者能够专注于核心业务逻辑的开发、尽可能轻松的完成后端的操作和管理。

          下面我们将分一下部分介绍如何上手使用云能力:


          云开发控制台

          云开发提供了一个控制台用于可视化管理云资源。控制台包含以下几大模块。

          • 概览:查看云资源的总体使用情况
          • 用户管理:查看小程序的用户访问记录
          • 数据库:管理数据库集合、记录、权限设置、索引设置
          • 存储管理:管理云文件、权限设置
          • 云函数:管理云函数、查看调用日志、监控记录
          • 统计分析:查看云资源详细使用统计

          在用户管理中会显示使用云能力的小程序的访问用户列表,默认以访问时间倒叙排列,访问时间的触发点是在小程序端调用 wx.cloud.init 方法,且其中的 traceUser 参数传值为 true。例:

          wx.cloud.init({  traceUser: true})

          初始化

          在小程序端开始使用云能力前,需先调用 wx.cloud.init 方法完成云能力初始化(注意小程序需先开通云服务,开通的方法是点击工具栏左上角的 “控制台” 按钮)。因此,如果要使用云能力,通常我们在小程序初始化时即调用这个方法。

          wx.cloud.init 方法的定义如下:

          function init(options): void

          wx.cloud.init 方法接受一个可选的 options 参数,方法没有返回值。

          options 参数定义了云开发的默认配置,该配置会作为之后调用其他所有云 API 的默认配置,options 提供的可选配置如下:

          字段数据类型必填默认值说明
          envstring | objectdefault默认环境配置,传入字符串形式的环境 ID 可以指定所有服务的默认环境,传入对象可以分别指定各个服务的默认环境,见下方详细定义
          traceUserbooleanfalse是否在将用户访问记录到用户管理中,在控制台中可见

          当 env 传入参数为对象时,可以指定各个服务的默认环境,可选字段如下:

          字段数据类型必填默认值说明
          databasestringdefault数据库 API 默认环境配置
          storagestringdefault存储 API 默认环境配置
          functionsstringdefault云函数 API 默认环境配置

          示例代码:

          wx.cloud.init({  env: 'test-x1dzi'})

          云函数端初始化

          cloud.init 方法的定义如下:

          function init(options): void

          cloud.init 方法接受一个可选的 options 参数,方法没有返回值。方法只能调用一次,多次调用时只有第一次调用生效。

          options 参数定义了云开发的默认配置,该配置会作为之后调用其他所有云 API 的默认配置,options 提供的可选配置如下:

          字段数据类型必填默认值说明
          envstring | object后续 API 调用的默认环境配置,传入字符串形式的环境 ID 或传入 cloud.DYNAMIC_CURRENT_ENV 可以指定所有服务的默认环境,传入对象可以分别指定各个服务的默认环境,见下方详细定义

          当 env 传入参数为对象时,可以指定各个服务的默认环境,可选字段如下:

          字段数据类型必填默认值说明
          databasestringdefault数据库 API 默认环境配置
          storagestringdefault存储 API 默认环境配置
          functionsstringdefault云函数 API 默认环境配置
          defaultstring缺省时 API 默认环境配置

          注意:env 设置只会决定本次云函数 API 调用的云环境,并不会决定接下来其他被调云函数中的 API 调用的环境,在其他被调云函数中需要通过 init 方法重新设置环境。

          建议:在设置 env 时指定 cloud.DYNAMIC_CURRENT_ENV 常量 (需 SDK v1.1.0 或以上) ,这样云函数内发起数据库请求、存储请求或调用其他云函数的时候,默认请求的云环境就是云函数当前所在的环境:

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event) => {  const { ENV, OPENID, APPID } = cloud.getWXContext()  // 如果云函数所在环境为 abc,则下面的调用就会请求到 abc 环境的数据库  const dbResult = await cloud.database().collection('test').get()  return {    dbResult,    ENV,    OPENID,    APPID,  }}
          注:上述代码中的 env 参数的值不能用 cloud.getWXContext().ENV 替代,因为在 exports.main 外部调用的 getWXContext() 无法获取到当前环境

          API 风格

          云开发的 API 风格与框架组件和 API 风格一致,但同时支持回调风格和Promise风格。在传入 API 的 Object 参数中,如果传入了 success、fail、complete 字段,则我们认为是采用回调风格,API 方法调用不返回 Promise。如果传入 API 的 Object 参数中 success、fail、complete 这三个字段都不存在,则我们认为是采用Promise风格,API 方法调用返回一个 Promise,Promise resolve 的结果同传入 success 回调的参数,reject 的结果同传入 fail 的参数。

          注意事项

          • 如果 init 时不传 env 参数,后续 API 调用将默认请求到第一个创建的环境,但这种方式并不总是预期的,因此这种方式已废弃,请务必明确传入 env 参数


          调试

          • 云函数本地调试
          • Network 面板
          • 环境提示

          云函数本地调试

          云开发提供了云函数本地调试功能,在本地提供了一套与线上一致的 Node.js 云函数运行环境,让开发者可以在本地对云函数调试,使用本地调试可以提高开发、调试效率:

          • 单步调试/断点调试:比起通过云开发控制台中查看线上打的日志的方法进行调试,使用本地调试后可以对云函数 Node.js 实例进行单步调试/断点调试
          • 集成小程序测试:在模拟器中对小程序发起的交互点击等操作如果触发了开启了本地调试的云函数,会请求到本地实例而不是云端
          • 优化开发流程、提高开发效率:调试阶段不需上传部署云函数,在调试云函数时,相对于不使用本地调试时的调试流程(“本地修改代码 -> 上传部署云函数 -> 调用")的调试流程,省去了上传等待的步骤,改成只需 “本地修改 -> 调用” 的流程,大大提高开发调试效率

          同时,本地调试还定制化提供了特殊的调试能力,包括 Network 面板支持展示 HTTP 请求和云开发请求、调用关系图展示、本地代码修改时热重载等等能力,帮助开发者更好的开发调试云函数。功能具体介绍见下方。

          建议开发者在开发阶段和上传代码前先使用本地调试测试通过后再上线部署。

          更详细的文档点此查看。

          Network 面板

          从微信开发者工具 1.02.1905302 及基础库 2.7.1 起,在小程序 Network 面板中会显示云开发请求(数据库、云函数、文件存储等调用),在 Network 面板中呈现时展示的是 API 名(wx.cloud.uploadFile 和 wx.cloud.downloadFile 除外),有特殊的请求类型 cloud,会展示调用所实际请求的环境 ID、请求体(数据库调用的请求体以 SDK 语法展示)、JSON 回包、耗时、及调用堆栈。

          注意事项: 在开发者工具中云开发接口的实现与客户端有差异,开发者工具中的耗时普遍会比客户端慢,我们在特定环境下的测试结果是客户端会比开发者工具快 33% 左右。

          以下是示例:

          devtools-cloud-network

          数据库调用详情示例:

          devtools-cloud-network

          回包示例:

          devtools-cloud-network

          环境提示

          从微信开发者工具 1.02.1905302 及基础库 2.7.1 起,在小程序调试器中,如果使用到 wx.cloud.init,则会在调试器中输出当前配置的小程序中使用的默认调用环境。

          devtools-network-cloud-init


          如在云开发数据库的基础介绍中所说,云开发提供了一个 JSON 数据库,本章将介绍以下内容:

          • 上手:用控制台创建我的第一个集合,插入我的第一条数据
          • 数据类型:了解数据库提供的数据类型
          • 权限控制:控制集合与记录的读写权限
          • 初始化:初始化数据库 API
          • 插入数据
          • 读取数据:读取数据
          • 构建查询条件:构建简单或复杂的查询条件
          • 更新数据:数据的局部更新与替换更新
          • 删除数据
          • 索引管理:为字段添加索引实现高效读写

          另外可参考小程序端和云函数端的数据库 API 文档


          上手云数据库

          这一节我们将介绍如何在控制台中创建我们的第一个数据库集合、往集合上插入数据、以及在控制台中查看刚刚插入的数据。

          创建第一个集合

          打开控制台,选择 "数据库" 标签页,通过 "添加集合" 入口创建一个集合。假设我们要创建一个待办事项小程序,我们创建一个名为 todos 的集合。创建成功后,可以看到 todos 集合管理界面,界面中我们可以添加记录、查找记录、管理索引和管理权限。

          数据库

          创建第一条记录

          控制台提供了可视化添加数据的交互界面,点击 "添加记录" 添加我们的第一条待办事项:

          {  // 描述,String 类型  "description": "learn mini-program cloud service",  // 截止时间,Date 类型  "due": Date("2018-09-01"),  // 标签,Array 类型  "tags": [    "tech",    "mini-program",    "cloud"  ],  // 个性化样式,Object 类型  "style": {    "color": "red"  },  // 是否已完成,Boolean 类型  "done": false}

          添加完成后可在控制台中查看到刚添加的数据。

          导入数据

          云控制台支持上传文件导入已有的数据,可查看导入指引了解如何操作。

          接下来,我们一起了解下数据库都提供了哪些数据类型。


          数据类型

          云开发数据库提供以下几种数据类型:

          • String:字符串
          • Number:数字
          • Object:对象
          • Array:数组
          • Bool:布尔值
          • GeoPoint:地理位置点
          • Date:时间
          • Null

          下面对几个需要额外说明的字段做下补充说明。

          Date

          Date 类型用于表示时间,精确到毫秒,在小程序端可用 JavaScript 内置 Date 对象创建。需要特别注意的是,在小程序端创建的时间是客户端时间,不是服务端时间,这意味着在小程序端的时间与服务端时间不一定吻合,如果需要使用服务端时间,应该用 API 中提供的 serverDate 对象来创建一个服务端当前时间的标记,当使用了 serverDate 对象的请求抵达服务端处理时,该字段会被转换成服务端当前的时间,更棒的是,我们在构造 serverDate 对象时还可通过传入一个有 offset 字段的对象来标记一个与当前服务端时间偏移 offset 毫秒的时间,这样我们就可以达到比如如下效果:指定一个字段为服务端时间往后一个小时。

          那么当我们需要使用客户端时间时,存放 Date 对象和存放毫秒数是否是一样的效果呢?不是的,我们的数据库有针对日期类型的优化,建议大家使用时都用 Date 或 serverDate 构造时间对象。

          GeoPoint

          GeoPoint 类型用于表示地理位置点,用经纬度唯一标记一个点,这是一个特殊的数据存储类型。注意,如果需要对类型为地理位置的字段进行查找,一定要建立地理位置索引。

          具体的地理位置 API 可参考 Geo API 文档

          Null

          null 相当于一个占位符,表示一个字段存在但是值为空。


          权限控制

          数据库的权限分为小程序端和管理端,管理端包括云函数端和控制台。小程序端运行在小程序中,读写数据库受权限控制限制,管理端运行在云函数上,拥有所有读写数据库的权限。云控制台的权限同管理端,拥有所有权限。小程序端操作数据库应有严格的安全规则限制。

          初期我们对操作数据库开放以下几种权限配置,每个集合可以拥有一种权限配置,权限配置的规则是作用在集合的每个记录上的。出于易用性和安全性的考虑,云开发为云数据库做了小程序深度整合,在小程序中创建的每个数据库记录都会带有该记录创建者(即小程序用户)的信息,以 _openid 字段保存用户的 openid 在每个相应用户创建的记录中。因此,权限控制也相应围绕着一个用户是否应该拥有权限操作其他用户创建的数据展开。

          以下按照权限级别从宽到紧排列如下:

          • 仅创建者可写,所有人可读:数据只有创建者可写、所有人可读;比如文章。
          • 仅创建者可读写:数据只有创建者可读写,其他用户不可读写;比如用私密相册。
          • 仅管理端可写,所有人可读:该数据只有管理端可写,所有人可读;如商品信息。
          • 仅管理端可读写:该数据只有管理端可读写;如后台用的不暴露的数据。

          简而言之,管理端始终拥有读写所有数据的权限,小程序端始终不能写他人创建的数据,小程序端的记录的读写权限其实分为了 “所有人可读,只有创建者可写“、”仅创建者可读写“、”所有人可读,仅管理端可写“、”所有人不可读,仅管理端可读写“。

          对一个用户来说,不同模式在小程序端和管理端的权限表现如下:

          模式小程序端
          读自己创建的数据
          小程序端
          写自己创建的数据
          小程序端
          读他人创建的数据
          小程序端
          写他人创建的数据
          管理端
          读写任意数据
          仅创建者可写,所有人可读×
          仅创建者可读写××
          仅管理端可写,所有人可读××
          仅管理端可读写:该数据只有管理端可读写××××

          在设置集合权限时应谨慎设置,防止出现越权操作。


          初始化

          在开始使用数据库 API 进行增删改查操作之前,需要先获取数据库的引用。以下调用获取默认环境的数据库的引用:

          const db = wx.cloud.database()

          如需获取其他环境的数据库引用,可以在调用时传入一个对象参数,在其中通过 env 字段指定要使用的环境。此时方法会返回一个对测试环境数据库的引用。

          示例:假设有一个环境名为 test,用做测试环境,那么可以如下获取测试环境数据库:

          const testDB = wx.cloud.database({  env: 'test'})

          要操作一个集合,需先获取它的引用。在获取了数据库的引用后,就可以通过数据库引用上的 collection 方法获取一个集合的引用了,比如获取待办事项清单集合:

          const todos = db.collection('todos')

          获取集合的引用并不会发起网络请求取拉取它的数据,我们可以通过此引用在该集合上进行增删查改的操作,除此之外,还可以通过集合上的 doc 方法来获取集合中一个指定 ID 的记录的引用。同理,记录的引用可以用于对特定记录进行更新和删除操作。

          假设我们有一个待办事项的 ID 为 todo-identifiant-aleatoire,那么我们可以通过 doc 方法获取它的引用:

          const todo = db.collection('todos').doc('todo-identifiant-aleatoire')

          接下来,我们看看如何往集合中插入数据。


          插入数据

          可以通过在集合对象上调用 add 方法往集合中插入一条记录。还是用待办事项清单的例子,比如我们想新增一个待办事项:

          db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    // _id: 'todo-identifiant-aleatoire', // 可选自定义 _id,在此处场景下用数据库自动分配的就可以了    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    // 为待办事项添加一个地理位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    // res 是一个对象,其中有 _id 字段标记刚创建的记录的 id    console.log(res)  }})

          当然,Promise 风格也是支持的,只要传入对象中没有 success, fail 或 complete,那么 add 方法就会返回一个 Promise:

          db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    location: new db.Geo.Point(113, 23),    done: false  }}).then(res => {  console.log(res)})

          数据库的增删查改 API 都同时支持回调风格和 Promise 风格调用。

          在创建成功之后,我们可以在控制台中查看到刚新增的数据。

          可以在 add API 文档中查阅完整的 API 定义。

          接下来,我们将学习如何使用 API 查询到刚插入的数据。


          读取数据

          在记录和集合上都有提供 get 方法用于获取单个记录或集合中多个记录的数据。

          假设我们已有一个集合 todos,其中包含以下格式记录:

          [  {    _id: 'todo-identifiant-aleatoire',    _openid: 'user-open-id', // 假设用户的 openid 为 user-open-id    description: "learn cloud database",    due: Date("2018-09-01"),    progress: 20,    tags: [      "cloud",      "database"    ],    style: {      color: 'white',      size: 'large'    },    location: Point(113.33, 23.33), // 113.33°E,23.33°N    done: false  },  {    _id: 'todo-identifiant-aleatoire-2',    _openid: 'user-open-id', // 假设用户的 openid 为 user-open-id    description: "write a novel",    due: Date("2018-12-25"),    progress: 50,    tags: [      "writing"    ],    style: {      color: 'yellow',      size: 'normal'    },    location: Point(113.22, 23.22), // 113.22°E,23.22°N    done: false  }  // more...]

          获取一个记录的数据

          我们先来看看如何获取一个记录的数据,假设我们已有一个 ID 为 todo-identifiant-aleatoire 的在集合 todos 上的记录,那么我们可以通过在该记录的引用调用 get 方法获取这个待办事项的数据:

          db.collection('todos').doc('todo-identifiant-aleatoire').get({  success: function(res) {    // res.data 包含该记录的数据    console.log(res.data)  }})

          也可以用 Promise 风格调用:

          db.collection('todos').doc('todo-identifiant-aleatoire').get().then(res => {  // res.data 包含该记录的数据  console.log(res.data)})

          获取多个记录的数据

          我们也可以一次性获取多条记录。通过调用集合上的 where 方法可以指定查询条件,再调用 get 方法即可只返回满足指定查询条件的记录,比如获取用户的所有未完成的待办事项:

          db.collection('todos').where({  _openid: 'user-open-id',  done: false}).get({  success: function(res) {    // res.data 是包含以上定义的两条记录的数组    console.log(res.data)  }})

          where 方法接收一个对象参数,该对象中每个字段和它的值构成一个需满足的匹配条件,各个字段间的关系是 "与" 的关系,即需同时满足这些匹配条件,在这个例子中,就是查询出 todos 集合中 _openid 等于 user-open-id 且 done 等于 false 的记录。在查询条件中我们也可以指定匹配一个嵌套字段的值,比如找出自己的标为黄色的待办事项:

          db.collection('todos').where({  _openid: 'user-open-id',  style: {    color: 'yellow'  }}).get({  success: function(res) {    console.log(res.data)  }})

          也可以用 "点表示法" 表示嵌套字段:

          db.collection('todos').where({  _openid: 'user-open-id',  'style.color': 'yellow'}).get({  success: function(res) {    console.log(res.data)  }})

          获取一个集合的数据

          如果要获取一个集合的数据,比如获取 todos 集合上的所有记录,可以在集合上调用 get 方法获取,但通常不建议这么使用,在小程序中我们需要尽量避免一次性获取过量的数据,只应获取必要的数据。为了防止误操作以及保护小程序体验,小程序端在获取集合数据时服务器一次默认并且最多返回 20 条记录,云函数端这个数字则是 100。开发者可以通过 limit 方法指定需要获取的记录数量,但小程序端不能超过 20 条,云函数端不能超过 100 条。

          db.collection('todos').get({  success: function(res) {    // res.data 是一个包含集合中有权限访问的所有记录的数据,不超过 20 条    console.log(res.data)  }})

          也可以用 Promise 风格调用:

          db.collection('todos').get().then(res => {  // res.data 是一个包含集合中有权限访问的所有记录的数据,不超过 20 条  console.log(res.data)})

          下面是在云函数端获取一个集合所有记录的例子,因为有最多一次取 100 条的限制,因此很可能一个请求无法取出所有数据,需要分批次取:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const MAX_LIMIT = 100exports.main = async (event, context) => {  // 先取出集合记录总数  const countResult = await db.collection('todos').count()  const total = countResult.total  // 计算需分几次取  const batchTimes = Math.ceil(total / 100)  // 承载所有读操作的 promise 的数组  const tasks = []  for (let i = 0; i < batchTimes; i++) {    const promise = db.collection('todos').skip(i * MAX_LIMIT).limit(MAX_LIMIT).get()    tasks.push(promise)  }  // 等待所有  return (await Promise.all(tasks)).reduce((acc, cur) => {    return {      data: acc.data.concat(cur.data),      errMsg: acc.errMsg,    }  })}

          接下来,我们将学习如何使用进阶的查询条件来完成简单或复杂的查询。


          构建查询条件

          使用数据库 API 提供的 where 方法我们可以构造复杂的查询条件完成复杂的查询任务。

          查询指令

          假设我们需要查询进度大于 30% 的待办事项,那么传入对象表示全等匹配的方式就无法满足了,这时就需要用到查询指令。数据库 API 提供了大于、小于等多种查询指令,这些指令都暴露在 db.command 对象上。比如查询进度大于 30% 的待办事项:

          const _ = db.commanddb.collection('todos').where({  // gt 方法用于指定一个 "大于" 条件,此处 _.gt(30) 是一个 "大于 30" 的条件  progress: _.gt(30)}).get({  success: function(res) {    console.log(res.data)  }})

          API 提供了以下查询指令:

          查询指令说明
          eq等于
          neq不等于
          lt小于
          lte小于或等于
          gt大于
          gte大于或等于
          in字段值在给定数组中
          nin字段值不在给定数组中

          具体的查询指令 API 文档可参考数据库 API 文档。

          逻辑指令

          除了指定一个字段满足一个条件之外,我们还可以通过指定一个字段需同时满足多个条件,比如用 and 逻辑指令查询进度在 30% 和 70% 之间的待办事项:

          const _ = db.commanddb.collection('todos').where({  // and 方法用于指定一个 "与" 条件,此处表示需同时满足 _.gt(30) 和 _.lt(70) 两个条件  progress: _.gt(30).and(_.lt(70))}).get({  success: function(res) {    console.log(res.data)  }})

          既然有 and,当然也有 or 了,比如查询进度为 0 或 100 的待办事项:

          const _ = db.commanddb.collection('todos').where({  // or 方法用于指定一个 "或" 条件,此处表示需满足 _.eq(0) 或 _.eq(100)  progress: _.eq(0).or(_.eq(100))}).get({  success: function(res) {    console.log(res.data)  }})

          如果我们需要跨字段进行 "或" 操作,可以做到吗?答案是肯定的,or 指令还可以用来接受多个(可以多于两个)查询条件,表示需满足多个查询条件中的任意一个,比如我们查询进度小于或等于 50% 或颜色为白色或黄色的待办事项:

          const _ = db.commanddb.collection('todos').where(_.or([  {    progress: _.lte(50)  },  {    style: {      color: _.in(['white', 'yellow'])    }  }])).get({  success: function(res) {    console.log(res.data)  }})

          具体的逻辑查询指令 API 文档可参考数据库 API 文档。

          接下来,我们一起学习如何更新数据。


          更新数据

          现在我们一起看看如何使用数据库 API 完成数据更新。

          更新数据主要有两个方法:

          API说明
          update局部更新一个或多个记录
          set替换更新一个记录

          局部更新

          使用 update 方法可以局部更新一个记录或一个集合中的记录,局部更新意味着只有指定的字段会得到更新,其他字段不受影响。

          比如我们可以用以下代码将一个待办事项置为已完成:

          db.collection('todos').doc('todo-identifiant-aleatoire').update({  // data 传入需要局部更新的数据  data: {    // 表示将 done 字段置为 true    done: true  },  success: function(res) {    console.log(res.data)  }})

          除了用指定值更新字段外,数据库 API 还提供了一系列的更新指令用于执行更复杂的更新操作,更新指令可以通过 db.command 取得:

          更新指令说明
          set设置字段为指定值
          remove删除字段
          inc原子自增字段值
          mul原子自乘字段值
          push如字段值为数组,往数组尾部增加指定值
          pop如字段值为数组,从数组尾部删除一个元素
          shift如字段值为数组,从数组头部删除一个元素
          unshift如字段值为数组,往数组头部增加指定值

          比如我们可以将一个待办事项的进度 +10%:

          const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').update({  data: {    // 表示指示数据库将字段自增 10    progress: _.inc(10)  },  success: function(res) {    console.log(res.data)  }})

          用 inc 指令而不是取出值、加 10 再写进去的好处在于这个写操作是个原子操作,不会受到并发写的影响,比如同时有两名用户 A 和 B 取了同一个字段值,然后分别加上 10 和 20 再写进数据库,那么这个字段最终结果会是加了 20 而不是 30。如果使用 inc 指令则不会有这个问题。

          如果字段是个数组,那么我们可以使用 push、pop、shift 和 unshift 对数组进行原子更新操作,比如给一条待办事项加多一个标签:

          const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').update({  data: {    tags: _.push('mini-program')  },  success: function(res) {    console.log(res.data)  }})

          可能读者已经注意到我们提供了 set 指令,这个指令有什么用呢?这个指令的用处在于更新一个字段值为另一个对象。比如如下语句是更新 style.color 字段为 'blue' 而不是把 style 字段更新为 { color: 'blue' } 对象:

          const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').update({  data: {    style: {      color: 'blue'    }  },  success: function(res) {    console.log(res.data)  }})

          如果需要将这个 style 字段更新为另一个对象,可以使用 set 指令:

          const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').update({  data: {    style: _.set({      color: 'blue'    })  },  success: function(res) {    console.log(res.data)  }})

          如果需要更新多个数据,需在 Server 端进行操作(云函数),在 where 语句后同样的调用 update 方法即可,比如将所有未完待办事项的进度加 10%:

          // 使用了 async await 语法const cloud = require('wx-server-sdk')const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: false      })    .update({      data: {        progress: _.inc(10)      },    })  } catch(e) {    console.error(e)  }}

          更完整详细的更新指令可以参考数据库 API 文档

          替换更新

          如果需要替换更新一条记录,可以在记录上使用 set 方法,替换更新意味着用传入的对象替换指定的记录:

          const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').set({  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    style: {      color: "skyblue"    },    // 位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    console.log(res.data)  }})

          如果指定 ID 的记录不存在,则会自动创建该记录,该记录将拥有指定的 ID。

          接下来,我们将一起学习如何删除记录。


          删除数据

          我们一起看看如何使用数据库 API 完成数据删除。

          删除一条记录

          对记录使用 remove 方法可以删除该条记录,比如:

          db.collection('todos').doc('todo-identifiant-aleatoire').remove({  success: function(res) {    console.log(res.data)  }})

          删除多条记录

          如果需要更新多个数据,需在 Server 端进行操作(云函数)。可通过 where 语句选取多条记录执行删除,只有有权限删除的记录会被删除。比如删除所有已完成的待办事项:

          // 使用了 async await 语法const cloud = require('wx-server-sdk')const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: true    }).remove()  } catch(e) {    console.error(e)  }}

          在大多数情况下,我们希望用户只能操作自己的数据(自己的代表事项),不能操作其他人的数据(其他人的待办事项),这就需要引入权限控制了。

          接下来,我们看看如何控制集合与记录的读写权限,达到保护数据的目的。


          索引管理

          建立索引是保证数据库性能、保证小程序体验的重要手段。我们应为所有需要成为查询条件的字段建立索引。建立索引的入口在控制台中,可分别对各个集合的字段添加索引。

          单字段索引

          对需要作为查询条件筛选的字段,我们可以创建单字段索引。如果需要对嵌套字段进行索引,那么可以通过 "点表示法" 用点连接起嵌套字段的名称。比如我们需要对如下格式的记录中的 color 字段进行索引时,可以用 style.color 表示。

          {  _id: '',  style: {    color: ''  }}

          在设置单字段索引时,指定排序为升序或降序并没有关系。在需要对索引字段按排序查询时,数据库能够正确的对字段排序,无论索引设置为升序还是降序。

          组合索引

          组合索引即一个索引包含多个字段。当查询条件使用的字段包含在索引定义的所有字段或前缀字段里时,会命中索引,优化查询性能。索引前缀即组合索引的字段中定义的前 1 到多个字段,如有在 A, B, C 三个字段定义的组合索引 A, B, C,那么 A 和 A, B 都属于该索引的前缀。

          组合索引具有以下特点:

          1. 字段顺序决定索引效果

          定义组合索引时,多个字段间的顺序不同是会有不同的索引效果的。比如对两个字段 A 和 B 进行索引,定义组合索引为 A, B 与定义组合索引为 B, A是不同的。当定义组合索引为 A, B 时,索引会先按 A 字段排序再按 B 字段排序。因此当组合索引设为 A, B 时,即使我们没有单独对字段 A 设立索引,但对字段 A 的查询可以命中 A, B 索引。需要注意的是,此时对字段 B 的查询是无法命中 A, B 索引的,因为 B 不属于索引 A, B 的前缀之一。

          2. 字段排序决定排序查询是否可以命中索引

          加入我们对字段 A 和 B 设置以下索引:

          A: 升序B: 降序

          那么当我们查询需要对 A, B 进行排序时,可以指定排序结果为 A 升序 B 降序或 A 降序 B 升序,但不能指定为 A 升序 B 升序或 A 降序 B 降序。


          索引属性

          唯一性限制

          创建索引时可以指定增加唯一性限制,具有唯一性限制的索引会要求被索引集合不能存在被索引字段值都相同的两个记录。即对任意具有唯一性限制的索引 I,假设其索引字段为 <F1, F2, ..., Fn>,则对集合 S 中任意的两个记录 R1 和 R2,必须满足条件 R1.F1 != R2.F1 && R1.F2 != R2.F2 && ... && R1.Fn != R2.Fn。需特别注意的是,假如记录中不存在某个字段,则对索引字段来说其值默认为 null,如果索引有唯一性限制,则不允许存在两个或以上的该字段为空 / 不存在该字段的记录。

          在创建索引的时候索引属性选择 唯一 即可添加唯一性限制。


          数据库导入

          云开发控制台支持从文件导入已有的数据。目前仅支持导入 CSV、JSON 格式的文件数据。

          要导入数据,需打开云开发控制台,切换到 “数据库” 标签页,并选择要导入数据的集合,点击 “导入” 按钮。

          数据库

          选择要导入的 CSV 或者 JSON 文件,以及冲突处理模式,点击 “导入” 按钮即可开始导入。

          文件格式

          JSON、CSV 文件必须是 UTF-8 的编码格式,且其内容类似 MongoDB 的导出格式,例如:

          JSON:

          {    "_id": "xxxxxx",    "age": 45}{    "_id": "yyyyyy",    "age": 21}

          CSV:

          _id,agexxxxxx,45yyyyyy,21

          需要注意以下几点:

          1、JSON 数据不是数组,而是类似 JSON Lines,即各个记录对象之间使用   分隔,而非逗号;

          2、JSON 数据每个键值对的键名首尾不能是 .,例如 ".a"、"abc.",且不能包含多个连续的 .,例如 "a..b";

          3、键名不能重复,且不能有歧义,例如 {"a": 1, "a": 2} 或 {"a": {"b": 1}, "a.b": 2};

          4、时间格式须为 ISODate 格式,例如 "date": { "$date" : "2018-08-31T17:30:00.882Z" };

          5、当使用 Insert 冲突处理模式时,同一文件不能存在重复的 _id 字段,或与数据库已有记录相同的 _id 字段;

          6、CSV 格式的数据默认以第一行作为导入后的所有键名,余下的每一行则是与首行键名一一对应的键值记录。

          目前提供了 Insert、Upsert 两种冲突处理模式。Insert 模式会在导入时总是插入新记录,Upsert 则会判断有无该条记录,如果有则更新记录,否则就插入一条新记录。

          导入完成后,可以在提示信息中看到本次导入记录的情况。

          数据库


          数据库导出

          云开发控制台支持导出集合已有的数据。目前仅支持导出 CSV、JSON 格式的文件数据。

          要导出数据,需打开云开发控制台,切换到 “数据库” 标签页,并选择要导出数据的集合,点击 “导出” 链接。

          数据库

          选择要导出的格式、保存的位置,以及字段,点击 “导出” 按钮即可开始导出的过程。

          当选择导出格式为 JSON 时,若不填写字段项,则默认导出所有数据。

          当选择导出格式为 CSV 时,则字段为必填项。字段之间使用英文逗号隔开,例如:

          _id,name,age,gender

          数据库备份与回档

          从开发者工具 1.02.202002282 版本开始,云开发提供了数据库回档功能。系统会自动开启数据库备份,并于每日凌晨自动进行一次数据备份,最长保存 7 天的备份数据。如有需要,开发者可在云控制台上通过新建回档任务将集合回档(还原)至指定时间点。

          回档期间,数据库的数据访问不受影响。回档完成后,开发者可在集合列表中看到原有数据库集合和回档后的集合。

          新建回档

          1. 登录微信开发者工具的云开发控制台。
          2. 在数据库页面点击数据库回档后可新建回档任务。

          新建回档任务

          1. 点击新建回档后,可选择所需回档的时间点和需要回档的集合。请注意:
          • 一次回档任务只能设置一个回档时间,所有待回档集合的回档时间都以此时间点为准;
          • 一次回档任务可选择多个集合,点击全选可回档该环境下所有集合。

          选择回档时间和集合

          1. 点击下一步后可设置回档后集合名称,请注意:
          • 每个待回档集合都可单独设置回档后的集合名称;
          • 系统会默认生成回档后的集合名称,生成规则为:待回档集合名称_bak;
          • 回档后集合名称不可与已有集合名称重复。

          回档后集合名称

          1. 点击确定后,开发者可在数据库回档页面查看回档进度。请注意:
          • 为避免数据冲突,当前有回档任务在执行时,将无法创建新的回档任务;
          • 回档完成后,开发者可在集合列表中看到原有数据库集合和回档后的集合。

          重命名集合

          回档已完成后,如有需要,开发者可在集合列表中选择对应集合,右键重命名该集合名称。


          云存储提供高可用、高稳定、强安全的云端存储服务,支持任意数量和形式的非结构化数据存储,如视频和图片,并在控制台进行可视化管理。云存储包含以下功能:

          • 存储管理:支持文件夹,方便文件归类。支持文件的上传、删除、移动、下载、搜索等,并可以查看文件的详情信息
          • 权限设置:可以灵活设置哪些用户是否可以读写该文件夹中的文件,以保证业务的数据安全
          • 上传管理:在这里可以查看文件上传历史、进度及状态
          • 文件搜索:支持文件前缀名称及子目录文件的搜索
          • 组件支持:支持在 image、audio 等组件中传入云文件 ID

          接下来,我们看看云文件管理提供了哪些 API、及如何在控制台中管理云文件:

          • 存储 API
          • 控制台中管理文件

          API 指引

          上传文件

          在小程序端可调用 wx.cloud.uploadFile 方法进行上传:

          wx.cloud.uploadFile({  cloudPath: 'example.png', // 上传至云端的路径  filePath: '', // 小程序临时文件路径  success: res => {    // 返回文件 ID    console.log(res.fileID)  },  fail: console.error})

          上传成功后会获得文件唯一标识符,即文件 ID,后续操作都基于文件 ID 而不是 URL。

          下载文件

          可以根据文件 ID 下载文件,用户仅可下载其有访问权限的文件:

          wx.cloud.downloadFile({  fileID: '', // 文件 ID  success: res => {    // 返回临时文件路径    console.log(res.tempFilePath)  },  fail: console.error})

          删除文件

          可以通过 wx.cloud.deleteFile 删除文件:

          wx.cloud.deleteFile({  fileList: ['a7xzcb'],  success: res => {    // handle success    console.log(res.fileList)  },  fail: console.error})

          更详细的 API 可参考小程序端及后端存储 API 文件。

          组件支持

          支持在 image、audio 等组件中传入云文件 ID,具体支持列表见文档

          换取临时链接

          可以根据文件 ID 换取临时文件网络链接,文件链接有有效期为两个小时:

          wx.cloud.getTempFileURL({  fileList: ['cloud://xxx.png'],  success: res => {    // fileList 是一个有如下结构的对象数组    // [{    //    fileID: 'cloud://xxx.png', // 文件 ID    //    tempFileURL: '', // 临时文件网络链接    //    maxAge: 120 * 60 * 1000, // 有效期    // }]    console.log(res.fileList)  },  fail: console.error})

          API 文档

          可以在此参考详细的小程序端存储 API 文档和服务端 API 文档


          管理文件

          在控制台中,选择存储管理标签页,可以在此看到云存储空间中所有的文件,还可以查看文件的详细信息、控制存储空间的读写权限。



          文件名命名限制

          • 不能为空
          • 不能以/开头
          • 不能出现连续/
          • 编码长度最大为850个字节
          • 推荐使用大小写英文字母、数字,即[a-z,A-Z,0-9]和符号 -,!,_,.,* 及其组合
          • 不支持 ASCII 控制字符中的字符上(↑),字符下(↓),字符右(→),字符左(←),分别对应 CAN(24),EM(25),SUB(26),ESC(27)
          • 如果用户上传的文件或文件夹的名字带有中文,在访问和请求这个文件或文件夹时,中文部分将按照 URL Encode 规则转化为百分号编码。
          • 不建议使用的特殊字符: ` ^ " { } [ ] ~ % # > < 及 ASCII 128-255 十进制
          • 可能需特殊处理后再使用的特殊字符: , : ; = & $ @ + ?(空格)及ASCII 字符范围:00-1F 十六进制(0-31 十进制)以及7F(127 十进制)

          组件支持

          小程序组件支持传入云文件 ID,支持列表如下:

          组件属性
          imagesrc
          videosrc、poster
          cover-imagesrc
          接口参数
          getBackgroundAudioManagersrc
          createInnerAudioContextsrc
          previewImageurls、current


          云函数即在云端(服务器端)运行的函数。在物理设计上,一个云函数可由多个文件组成,占用一定量的 CPU 内存等计算资源;各云函数完全独立;可分别部署在不同的地区。开发者无需购买、搭建服务器,只需编写函数代码并部署到云端即可在小程序端调用,同时云函数之间也可互相调用。

          一个云函数的写法与一个在本地定义的 JavaScript 方法无异,代码运行在云端 Node.js 中。当云函数被小程序端调用时,定义的代码会被放在 Node.js 运行环境中执行。我们可以如在 Node.js 环境中使用 JavaScript 一样在云函数中进行网络请求等操作,而且我们还可以通过云函数后端 SDK 搭配使用多种服务,比如使用云函数 SDK 中提供的数据库和存储 API 进行数据库和存储的操作,这部分可参考数据库存储后端 API 文档。

          云开发的云函数的独特优势在于与微信登录鉴权的无缝整合。当小程序端调用云函数时,云函数的传入参数中会被注入小程序端用户的 openid,开发者无需校验 openid 的正确性因为微信已经完成了这部分鉴权,开发者可以直接使用该 openid。

          接下来,我们将逐步学习以下内容:

          • 我的第一个云函数
          • 获取小程序用户信息
          • 异步返回结果
          • 使用 wx-server-sdk
          • 在开发者工具中管理云函数
          • 测试、日志与监控
          • 注意事项

          我的第一个云函数

          我们以定义一个将两个数字相加的函数作为我们第一个云函数的示例。

          在项目根目录找到 project.config.json 文件,新增 cloudfunctionRoot 字段,指定本地已存在的目录作为云函数的本地根目录

          示例:

          {   "cloudfunctionRoot": "./functions/"}

          project.config.json 的其他配置,详见项目配置文件

          完成指定之后,云函数的根目录的图标会变成 “云目录图标”,云函数根目录下的第一级目录(云函数目录)是与云函数名字相同的,如果对应的线上环境存在该云函数,则我们会用一个特殊的 “云图标” 标明

          接着,我们在云函数根目录上右键,在右键菜单中,可以选择创建一个新的 Node.js 云函数,我们将该云函数命名为 add。开发者工具在本地创建出云函数目录和入口 index.js 文件,同时在线上环境中创建出对应的云函数。创建成功后,工具会提示是否立即本地安装依赖,确定后工具会自动安装 wx-server-sdk。我们可以看到类似如下的一个云函数模板:

          const cloud = require('wx-server-sdk')// 云函数入口函数exports.main = async (event, context) => {}

          云函数的传入参数有两个,一个是 event 对象,一个是 context 对象。event 指的是触发云函数的事件,当小程序端调用云函数时,event 就是小程序端调用云函数时传入的参数,外加后端自动注入的小程序用户的 openid 和小程序的 appid。context 对象包含了此处调用的调用信息和运行状态,可以用它来了解服务运行的情况。在模板中也默认 require 了 wx-server-sdk,这是一个帮助我们在云函数中操作数据库、存储以及调用其他云函数的微信提供的库,关于 wx-server-sdk 的使用我们在另一个章节讲述。

          我们填充一下模板:

          exports.main = async (event, context) => {  return {    sum: event.a + event.b  }}

          本段代码的意思是将传入的 a 和 b 相加并作为 sum 字段返回给调用端。

          在小程序中调用这个云函数前,我们还需要先将该云函数部署到云端。在云函数目录上右键,在右键菜单中,我们可以将云函数整体打包上传并部署到线上环境中。

          部署完成后,我们可以在小程序中调用该云函数:

          wx.cloud.callFunction({  // 云函数名称  name: 'add',  // 传给云函数的参数  data: {    a: 1,    b: 2,  },  success: function(res) {    console.log(res.result) // 3  },  fail: console.error})

          当然,Promise 风格的调用也是支持的:

          wx.cloud.callFunction({  // 云函数名称  name: 'add',  // 传给云函数的参数  data: {    a: 1,    b: 2,  },}).then(res => {  console.log(res.result) // 3}).catch(console.error)

          那么到这里,我们就成功创建了我们的第一个云函数,并在小程序中成功调用!

          接下来,我们介绍云函数和小程序登录态如何无缝结合,以及如何在云函数端获取小程序用户信息(openid 和 appid)。


          获取小程序用户信息

          云开发的云函数的独特优势在于与微信登录鉴权的无缝整合。当小程序端调用云函数时,云函数的传入参数中会被注入小程序端用户的 openid,开发者无需校验 openid 的正确性,因为微信已经完成了这部分鉴权,开发者可以直接使用该 openid。与 openid 一起同时注入云函数的还有小程序的 appid。

          从小程序端调用云函数时,开发者可以在云函数内使用 wx-server-sdk 提供的 getWXContext 方法获取到每次调用的上下文(appid、openid等),无需维护复杂的鉴权机制,即可获取天然可信任的用户登录态(openid)。可以写这么一个云函数进行测试:

          // index.jsconst cloud = require('wx-server-sdk')exports.main = (event, context) => {  // 这里获取到的 openId、 appId 和 unionId 是可信的,注意 unionId 仅在满足 unionId 获取条件时返回  let { OPENID, APPID, UNIONID } = cloud.getWXContext()   return {    OPENID,    APPID,    UNIONID,  }}

          假设云函数命名为 test,上传并部署该云函数后,可在小程序中测试调用:

          wx.cloud.callFunction({  name: 'test',  complete: res => {    console.log('callFunction test result: ', res)  }})

          会在调试器看到输出的 res 为如下结构的对象:

          {  "APPID": "xxx",  "OPENID": "yyy",  "UNIONID": "zzz", // 仅在满足 unionId 获取条件时返回}

          接下来,我们一起看看如果在云函数中需要进行一段异步操作再返回的时候该如何处理。


          异步返回结果

          经常,我们需要在云函数中处理一些异步操作,在异步操作完成后再返回结果给到调用方。此时我们可以通过在云函数中返回一个 Promise 的方法来完成。

          一个最简的 setTimeout 示例:

          // index.jsexports.main = async (event, context) => {  return new Promise((resolve, reject) => {    // 在 3 秒后返回结果给调用方(小程序 / 其他云函数)    setTimeout(() => {      resolve(event.a + event.b)    }, 3000)  })}

          假设云函数名字为 test,上传部署该云函数后,我们可以在小程序端测试调用:

          // 在小程序代码中:wx.cloud.callFunction({  name: 'test',  data: {    a: 1,    b: 2,  },  complete: res => {    console.log('callFunction test result: ', res)  },})

          此时应该看到调试器输出:

          callFunction test result: 3

          使用 npm

          在云函数中我们可以引入第三方依赖来帮助我们更快的开发。云函数的运行环境是 Node.js,因此我们可以使用 npm 安装第三方依赖。比如除了使用 Node.js 提供的原生 http 接口在云函数中发起网络请求,我们还可以使用一个流行的 Node.js 网络请求库 request 来更便捷的发起网络请求。

          注意,现在上传云函数时不会在云端自动安装依赖,需要开发者在本地安装好依赖后一起打包上传。

          接下来,我们一起了解下官方提供的云函数端 SDK: wx-server-sdk。


          在云函数中使用 wx-server-sdk

          云函数属于管理端,在云函数中运行的代码拥有不受限的数据库读写权限和云文件读写权限。需特别注意,云函数运行环境即是管理端,与云函数中的传入的 openId 对应的微信用户是否是小程序的管理员 / 开发者无关。

          云函数中使用 wx-server-sdk 需在对应云函数目录下安装 wx-server-sdk 依赖,在创建云函数时会在云函数目录下默认新建一个 package.json 并提示用户是否立即本地安装依赖。请注意云函数的运行环境是 Node.js,因此在本地安装依赖时务必保证已安装 Node.js,同时 node 和 npm 都在环境变量中。如不本地安装依赖,可以用命令行在该目录下运行:

          npm install --save wx-server-sdk@latest

          在云函数中调用其他 API 前,同小程序端一样,也需要执行一次初始化方法:

          const cloud = require('wx-server-sdk')// 默认配置cloud.init()// 或者传入自定义配置cloud.init({  env: 'some-env-id'})

          wx-server-sdk 与小程序端的云 API 以同样的风格提供了数据库、存储和云函数的 API。下面提供几个简单的操作数据库、存储和云函数的示例:

          云函数中调用数据库

          假设在数据库中已有一个 todos 集合,我们可以如下方式取得 todos 集合的数据:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  // collection 上的 get 方法会返回一个 Promise,因此云函数会在数据库异步取完数据后返回结果  return db.collection('todos').get()}

          云函数中调用存储

          假设我们要上传在云函数目录中包含的一个图片文件(demo.jpg):

          const cloud = require('wx-server-sdk')const fs = require('fs')const path = require('path')exports.main = async (event, context) => {  const fileStream = fs.createReadStream(path.join(__dirname, 'demo.jpg'))  return await cloud.uploadFile({    cloudPath: 'demo.jpg',    fileContent: fileStream,  })}
          在云函数中,__dirname 的值是云端云函数代码所在目录

          云函数中调用其他云函数

          假设我们要在云函数中调用另一个云函数 sum 并返回 sum 所返回的结果:

          const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  return await cloud.callFunction({    name: 'sum',    data: {      x: 1,      y: 2,    }  })}

          更详细的 wx-server-sdk 文档可参见服务端 API 文档。

          接下来,我们一起了解下云函数的运行机制。


          运行机制

          运行环境

          云函数运行在云端 Linux 环境1中,一个云函数在处理并发请求的时候会创建多个云函数实例,每个云函数实例之间相互隔离,没有公用的内存或硬盘空间。云函数实例的创建、管理、销毁等操作由平台自动完成。每个云函数实例都在 /tmp 目录下提供了一块 512MB 的临时磁盘空间用于处理单次云函数执行过程中的临时文件读写需求,需特别注意的是,这块临时磁盘空间在函数执行完毕后可能被销毁,不应依赖和假设在磁盘空间存储的临时文件会一直存在。如果需要持久化的存储,请使用云存储功能。

          无状态函数

          云函数应是无状态的,幂等的,即一次云函数的执行不依赖上一次云函数执行过程中在运行环境中残留的信息。

          为了保证负载均衡,云函数平台会根据当前负载情况控制云函数实例的数量,并且会在一些情况下重用云函数实例,这使得连续两次云函数调用如果都由同一个云函数实例运行,那么两者会共享同一个临时磁盘空间,但因为云函数实例随时可能被销毁,并且连续的请求不一定会落在同一个实例,因此云函数不应依赖之前云函数调用中在临时磁盘空间遗留的数据。总的原则即是云函数代码应是无状态的。

          事件模型

          云函数的调用采用事件触发模型,小程序端的每一次调用即触发了一次云函数调用事件,云函数平台会新建或复用已有的云函数实例来处理这次调用。同理,因为云函数间也可以相互调用,因此云函数间相互调用也是触发了一次调用事件。

          自动扩缩容

          开发者无需关心云函数扩容和缩容的问题,平台会根据负载自动进行扩缩容。

          Footnotes

          1. 当前运行环境是在 CentOS 7.2 中,特别注意编写代码不应依赖特定的操作系统或特定的操作系统版本号,运行环境可能会发生变化,代码应尽量与平台无关

          注意事项 & FAQ

          临时存储空间

          云函数的运行环境中在 /tmp 目录下提供了一块 512MB 的临时磁盘空间,用于处理单次云函数执行过程中的临时文件读写需求,需特别注意的是,这块临时磁盘空间在函数执行完毕后可能被销毁,不应依赖和假设在磁盘空间存储的临时文件会一直存在。如果需要持久化的存储,请使用云存储功能。

          用户代码目录:__dirname

          在云函数执行过程中,通过 __dirname 可获取当前云函数的根目录,如果有随云函数打包上传的资源文件,可以通过 __dirname 加相对路径引用获取。

          Node.js native 依赖

          如果有使用到平台相关的 native 依赖,即依赖需要在相应平台下编译(Windows / macOS / Linux ...)的,务必注意在 Linux 平台(CentOS 7 最佳)下编译后再上传,否则可能出现环境兼容性问题。


          在开发者工具中管理云函数

          配置云函数本地目录

          在项目根目录中可以使用 project.config.json 文件,在其中定义 cloudfunctionRoot 字段,指定本地已存在的目录作为云函数的本地根目录。

          云函数操作

          在云函数根目录或者云函数目录上,通过鼠标右键,我们可以唤出右键菜单,完成以下操作

          1. 查看当前环境
          2. 切换环境
          3. 新建 Node.js 云函数
          4. 下载线上环境的云函数列表
          5. 下载线上环境的云函数代码并覆盖本地
          6. 对比本地代码和线上环境的代码
          7. 上传并部署云函数到线上环境

          查看和切换环境

          在云函数根目录上右键,在右键菜单中,可以查看当前对应的环境,同时可以切换环境,之后的所有右键菜单都是在这个环境下进行操作

          新建 Node.js 云函数

          在云函数根目录上右键,在右键菜单中,可以选择创建一个新的 Node.js 云函数,开发者工具在本地创建出以下目录和文件,同时在线上环境中创建出对应的云函数:

          • 云函数目录:以云函数名字命名的目录,存放该云函数的所有代码
          • index.js:云函数入口文件,云函数被调用时实际执行的入口函数是 index.js 中导出的 main 方法
          • package.json:npm 包定义文件,其中默认定义了最新 wx-server-sdk 依赖

          在创建成功后,工具会提示是否为该云函数立即安装本地依赖即 wx-server-sdk,如是,则工具会开启终端执行 npm install


          下载云函数列表

          在云函数根目录上右键,在右键菜单中,我们可以将线上环境中的云函数列表同步到本地,开发者工具会根据云函数的名字,在本地中创建出对应的云函数目录

          下载云函数

          在一个云函数目录上右键可以在菜单中选择下载该云函数,云函数代码会被下载到指定目录。

          上传并部署

          在云函数目录上右键,在右键菜单中,我们可以将云函数整体打包上传并部署到线上环境中

          更多设置

          我们通过右键菜单的 “更多设置” 可以进入云函数的沉浸式交互场景,在这个场景里可以完成以上所有的云函数操作,在云目录上按 ctrl 可以进行多选批量操作

          接下来,我们一起看看如何在开发云函数时进行测试、查看日志、以及查看监控。


          测试、日志与监控

          测试

          云开发提供了云函数测试功能,可以方便地调试你的代码。在控制台的对应云函数的管理面板中,点击 “测试” 按钮即可打开测试弹窗。

          测试弹窗

          点击“提交方法”下拉菜单可以选择测试函数的模板方法,当前只支持Hello World 事件模板。模板在测试时作为 event 参数传递给函数。在“测试参数”的编辑器中输入想测试的参数后,点击“执行”按钮即可运行代码。执行完毕后将在“运行测试”栏显示运行结果。

          除了可视化的云函数测试功能,我们还提供命令行工具 scf-cli, 助你在本地快速调试。

          日志

          在这里可以查看云函数的调用日志,方便开发者对开发调试。

          监控

          在这里可以查看云函数的调用次数、运行时间、错误次数。并支持将这些数据导出。

          云调用

          版本要求:wx-server-sdk >= 0.4.0、开发者工具 >= 1.02.1904090 (RC版下载)

          云调用是云开发提供的基于云函数使用小程序开放接口的能力,目前覆盖以下使用场景:

          • 服务端调用
          • 开放数据调用
          • 消息推送

          一、服务端调用

          云调用需要在云函数中通过 wx-server-sdk 使用。在云函数中使用云调用调用服务端接口无需换取 access_token,只要是在从小程序端触发的云函数中发起的云调用都经过微信自动鉴权,可以在登记权限后直接调用如发送模板消息等开放接口。使用方式如下:

          1. 查看服务端接口是否支持云调用

          在服务端接口列表中罗列了所有的服务端接口,如果接口支持云调用,则在接口名称旁会带有 云调用 的标签。同时,在每一个服务端接口文档中,如果接口支持云调用,也会有专门的支持说明以及相应的使用文档。

          2. 查看接口的云调用文档

          在支持云调用的接口文档中,会分别列出 HTTPS 调用的文档及云调用的文档,云调用文档同 HTTPS 调用文档一样包含请求参数、返回值及示例。

          3. 为云函数声明所需调用的接口

          接着,需要配置云调用权限,每个云函数需要声明其会使用到的接口,否则无法调用,声明的方法是在云函数目录下的 config.json(如无需新建)配置文件的 permissions.openapi 字段中增加要调用的接口名,permissions.openapi 是个字符串数组字段,值必须为所需调用的服务端接口名称。在每次使用微信开发者工具上传云函数时均会根据配置更新权限,该配置有10分钟的缓存,如果更新后提示没有权限,稍等10分钟后再试。以下是一个示例的声明了使用发送模板消息接口的配置文件:

          {  "permissions": {    "openapi": [      "templateMessage.send"    ]  }}

          4. 在云函数中使用云调用

          首先云函数中需要使用版本号至少 0.4.0 的 wx-server-sdk,建议 wx-server-sdk 始终保持最新,保证云函数目录下的 package.json 的 wx-server-sdk 字段为 latest,如本地安装依赖,请执行 npm install --save wx-server-sdk@latest。

          接下来,可在云函数中使用云调用 API 了。云调用 API 均挂载在 wx-server-sdk 模块的 openapi 对象下,各个开放接口类别在 openapi 对象下设二级命名空间对象(如模板消息接口的方法均在 openapi.templateMessage 下),该对象下挂载该类别下的所有开放方法(比如模板消息的发送接口是 openapi.templateMessage.send)。各接口从属的类别名称和方法名称可以通过接口名称查看,接口名称均以 <类别>.<方法> 命名,如发送模板消息的接口名称是 templateMessage.send。下面是一个给自己发送模板消息的示例:

          如需可直接运行的示例,请在 IDE 中创建一个云开发快速启动模板的项目,其中有包含发送模板消息的云调用的示例
          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  try {    const result = await cloud.openapi.templateMessage.send({      touser: cloud.getWXContext().OPENID, // 通过 getWXContext 获取 OPENID      page: 'index',      data: {        keyword1: {          value: '339208499'        },        keyword2: {          value: '2015年01月05日 12:30'        },        keyword3: {          value: '腾讯微信总部'        },        keyword4: {          value: '广州市海珠区新港中路397号'        }      },      templateId: 'TEMPLATE_ID',      formId: 'FORMID',      emphasisKeyword: 'keyword1.DATA'    })    // result 结构    // { errCode: 0, errMsg: 'openapi.templateMessage.send:ok' }    return result  } catch (err) {    // 错误处理    // err.errCode !== 0    throw err  }}

          二、开放数据调用

          对返回敏感开放数据的小程序端接口,从基础库 2.7.0 起,如果小程序已开通云开发,则可在开放数据接口的返回值中获取到唯一对应敏感开放数据的 cloudID,通过云调用可以直接获取到开放数据,具体使用方法见 云调用直接获取开放数据。

          三、消息推送

          云开发也支持通过云函数接收小程序消息推送(如接收到客服消息时触发云函数),具体接入方式见消息推送。


          微信支付

          从开发者工具 1.02.2005111 起,云控制台支持云开发微信支付商户绑定,在绑定完成后可在云开发中原生接入微信支付:

          1. 免签名:所有接口免签名、直接获取小程序 wx.requestPayment 所需参数
          2. 接收回调:云函数支持接收异步支付结果回调

          pay

          资质

          需要是已经开通了微信支付,且已绑定了商户号的小程序。

          开通

          在云控制台 -> 设置 -> 全局设置中开通。

          权限

          添加商户号后需要分别进行帐号绑定、jsapi 和 api 退款权限授权。请注意:

          1)帐号绑定:需要在绑定的商户号管理员在微信支付提供的【微信支付商家助手】小程序上确认授权。

          2)jsapi 和 api 退款权限,需要前往微信支付商户平台我的授权产品中进行确认授权。说明

          完成授权后即可调用微信支付相关接口能力。

          接口

          wx-server-sdk >= 2.0.2

          云开发提供了微信支付相关接口和服务端回调,包括统一下单、查询订单、关闭订单、申请退款、查询退款、下载对账单,具体文档见 API 文档。

          下单关键开发流程:

          1. 小程序调用云函数,在云函数中调用统一下单接口,参数中带上接收异步支付结果的云函数名和其所在云环境 ID
          2. 统一下单接口返回的成功结果对象中有 payment 字段,该字段即是小程序端发起支付的接口(wx.requestPayment)所需的所有信息
          3. 小程序端拿到云函数结果,调用 wx.requestPayemnt 发起支付
          4. 支付完成后,在统一下单接口中配置的云函数将收到支付结果通知

          注意:收到支付结果回调的云函数必须返回一个 { "errcode": 0 } 的对象,否则会认为回调处理失败,在接下来两天内会持续收到回调,直到返回成功为止。具体返回值协议见统一下单接口文档。


          告警

          目前小程序·云开发提供两种告警配置:

          • 基础告警:包括资源使用量提醒和计费相关信息,告警规则由系统配置,开发者可修改对应的告警渠道。
          • 自定义告警:由开发者自定义告警条件。

          告警群配置

          开发者可以通过登录 微信开发者工具,在 云开发控制台 的 设置 页面中的 告警设置 中使用该功能。目前加入告警群的方式包括:

          • 通过扫描二维码加入。
          • 在告警群中邀请相关人员加入。

          移除群成员的方式包括:

          • 告警群中的用户主动退出告警群。
          • 小程序的开发者在 云开发控制台 中的 设置 页面中的 告警设置 中移除相关人员。

          自定义告警

          开发者可通过登录 微信开发者工具,在 云开发控制台 的 设置 页面中的 自定义告警 中配置告警策略。每个环境最多可配置 50 条告警策略,每个告警策略中最多可添加 10 个告警条件。

          每条告警策略需录入信息包括:

          • 告警策略名称
          • 环境 ID
          • 资源类型:目前仅支持对云函数配置自定义告警
          • 告警对象:每条告警规则至少需要选择一个告警对象
          • 告警条件:告警指标:目前仅支持云函数错误次数和云函数运行时间统计周期:目前的统计周期仅支持 5 分钟统计一次比较方式:目前提供的比较方式包括 >、>=、<、<=、= 以及 !=持续周期:目前支持的持续周期包括持续 1 个周期、持续 2 个周期、持续 3 个周期、持续 4 个周期以及持续 5 个周期告警频率:目前支持的告警频率包括每小时告警一次和每 12 个小时告警一次
          • 告警渠道:目前自定义告警仅支持通过群告警下发消息

          自定义告警设置

          基础告警

          基础告警包括:

          • 资源使用提醒
          • 计费相关提醒

          基础告警为系统默认设置告警规则,开发者暂时无法修改相关告警规则,但可通过 告警渠道配置 设置接收告警的方式。详细的告警规则可参考 告警规则。

          告警渠道配置

          目前系统提供两种消息推送渠道,用于推送基础告警:

          • 通过 微信公众平台 公众号推送告警消息至小程序的相关人员
          • 推送告警消息至 小程序云监控告警群 中

          默认情况下,系统同时开启这两种告警渠道。

          开发者可以通过登录 微信开发者工具,在 云开发控制台 的 设置 页面中的 告警设置 中使用该功能。默认情况下,系统会同时开启 公告号告警 和 群告警 两种渠道。如需调整,可点击 设置 进行修改。

          告警设置

          告警规则

          现有的告警规则包括:

          情形描述告警规则公众号告警人群
          资源使用提醒存储容量80% 套餐量,90% 套餐量小程序所有开发者
          资源使用提醒存储下载调用次数80% 套餐量,90% 套餐量小程序所有开发者
          资源使用提醒存储上传调用次数80% 套餐量,90% 套餐量小程序所有开发者
          资源使用提醒CDN 回源流量80% 套餐量,90% 套餐量小程序所有开发者
          资源使用提醒CDN 流量80% 套餐量,90% 套餐量小程序所有开发者
          资源使用提醒云函数调用次数80% 套餐量,90% 套餐量小程序所有开发者
          资源使用提醒云函数资源使用量80% 套餐量,90% 套餐量小程序所有开发者
          资源使用提醒数据库容量80% 套餐量,90% 套餐量小程序所有开发者
          资源使用提醒数据库读取次数80% 套餐量,90% 套餐量小程序所有开发者
          资源使用提醒数据库写入次数80% 套餐量,90% 套餐量小程序所有开发者
          计费相关提醒新购发货成功通知新购发货成功后下单者和小程序管理员
          计费相关提醒资源到期通知资源到期前 7 天开始推送小程序所有开发者
          计费相关提醒续费成功通知续费成功后下单者和小程序管理员
          计费相关提醒资源停服通知资源停服后小程序所有开发者
          计费相关提醒资源释放通知资源释放后小程序所有开发者
          计费相关提醒套餐变更成功通知升配或降配成功后下单者和小程序管理员
          计费相关提醒资源超限停服通知资源超限停服后小程序所有开发者


          工单

          使用说明

          开发者可通过云开发控制台提供的 工单 功能提交相应的工单用于解决部分资源使用过程中的问题。目前 工单 仅支持处理以下问题:

          • 资源故障相关
          • 费用相关

          其他问题请前往 微信开放社区 提问。

          新建工单

          1. 开发者可登录 微信开发者工具 的 云开发控制台,在 工单 功能中点击新建工单。目前仅支持同一小程序下的开发者创建该小程序所属工单记录。

          创建工单

          1. 阅读提醒事项后,点击确定即可跳转至工单编辑页面。
          2. 编辑工单时,目前仅支持文字和图片的输入方式。为保证图片的正常显示,请通过点击 图片 添加按钮的方式添加图片资源。

          编辑工单

          1. 提交工单后,开发者还可根据需求,添加相应的工单评论或关闭工单。
          2. 工单被 客服 人员处理后,系统会通过微信公众平台公众号下发相应的消息提醒。

          查看工单

          1. 开发者可登录 微信开发者工具 的 云开发控制台,在 工单 功能中查看工单列表。

          关闭工单

          1. 点击相应问题标题,系统即可跳转至工单查看页面。在工单查看页面,开发者还可根据需求,添加相应的工单评论或关闭工单。
          2. 目前仅支持同一小程序下的开发者查看该小程序所属工单记录。非小程序开发者,无查看权限。

          关闭工单

          开发者可通过工单编辑页面的 关闭工单 按钮关闭已处理完毕的工单。对于 已完结 的工单,用户无法继续添加评论。

          同时,在用户长时间未回复工单情况下,系统会在 7 天后自动关闭工单。

          关闭工单


          静态网站托管

          开发者工具 1.03.2006042 起

          静态网站托管是云开发为开发者提供的 Web 资源托管服务,网站的静态资源(HTML、JavaScript、CSS、图片、音频、视频等)可以托管在该服务上,并享有以下能力:

          1. 默认域名:获得对应云环境的唯一专属默认域名,通过域名可访问静态资源,域名可以用于测试或线上使用
          2. 小程序 webview:小程序不用配置业务域名即可在 <web-view> 打开云开发静态网站托管的域名(仅支持能够使用 <web-view> 标签的小程序)
          3. CDN 加速
          4. 可以免鉴权直接打开小程序:非个人主体的认证的小程序,使用静态网站托管的网页,可以免鉴权跳转任意合法合规的小程序,查看详情

          开通方式

          开通静态托管要求使用后付费,因此如果环境不是后付费,请先切换至后付费、或新创建一个后付费的环境。

          静态托管的开通入口在 “设置 -> 拓展功能” 中。

          文件管理

          静态资源文件的管理操作同云开发的文件存储能力。

          索引文档

          索引文档即网站的首页,如果直接访问域名而不指定具体资源文件路径,则默认访问索引文档。

          注销

          静态托管开通后可以随时注销,入口同样在 “设置 -> 拓展功能” 中。

          Web SDK

          可使用云开发 Web SDK 访问云开发资源。注意现在 Web 中暂不支持登录访问模式,仅支持未登录访问模式。需要首先在云开发控制台中开启允许未登录访问后,Web 中才可以访问云开发资源。

          Web SDK 介绍。


          wx.cloud.init

          在调用云开发各 API 前,需先调用初始化方法 init 一次(全局只需一次)

          wx.cloud.init 方法的定义如下:

          function init(options): void

          wx.cloud.init 方法接受一个可选的 options 参数,方法没有返回值。

          options 参数定义了云开发的默认配置,该配置会作为之后调用其他所有云 API 的默认配置,options 提供的可选配置如下:

          字段数据类型必填默认值说明
          envstring | objectdefault默认环境配置,传入字符串形式的环境 ID 可以指定所有服务的默认环境,传入对象可以分别指定各个服务的默认环境,见下方详细定义
          traceUserbooleanfalse是否在将用户访问记录到用户管理中,在控制台中可见

          当 env 传入参数为对象时,可以指定各个服务的默认环境,可选字段如下:

          字段数据类型必填默认值说明
          databasestringdefault数据库 API 默认环境配置
          storagestringdefault存储 API 默认环境配置
          functionsstringdefault云函数 API 默认环境配置

          示例代码:

          wx.cloud.init({  env: 'test-x1dzi'})

          小程序·云开发提供了丰富的数据库操作 API,此处是数据库小程序端的 API 参考文档。

          数据库 API 都是懒执行的,这意味着只有真实需要网络请求的 API 调用才会发起网络请求,其余如获取数据库、集合、记录的引用、在集合上构造查询条件等都是不会触发网络请求的。触发网络请求的 API 有如下几个:

          API说明
          get获取集合 / 记录数据
          add在集合上新增记录
          update更新集合 / 记录数据
          set替换更新一个记录
          remove删除记录
          count统计查询语句对应的记录条数

          获取引用的 API 有如下几个:

          API说明
          database获取数据库引用,返回 Database 对象
          collection获取集合引用,返回 Collection 对象
          doc获取对一个记录的引用,返回 Document 对象

          在数据库 (Database) 对象上有如下字段:

          字段说明
          command获取数据库查询及更新指令,返回 Command
          serverDate构造服务端时间
          Geo获取地理位置操作对象,返回 Geo 对象

          在集合 (Collection) 对象上有如下 API:

          API说明
          doc获取对一个记录的引用,返回 Document 对象
          add在集合上新增记录
          where构建一个在当前集合上的查询条件,返回 Query,查询条件中可使用查询指令
          orderBy指定查询数据的排序方式
          limit指定返回数据的数量上限
          skip指定查询时从命中的记录列表中的第几项之后开始返回
          field指定返回结果中每条记录应包含的字段

          在记录 (Document) 对象上有如下 API:

          API说明
          get获取记录数据
          update局部更新数据
          set替换更新记录
          remove删除记录
          field指定返回结果中记录应包含的字段

          Command (db.command) 对象上有如下查询指令:

          API说明
          eq字段是否等于指定值
          neq字段是否不等于指定值
          lt字段是否小于指定值
          lte字段是否小于或等于指定值
          gt字段是否大于指定值
          gte字段是否大于或等于指定值
          in字段值是否在指定数组中
          nin字段值是否不在指定数组中
          and条件与,表示需同时满足另一个条件
          or条件或,表示如果满足另一个条件也匹配

          Command (db.command) 对象上有如下更新指令:

          API说明
          set设置字段为指定值
          remove删除字段
          inc原子自增字段值
          mul原子自乘字段值
          push如字段值为数组,往数组尾部增加指定值
          pop如字段值为数组,从数组尾部删除一个元素
          shift如字段值为数组,从数组头部删除一个元素
          unshift如字段值为数组,往数组头部增加指定值

          wx.cloud.database

          获取数据库的引用

          方法签名如下:

          function database(options?: object): Database

          方法接受一个可选对象参数 options,其字段定义如下:

          字段名类型必填默认值说明
          envstring-环境 ID

          示例代码

          以下调用获取默认环境的数据库的引用:

          const db = wx.cloud.database()

          假设有一个环境名为 test,用做测试环境,那么可以如下获取测试环境数据库:

          const testDB = wx.cloud.database({  env: 'test'})``

          db.collection

          获取集合的引用

          方法签名如下:

          function collection(name: string): Collection

          方法接受一个 name 参数,指定需引用的集合名称

          示例代码

          const db = wx.cloud.database()const todosCollection = db.collection('todos')

          Collection.doc

          获取记录的引用

          方法签名如下:

          function doc(id: string | number): Document

          方法接受一个 id 参数,指定需引用的记录 ID

          示例代码

          const myTodo = db.collection('todos').doc('my-todo-id')


          Collection.get / Query.get

          获取集合数据,或获取根据查询条件筛选后的集合数据。

          如果没有指定 limit,则默认最多取 20 条记录。

          如果没有指定 skip,则默认从第 0 条记录开始取,skip 常用于分页,例子可见本节的第二个示例代码。

          函数签名如下:

          function get(options?: object): Promise<Result>

          参数说明

          options 为可选参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

          字段名类型必填默认值说明
          successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
          failFunction失败回调
          completeFunction调用结束的回调函数(调用成功、失败都会执行)

          返回值说明

          如不传 options 参数,或传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve查询的结果,Result 定义见下方
          reject失败原因

          Result 说明

          success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          dataArray查询的结果数组,数据的每个元素是一个 Object,代表一条记录

          示例代码 1

          获取我的待办事项清单

          回调风格

          const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).get({  success: function(res) {    console.log(res.data)  }})

          Promise 风格

          const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).get().then(res => {  console.log(res.data)})

          示例代码 2:分页取数据

          获取我的第二页的待办事项清单,假设一页 10 条,现在要取第 2 页,则可以指定 skip 10 条记录

          // Promise 风格const db = wx.cloud.database()db.collection('todos')  .where({    _openid: 'xxx', // 填入当前用户 openid  })  .skip(10) // 跳过结果集中的前 10 条,从第 11 条开始返回  .limit(10) // 限制返回数量为 10 条  .get()  .then(res => {    console.log(res.data)  })  .catch(err => {    console.error(err)  })

          Document.get

          获取记录数据,或获取根据查询条件筛选后的记录数据

          函数签名如下:

          function get(options?: object): Promise<Result>

          参数说明

          options 为可选参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

          字段名类型必填默认值说明
          successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
          failFunction失败回调
          completeFunction调用结束的回调函数(调用成功、失败都会执行)

          返回值说明

          如不传 options 参数,或传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve查询的结果,Result 定义见下方
          reject失败原因

          Result 说明

          success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          dataObject记录的数据,是一个 Object

          示例代码

          获取我的指定待办事项详细信息

          回调风格

          const db = wx.cloud.database()db.collection('todos').doc('<some-todo-id>').get({  success: function(res) {    console.log(res.data)  }})

          Promise 风格

          const db = wx.cloud.database()db.collection('todos').doc('<some-todo-id>').get().then(res => {  console.log(res.data)})

          Collection.add

          在集合上新增记录

          函数签名如下:

          function add(options: object): Promise<Result>

          参数说明

          options 为必填参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

          字段名类型必填默认值说明
          dataObject新增记录的定义
          successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
          failFunction失败回调
          completeFunction调用结束的回调函数(调用成功、失败都会执行)

          返回值说明

          如传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise 的 resolve 和 reject的结果定义如下:

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          _idString | Number新增的记录的 ID

          示例代码

          新增一条待办事项:

          回调风格

          db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    // _id: 'todo-identifiant-aleatoire', // 可选自定义 _id,在此处场景下用数据库自动分配的就可以了    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    // 为待办事项添加一个地理位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    // res 是一个对象,其中有 _id 字段标记刚创建的记录的 id    console.log(res)  },  fail: console.error})

          Promise 风格

          db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    location: new db.Geo.Point(113, 23),    done: false  }}).then(res => {  console.log(res)}).catch(console.error)

          Collection.update / Query.update

          更新多条记录

          函数签名如下:

          function update(options: object): Promise<Result>

          参数说明

          options 为必填参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

          字段名类型必填默认值说明
          dataObject更新对象
          successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
          failFunction失败回调
          completeFunction调用结束的回调函数(调用成功、失败都会执行)

          返回值说明

          如传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise 的 resolve 和 reject的结果定义如下:

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 对象是一个如下结构的对象:

          字段类型说明
          updatednumber成功更新的记录数量
          注:API 调用成功不一定代表想要更新的记录已被更新,比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录,所以会得到更新 API 调用成功但其实没有记录被更新的情况,这种情况可以通过 stats.updated 看出来

          示例代码

          更新待办事项,将所有未完待办事项进度加 10:

          回调风格

          const _ = db.commanddb.collection('todos').where({  done: false  }).update({  data: {    progress: _.inc(10)  },  success: console.log,  fail: console.error})

          Promise 风格

          const _ = db.commanddb.collection('todos').where({  done: false  }).update({  data: {    progress: _.inc(10)  },}).then(console.log).catch(console.error)

          Document.update

          更新一条记录

          函数签名如下:

          function update(options: object): Promise<Result>

          参数说明

          options 为必填参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

          字段名类型必填默认值说明
          dataObject更新对象
          successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
          failFunction失败回调
          completeFunction调用结束的回调函数(调用成功、失败都会执行)

          返回值说明

          如传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise 的 resolve 和 reject的结果定义如下:

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 对象是一个如下结构的对象:

          字段类型说明
          updatednumber成功更新的记录数量,在此只可能为 0 或 1

          示例代码

          更新待办事项,将所有未完待办事项进度加 10:

          回调风格

          db.collection('todos').doc('todo-identifiant-aleatoire').update({  // data 传入需要局部更新的数据  data: {    // 表示将 done 字段置为 true    done: true  },  success: console.log,  fail: console.error})

          Promise 风格

          db.collection('todos').doc('todo-identifiant-aleatoire').update({  // data 传入需要局部更新的数据  data: {    // 表示将 done 字段置为 true    done: true  }}).then(console.log).catch(console.error)

          Document.set

          替换更新一条记录

          函数签名如下:

          function set(options: object): Promise<Result>

          参数说明

          options 为必填参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

          字段名类型必填默认值说明
          dataObject更新对象
          successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
          failFunction失败回调
          completeFunction调用结束的回调函数(调用成功、失败都会执行)

          返回值说明

          如传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise 的 resolve 和 reject的结果定义如下:

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          _idString | Number记录的 ID
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 对象是一个如下结构的对象:

          字段类型说明
          updatednumber成功更新的记录数量,若指定的 _id 已存在则为 1,否则为 0
          creatednumber成功更新的记录数量,若指定的 _id 已存在则为 0,否则为 1

          示例代码

          const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').set({  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    style: {      color: "skyblue"    },    // 位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    console.log(res.data)  }})

          Document.remove

          删除一条记录

          函数签名如下:

          function remove(options: object): Promise<Result>

          参数说明

          options 为必填参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

          字段名类型必填默认值说明
          successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
          failFunction失败回调
          completeFunction调用结束的回调函数(调用成功、失败都会执行)

          返回值说明

          如传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise 的 resolve 和 reject的结果定义如下:

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 对象是一个如下结构的对象:

          字段类型说明
          removednumber成功删除的记录数量,在此只可能为 0 或 1

          示例代码

          更新待办事项,将所有未完待办事项进度加 10:

          回调风格

          db.collection('todos').doc('todo-identifiant-aleatoire').remove({  success: console.log,  fail: console.error})

          Promise 风格

          db.collection('todos').doc('todo-identifiant-aleatoire').remove()  .then(console.log)  .catch(console.error)

          Collection.count / Query.count

          统计集合记录数或统计查询语句对应的结果记录数,注意这与集合权限设置有关,一个用户仅能统计其有读权限的记录数。

          函数签名如下:

          function count(options?: object): Promise<Result>

          参数说明

          options 为可选参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

          字段名类型必填默认值说明
          successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
          failFunction失败回调
          completeFunction调用结束的回调函数(调用成功、失败都会执行)

          返回值说明

          如不传 options 参数,或传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve查询的结果,Result 定义见下方
          reject失败原因

          Result 说明

          success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          totalnumber结果数量

          示例代码

          获取我的待办事项总数

          回调风格

          const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).count({  success: function(res) {    console.log(res.total)  }})

          Promise 风格

          const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).count().then(res => {  console.log(res.total)})

          Collection.where

          指定筛选条件

          方法签名如下:

          function where(rule: object): Query

          方法接受一个必填对象参数 rule,用于定义筛选条件

          示例代码

          找出未完成的进度 50 的待办事项:

          const db = wx.cloud.database()db.collection('todos').where({  done: false,  progress: 50}).get({  success: console.log,  fail: console.error})

          Collection.orderBy / Query.orderBy

          指定查询排序条件

          方法签名如下:

          function orderBy(fieldName: string, order: string): Collection | Query

          方法接受一个必填字符串参数 fieldName 用于定义需要排序的字段,一个字符串参数 order 定义排序顺序。order 只能取 asc 或 desc。

          如果需要对嵌套字段排序,需要用 "点表示法" 连接嵌套字段,比如 style.color 表示字段 style 里的嵌套字段 color。

          同时也支持按多个字段排序,多次调用 orderBy 即可,多字段排序时的顺序会按照 orderBy 调用顺序先后对多个字段排序

          示例代码:按一个字段排序

          按进度排升序取待办事项

          const db = wx.cloud.database()db.collection('todos').orderBy('progress', 'asc')  .get()  .then(console.log)  .catch(console.error)

          示例代码:按多个字段排序

          先按 progress 排降序(progress 越大越靠前)、再按 description 排升序(字母序越前越靠前)取待办事项:

          const db = wx.cloud.database()db.collection('todos')  .orderBy('progress', 'desc')  .orderBy('description', 'asc')  .get()  .then(console.log)  .catch(console.error)

          Collection.limit / Query.limit

          指定查询结果集数量上限

          支持端:小程序 , 云函数 , Web

          指定查询结果集数量上限

          参数

          value: number

          返回值

          Collection

          说明

          limit 在小程序端默认及最大上限为 20,在云函数端默认及最大上限为 1000

          示例代码

          db.collection('todos').limit(10)  .get()  .then(console.log)  .catch(console.error)


          Collection.skip / Query.skip

          指定查询返回结果时从指定序列后的结果开始返回,常用于分页

          方法签名如下:

          function skip(offset: number): Collection | Query

          示例代码

          const db = wx.cloud.database()db.collection('todos').skip(10)  .get()  .then(console.log)  .catch(console.error)

          db.command

          获取数据库查询及更新指令,列表见 API 列表中的 command 列表

          示例代码

          const _ = db.command

          db.RegExp

          从基础库 2.3.2 开始(wx-server-sdk 从 0.0.23 开始),数据库支持正则表达式查询,开发者可以在查询语句中使用 JavaScript 原生正则对象或使用 db.RegExp 方法来构造正则对象然后进行字符串匹配。在查询条件中对一个字段进行正则匹配即要求该字段的值可以被给定的正则表达式匹配,注意正则表达式不可用于 db.command 内(如 db.command.in)。

          使用正则表达式匹配可以满足字符串匹配需求,但不适用于长文本 / 大数据量的文本匹配 / 搜索,因为会有性能问题,对此类场景应使用文本搜索引擎如 ElasticSearch 等实现。

          db.RegExp 定义如下:

          function RegExp(initOptions: IInitOptions): DBRegExpinterface IInitOptions {  regexp: string // 正则表达式,字符串形式  options: string // flags,包括 i, m, s 但前端不做强限制}

          options 支持 i, m, s 这四个 flag,注意 JavaScript 原生正则对象构造时仅支持其中的 i, m 两个 flag,因此需要使用到 s 这个 flag 时必须使用 db.RegExp 构造器构造正则对象。flag 的含义见下表:

          flag说明
          i大小写不敏感
          m跨行匹配;让开始匹配符 ^ 或结束匹配符 $ 时除了匹配字符串的开头和结尾外,还匹配行的开头和结尾
          s让 . 可以匹配包括换行符在内的所有字符

          基础用法示例:

          // 原生 JavaScript 对象db.collection('todos').where({  description: /miniprogram/i})// 数据库正则对象db.collection('todos').where({  description: db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})// 用 new 构造也是可以的db.collection('todos').where({  description: new db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})

          db.serverDate

          构造一个服务端时间的引用。可用于查询条件、更新字段值或新增记录时的字段值。

          方法签名如下:

          function serverDate(options?: object): ServerDate

          方法接受一个可选对象参数 options,其字段定义如下:

          字段名类型必填默认值说明
          offsetnumber引用的服务端时间偏移量,毫秒为单位,可以是正数或负数

          示例代码

          新增记录时设置字段为服务端时间:

          const db = wx.cloud.database()db.collection('todos').add({  description: 'eat an apple',  createTime: db.serverDate()})

          更新字段为服务端时间往后一小时:

          const db = wx.cloud.database()db.collection('todos').doc('my-todo-id').update({  due: db.serverDate({    offset: 60 * 60 * 1000  })})``

          db.Geo

          该对象上含有地理位置构造器。

          拥有字段如下:

          字段说明
          Point地理位置点

          db.Geo.Point

          构造一个地理位置点。可用于查询条件、更新字段值或新增记录时的字段值。

          方法签名如下:

          function Point(longitude: number, latitude: number): Point

          方法接受两个必填参数,第一个是经度(longitude),第二个是纬度(latitude),务必注意顺序

          示例代码

          const db = wx.cloud.database()db.collection('todos').add({  description: 'eat an apple',  location: db.Geo.Point(113, 23)})

          db.command.eq

          查询筛选条件,表示字段等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

          方法签名:

          function eq(value: any): Command

          比如筛选出所有自己发表的文章,除了用传对象的方式:

          const myOpenID = 'xxx'db.collection('articles').where({  _openid: myOpenID})

          还可以用指令:

          const _ = db.commandconst myOpenID = 'xxx'db.collection('articles').where({  _openid: _.eq(openid)})

          注意 eq 指令比对象的方式有更大的灵活性,可以用于表示字段等于某个对象的情况,比如:

          // 这种写法表示匹配 stat.publishYear == 2018 且 stat.language == 'zh-CN'db.collection('articles').where({  stat: {    publishYear: 2018,    language: 'zh-CN'  }})// 这种写法表示 stat 对象等于 { publishYear: 2018, language: 'zh-CN' }const _ = db.commanddb.collection('articles').where({  stat: _.eq({    publishYear: 2018,    language: 'zh-CN'  })})

          db.command.neq

          表示字段不等于某个值,和 db.command.eq 相反


          db.command.lt

          查询筛选条件,表示字段需小于指定值。可以传入 Date 对象用于进行日期比较。

          方法签名:

          function lt(value: number | Date): Command

          示例代码

          找出进度小于 50 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.lt(50)}).get({  success: console.log,  fail: console.error})

          db.command.lte

          查询筛选条件,表示字段需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

          方法签名:

          function lte(value: number | Date): Command

          示例代码

          找出进度小于或等于 50 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.lte(50)}).get({  success: console.log,  fail: console.error})

          db.command.gt

          查询筛选条件,表示字段需大于指定值。可以传入 Date 对象用于进行日期比较。

          方法签名:

          function gt(value: number | Date): Command

          示例代码

          找出进度大于 50 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.gt(50)}).get({  success: console.log,  fail: console.error})

          db.command.gte

          查询筛选条件,表示字段需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

          方法签名:

          function gte(value: number | Date): Command

          示例代码

          找出进度大于或等于 50 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.gte(50)}).get({  success: console.log,  fail: console.error})

          db.command.in

          查询筛选条件,表示字段的值需在给定的数组内。

          方法签名:

          function in(values: any[]): Command

          示例代码

          找出进度为 0 或 100 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.in([0, 100])}).get({  success: console.log,  fail: console.error})

          db.command.in

          查询筛选条件,表示字段的值需不在给定的数组内。

          方法签名:

          function nin(values: any[]): Command

          示例代码

          找出进度不是 0 或 100 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.nin([0, 100])}).get({  success: console.log,  fail: console.error})


          db.command.and

          查询指令,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

          示例代码

          如筛选出进度大于 50 小于 100 的 todo:

          流式写法:

          const _ = db.commanddb.collection('todo').where({  progress: _.gt(50).and(_.lt(100))})

          前置写法:

          const _ = db.commanddb.collection('todo').where({  memory: _.and(_.gt(50), _.lt(100))})

          db.command.or

          查询指令,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

          字段值的 “或” 操作指的是指定一个字段值为多个值之一即可:

          字段值的或操作:示例代码

          如筛选出进度大于 80 或小于 20 的 todo:

          流式写法:

          const _ = db.commanddb.collection('todo').where({  progress: _.gt(80).or(_.lt(20))})

          前置写法:

          const _ = db.commanddb.collection('todo').where({  progress: _.or(_.gt(80), _.lt(20))})

          前置写法也可接收一个数组:

          const _ = db.commanddb.collection('todo').where({  progress: _.or([_.gt(80), _.lt(20)])})

          跨字段的 “或” 操作指条件 “或”,相当于可以传入多个 where 语句,满足其中一个即可,示例:

          跨字段的或操作:示例代码

          如筛选出进度大于 80 或已标为已完成的 todo:

          const _ = db.commanddb.collection('todo').where(_.or([  {    progress: _.gt(80)  },  {    done: true  }]))


          db.command.set

          更新指令。用于设定字段等于指定值。

          函数签名:

          function set(value: any): Command

          这种方法相比传入纯 JS 对象的好处是能够指定字段等于一个对象:

          // 以下方法只会更新 style.color 为 red,而不是将 style 更新为 { color: 'red' },即不影响 style 中的其他字段db.collection('todos').doc('doc-id').update({  data: {    style: {      color: 'red'    }  }})// 以下方法更新 style 为 { color: 'red', size: 'large' }db.collection('todos').doc('doc-id').update({  data: {    style: _.set({      color: 'red',      size: 'large'    })  }})

          db.command.remove

          更新指令。用于表示删除某个字段。

          函数签名:

          function remove(): Command

          示例代码

          删除 style 字段:

          const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    style: _.remove()  }})

          db.command.inc

          更新指令。用于指示字段自增某个值,这是个原子操作,使用这个操作指令而不是先读数据、再加、再写回的好处是:

          1. 原子性:多个用户同时写,对数据库来说都是将字段加一,不会有后来者覆写前者的情况
          2. 减少一次网络请求:不需先读再写

          mul 指令同理。

          函数签名:

          function inc(value: number): Command

          示例代码

          将一个 todo 的进度自增 10:

          const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    progress: _.inc(10)  }})

          db.command.mul

          更新指令。用于指示字段自乘某个值,这是个原子操作,使用这个操作指令而不是先读数据、再加、再写回的好处是:

          1. 原子性:多个用户同时写,对数据库来说都是将字段自乘,不会有后来者覆写前者的情况
          2. 减少一次网络请求:不需先读再写

          inc 指令同理。

          函数签名:

          function mul(value: number): Command

          示例代码

          将一个 todo 的进度乘 2:

          const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    progress: _.mul(2)  }})

          db.command.push

          更新指令,对一个值为数组的字段,往数组尾部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

          函数签名:

          function push(values: any[]): Command

          示例代码

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push(['mini-program', 'cloud'])  }})

          db.command.pop

          更新指令,对一个值为数组的字段,将数组尾部元素删除。

          函数签名:

          function pop(values: any[]): Command

          示例代码

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.pop()  }})

          db.command.shift

          更新指令,对一个值为数组的字段,将数组头部元素删除。

          函数签名:

          function shift(values: any[]): Command

          示例代码

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.shift()  }})

          db.command.unshift

          更新指令,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

          函数签名:

          function unshift(values: any[]): Command

          示例代码

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.unshift(['mini-program', 'cloud'])  }})

          get

          在集合和记录上都有 get 方法:

          update

          即可更新单条记录,也可更新多条记录


          remove

          小程序端只可删除单条记录,如果需删除多条记录,需使用云函数端 API

          云开发 Server API 文档

          云端运行环境为 Node.js,开发时请安装 Node.js 和 npm。

          使用云开发需在云函数目录中安装 wx-server-sdk 依赖:

          npm install --save wx-server-sdk

          在工具云函数根目录中创建云函数时,默认会创建一个定义了 wx-server-sdk 依赖的 package.json,并在创建成功时提示自动安装依赖。如果在你的环境中无法直接使用 npm install,比如需要走代理、使用自建的 npm 源站、使用其他包管理器如 yarn 等的情况,则不能使用工具的自动安装依赖,需手工执行相应依赖安装命令。

          需要特别注意的是,在 wx-server-sdk 中不再兼容 success、fail、complete 回调,总是只会返回 Promise。

          以下是 wx-server-sdk API 文档分类入口:

          • 初始化
          • 数据库
          • 存储
          • 云函数

          init

          在调用云开发各 API 前,需先调用初始化方法 init 一次(全局只需一次)

          init 方法的定义如下:

          function init(options): void

          init 方法接受一个可选的 options 参数,方法没有返回值。

          options 参数定义了云开发的默认配置,该配置会作为之后调用其他所有云 API 的默认配置,options 提供的可选配置如下:

          字段数据类型必填默认值说明
          envstring | objectdefault默认环境配置,传入字符串形式的环境 ID 可以指定所有服务的默认环境,传入对象可以分别指定各个服务的默认环境,见下方详细定义

          当 env 传入参数为对象时,可以指定各个服务的默认环境,可选字段如下:

          字段数据类型必填默认值说明
          databasestringdefault数据库 API 默认环境配置
          storagestringdefault存储 API 默认环境配置
          functionsstringdefault云函数 API 默认环境配置

          示例代码:

          const cloud = require('wx-server-sdk')cloud.init({  env: 'test-x1dzi'})

          需要特别注意的是,在 wx-server-sdk 中不再兼容 success、fail、complete 回调,总是只会返回 Promise。


          工具类 API

          云开发提供了一系列工具类的 API,此处是存储小程序端的 API 参考文档。

          API说明
          getWXContext获取微信上下文


          getWXContext

          在云函数中获取微信调用上下文,该方法无需传入参数,会返回以下字段:

          字段含义字段存在条件最低版本
          OPENID小程序用户 openid小程序端调用云函数时
          APPID小程序 AppID小程序端调用云函数时
          UNIONID小程序用户 unionid小程序端调用云函数,并且满足 unionid 获取条件
          ENV云函数所在环境的 ID0.6.0
          SOURCE调用来源(云函数本次运行是被什么触发)0.7.0

          SOURCE 值跟随调用链条传递,会表示调用链路情况(用英文逗号分隔),比如小程序调用云函数 A,再在云函数 A 内调用云函数 B,则 A 获得的 SOURCE 为 wx_client, B 内获得的 SOURCE 为 wx_client,scf(微信小程序调用,然后云函数调用)。

          SOURCE 的枚举类型:

          SOURCE 值含义
          wx_devtools微信 IDE 调用
          wx_client微信小程序调用
          wx_http微信 HTTP API 调用
          wx_unknown微信未知来源调用
          scf云函数调用云函数
          其他非微信端触发

          如果在云函数本地调试中,ENV 会为 local,SOURCE 会为 wx_client。

          注意事项

          请不要在 exports.main 外使用 getWXContext,此时尚没有调用上下文,无法获取得到信息。

          使用示例

          const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  const {    OPENID,    APPID,    UNIONID,    ENV,  } = cloud.getWXContext()  return {    OPENID,    APPID,    UNIONID,    ENV,  }}


          小程序·云开发提供了丰富的数据库操作 API,此处是数据库 Server 端的 API 参考文档,可用于云函数运行环境。

          Server 端的 API 与小程序端基本保持一致,有如下不同:

          1. Server API 不再接受回调(success, fail, complete),统一返回 Promise
          2. Server 端有批量写和批量删除的权限,即可在集合或查询语句上调用 update 或 remove
          3. Server 端独有 API 如创建集合(db.createCollection)

          数据库 API 都是懒执行的,这意味着只有真实需要网络请求的 API 调用才会发起网络请求,其余如获取数据库、集合、记录的引用、在集合上构造查询条件等都是不会触发网络请求的。触发网络请求的 API 有如下几个:

          API说明
          get获取集合 / 记录数据
          add在集合上新增记录
          update更新集合 / 记录数据
          set替换更新一个记录
          remove删除记录
          count统计查询语句对应的记录条数

          获取引用的 API 有如下几个:

          API说明
          database获取数据库引用,返回 Database 对象
          collection获取集合引用,返回 Collection 对象
          doc获取对一个记录的引用,返回 Document 对象

          在数据库 (Database) 对象上有如下字段:

          字段说明
          command获取数据库查询及更新指令,返回 Command
          serverDate构造服务端时间
          Geo获取地理位置操作对象,返回 Geo 对象
          createCollection创建一个集合

          在集合 (Collection) 对象上有如下 API:

          API说明
          doc获取对一个记录的引用,返回 Document 对象
          add在集合上新增记录
          update更新数据
          where构建一个在当前集合上的查询条件,返回 Query,查询条件中可使用查询指令
          remove删除匹配相应筛选条件的记录
          orderBy指定查询数据的排序方式
          limit指定返回数据的数量上限
          skip指定查询时从命中的记录列表中的第几项之后开始返回
          field指定返回结果中每条记录应包含的字段

          在记录 (Document) 对象上有如下 API:

          API说明
          get获取记录数据
          update局部更新数据
          set替换更新记录
          remove删除记录
          field指定返回结果中记录应包含的字段

          Command (db.command) 对象上有如下查询指令:

          API说明
          eq字段是否等于指定值
          neq字段是否不等于指定值
          lt字段是否小于指定值
          lte字段是否小于或等于指定值
          gt字段是否大于指定值
          gte字段是否大于或等于指定值
          in字段值是否在指定数组中
          nin字段值是否不在指定数组中
          and条件与,表示需同时满足另一个条件
          or条件或,表示如果满足另一个条件也匹配

          Command (db.command) 对象上有如下更新指令:

          API说明
          set设置字段为指定值
          remove删除字段
          inc原子自增字段值
          mul原子自乘字段值
          push如字段值为数组,往数组尾部增加指定值
          pop如字段值为数组,从数组尾部删除一个元素
          shift如字段值为数组,从数组头部删除一个元素
          unshift如字段值为数组,往数组头部增加指定值

          API reject 时返回的 Error 对象均含以下两个字段:

          字段类型说明
          errCodenumber错误码
          errMsgstring错误信息

          cloud.database

          获取数据库的引用

          方法签名如下:

          function database(options?: object): Database

          方法接受一个可选对象参数 options,其字段定义如下:

          字段名类型必填默认值说明
          envstring-环境 ID

          示例代码

          以下调用获取默认环境的数据库的引用:

          const db = wx.cloud.database()

          假设有一个环境名为 test,用做测试环境,那么可以如下获取测试环境数据库:

          const testDB = wx.cloud.database({  env: 'test'})

          也可以通过 init 传入默认环境的方式使得获取数据库时默认是默认环境数据库:

          cloud.init({  env: 'test'})const testDB = wx.cloud.database()

          db.collection

          获取集合的引用

          方法签名如下:

          function collection(name: string): Collection

          方法接受一个 name 参数,指定需引用的集合名称

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const todosCollection = db.collection('todos')

          Collection.doc

          获取记录的引用

          方法签名如下:

          function doc(id: string | number): Document

          方法接受一个 id 参数,指定需引用的记录 ID

          示例代码

          const myTodo = db.collection('todos').doc('my-todo-id')


          Collection.get / Query.get

          获取集合数据,或获取根据查询条件筛选后的集合数据。

          如果没有指定 limit,则默认最多取 20 条记录。

          如果没有指定 skip,则默认从第 0 条记录开始取,skip 常用于分页,例子可见第二个示例代码。

          如果需要取集合中所有的数据,可以参考第三个示例代码

          函数签名如下:

          function get(): Promise<Result>

          返回值说明

          Promise 的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve查询的结果,Result 定义见下方
          reject失败原因

          Result 说明

          Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          dataArray查询的结果数组,数据的每个元素是一个 Object,代表一条记录

          示例代码 1

          获取我的待办事项清单

          Promise 风格

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos').where({    _openid: 'xxx' // 填入当前用户 openid  }).get()}

          示例代码 2:分页取数据

          获取我的第二页的待办事项清单,假设一页 10 条,现在要取第 2 页,则可以指定 skip 10 条记录

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos')    .where({      _openid: 'xxx', // 填入当前用户 openid    })    .skip(10) // 跳过结果集中的前 10 条,从第 11 条开始返回    .limit(10) // 限制返回数量为 10 条    .get()}

          示例代码 3:取集合所有数据

          获取集合中的所有待办事项清单:因为有默认 limit 100 条的限制,因此很可能一个请求无法取出所有数据,需要分批次取:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const MAX_LIMIT = 100exports.main = async (event, context) => {  // 先取出集合记录总数  const countResult = await db.collection('todos').count()  const total = countResult.total  // 计算需分几次取  const batchTimes = Math.ceil(total / 100)  // 承载所有读操作的 promise 的数组  const tasks = []  for (let i = 0; i < batchTimes; i++) {    const promise = db.collection('todos').skip(i * MAX_LIMIT).limit(MAX_LIMIT).get()    tasks.push(promise)  }  // 等待所有  return (await Promise.all(tasks)).reduce((acc, cur) => {    return {      data: acc.data.concat(cur.data),      errMsg: acc.errMsg,    }  })}

          Document.get

          获取记录数据,或获取根据查询条件筛选后的记录数据

          函数签名如下:

          function get(): Promise<Result>

          返回值说明

          Promise 的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve查询的结果,Result 定义见下方
          reject失败原因

          Result 说明

          success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          dataObject记录的数据,是一个 Object

          示例代码

          获取我的指定待办事项详细信息

          Promise 风格

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('<some-todo-id>').get()  } catch(e) {    console.error(e)  }}


          Collection.add

          在集合上新增记录

          函数签名如下:

          function add(options: object): Promise<Result>

          参数说明

          字段名类型必填默认值说明
          dataObject新增记录的定义

          返回值说明

          Promise 的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          _idString | Number新增的记录的 ID

          示例代码

          新增一条待办事项:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').add({      // data 字段表示需新增的 JSON 数据      data: {        description: "learn cloud database",        due: new Date("2018-09-01"),        tags: [          "cloud",          "database"        ],        // 位置(113°E,23°N)        location: new db.Geo.Point(113, 23),        done: false      }    })  } catch(e) {    console.error(e)  }}


          Collection.update / Query.update

          更新多条记录

          函数签名如下:

          function update(options: object): Promise<Result>

          参数说明

          字段名类型必填默认值说明
          dataObject更新对象

          返回值说明

          Promise 的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 对象是一个如下结构的对象:

          字段类型说明
          updatednumber成功更新的记录数量
          注:API 调用成功不一定代表想要更新的记录已被更新,比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录,所以会得到更新 API 调用成功但其实没有记录被更新的情况,这种情况可以通过 stats.updated 看出来

          示例代码

          更新待办事项,将所有未完待办事项进度加 10:

          Promise 风格

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: false      })    .update({      data: {        progress: _.inc(10)      },    })  } catch(e) {    console.error(e)  }}


          Collection.remove / Query.remove

          删除多条记录

          函数签名如下:

          function remove(options: object): Promise<Result>

          返回值说明

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 对象是一个如下结构的对象:

          字段类型说明
          removednumber成功删除的记录数量

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: true    }).remove()  } catch(e) {    console.error(e)  }}


          Document.update

          更新一条记录

          函数签名如下:

          function update(options: object): Promise<Result>

          参数说明

          字段名类型必填默认值说明
          dataObject更新对象

          返回值说明

          Promise 的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 对象是一个如下结构的对象:

          字段类型说明
          updatednumber成功更新的记录数量,在此只可能为 0 或 1

          示例代码

          更新待办事项,将所有未完待办事项进度加 10:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').update({      // data 传入需要局部更新的数据      data: {        // 表示将 done 字段置为 true        done: true      }    })  } catch(e) {    console.error(e)  }}


          Document.set

          替换更新一条记录

          函数签名如下:

          function set(options: object): Promise<Result>

          参数说明

          字段名类型必填默认值说明
          dataObject更新对象

          返回值说明

          Promise 的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          _idString | Number记录的 ID
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 对象是一个如下结构的对象:

          字段类型说明
          updatednumber成功更新的记录数量,若指定的 _id 已存在则为 1,否则为 0
          creatednumber成功更新的记录数量,若指定的 _id 已存在则为 0,否则为 1

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').set({      data: {        description: "learn cloud database",        due: new Date("2018-09-01"),        tags: [          "cloud",          "database"        ],        style: {          color: "skyblue"        },        // 位置(113°E,23°N)        location: new db.Geo.Point(113, 23),        done: false      }    })  } catch(e) {    console.error(e)  }}


          Document.remove

          删除一条记录

          函数签名如下:

          function remove(): Promise<Result>

          返回值说明

          结果说明
          resolve新增记录的结果,Result 定义见下方
          reject失败原因

          Result 说明

          Promise resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 对象是一个如下结构的对象:

          字段类型说明
          removednumber成功删除的记录数量,在此只可能为 0 或 1

          示例代码

          更新待办事项,将所有未完待办事项进度加 10:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').remove()  } catch(e) {    console.error(e)  }}


          Collection.count / Query.count

          统计集合记录数或统计查询语句对应的结果记录数,云函数端因属于管理端,因此可以统计所有集合的记录数(小程序端统计会受限于权限,可见小程序端的 count

          函数签名如下:

          function count(): Promise<Result>

          返回值说明

          Promise 的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve查询的结果,Result 定义见下方
          reject失败原因

          Result 说明

          resolve 的结果 Result 是一个如下结构的对象:

          字段类型说明
          totalnumber结果数量

          示例代码

          获取我的待办事项总数

          Promise 风格

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos').where({    _openid: 'xxx' // 填入当前用户 openid  }).count()}


          Collection.where

          指定筛选条件

          方法签名如下:

          function where(rule: object): Query

          方法接受一个必填对象参数 rule,用于定义筛选条件

          示例代码

          找出未完成的进度 50 的待办事项:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: false,      progress: 50    })    .get()  } catch(e) {    console.error(e)  }}


          Collection.orderBy / Query.orderBy

          指定查询排序条件

          方法签名如下:

          function orderBy(fieldName: string, order: string): Collection | Query

          方法接受一个必填字符串参数 fieldName 用于定义需要排序的字段,一个字符串参数 order 定义排序顺序。order 只能取 asc 或 desc。

          同时也支持按多个字段排序,多次调用 orderBy 即可,多字段排序时的顺序会按照 orderBy 调用顺序先后对多个字段排序

          示例代码:按一个字段排序

          按进度排升序取待办事项

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos').orderBy('progress', 'asc').get()}

          示例代码:按多个字段排序

          先按 progress 排降序(progress 越大越靠前)、再按 description 排升序(字母序越前越靠前)取待办事项:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos')    .orderBy('progress', 'desc')    .orderBy('description', 'asc')    .get()}


          Collection.limit / Query.limit

          指定查询结果集数量上限

          方法签名如下:

          function limit(max: number): Collection | Query

          方法接受一个必填参数 max 用于定义最大结果集返回数量,上限 100

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').limit(10).get()  } catch(e) {    console.error(e)  }}

          Collection.skip / Query.skip

          指定查询返回结果时从指定序列后的结果开始返回,常用语分页

          方法签名如下:

          function skip(offset: number): Collection | Query

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').skip(10).get()  } catch(e) {    console.error(e)  }}


          Collection.field / Query.field / Document.field

          指定返回结果中记录需返回的字段

          方法签名如下:

          function field(definition: object): Collection | Query | Document

          方法接受一个必填字段用于指定需返回的字段

          示例代码

          返回 description, done 和 progress 三个字段:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').field({      description: true,      done: true,      progress: true    }).get()  } catch(e) {    console.error(e)  }}

          db.command

          获取数据库查询及更新指令,列表见 API 列表中的 command 列表

          示例代码

          const _ = db.command

          db.RegExp

          从基础库 2.3.2 开始(wx-server-sdk 从 0.0.23 开始),数据库支持正则表达式查询,开发者可以在查询语句中使用 JavaScript 原生正则对象或使用 db.RegExp 方法来构造正则对象然后进行字符串匹配。在查询条件中对一个字段进行正则匹配即要求该字段的值可以被给定的正则表达式匹配,注意正则表达式不可用于 db.command 内(如 db.command.in)。

          使用正则表达式匹配可以满足字符串匹配需求,但不适用于长文本 / 大数据量的文本匹配 / 搜索,因为会有性能问题,对此类场景应使用文本搜索引擎如 ElasticSearch 等实现。

          db.RegExp 定义如下:

          function RegExp(initOptions: IInitOptions): DBRegExpinterface IInitOptions {  regexp: string // 正则表达式,字符串形式  options: string // flags,包括 i, m, s 但前端不做强限制}

          options 支持 i, m, s 这四个 flag,注意 JavaScript 原生正则对象构造时仅支持其中的 i, m 两个 flag,因此需要使用到 s 这个 flag 时必须使用 db.RegExp 构造器构造正则对象。flag 的含义见下表:

          flag说明
          i大小写不敏感
          m跨行匹配;让开始匹配符 ^ 或结束匹配符 $ 时除了匹配字符串的开头和结尾外,还匹配行的开头和结尾
          s让 . 可以匹配包括换行符在内的所有字符

          基础用法示例:

          // 原生 JavaScript 对象db.collection('todos').where({  description: /miniprogram/i})// 数据库正则对象db.collection('todos').where({  description: db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})// 用 new 构造也是可以的db.collection('todos').where({  description: new db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})


          db.serverDate

          构造一个服务端时间的引用。可用于查询条件、更新字段值或新增记录时的字段值。

          方法签名如下:

          function serverDate(options?: object): ServerDate

          方法接受一个可选对象参数 options,其字段定义如下:

          字段名类型必填默认值说明
          offsetnumber引用的服务端时间偏移量,毫秒为单位,可以是正数或负数

          示例代码

          新增记录时设置字段为服务端时间:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').add({      description: 'eat an apple',      createTime: db.serverDate()    })  } catch(e) {    console.error(e)  }}

          更新字段为服务端时间往后一小时:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('my-todo-id').update({      due: db.serverDate({        offset: 60 * 60 * 1000      })    })  } catch(e) {    console.error(e)  }}``


          db.Geo

          该对象上含有地理位置构造器。

          拥有字段如下:

          字段说明
          Point地理位置点

          db.Geo.Point

          构造一个地理位置点。可用于查询条件、更新字段值或新增记录时的字段值。

          方法签名如下:

          function Point(longitude: number, latitude: number): Point

          方法接受两个必填参数,第一个是经度(longitude),第二个是纬度(latitude),务必注意顺序

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').add({      description: 'eat an apple',      location: new db.Geo.Point(113, 23)    })  } catch(e) {    console.error(e)  }}

          db.command.eq

          查询筛选条件,表示字段等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array。

          方法签名:

          function eq(value: any): Command

          比如筛选出所有自己发表的文章,除了用传对象的方式:

          const myOpenID = 'xxx'db.collection('articles').where({  _openid: myOpenID})

          还可以用指令:

          const _ = db.commandconst myOpenID = 'xxx'db.collection('articles').where({  _openid: _.eq(openid)})

          注意 eq 指令比对象的方式有更大的灵活性,可以用于表示字段等于某个对象的情况,比如:

          // 这种写法表示匹配 stat.publishYear == 2018 且 stat.language == 'zh-CN'db.collection('articles').where({  stat: {    publishYear: 2018,    language: 'zh-CN'  }})// 这种写法表示 stat 对象等于 { publishYear: 2018, language: 'zh-CN' }const _ = db.commanddb.collection('articles').where({  stat: _.eq({    publishYear: 2018,    language: 'zh-CN'  })})

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('articles').where({      stat: _.eq({        publishYear: 2018,        language: 'zh-CN'      })    })    .get()  } catch(e) {    console.error(e)  }}

          db.command.neq

          表示字段不等于某个值,和 db.command.eq 相反


          db.command.lt

          查询筛选条件,表示字段需小于指定值。

          方法签名:

          function lt(value: number): Command

          示例代码

          找出进度小于 50 的 todo

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.lt(50)    })    .get()  } catch(e) {    console.error(e)  }}

          db.command.lte

          查询筛选条件,表示字段需小于或等于指定值。

          方法签名:

          function lte(value: number): Command

          示例代码

          找出进度小于或等于 50 的 todo

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.lte(50)    })    .get()  } catch(e) {    console.error(e)  }}

          db.command.gt

          查询筛选条件,表示字段需大于指定值。

          方法签名:

          function gt(value: number): Command

          示例代码

          找出进度大于 50 的 todo

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.gt(50)    })    .get()  } catch(e) {    console.error(e)  }}

          db.command.gte

          查询筛选条件,表示字段需大于或等于指定值。

          方法签名:

          function gte(value: number): Command

          示例代码

          找出进度大于或等于 50 的 todo

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.gte(50)    })    .get()  } catch(e) {    console.error(e)  }}

          db.command.in

          查询筛选条件,表示字段的值需在给定的数组内。

          方法签名:

          function in(values: any[]): Command

          示例代码

          找出进度为 0 或 100 的 todo

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.in([0, 100])    })    .get()  } catch(e) {    console.error(e)  }}

          db.command.in

          查询筛选条件,表示字段的值需不在给定的数组内。

          方法签名:

          function nin(values: any[]): Command

          示例代码

          找出进度不是 0 或 100 的 todo

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.nin([0, 100])    })    .get()  } catch(e) {    console.error(e)  }}

          db.command.nin

          支持端:小程序 , 云函数 , Web

          查询筛选操作符,表示要求值不在给定的数组内。

          参数

          value: any[]

          返回值

          Command

          示例代码

          找出进度不是 0 或 100 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.nin([0, 100])}).get({  success: console.log,  fail: console.error})


          db.command.and

          查询指令,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

          示例代码

          如筛选出进度大于 50 小于 100 的 todo:

          流式写法:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todo').where({      progress: _.gt(50).and(_.lt(100))    }).get()  } catch(e) {    console.error(e)  }}

          前置写法:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todo').where({      memory: _.and(_.gt(50), _.lt(100))    }).get()  } catch(e) {    console.error(e)  }}

          db.command.or

          查询指令,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

          字段值的 “或” 操作指的是指定一个字段值为多个值之一即可:

          字段值的或操作:示例代码

          如筛选出进度大于 80 或小于 20 的 todo:

          流式写法:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todo').where({      progress: _.gt(80).or(_.lt(20))    }).get()  } catch(e) {    console.error(e)  }}

          前置写法:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todo').where({      memory: _.or(_.gt(80), _.lt(20))    }).get()  } catch(e) {    console.error(e)  }}

          跨字段的 “或” 操作指条件 “或”,相当于可以传入多个 where 语句,满足其中一个即可,示例:

          跨字段的或操作:示例代码

          如筛选出进度大于 80 或已标为已完成的 todo:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todo').where(_.or([      {        progress: _.gt(80)      },      {        done: true      }    ]))  } catch(e) {    console.error(e)  }}

          db.command.not

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          查询操作符,用于表示逻辑 "非" 的关系,表示需不满足指定的条件。

          参数

          command: Command

          返回值

          Command

          示例

          如筛选出进度不等于100的 todo:

          const _ = db.commanddb.collection('todo').where({  progress: _.not(_.eq(100))})

          not 也可搭配其他逻辑指令使用,包括 and, or, nor, not,如 or:

          const _ = db.commanddb.collection('todo').where({  progress: _.not(_.or([_.lt(50), _.eq(100)]))})

          db.command.nor

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          查询操作符,用于表示逻辑 "都不" 的关系,表示需不满足指定的所有条件。如果记录中没有对应的字段,则默认满足条件。

          参数

          expressions: any[]

          返回值

          Command

          示例 1

          筛选出进度既不小于20又不大于80的 todo :

          const _ = db.commanddb.collection('todo').where({  progress: _.nor([_.lt(20), _.gt(80)])})

          以上同时会筛选出不存在 progress 字段的记录,如果要要求 progress 字段存在,可以用 exists 指令:

          const _ = db.commanddb.collection('todo').where({  progress: _.exists().nor([_.lt(20), _.gt(80)])  // 等价于以下非链式调用的写法:  // progress: _.exists().and(_.nor([_.lt(20), _.gt(80)]))}).get()

          示例 2

          筛选出 progress 不小于 20 且 tags 数组不包含 miniprogram 字符串的记录:

          const _ = db.commanddb.collection('todo').where(_.nor([{  progress: _.lt(20),}, {  tags: 'miniprogram',}])).get()

          以上会筛选出满足以下条件之一的记录:

          1. progress 不小于 20 且 tags 数组不包含 miniprogram 字符串
          2. progress 不小于 20 且 tags 字段不存在
          3. progress 字段不存在 且 tags 数组不包含 miniprogram 字符串
          4. progress 不小于 20 且 tags 字段不存在

          如果要求 progress 和 tags 字段存在,可以用 exists 指令:

          const _ = db.commanddb.collection('todo').where(  _.nor([{    progress: _.lt(20),  }, {    tags: 'miniprogram',  }])  .and({    progress: _.exists(true),    tags: _.exists(true),  }))

          调用风格

          方法接收两种传参方式,一是传入一个数组参数,二是传入多个参数,效果一样。

          // 传入数组function nor(expressions: Expression[]): Command// 传入多参数function nor(...expressions: Expression[]): Command


          db.command.set

          更新指令。用于设定字段等于指定值。

          函数签名:

          function set(value: any): Command

          这种方法相比传入纯 JS 对象的好处是能够指定字段等于一个对象:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    // 以下方法只会更新 style.color 为 red,而不是将 style 更新为 { color: 'red' },即不影响 style 中的其他字段    const res1 = await db.collection('todos').doc('doc-id').update({      data: {        style: {          color: 'red'        }      }    })    // 以下方法更新 style 为 { color: 'red', size: 'large' }    const res2 = await db.collection('todos').doc('doc-id').update({      data: {        style: _.set({          color: 'red',          size: 'large'        })      }    })    return {      res1,      res2,    }  } catch(e) {    console.error(e)  }}

          db.command.remove

          更新指令。用于表示删除某个字段。

          函数签名:

          function remove(): Command

          示例代码

          删除 style 字段:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-id').update({      data: {        style: _.remove()      }    })  } catch(e) {    console.error(e)  }}

          db.command.inc

          更新指令。用于指示字段自增某个值,这是个原子操作,使用这个操作指令而不是先读数据、再加、再写回的好处是:

          1. 原子性:多个用户同时写,对数据库来说都是将字段加一,不会有后来者覆写前者的情况
          2. 减少一次网络请求:不需先读再写

          mul 指令同理。

          函数签名:

          function inc(value: number): Command

          示例代码

          将一个 todo 的进度自增 10:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-id').update({      data: {        progress: _.inc(10)      }    })  } catch(e) {    console.error(e)  }}

          db.command.mul

          更新指令。用于指示字段自乘某个值,这是个原子操作,使用这个操作指令而不是先读数据、再加、再写回的好处是:

          1. 原子性:多个用户同时写,对数据库来说都是将字段自乘,不会有后来者覆写前者的情况
          2. 减少一次网络请求:不需先读再写

          inc 指令同理。

          函数签名:

          function mul(value: number): Command

          示例代码

          将一个 todo 的进度乘 2:

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-id').update({      data: {        progress: _.mul(2)      }    })  } catch(e) {    console.error(e)  }}

          db.command.push

          更新指令,对一个值为数组的字段,往数组尾部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

          函数签名:

          function push(values: any[]): Command

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('doc-id').update({      data: {        tags: _.push(['mini-program', 'cloud'])      }    })  } catch(e) {    console.error(e)  }}

          db.command.pop

          更新指令,对一个值为数组的字段,将数组尾部元素删除。

          函数签名:

          function pop(values: any[]): Command

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('doc-id').update({      data: {        tags: _.pop()      }    })  } catch(e) {    console.error(e)  }}

          db.command.shift

          更新指令,对一个值为数组的字段,将数组头部元素删除。

          函数签名:

          function shift(values: any[]): Command

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('doc-id').update({      data: {        tags: _.shift()      }    })  } catch(e) {    console.error(e)  }}

          db.command.unshift

          更新指令,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

          函数签名:

          function unshift(values: any[]): Command

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('doc-id').update({      data: {        tags: _.unshift(['mini-program', 'cloud'])      }    })  } catch(e) {    console.error(e)  }}

          Database.createCollection

          创建集合,如果集合已经存在会创建失败

          函数签名如下:

          function createCollection(): Promise<Result>

          返回值说明

          Promise 的 resolve 和 reject 的结果定义如下:

          结果说明
          resolve查询的结果,Result 定义见下方
          reject失败原因

          Result 说明

          Promise resolve 的结果 Result 是一个仅含 errMsg 的对象

          示例代码

          const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.createCollection('todos')}


          update

          即可更新单条记录,也可更新多条记录

          remove

          即可删除单条记录,也可更新多条记录

          存储 API

          云开发提供了一系列存储操作 API,此处是存储小程序端的 API 参考文档。

          API说明
          uploadFile上传文件
          downloadFile下载文件
          deleteFile删除文件
          getTempFileURL换取临时链接

          uploadFile

          将本地资源上传至云存储空间,如果上传至同一路径则是覆盖。

          请求参数

          字段说明数据类型默认值必填
          cloudPath云存储路径String-Y
          fileContent要上传文件的内容fs.ReadStream-Y

          Promise返回结果说明

          字段说明数据类型
          fileID文件 IDString
          statusCode服务器返回的 HTTP 状态码Number

          错误返回参数

          字段说明数据类型
          errCode错误码Number
          errMsg错误信息,格式 apiName:fail msgString

          使用示例

          Promise 风格

          const cloud = require('wx-server-sdk')const fs = require('fs')const path = require('path')exports.main = async (event, context) => {  const fileStream = fs.createReadStream(path.join(__dirname, 'demo.jpg'))  return await cloud.uploadFile({    cloudPath: 'demo.jpg',    fileContent: fileStream,  })}


          downloadFile

          从云存储空间下载文件

          请求参数

          字段说明数据类型默认值必填
          fileID云文件 IDString-Y

          Promise 返回参数

          字段说明数据类型
          fileContent文件内容Buffer
          statusCode服务器返回的 HTTP 状态码Number

          错误返回参数

          字段说明数据类型
          errCode错误码Number
          errMsg错误信息,格式 apiName:fail msgString

          使用示例

          Promise 风格

          const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  const fileID = 'xxxx'  const res = await cloud.downloadFile({    fileID: fileID,  })  const buffer = res.fileContent  return buffer.toString('utf8')}

          getTempFileURL

          用云文件 ID 换取真实链接,可自定义有效期,默认一天且最大不超过一天

          请求参数

          字段说明数据类型默认值必填
          fileList要换取临时链接的云文件 ID 列表String[]-Y

          fileList 数组中的每一个元素是一个云文件 fileID

          Promise 返回参数

          字段说明数据类型
          fileList文件列表Object

          fileList 数组中的每一个元素是有如下字段的 Object

          字段说明数据类型
          fileID云文件 IDString
          tempFileURL临时文件路径String
          status状态码,0 为成功Number
          errMsg成功为 ok,失败为失败原因String

          错误返回参数

          字段说明数据类型
          errCode错误码Number
          errMsg错误信息,格式 apiName:fail msgString

          使用示例

          Promise 风格

          const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  const fileList = ['cloud://xxx', 'cloud://yyy']  const result = await cloud.getTempFileURL({    fileList: fileList,  })  return result.fileList}


          deleteFile

          从云存储空间删除文件

          请求参数

          字段说明数据类型默认值必填
          fileList云文件 ID 字符串数组String[]-Y

          Promise 返回参数

          字段说明数据类型
          fileList删除结果列表,列表中的每一个对象的定义见下表Object[]

          fileList 列表中的对象说明

          字段说明数据类型
          fileID云文件 IDString
          status状态码,0 为成功Number
          errMsg成功为 ok,失败为失败原因String

          错误返回参数

          字段说明数据类型
          errCode错误码Number
          errMsg错误信息,格式 apiName:fail msgString

          使用示例

          const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  const fileIDs = ['xxx', 'xxx']  const result = await cloud.deleteFile({    fileList: fileIDs,  })  return result.fileList}


          支付方式

          小程序·云开发在开通时,开发者会授权将小程序的注册信息用于进行云服务的初始化。此时,小程序帐号会对应生成或绑定一个腾讯云帐号。

          • 生成:如果该小程序帐号在开通云开发前,并未授权为某个腾讯云帐号的微信公众平台登录方式,则系统会新建一个腾讯云帐号。
          • 绑定:如果该小程序帐号在开通云开发前,已授权为某个腾讯云帐号的微信公众平台登录方式,则系统会自动关联该腾讯云帐号。

          支付方式

          目前小程序·云开发支持三种支付方式:

          • 预付费:个人账户扣款:适用于个人账户结算的小程序,目前仅支付微信支付
          • 预付费:腾讯云账户扣款:适用于通过腾讯云账户统一结算的小程序
          • 按量付费:腾讯云账户扣款:适用于暂时无法准确预估使用量的小程序,目前仅支持从腾讯云账户扣款

          其中,系统默认使用的支付方式为预付费:个人账户扣款。如需使用其他支付方式,需下载最新 nightly 版本 的开发者工具进行选择或切换。

          初次购买预付费套餐

          对于初次购买预付费配额的小程序,可在选定配额后,选择订单的支付方式。

          一旦该订单支付成功,后续该环境下的订单将自动使用所选支付方式进行扣款。如需调整可前往 环境设置-支付方式 切换支付方式。

          初次购买

          开通按量付费

          环境创建后,开发者可按需在配额设置中直接开通按量付费。小程序一旦开通按量付费后,将无法再切换到预付费支付方式,请开发者谨慎操作。

          具体按量付费计费策略请参考文档《小程序·云开发按量付费》。

          开通按量付费

          切换支付方式

          对于已经购买过付费配额的小程序,如需调整支付方式,可在云开发控制台 环境设置-支付方式 进行切换。目前,在切换支付方式时,开发者可选择的支付方式包括:

          • 预付费:个人账户扣款
          • 预付费:腾讯云账户扣款
          • 按量付费:腾讯云账户扣款

          当出现以下几种情况时,小程序则无法进行支付方式的切换:

          • 当前支付方式为按量付费的环境暂不支持切换支付方式;
          • 由于可开发发票余额小于退费金额,则无法进行付费方式切换。此时,开发者可选择在可开发票金额大于退费金额后或退回发票后再切换支付方式。详情请参考《小程序·云开发发票管理》;
          • 该小程序从未购买过任何预付费配额时,将无法切换支付方式。开发者可在初次购买预付费配额时,直接选择支付方式或直接开通按量付费;
          • 超过切换次数限制:单个小程序帐号累计支付方式切换次数不得超过 4 次;单个小程序帐号每月有且仅能切换一次支付方式;
          • 切换至按量计费后无法再切换支付方式,请谨慎操作;
          • 环境由于到期未续费,已经处于隔离期时,需先进行续费,才可再切换支付方式。

          如遇特殊情况,可通过工单联系我们,具体工单提交方式请参考文档《小程序·云开发工单》。

          切换支付方式

          腾讯云费用中心

          对于使用预付费:腾讯云账户扣款或按量付费:腾讯云账户扣款支付方式的小程序,可通过云开发控制台 环境设置——支付方式 中的腾讯云账户费用中心入口登录腾讯云费用中心,进行充值、订单管理、续费管理、发票与合同管理等操作。

          同时开发者也可以登录腾讯云官网,使用微信公众号作为登录方式,选择对应的小程序帐号授权登录腾讯云控制台。并前往费用中心,进行充值、订单管理、续费管理、发票与合同管理等操作。

          请注意:

          • 对于使用预付费:个人账户扣款或按量付费:腾讯云账户扣款支付的订单需在云开发控制台 费用中心-发票管理 中开具对应订单金额的发票。
          • 对于使用预付费:腾讯云账户扣款或按量付费:腾讯云账户扣款支付的订单需在腾讯云费用中心 发票与合同管理 中开具对应订单金额的发票。


          预付费

          目前小程序·云开发提供的预付费模式包括:

          • 预付费:个人账户扣款:适用于个人账户结算的小程序,目前仅支付微信支付
          • 预付费:腾讯云账户扣款:适用于通过腾讯云账户统一结算的小程序

          系统默认使用的支付方式为预付费:个人账户扣款。以上预付费方式的计费单位为 元/月,在满足配额调整规则的条件下开发者可随时调整配置。

          同时,为方便开发者以最低的资源成本进行功能开发,小程序·云开发还提供了免费版套餐供开发者试用。

          分类参数免费额度
          存储容量5GB
          下载操作次数150 万次/月
          上传操作次数60 万次/月
          CDN回源流量5GB/月
          CDNCDN流量5GB/月
          云函数资源使用量 GBs4 万 GBs/月
          外网出流量1GB/月
          数据库容量2GB
          同时连接数20
          读操作次数5万次/天
          写操作次数3万次/天
          集合限制100个

          配额说明

          资源配额

          以下为云开发各类资源配额指标,由腾讯云 TCB 提供存储和计算服务。 用户可通过下载最新的微信开发者工具使用该功能。 资源配额可分为三类:资源均衡型、CDN 资源消耗型、云函数资源消耗型、数据库资源消耗型。

          资源均衡型

          分类参数基础版 1基础版 2专业版 1专业版 2专业版 3旗舰版 1旗舰版 2旗舰版 3企业版 1
          存储容量5GB10GB50GB100GB300GB500GB700GB1000GB1300GB
          下载操作次数150万/月200万/月750万/月1500万/月2500万/月3750万/月4500万/月5000万/月6000万/月
          上传操作次数60万/月100万/月300万/月600万/月1000万/月1500万/月2000万/月2500万/月3000万/月
          CDN回源流量15GB/月10GB/月50GB/月150GB/月300GB/月500GB/月600GB/月800GB/月1000GB/月
          CDNCDN流量5GB/月25GB/月50GB/月150GB/月300GB/月500GB/月1000GB/月2000GB/月4000GB/月
          云函数资源使用量GBs34万/月20万/月40万/月150万/月300万/月400万/月1500万/月3000万/月4000万/月
          外网出流量1GB/月3GB/月5GB/月10GB/月20GB/月25GB/月100GB/月200GB/月400GB/月
          数据库容量2GB3GB5GB10GB20GB10GB50GB100GB200GB
          同时连接数42050100200300400500500500
          读操作数5万/天25万/天50万/天150万/天300万/天500万/天1000万/天2000万/天5000万/天
          写操作数3万/天15万/天30万/天100万/天200万/天300万/天500万/天1000万/天3000万/天
          集合限制100个150个200个300个400个400个500个600个800个
          总价免费30 元/月104 元/月390 元/月690 元/月860 元/月2,499 元/月4,699 元/月8,999 元/月

          CDN 资源消耗型

          分类参数CDN 版 1CDN 版 2CDN 版 3
          存储容量50GB100GB500GB
          下载操作次750万/月1500万/月3750万/月
          上传操作次数300万/月600万/月1500万/月
          CDN回源流量50GB/月150GB/月500GB/月
          CDNCDN流量500GB/月3072GB/月10240GB/月
          云函数资源使用量GBs20万/月50万/月150万/月
          外网出流量3GB/月5GB/月10GB/月
          数据库容量3GB5GB10GB
          同时连接数50100200
          读操作数25万/天50万/天150万/天
          写操作数15万/天30万/天100万/天
          集合限制150个200个300个
          总价149 元/月690 元/月2,199 元/月

          云函数资源消耗型

          分类参数云函数版 1云函数版 2云函数版 3
          存储容量5GB10GB50GB
          下载操作次数150万/月200万/月750 万/月
          上传操作次数60万/月100 万/月300万/月
          CDN回源流量5GB/月10GB/月50GB/月
          CDNCDN流量5GB/月25GB/月150GB/月
          云函数资源使用量GBs40万/月400万/月1500万/月
          外网出流量5GB/月25GB/月100GB/月
          数据库容量3GB10GB20GB
          同时连接数50200300
          读操作数25万/天150万/天300万/天
          写操作数15万/天100万/天200万/天
          集合限制150个300个400个
          总价79 元/月390 元/月1,299 元/月

          数据库资源消耗型

          分类参数数据库版 1数据库版 2数据库版 3
          存储容量5GB10GB50GB
          下载操作次数150万/月200万/月750 万/月
          上传操作次数60万/月100 万/月300万/月
          CDN回源流量5GB/月10GB/月50GB/月
          CDNCDN流量5GB/月25GB/月50GB/月
          云函数资源使用量GBs20万/月150万/月400万/月
          外网出流量3GB/月10GB/月25GB/月
          数据库容量5GB50GB200GB
          同时连接数100400500
          读操作数50万/天500万/天5000万/天
          写操作数30万/天300万/天3000万/天
          集合限制200个400个800个
          总价69 元/月590 元/月1,799 元/月

          除以上配额参数外,小程序·云开发资源还包括以下系统参数限制(所有版本配额都遵守相同的系统参数限制):

          • 云函数(单次运行)运行内存:256M5
          • 云函数数量:50个
          • 云函数并发数:10006
          • 数据库流量:单次出包大小为16M
          • 数据库单集合索引限制:20个
          • 单个小程序的小程序端请求频率限制:100 万次/分钟

          注:

          1. CDN回源流量:指开启了 CDN 加速后,CDN 回源存储时产生的流量。
          2. 云函数调用次数:已放开调用次数限制,现所有套餐均改为无限调用次数
          3. 云函数资源使用量 GBs:资源使用量 = 函数配置内存 X 运行计费时长。用户资源使用量,是由函数配置内存,乘以函数运行时的计费时长得出,其中配置内存转换为 GB 单位,计费时长由毫秒(ms)转换为秒(s)单位,因此,资源使用量的计算单位为 GBs(GB-秒)。例如,配置为 256MB 的函数,单次运行了 1760 ms,计费时长为 1800 ms,则单次运行的资源使用量为 (256/1024)*(1800/1000) = 0.45 GBs。针对函数的每次运行,均会计算资源使用量,并按月汇总求和,作为当月的资源使用量。
          4. 数据库同时连接数 :数据库请求并发数量,如同时有三十个数据库操作请求,则有二十个会同时执行,剩下十个返回超出并发错误;一次数据库请求(无论小程序端发起还是云函数端发起)将耗费一个连接;每个云环境分别有一个同时连接数限制、独立计数。假如数据库查询平均耗时 10ms,那么一个连接可以支持 100qps(1000ms/10ms=100),20个连接可以支持到 2000qps。
          5. 云函数(单次运行)运行内存:云函数运行时最大可用内存为 256 MB。在云函数运行日志中展示的运行内存信息,为当次运行时的实际使用内存。实际使用内存可能低于最大可用内存,计费时按配置内存即 256 MB 计算。
          6. 云函数同时连接数:已放开同时连接数限制,现所有套餐均改为统一的最大上限 1000

          服务等级协议

          小程序·云开发由腾讯云 TCB 提供存储和计算服务,因此小程序·云开发遵循《腾讯云云开发服务等级协议(SLA)》中的相关规定。

          对于已购买云开发套餐并已产生费用的客户,如服务可用性低于标准,开发者有权根据服务等级协议中的赔偿方案,通过相应账户的 工单 申请赔付。具体可用性计算规则、赔偿标准和申请方式遵循《腾讯云云开发服务等级协议(SLA)》中的规定。

          特别说明

          • 自付费功能上线起,将不再受理通过邮箱申请的小程序·云开发配额调整申请。
          • 对于截止2019-06-21日前申请调整的配额的截止日期统一延长至2019-08-31。

          配额调整

          配额调整方式

          如需调整配额,可按照以下方式操作:

          1. 登录 微信开发者工具 并打开 云控制台。
          2. 点击 设置 页面,选择需调整到的配额版本。

          调整配额

          1. 核对调整信息并确认已阅读并同意《小程序·云开发资源配额调整规则》。
          2. 在购买页选择相应的购买时长,确认无误后点击 提交订单。
          • 配额:为当前将购买的配额版本,目前系统分别提供了基础版、专业版、旗舰版、企业版和豪华版共计 5 种配额以适用于不同的业务场景。
          • 价格:为当前将购买的配额版本的价格信息,计费单位为月。
          • 购买时长:用户可根据自身需求选择相应的购买时长,目前单次购买时长最低不得低于 1 个月,最高不得超过 6 个月。
          • 到期时间:到期时间的计算规则可参考《小程序·云开发资源配额调整规则》。
          • 合计价格:根据用户选择的配额、到期时间等信息计算得到。具体计算规则可参考《小程序·云开发资源配额调整规则》。

          提交订单

          1. 提交订单后可选择相应的支付方式并进行支付。系统目前仅支持微信支付,由于受微信支付的支付额度限制,单日支付金额需小于 ¥50,000 元。

          查看订单详情

          提交订单,用户可以在 历史配额 页面的订单记录列表中,查看订单号、创建时间和订单状态等,并可通过点击订单记录查看详细的订单信息。

          订单状态

          当订单处于不同的状态时,将影响环境的配额调整操作。具体情况如下:

          • 当有订单处于未支付、支付中 以及发货中的状态时,用户将无法对当前环境再进行任何的配额调整操作。
          • 对于升配、降配和续费成功的订单,订单状态将处于发货成功,届时用户可再次进行配额调整或续费操作。
          • 对于升配或续费失败的订单,订单状态将处于 已退款 ,届时用户可重新发起配额调整或续费操作。
          • 对于降配失败的订单,订单状态将处于 已取消,届时用户可重新发起配额调整。

          取消订单

          对于 未支付 的订单用户可通过点击 取消 按钮,取消该订单。

          取消订单

          删除订单

          对于已取消的订单,用户可通过点击 删除 按钮,删除该订单。删除后订单将不再显示在 历史配额 中。

          删除订单


          配额调整规则

          根据用户选择调整到的配额版本和当前配额版本的差异,配额调整可分为升配和降配。升配和降配具体的调整规则如下所述:

          升配规则

          第一次从基础版升配

          从用户创建环境开始计算,第一次从基础版升级到其他配额时:

          • 用户可手动输入输入购买时长,单次购买时长不得低于 1 个月,且不得高于 6 个月。
          • 到期时间将根据根据购买时长在当前购买时间的基础上进行延长。
          • 升配费用将根据新配额的按月价格和购买时长等计算得到,具体计算方法为:
          升配费用 = 新配置按月价格 * 升配月数 * 新配置适用折扣;(无折扣不用乘折扣系数)
          • 系统目前仅支持微信支付。由于受微信支付的支付额度限制,单日支付金额需小于 ¥50,000 元。

          非第一次从基础版升配

          从用户创建环境开始计算,非第一次从基础版升级到其他配额时:

          • 到期时间将沿用当前生效配额的到期时间。
          • 升配月数将根据资源到期时间和当前时间计算得到,具体计算方法为:
          升配月数 = (资源到期时间 - 当前时间)/ (365 / 12);
          • 升配费用将按照配置的按月价格和升配月数等参数计算得到,具体计算方法为:
          升配费用 = 新配置按月价格 * 升配月数 * 新配置适用折扣- 老配置按月价格 * 升配月数 * 老配置适用折扣;(无折扣不用乘折扣系数)

          降配规则

          降配说明

          当从较高版本的资源配额调整到较低版本的资源配额时,将产生降配操作。降配过程中:

          1. 出现以下情形时,系统将限制用户降配,具体包括:
          • 存储容量、数据库容量以及数据库集合数量超过配额限制将无法降配。用户可以清理资源后再进行降配。
          • 存储下载次数、上传次数、CDN回源流量、CDN流量、云函数调用次数、云函数资源使用量、云函数外网出流量超过降配配额限制将无法降配。可在下一资源生命周期再进行降配。
          • 数据库读操作次数和数据库写操作次数超限后,可选择下一自然日再进行配额调整或强制降配。强制降配将导致已超限资源本自然日内无法继续使用。
          • 降配产生的退费金额超过了可开发票金额将无法降配。用户可将发票退回或当退费金额小于可开发票金额后再进行降配。发票退回操作步骤可参考《发票管理》。
          1. 到期时间将沿用当前生效配额的到期时间。

          退款金额

          资源降配遵循先退款再购买原则,具体计算方法为:

          降配退款金额 = 资源清退退款 - 资源新购费用

          其中:

          1. 资源清退退款:按照非全额退款规则计算退款金额,具体计算方法为:
          退款金额 = 当前有效订单金额 + 未开始订单金额 - 资源已消费金额其中:- 当前有效订单金额/未开始订单金额:付费现金- 资源已消费金额 =(已使用时长/总时长)* 订单金额
          1. 资源新购费用:按新购的价格及对应折扣进行计算购买金额。

          退款途径

          降配退款金额依据购买时使用的非代金券费用按支付方式(现金/赠送金)及支付比例退还到支付方账户。


          续费说明

          基础版续费

          基础版可供开发者免费使用,因此在资源生命周期到期日,系统会自动进行续费操作,无需开发者手动续费。每次续费将按照一个月的粒度延长资源的到期时间。

          非基础版配额续费

          非基础版配额需用户手动进行续费并支付相应的费用。具体操作流程如下:

          1. 用户可通过选择当前生效配额,并点击续费按钮进行续费。

          续费

          1. 用户可选择续费时长并提交订单。续费时需注意:
          • 用户可手动输入购买时长,单次购买时长不得低于 1 个月,且不得高于 6 个月。
          • 到期时间将根据续费时长在当前环境的到期时间的基础上进行延长。
          • 续费价格将根据当前配额的按月价格和购买时长计算得到,具体计算方法为:
          续费费用 = 续费配额的按月价格 * 购买月数 * 适用折扣;(无折扣不用乘折扣系数)
          • 系统目前仅支持微信支付。由于受微信支付的支付额度限制,单日支付金额需小于 ¥50,000 元。

          提交续费

          隔离期续费说明

          资源到期当天会系统会推送资源停服通知。到期次日至到期后 7 天,资源进入隔离期,在此期间用户对资源可以进行续费找回。具体续费规则如下:

          • 用户续费金额按照续费时长计算费用。
          • 到期时间为原有配额的到期时间加上续费时长。例如:用户原来到期时间是 19 年 7 月 20 日,隔离期从 7 月 21 日 - 7 月 27 日,在隔离期续费一个月,所需支付1个月的费用,新的到期时间为 19 年 8 月 20 日;

          资源超限和到期停服规则

          资源超限

          在一个计费周期内,若某项资源使用量超出当前配额限制,系统将限制对该资源的使用,具体限制策略如下:

          • 存储容量、数据库容量、数据库集合超限时,将无法存储或处理更多数据。除非清理数据到上限值以下或升级到更高配额套餐。
          • CDN 流量、CDN 回源流量、存储下载次数限制、存储上传次数限制、云函数调用次数、云函数资源使用量和云函数外网出流量超限时,在下一资源生命周期前将无法使用资源。除非升级到更高配额套餐。
          • 数据库读操作次数和数据库写操作次数超限时,在当前自然日内将无法使用资源。除非升级到更高配额套餐。
          • 同时连接数、函数并发达到上限后后续的连接都将被拒,直到某些现有连接关闭为止。已连接的用户可以继续使用应用。除非升级到更高配额套餐。

          到期通知

          资源会在到期前 7 天开始,隔天推送到期通知,通知消息将通过微信公众平台公众号通知到小程序的开发者。

          停服通知

          资源到期当天会推送资源停服通知,通知消息将通过微信公众平台公众号通知到小程序的开发者。到期次日至到期后 7 天,仍可以进行续费找回。若到期 7 天后(包括第 7 天)未进行续费,系统将在到期后第 8 天开始释放资源,届时环境中的数据将被清除且不可恢复。

          到期停服后:

          • 存储、数据库和 CDN 资源均无法使用。
          • 对于云函数:已有函数无法被触发。定时触发器暂停运行,停止触发函数。对于同步调用,函数将报错并无法执行。

          回收机制

          • 资源到期前 7 天,系统会开始发送到期通知。
          • 资源到期当日系统会发送资源停服通知。
          • 到期次日至到期后 7 天,仍可以进行续费找回。
          • 若到期 7 天后(包括第 7 天)未进行续费,系统将在到期后第 8 天开始释放资源,届时环境中的数据将被清除且不可恢复。


          按量付费

          小程序·云开发已提供按量付费功能。在按量付费模式下,系统每月会提供一定的免费额度供开发者使用,超过免费额度的资源消耗将按照对应的刊例价扣除费用。

          在使用按量付费功能时请注意:

          • 小程序一旦开通按量付费后,将无法再切换到预付费支付方式,请开发者谨慎操作;
          • 通过小程序管理后台和微信开发者工具云控制台申请的代金券无法用于按量付费模式;
          • 同时,在按量付费模式下,基础告警功能将不再适用,但是开发者仍然可以使用自定义告警功能。具体告警功能使用方式可参考文档《小程序·云开发告警》;
          • 需下载最新 nightly 版本 的开发者工具进行开通。

          费用计算

          按量付费的每月免费额度和刊例价信息如下:

          参数价格免费额度
          存储空间0.0043 元/GB/天5GB
          存储下载操作次数0.01 元/万次150 万次/月
          存储上传操作次数0.01 元/万次60 万次/月
          CDN回源流量0.15 元/GB5GB/月
          CDN流量0.18 元/GB5GB/月
          云函数资源使用量0.00011108 元/GBs4 万 GBs/月
          云函数外网出流量0.8 元/GB1GB/月
          数据库容量0.07 元/GB2GB
          数据库读操作次数0.015 元/万次5万次/天
          数据库写操作次数0.05 元/万次3万次/天

          可选拓展功能的按量付费的每月免费额度和刊例价信息如下:

          参数价格免费额度
          静态资源容量0.0042 元/GB/天开通后前两个月 1GB/天
          静态资源流量0.15 元/万次开通后前两个月 5GB

          请注意,小程序·云开发资源在按量付费模式下,需遵守以下系统参数限制:

          • 数据库容量:2TB
          • 云函数(单次运行)运行内存1:256M
          • 云函数并发数2:1000
          • 数据库同时连接数3:1000
          • 单个小程序的小程序端请求频率限制:100 万次/分钟

          在按量付费模式下,系统会每日进行资源消耗和结算并进行扣费。开发者可登录腾讯云费用中心进行充值或查看账单信息。

          注:

          1. 云函数(单次运行)运行内存:云函数运行时最大可用内存为 256MB。在云函数运行日志中展示的运行内存信息,为当次运行时的实际使用内存。实际使用内存可能低于最大可用内存,计费时按配置内存即 256MB 计算。
          2. 云函数并发数:云函数的并发数量是指在任意指定时间对函数代码的执行数量。对于当前的 SCF 函数来说,每个发布的事件请求就会执行一次。因此,这些触发器发布的事件数(即请求量)会影响函数的并发数。开发者以使用以下公式来估算并发的函数实例总数目。每秒请求量 * 函数执行时间(按秒) 例如,考虑一个处理存储事件的函数,假定函数平均用时0.2秒(即200毫秒),存储每秒发布300个请求至函数。这样将同时生产 300 * 0.2 = 60 个函数实例。
          3. 数据库同时连接数 :数据库请求并发数量,如同时有三十个数据库操作请求,则有二十个会同时执行,剩下十个返回超出并发错误;一次数据库请求(无论小程序端发起还是云函数端发起)将耗费一个连接;每个云环境分别有一个同时连接数限制、独立计数。假如数据库查询平均耗时 10ms,那么一个连接可以支持 100qps(1000ms/10ms=100),20个连接可以支持到 2000qps。

          欠费和停服处理

          从账户余额被扣为负值时,系统会通过微信公众平台公众号通知到小程序管理员并同步欠费信息至小程序云监控告警群,提示开发者尽快充值。

          从账户余额被扣为负值时刻起,小程序·云开发资源在 12 小时内可继续使用且继续扣费,12 小时后未及时充值,系统将自动隔离资源且停止扣费。

          进入资源隔离期后,系统会通过微信公众平台公众号通知到小程序管理员并同步停服信息至小程序云监控告警群。同时:

          • 7*24 小时内,若充值至余额大于 0,计费将继续,用户可继续使用小程序·云开发提供的服务。
          • 7*24 小时内,若账户余额尚未充值到大于 0,则无法使用服务。
          • 7*24 小时后,若账户余额未充值到大于 0,按量计费环境将被回收。届时环境中的数据将被清除且不可恢复。

          进入资源隔离期后:

          • 存储、数据库和 CDN 资源均无法使用。
          • 对于云函数:已有函数无法被触发。定时触发器暂停运行,停止触发函数。对于同步调用,函数将报错并无法执行。


          发票管理

          可开发票金额

          可开发票金额为该帐号(小程序帐号)下所有环境购买订单所产生的可开发票金额。其计算方式为:

          可开发票金额 = 总金额 - 已开发票金额

          其中:

          • 总金额为该帐号(小程序帐号)下所有环境购买订单所产生的总金额。
          • 已开发票金额为该帐号(小程序帐号)下所有已开发票的总金额。

          申请开票

          小程序·云开发由腾讯云 TCB 提供存储和计算服务,因此发票由腾讯云计算(北京)有限责任公司开具。具体申请开票流程如下:

          1. 用户可通过点击 申请开票 开具所需金额发票。

          发票

          1. 开发票时需填入相应的开票信息,具体包括:
          • 开票金额
          • 发票类型
          • 邮寄地址

          申请开票时请注意:

          • 开票金额不得超过可开发票金额。
          • 当开票金额小于 10 元时,发票将采取顺丰到付的邮寄方式,运费由用户承担。当开票金额不低于 10 元时,系统将提供免费的邮寄服务。
          • 当天 24 点前可取消开发票申请。
          • 若因信息填写错误导致发票不可用或丢失,需发起退票申请(流程周期较长),请仔细核对发票信息和邮寄地址。
          • 对于个人增值税普通发票,发票抬头一律为 个人。
          • 只有主体类型为 企业 的小程序才可开具 企业增值税专用发票,且发票抬头为小程序主体名称,用户不可自行修改。

          查看开票详情

          申请开票后,用户可以在 发票 页面的申请记录列表中,确认发票开具金额和状态,并可通过点击发票记录查看详细的发票信息和邮寄信息。

          取消开发票申请

          当天 24 点前,用户均可通过 取消 操作取消该开发票申请。一旦状态变更为开票中,用户将无法再取消该申请。

          发票退回

          若出现以下情况,可提交工单进行退票。提交工单时需填写问题描述为退发票,需写明退票原因,提交工单后将由客服人员处理。具体原因包括:

          • 发票类型错误。
          • 退费退票。
          • 税号、开户行账号错误。
          • 发票打印错误。
          • 主体工商名称变更。
          • 发票金额有误。

          退票过程中请注意:

          • 退票需用户自行邮寄发票及相关证明,邮费需自行支付。
          • 此操作一旦进行将无法撤回,请谨慎操作。
          • 不同情况下退票需邮寄的材料包括:退票时专票已抵扣需提供:税务局开具的 红字通知单 + 发票复印件 + 公司拒收证明。退票时专票未抵扣需提供:发票原件 + 公司拒收证明。其他退票:发票原件。

          发票丢失处理

          增值税普通发票:我们可以为你提供发票底联复印件(加盖发票章)或扫描件,用户可在控制台 提交工单 申请,工单中请写明原因及发票号码和金额。税务确认信息后,将于5 - 7个工作日内回复。

          增值税专用发票:用户需要在其所在地主管税局办理发票遗失流程后,提供《行政处罚决定书》复印件(加盖公章)邮寄到对应收件地址。由税务到税局开具《丢失增值税专用发票已报税证明单》,用户收到该凭证后可凭《丢失增值税发票已报税证明单》入账并抵扣相应税款。

          注意:

          • 《丢失增值税发票已报税证明单》只适用丢失增值税专用发票;丢失增值税普通发票税局不支持开具。
          • 具体邮寄地址可通过子在云开发控制台提交 工单 获取。


          代金券申请方式

          为助力开发者以更低的资源成本实现小程序的功能迭代,小程序·云开发提供了以下两种代金券:

          • 通用代金券:专业版/旗舰版;
          • 特殊代金券。

          申请代金券前请注意:

          • 通用代金券和特殊代金券仅适用于预付费的模式,不支持在按量付费模式中使用;
          • 申请过通用代金券的帐号将无法再申请特殊代金券;
          • 申请过特殊代金券的帐号待发券完成后,可继续申请通用代金券。

          开发者可在 nightly 版本微信开发者工具云开发控制台费用管理的代金券模块申请相应的代金券。

          代金券

          通用代金券

          申请标准

          系统提供的专业版(104 元/月)和旗舰版(860 元/月)两种代金券,每种代金券的申请标准分别为:

          • 专业版:最近 31 天,连续 5 天每天记录到用户访问中的独立访客(UV)不低于 100 的小程序可申请专业版代金券。
          • 旗舰版:最近 31 天,连续 5 天每天记录到用户访问中的独立访客(UV)不低于 2000 的小程序可申请旗舰版代金券。

          其中:

          • 连续 5 天:是指不低于连续 5 天。连续 5 天、连续 6 天、连续 7 天等均为有效数据。
          • 记录到用户访问中:如需将访问用户记录到云控制台的用户访问中,在调用 wx.cloud.init 方法时,需将 traceUser 置为 true。未被记录到用户访问中的用户将不作为有效数据,具体使用方式请参考 wx.cloud.init.
          • 独立访客(UV):是指按照访客进行去重,每个独立用户为一次有效数据。
          • 不低于 100/2000:是指大于或等于 100/2000。

          满足旗舰版申请标准的小程序帐号同时也满足专业版的申请标准。但是,每个小程序帐号有且仅能申请专业版/旗舰版中的一种,且当代金券申请进入发券中状态时,将无法更换申请的代金券类型,请谨慎申请。

          申请说明

          代金券申请包括以下几个状态:

          • 未申请:在未申请状态时,如果满足代金券申请标准,则小程序的开发者可发起代金券申请。
          • 未审核:提交申请后,代金券申请会处于未审核状态。此时开发者可取消申请,取消后可再次发起代金券申请操作。
          • 发券中:审核通过后,代金券申请会处于发券中状态。对于处于发券中的小程序,开发者将无法撤销申请或更换代金券类型,因此请谨慎申请代金券。
          • 发券完成:代金券发放完毕后,代金券申请会处于发券完成状态,后续将不会再发放代金券。

          申请通过后系统会每月定时发放代金券,累计下发 12 个月。除第一次外,每次发放代金券时间一般情况下会在申请时间的基础上提前两天发放。如遇申请时间为 30 或者 31 号,则发放时间是以 29 号为准提前两天。

          申请通过/拒绝或发放代金券时,系统会通过模版消息通知到申请人,同时通过告警群通知到群成员。

          申请被拒绝后,如有需要开发者可通过微信开发者工具的云开发控制台中的工单联系我们。

          特殊代金券

          当前无可申请的特殊代金券。

          代金券使用说明

          以下代金券使用说明同时适用于通用代金券和特殊代金券。

          开发者可登录微信开发者工具的云开发控制台查看代金券的详细信息。同时,在购买预付费套餐时使用对应代金券。

          发放的代金券的状态分为待使用、已冻结、已使用、已过期。每种状态的说明如下:

          • 待使用:未使用且未过期的代金券,可以用于抵扣费用。
          • 已冻结:显示已确认订单但未支付的代金券。
          • 已使用:余额已使用完毕的代金券,不可用于抵扣费用。
          • 已过期:已过有效期的代金券,不可用于抵扣费用。

          如需了解代金券的具体信息,包括代金券编号、可用金额、总金额、状态、使用门槛、到期时间等,可在云开发控制台费用管理的代金券模块查看。

          发放的代金券可在支付订单时使用。使用过程中需遵守以下规则:

          • 一个订单只能使用一张代金券。
          • 一张代金券仅能用于一个订单。
          • 基于代金券支付的订单购买时长不得超过 1 个月。
          • 代金券无金额门槛,可用于购买任意版本的云开发套餐。
          • 代金券被冻结或已过期时,将无法使用代金券。
          • 对于使用代金券支付的订单,在发起退费时,代金券将不予以退还。

          使用代金券


          兼容性问题

          云开发能力从基础库 2.2.3 开始支持,现在 2.2.3 或以上的基础库已覆盖绝大部分用户(目前约 99.6% ),不应继续使用旧的兼容性处理方式。如采用了旧的兼容性处理方式,请去除 app.json / game.json 中的字段 "cloud": true。


          云开发更新日志

          小程序基础库更新日志(云开发部分)

          v2.8.3 (2019.09.23)

          1. A 增加 数据库 8 个查询指令、7 个更新指令、1 个投影操作符 详情

          v2.8.1 (2019.08.22)

          1. A 增加 数据库实时数据推送 详情

          v2.7.3 (2019.07.05)

          1. A 增加 数据库支持聚合能力 详情

          v2.6.3 (2019.02.27)

          1. A 增加 云开发数据库支持地理位置 API

          v2.4.1 (2018.11.19)

          1. A 增加 插件支持使用云开发

          v2.3.2 (2018.10.25)

          1. A 增加 db.RegExp 及正则查询支持

          v2.2.3 (2018.08.19)

          1. A 新增 小程序·云开发 SDK 详情

          wx-server-sdk 更新日志

          2.1.1 (2020.06.04)

          1. A 新增 小游戏虚拟支付沙箱环境接口

          2.1.0 (2020.06.03)

          1. A 新增 小游戏虚拟支付能力
          2. A 新增 数据库更新和删除 API 增加 multi 选项

          2.0.2 (2020.05.06)

          1. A 新增 微信支付能力
          2. A 新增 云函数灰度能力

          1.8.3 (2020.04.03)

          1. A 新增 定义文件 index.d.ts

          1.8.0 (2020.01.03)

          1. U 更新 云调用 openapi 支持设置不自动转换驼峰命名法和蛇底命名法

          1.7.0 (2019.12.24)

          1. A 新增 数据库事务 API
          2. U 更新 不再支持 node 8 以下运行环境,使用开发者工具本地调试需使用 node 8 或以上

          1.6.0 (2019.12.12)

          1. A 新增 定时触发器中支持使用 DYNAMIC_CURRENT_ENV

          1.5.3 (2019.11.08)

          1. U 更新 tcb-admin-node 依赖至 1.16.2,修复触发器内使用云调用可能失败的问题

          1.5.0 (2019.10.23)

          1. A 新增 logger 方法,支持高级日志

          1.4.0 (2019.10.21)

          1. A 新增 新增 not、expr 操作符

          1.3.1 (2019.10.14)

          1. F 修复 push 操作符接收数组参数的问题

          1.3.0 (2019.10.14)

          1. A 新增 查询操作符:all, elemMatch, exists, size, mod
          2. A 新增 更新操作符:push, pull, pullAll, addToSet, rename, max, min
          3. A 新增 聚合流水线阶段:lookup
          4. A 新增 可用于聚合流水线 lookup 阶段的 pipeline 操作符

          详询数据库 API 列表

          1.2.2 (2019.10.11)

          1. F 修复 使用 DYNAMIC_CURRENT_ENV 时发起云调用会失败的问题

          1.2.1 (2019.09.16)

          1. A 新增 数据库多个查询、投影操作符

          1.1.1 (2019.09.12)

          1. A 新增 常量 DYNAMIC_CURRENT_ENV

          v0.8.1 (2019.07.01)

          1. A 增加 数据库聚合能力 详情

          0.7.0 (2019.06.28)

          1. A 新增 getWXContext 新增返回表示云函数最初调用来源的 SOURCE 字段

          v0.6.0(2019.05.30)

          1. A 新增 云函数内可通过 getWXContext 获取当前所在环境 详情

          v0.5.1(2019.05.15)

          1. F 修复 部分 tmp secret key expired 错误问题
          2. A 新增 云调用服务端调用 详情
          3. A 新增 云调用开放数据调用 详情

          v0.2.2 (2019.03.22)

          1. A 增加 云开发数据库支持地理位置 API

          0.0.24(2018.10.29)

          1. A 新增 数据库支持正则查询

          0.0.22 (2018.10.24)

          1. U 更新 callOpenAPI 不需传 event 参数

          0.0.21 (2018.10.19)

          1. U 新增 getWXContext API,用于获取微信调用上下文,包括 APPID、OPENID 和 UNIONID

          0.0.11(2018.08.30)

          1. U 更新 callFunction 返回 requestID

          0.0.9(2018.08.19)

          1. U 更新 getTempFileURL 传入参数更新

          0.0.7(2018.08.16)

          1. A 新增 云开发数据库、云函数、文件存储基础能力

          IDE 云开发 & 云控制台更新日志

          2019.10.18 (>= 1.02.1910182)

          1. A 新增 定时触发器支持使用云调用

          2019.06.25 (>= 1.02.1906252)

          1. A 新增 云控制台支持云函数接收消息推送配置 详情

          2019.06.20 (>= 1.02.1906202)

          1. A 新增 云控制台支持数据库高级查询/CRUD 详情

          2019.05.30 (>= 1.02.1905302)

          1. A 新增 IDE Network 面板支持展示云开发请求 详情

          2019.05.24 (>= 1.02.1905242)

          1. A 新增 IDE 支持云函数增量上传(上传单文件或目录)
          2. A 新增 云函数本地调试支持开发数据调用 详情

          2019.05.17 (>= 1.02.1905172)

          1. A 新增 控制台支持展示详细配额使用信息

          2019.03.25 (>= 1.02.1903251)

          1. A 新增 云控制台支持添加地理位置索引 详情

          2019.03.21 (>= 1.02.1903211)

          1. A 新增 IDE 支持云函数本地调试 详情

          2018.12.18 (>= 1.02.1812180)

          1. A 新增 插件 plugin.json 支持 cloud: true 详情

          2018.11.27 (>= 1.02.1811270)

          1. A 新增 定时触发器 详情

          2018.11.15 (>= 1.02.1811150)

          1. A 新增 云数据库索引可以增加唯一性限制 详情
          2. A 新增 云数据库导出 详情


          错误码

          在使用云能力时抛出的异常(fail 回调 / Promise reject)Error 对象中会带有 errCode 和 errMsg,云开发 HTTP API 回包中也会带有errcode和errmsg,这里是 errCode 值的一览表。

          错误码含义
          -1通用错误
          -401001SDK 通用错误:无权限使用 API
          -401002SDK 通用错误:API 传入参数错误
          -401003SDK 通用错误:API 传入参数类型错误
          -402001SDK 数据库错误:检测到循环引用
          -402002SDK 数据库错误:初始化监听失败
          -402003SDK 数据库错误:重连 WebSocket 失败
          -402004SDK 数据库错误:重建监听失败
          -402005SDK 数据库错误:关闭监听失败
          -402006SDK 数据库错误:收到服务器错误信息
          -402007SDK 数据库错误:从服务器收到非法数据
          -402008SDK 数据库错误:WebSocket 连接异常
          -402009SDK 数据库错误:WebSocket 连接断开
          -402010SDK 数据库错误:检查包序失败
          -402011SDK 数据库错误:未知异常
          -501001云资源通用错误:云端系统错误
          -403001SDK 文件存储错误:上传的文件超出大小上限
          -404001SDK 云函数错误:云函数调用内部失败:空回包
          -404002SDK 云函数错误:云函数调用内部失败:空 eventid
          -404003SDK 云函数错误:云函数调用内部失败:空 pollurl
          -404004SDK 云函数错误:云函数调用内部失败:空 poll 结果 json
          -404005SDK 云函数错误:云函数调用失败:超出最大正常结果轮询尝试次数
          -404006SDK 云函数错误:云函数调用内部失败:空 base resp
          -404007SDK 云函数错误:云函数调用失败:baseresponse.errcode 非 0
          -404008SDK 云函数错误:云函数调用失败:v1 轮询状态码异常
          -404009SDK 云函数错误:云函数调用内部失败:轮询处理异常
          -404010SDK 云函数错误:云函数调用失败:轮询结果已超时过期1
          -404011SDK 云函数错误:云函数调用失败:函数执行失败
          -404012SDK 云函数错误:云函数调用失败:超出最大轮询超时后尝试次数2
          -40400xSDK 云函数错误:云函数调用失败
          -404011SDK 云函数错误:云函数执行失败
          -501002云资源通用错误:云端响应超时
          -501003云资源通用错误:请求次数超出环境配额
          -501004云资源通用错误:请求并发数超出环境配额
          -501005云资源通用错误:环境信息异常
          -501007云资源通用错误:参数错误
          -501009云资源通用错误:操作的资源对象非法或不存在
          -501015云资源通用错误:读请求次数配额耗尽
          -501016云资源通用错误:写请求次数配额耗尽
          -501017云资源通用错误:磁盘耗尽
          -501018云资源通用错误:资源不可用
          -501019云资源通用错误:未授权操作
          -501020云资源通用错误:未知参数错误
          -501021云资源通用错误:操作不支持
          -502001云资源数据库错误:数据库请求失败
          -502002云资源数据库错误:非法的数据库指令
          -502003云资源数据库错误:无权限操作数据库
          -502005云资源数据库错误:集合不存在
          -502010云资源数据库错误:操作失败
          -502011云资源数据库错误:操作超时
          -502012云资源数据库错误:插入失败
          -502013云资源数据库错误:创建集合失败
          -502014云资源数据库错误:删除数据失败
          -502015云资源数据库错误:查询数据失败
          -503001云资源文件存储错误:云文件请求失败
          -503002云资源文件存储错误:无权限访问云文件
          -503003云资源文件存储错误:文件不存在
          -503003云资源文件存储错误:非法签名
          -504001云资源云函数错误:云函数调用失败
          -504002云资源云函数错误:云函数执行失败
          -601001微信后台通用错误:系统错误
          -601002微信后台通用错误:系统参数错误
          -601003微信后台通用错误:系统网络错误
          -604001微信后台云函数错误:回包大小超过 1M
          -604100微信后台云函数错误:API 不存在
          -604101微信后台云函数错误:无权限调用此 API
          -604102微信后台云函数错误:调用超时
          -604103微信后台云函数错误:云调用系统错误
          -604104微信后台云函数错误:非法调用来源
          -604101微信后台云函数错误:调用系统错误
          -605101微信后台 HTTP API 错误:查询语句解析失败

          额外说明

          1. 常见原因:发起调用后客户端网络异常;发起调用后在函数调用结果返回前切出小程序后台,并在后台函数调用结果缓存超期后才返回小程序前台。
          2. 常见原因:客户端网络异常。

          特殊错误说明:

          • 如果 AppID 没有开通云开发服务,或刚开通云开发但还没有过准备期(十分钟),则调用 cloud.init 时会出现 cloud init error:{ errMsg: "invalid scope" } 的错误,如果是因没有开通云开发,则请先进行开通操作,如果是刚开通,请稍等十分钟再重试。


          常量

          DYNAMIC_CURRENT_ENV

          支持端:云函数 1.1.0

          标志当前所在环境,注意该值不是当前所在环境 ID 的字符串,其值等价于 Symbol.for('DYNAMIC_CURRENT_ENV'),是用于标志当前所在环境的。如在 init 中如果给 env 参数传该常量值,则后续的 API 请求会自动请求当前所在环境的云资源,如云函数 A 当前所在环境是 test-123,则其接下来请求数据库、文件存储、云函数时都默认请求环境 test-123 的数据库、文件存储、云函数。

          常量可用于:

          • cloud.init 的 env 参数
          • cloud.updateConfig 的 env 参数
          • 各 API 的 config 参数中的 env 参数

          注意事项:

          • 自 1.7.1 起,该变量支持在定时触发器中使用,之前的版本不支持。

          示例

          cloud.init: 设置 API 默认环境等于当前所在环境

          cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})

          cloud.database: 设置新数据库对象的调用环境等于当前所在环境

          cloud.init({  env: 'xxx'})// 不同于 init 时设置的环境,db 对象的请求将会去到和当前云函数所在环境相同的环境const db = cloud.database({  env: cloud.DYNAMIC_CURRENT_ENV})

          cloud.callFunction: 设置调用的同环境的云函数

          cloud.init({  env: 'xxx'})// 不同于 init 时设置的环境,对云函数 getInfo 的请求将会去到和当前云函数所在环境相同的环境const callResult = await cloud.callFunction({  name: 'getInfo',  config: {    env: cloud.DYNAMIC_CURRENT_ENV  },  data: {    // ...  },})


          Promise Cloud.callFunction(Object object)

          支持端:小程序 , 云函数

          调用云函数

          参数

          Object object

          属性类型默认值必填说明
          namestring云函数名
          dataObject传递给云函数的参数,在云函数中可通过 event 参数获取
          configObject配置
          successfunction接口调用成功的回调函数
          failfunction接口调用失败的回调函数
          completefunction接口调用结束的回调函数(调用成功、失败都会执行)

          object.config 的结构

          属性类型默认值必填说明
          envstring环境 ID,填写后将忽略 init 时指定的环境 ID

          返回值

          Promise.<Object>

          属性类型说明
          resultany云函数返回的结果
          requestIDstring云函数执行 ID,可用于日志查询

          data 参数说明

          如果 data 中包含大数据字段(建议临界值 256KB),建议使用 wx.cloud.CDN 标记大数据字段,标记后在调用云函数时,该字段的内容将会上传至临时 CDN,然后在云函数中接收到的该字段值将是 CDN url,可在云函数中下载访问。通过这种方式,可以避免大数据传输造成的性能问题、及避免触及调用链路的传输大小限制。

          如果在 data 中如果传入了 Buffer 类型的数据,数据在 JSON 序列化的过程中会被转成 { "type": "Buffer", data: number[] } 的格式,以小程序端调用为例:

          // 小程序端调用wx.cloud.callFunction({  // ...  data: {    buf: ArrayBuffer // 此处填入了某种方式获取得到的 Buffer 数据,可以是 request 下来的,可以是读文件读出来的等等  },})// 云函数端收到的 event 参数的结构:{  "type": "Buffer",  "data": [ 17, 371, 255, ... ] // Uint8 Array}

          因此应当避免传入 Buffer 类型的数据,因为会让数据体积增大,增加传输耗时,如果需要传递 Buffer,有两种替代的建议方式:

          1. 若 Buffer 较大,可使用 wx.loud.CDN 方法标记字段内容
          2. 若 Buffer 非常小 (如 < 10k),可将 Buffer 转成 base64 再调用

          示例代码

          假设已有一个云函数 add:

          exports.add = (event, context, cb) => {  return event.x + event.y}

          在小程序端发起对云函数 add 的调用:

          wx.cloud.callFunction({  // 要调用的云函数名称  name: 'add',  // 传递给云函数的event参数  data: {    x: 1,    y: 2,  }}).then(res => {  // output: res.result === 3}).catch(err => {  // handle error})

          在云函数端任意云函数发起对云函数 add 的调用(完整云函数代码示例):

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const res = await cloud.callFunction({    // 要调用的云函数名称    name: 'add',    // 传递给云函数的参数    data: {      x: 1,      y: 2,    }  })  // 3  return res.result}

          小程序端 callback 风格调用:

          小程序端同时支持 Callback 风格调用,如上 Promise 风格的调用可以用 Callback 风格改写:

          wx.cloud.callFunction({  // 要调用的云函数名称  name: 'add',  // 传递给云函数的参数  data: {    x: 1,    y: 2,  },  success: res => {    // output: res.result === 3  },  fail: err => {    // handle error  },  complete: () => {    // ...  }})


          Cloud.uploadFile()

          支持端:小程序 , 云函数 , Web

          将本地资源上传至云存储空间,如果上传至同一路径则是覆盖


          Cloud.downloadFile()

          支持端:小程序 , 云函数 , Web

          从云存储空间下载文件


          wx.cloud.downloadFile

          从云存储空间下载文件

          请求参数

          字段说明数据类型默认值必填
          fileID云文件 IDString-Y
          config配置Object-N
          success成功回调
          fail失败回调
          complete结束回调

          config 对象定义

          字段说明数据类型
          env使用的环境 ID,填写后忽略 init 指定的环境String

          success 返回参数

          字段说明数据类型
          tempFilePath临时文件路径String
          statusCode服务器返回的 HTTP 状态码Number
          errMsg成功为 downloadFile:ok,失败为失败原因String

          fail 返回参数

          字段说明数据类型
          errCode错误码 Number
          errMsg错误信息,格式 downloadFile:fail msgString

          使用示例

          Callback 风格

          wx.cloud.downloadFile({  fileID: 'a7xzcb',  success: res => {    // get temp file path    console.log(res.tempFilePath)  },  fail: err => {    // handle error  }})

          Promise 风格

          wx.cloud.downloadFile({  fileID: 'a7xzcb'}).then(res => {  // get temp file path  console.log(res.tempFilePath)}).catch(error => {  // handle error})

          返回值 如果请求参数中带有 success/fail/complete 回调中的任一个,则会返回一个 downloadTask 对象,通过 downloadTask 对象可监听上传进度变化事件,以及取消上传任务。


          downloadFile

          从云存储空间下载文件

          请求参数

          字段说明数据类型默认值必填
          fileID云文件 IDString-Y

          Promise 返回参数

          字段说明数据类型
          fileContent文件内容Buffer
          statusCode服务器返回的 HTTP 状态码Number

          错误返回参数

          字段说明数据类型
          errCode错误码Number
          errMsg错误信息,格式 apiName:fail msgString

          使用示例

          Promise 风格

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const fileID = 'xxxx'  const res = await cloud.downloadFile({    fileID: fileID,  })  const buffer = res.fileContent  return buffer.toString('utf8')}


          Cloud.deleteFile(fileList: string[]): Promise<Object>

          支持端:小程序 , 云函数 , Web

          从云存储空间删除文件,一次最多 50 个

          参数

          fileList: string[]

          云文件 ID 字符串数组

          返回值

          Promise.<Object>

          属性类型说明
          fileListObject文件列表

          fileList 的结构

          属性类型说明
          fileIDstring云文件 ID
          statusnumber状态码,0 为成功
          errMsgstring成功为 ok,失败为失败原因

          小程序端示例

          Promise 风格

          wx.cloud.deleteFile({  fileList: ['a7xzcb']}).then(res => {  // handle success  console.log(res.fileList)}).catch(error => {  // handle error})

          Callback 风格

          wx.cloud.deleteFile({  fileList: ['a7xzcb'],  success: res => {    // handle success    console.log(res.fileList)  },  fail: err => {    // handle error  },  complete: res => {    // ...  }})

          云函数端示例

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const fileIDs = ['xxx', 'xxx']  const result = await cloud.deleteFile({    fileList: fileIDs,  })  return result.fileList}


          Cloud.getTempFileURL(fileList: string[]): Promise<Object>

          支持端:小程序 , 云函数 , Web

          用云文件 ID 换取真实链接,公有读的文件获取的链接不会过期,私有的文件获取的链接十分钟有效期。一次最多取 50 个。

          参数

          fileList: string[]

          要换取临时链接的云文件 ID 列表

          返回值

          Promise.<Object>

          属性类型说明
          fileListObject文件列表

          fileList 的结构

          属性类型说明
          fileIDstring云文件 ID
          tempFileURLstring临时文件路径
          statusnumber状态码,0 为成功
          errMsgstring成功为 ok,失败为失败原因

          小程序端示例

          Promise 风格

          wx.cloud.getTempFileURL({  fileList: [{    fileID: 'a7xzcb',    maxAge: 60 * 60, // one hour  }]}).then(res => {  // get temp file URL  console.log(res.fileList)}).catch(error => {  // handle error})

          Callback 风格

          wx.cloud.getTempFileURL({  fileList: ['cloud://xxx', 'cloud://yyy'],  success: res => {    // get temp file URL    console.log(res.fileList)  },  fail: err => {    // handle error  }})

          云函数端示例

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const fileList = ['cloud://xxx', 'cloud://yyy']  const result = await cloud.getTempFileURL({    fileList: fileList,  })  return result.fileList}


          Cloud.getWXContext(): Object

          支持端:云函数

          在云函数中获取微信调用上下文

          返回值

          Object

          wxContext

          属性类型说明
          OPENIDstring小程序用户 openid,小程序端调用云函数时有
          APPIDstring小程序 AppID,小程序端调用云函数时有
          UNIONIDstring小程序用户 unionid,小程序端调用云函数,并且满足 unionid 获取条件时有
          ENVstring云函数所在环境的 ID
          SOURCEstring调用来源(云函数本次运行是被什么触发)
          CLIENTIPstring小程序客户端 IPv4 地址
          CLIENTIPV6string小程序客户端 IPv6 地址

          使用说明

          SOURCE 值跟随调用链条传递,会表示调用链路情况(用英文逗号分隔),比如小程序调用云函数 A,再在云函数 A 内调用云函数 B,则 A 获得的 SOURCE 为 wx_client, B 内获得的 SOURCE 为 wx_client,scf(微信小程序调用,然后云函数调用)。

          SOURCE 的枚举类型:

          SOURCE 值含义
          wx_devtools微信 IDE 调用
          wx_client微信小程序调用
          wx_http微信 HTTP API 调用
          wx_unknown微信未知来源调用
          scf云函数调用云函数
          其他非微信端触发

          如果在云函数本地调试中,ENV 会为 local,SOURCE 会为 wx_client。

          注意事项

          请不要在 exports.main 外使用 getWXContext,此时尚没有调用上下文,无法获取得到信息。

          示例代码

          const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  const {    OPENID,    APPID,    UNIONID,    ENV,  } = cloud.getWXContext()  return {    OPENID,    APPID,    UNIONID,    ENV,  }}

          Cloud.logger(): Object

          支持端:云函数 1.5.0

          云函数中使用高级日志能力

          返回值

          Object

          logger

          属性类型说明
          logfunction默认等级的日志
          infofunction普通等级的日志
          warnfunction警告等级的日志
          errorfunction错误等级的日志

          使用说明

          用于使用高级日志能力。

          logger 方法返回一个 log 对象,log 对象包含以下方法,每调用一次产生一条日志记录: log:默认等级的日志 info:普通等级的日志 warn:警告等级的日志 error:错误等级的日志

          所有的方法都接收一个对象,对象的每个 <key, value> 对都会作为日志一条记录的一个可检索的键值对,其中 value 无论类型是什么都会自动转成字符串

          示例代码

          // 云函数入口文件const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV,})// 云函数入口函数exports.main = async (event, context) => {  const wxContext = cloud.getWXContext()  const log = cloud.logger()  log.info({    name: 'xx',    cost: 10,    attributes: {      width: 100,      height: 200,    },    colors: ['red', 'blue'],  })  // 输出到日志记录中会有这么一条记录:  // {  //   "level": "info",  //   "name": "xx",  //   "cost": "10",  //   "attributes": "{ width: 100, height: 200 }",  //   "colors": "[ "red", "blue" ]"  //   ..., // 其他系统字段  // }  return {    event,    openid: wxContext.OPENID,    appid: wxContext.APPID,    unionid: wxContext.UNIONID,  }}

          Cloud.CDN(opt: string|ArrrayBuffer|Object)

          支持端:小程序 2.12.0

          小程序端调云函数传递大数据可用的临时 CDN

          参数

          opt: string|ArrrayBuffer|Object

          使用说明

          标记需要上传到 CDN 的文件/大字符串然后转换成 HTTP URL 的数据,必须在 callFunction 中使用。

          小程序端调用云函数时,如需传递大数据(建议 128k 以上时),可用此 CDN 方法标记需要传递的数据,即可以是字符串,也可以是临时文件路径。标记之后,在调用云函数时,系统会自动上传相应数据到临时 CDN,最终云函数内接收到的该字段将会是一个 CDN 地址,可在云函数内请求下来。

          用这个方法可以避免大数据在云函数链路内的传输,提高大数据调用时的性能,同时避免触及调用数据的大小限制。

          CDN 方法可以接收三种参数类型:

          • String
          • ArrayBuffer
          • 文件路径定义对象

          当使用文件路径定义对象时,将在调用服务 API 时自动将相应文件路径对应的文件内容上传至 CDN 并转换成 CDN URL,对象定义如下: 入参*

          接收一个对象,对象下有如下定义的字段:

          字段名类型必填说明
          typestring定义对象的类型,必填 filePath
          filePathstring文件路径

          示例代码

          wx.cloud.callFunction({  name: 'test',  data: {    strDemo: wx.cloud.CDN('some large string'),    filePathDemo: wx.cloud.CDN({      type: 'filePath',      filePath: 'xxxxxxxx',    })  },}).then(console.log).catch(console.error)


          Cloud.openapi

          云调用 API 对象。


          Cloud.CloudID(cloudID: string)

          支持端:小程序 2.7.0

          声明字符串为 CloudID(开放数据 ID),该接口传入一个字符串,返回一个 CloudID 特殊对象,将该对象传至云函数可以获取其对应的开放数据。详见通过云调用获取开放数据

          参数

          cloudID: string

          通过开放能力在小程序端获取得到的 CloudID

          示例代码

          小程序端调用

          wx.cloud.callFunction({  name: 'myFunction',  data: {    weRunData: wx.cloud.CloudID('xxx'), // 这个 CloudID 值到云函数端会被替换    obj: {      shareInfo: wx.cloud.CloudID('yyy'), // 非顶层字段的 CloudID 不会被替换,会原样字符串展示    }  }})

          在云函数端接收到的 event 将会包含对应开放数据的对象,其中 event.weRunData 会因为符合规则而包含开放数据,event.shareInfo 则不会,event 结构将如下:

          {  "weRunData": {    "cloudID": "27_Ih-9vxDaOhIbh48Bdpk90DUkUoNMAPaNtg7OSGM-P2wPEk1NbspjKGoql_g",    "data": {      "stepInfoList": [        {          "step": 9103,          "timestamp": 1571673600        },        {          "step": 9783,          "timestamp": 1571760000        }      ],      "watermark": {        "appid": "wx3d289323f5900f8e",        "timestamp": 1574338655      }    }  },  "obj": {    "shareInfo": "xxx"  }}

          Cloud.getOpenData(list: string[]): Object

          支持端:云函数

          获取 CloudID 对应的开放数据

          参数

          list: string[]

          要获取对应开放数据的 CloudID 列表

          返回值

          Object

          属性类型说明
          listArray.<Object>开放数据列表,与传入的 CloudID 列表一一对应

          list 的结构

          属性类型说明
          cloudIDstring开放数据 CloudID
          dataObject开放数据

          说明

          详见通过云调用获取开放数据

          示例代码

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const res = await cloud.getOpenData({    list: event.openData.list, // 假设 event.openData.list 是一个 CloudID 字符串列表  })  return res.list}

          返回的结果结构类似如下(假设 list 长度为 1,其中的 CloudID 是微信运动数据的 CloudID):

          [{  "cloudID": "27_Ih-9vxDaOhIbh48Bdpk90DUkUoNMAPaNtg7OSGM-P2wPEk1NbspjKGoql_g",  "data": {    "stepInfoList": [      {        "step": 9103,        "timestamp": 1571673600      },      {        "step": 9783,        "timestamp": 1571760000      }    ],    "watermark": {      "appid": "wx3d289323f5900f8e",      "timestamp": 1574338655    }  }

          Cloud.getVoIPSign(options: Object): Promise<Object>

          支持端:云函数

          获取实时语音签名

          参数

          options: Object

          属性类型默认值必填说明
          groupIdstring游戏房间的标识
          noncestring随机字符串,长度应小于 128
          timestampnumber生成这个随机字符串的 UNIX 时间戳(精确到秒)

          返回值

          Promise.<Object>

          属性类型说明
          signaturestring签名

          示例代码

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const result = await cloud.getVoIPSign({    groupId: 'xxx',    timestamp: 1557056066,    nonce: 'yyy'  })  return result.fileListt}


          CloudPay.unifiedOrder()

          支持端:云函数 2.0.2

          统一下单

          说明

          商户在小程序中先调用该接口在微信支付服务后台生成预支付交易单,返回正确的预支付交易后调起支付。

          关键参数说明

          云开发相关关键参数说明: 回调函数设置:envId 和 functionName 用来设置接收支付后的异步通知回调的云函数 返回字段 payment:该对象即是在小程序端调用 wx.requestPayment 所需的信息

          回调云函数返回协议

          支付结果回调的云函数必须返回如下一个对象,否则会视为回调不成功,云函数会收到重复的支付回调:

          字段名变量名必填类型描述
          错误码errcodeNumber0
          错误信息errmsgString

          参数说明

          字段名变量名必填类型示例值描述
          结果通知回调云函数名functionNameStringpaycallback接收微信支付异步通知回调的云函数名
          结果通知回调云函数环境envIdStringtest-123接收微信支付异步通知回调的云函数所在的环境 ID
          子商户号subMchIdString(32)1900000109微信支付分配的子商户号
          设备号deviceInfoString(32)013467007045764终端设备号(门店号或收银设备ID),注意:PC网页或公众号内支付请传"WEB"
          随机字符串nonceStrString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
          商品描述bodyString(128)腾讯充值中心-QQ会员充值商品简单描述,该字段须严格按照规范传递,具体请见参数规定
          商品详情detailString(6000)商品详细描述,对于使用单品优惠的商户,该字段必须按照规范上传,详见“单品优惠参数说明”
          附加数据attachString(127)说明附加数据,在查询API和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据
          商户订单号outTradeNoString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
          货币类型feeTypeString(16)CNY符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
          总金额totalFeeInt888订单总金额,只能为整数,详见支付金额
          终端IPspbillCreateIpString(64)123.12.12.123支持IPV4和IPV6两种格式的IP地址。调用微信支付API的机器IP
          交易起始时间timeStartString(14)20091225091010订单生成时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则
          交易结束时间timeExpireString(14)20091227091010订单失效时间,格式为yyyyMMddHHmmss,如2009年12月27日9点10分10秒表示为20091227091010。订单失效时间是针对订单号而言的,由于在请求支付的时候有一个必传参数prepay_id只有两小时的有效期,所以在重入时间超过2小时的时候需要重新请求下单接口获取新的prepay_id。其他详见时间规则。
          建议:最短失效时间间隔大于1分钟
          订单优惠标记goodsTagString(32)WXG订单优惠标记,代金券或立减优惠功能的参数,说明详见代金券或立减优惠
          交易类型tradeTypeString(16)JSAPI小程序取值如下:JSAPI,详细说明见参数规定
          指定支付方式limitPayString(32)no_creditno_credit--指定不能使用信用卡支付
          用户标识openidString(128)oUpF8uMuAJO_M2pxb1Q9zNjWeS6otrade_type=JSAPI,此参数必传,用户在商户appid下的唯一标识。openid如何获取,可参考【获取openid】。
          用户子标识subOpenidString(128)oUpF8uMuAJO_M2pxb1Q9zNjWeS6otrade_type=JSAPI,此参数必传,用户在子商户appid下的唯一标识。openid和sub_openid可以选传其中之一,如果选择传sub_openid,则必须传sub_appid。下单前需要调用【网页授权获取用户信息】接口获取到用户的Openid。
          电子发票入口开放标识receiptString(8)YY,传入Y时,支付成功消息和支付详情页将出现开票入口。需要在微信支付商户平台或微信公众平台开通电子发票功能,传此字段才可生效
          场景信息sceneInfoString(256)Y该字段常用于线下活动时的场景信息上报,支持上报实际门店信息,商户也可以按需求自己上报相关信息。该字段为JSON对象数据,对象格式为{"store_info":{"id": "门店ID","name": "名称","area_code": "编码","address": "地址" }}

          sceneInfo.storeInfo 对象说明*

          字段名变量名必填类型示例值描述
          门店ididString(32)SZTX001门店编号,由商户自定义
          门店名称nameString(64)腾讯大厦腾大餐厅门店名称 ,由商户自定义
          门店行政区划码area_codeString(6)440305门店所在地行政区划码,详细见《最新县及县以上行政区划代码》
          门店详细地址addressString(128)科技园中一路腾讯大厦门店详细地址 ,由商户自定义

          返回值说明

          字段名变量名必填类型示例值描述
          返回状态码returnCodeString(16)SUCCESSSUCCESS/FAIL 此字段是通信标识,非交易标识,交易是否成功需要查看result_code来判断
          返回信息returnMsgString(128)签名失败返回信息,如非空,为错误原因。如 签名失败、参数格式校验错误

          以下字段在returnCode为SUCCESS的时候有返回

          字段名变量名必填类型示例值描述
          小程序中发起支付所需信息paymentObject小程序端调用 wx.requestPayment 所需信息
          服务商的APPIDappidString(32)wxd678efh567hg6787服务商商户的APPID
          商户号mch_idString(32)1900000109调用接口提交的商户号
          小程序的APPIDsub_appidString(32)wx8888888888888888微信分配的小程序ID
          子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
          设备号device_infoString(32)013467007045764调用接口提交的终端设备号,
          随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS微信返回的随机字符串
          签名signString(64)C380BEC2BFD727A4B6845133519F3AD6微信返回的签名,详见签名算法
          业务结果result_codeString(16)SUCCESSSUCCESS/FAIL
          错误代码err_codeString(32)SYSTEMERROR详细参见第6节错误列表
          错误代码描述err_code_desString(128)系统错误错误返回的信息描述

          以下字段在returnCode 和result_code都为SUCCESS的时候有返回

          字段名变量名必填类型示例值描述
          交易类型trade_typeString(16)JSAPI调用接口提交的交易类型,取值如下:JSAPI,详细说明见参数规定
          预支付交易会话标识prepay_idString(64)wx201410272009395522657a690389285100微信生成的预支付回话标识,用于后续接口调用中使用,该值有效期为2小时
          二维码链接code_urlString(64)weixin://wxpay/bizpayurl/up?pr=NwY5Mz9&groupid=00trade_type=NATIVE时有返回,此url用于生成支付二维码,然后提供给用户进行扫码支付。注意:code_url的值并非固定,使用时按照URL格式转成二维码即可

          错误码

          名称描述原因解决方案
          INVALID_REQUEST参数错误参数格式有误或者未按规则上传订单重入时,要求参数值与原请求一致,请确认参数问题
          NOAUTH商户无此接口权限商户未开通此接口权限请商户前往申请此接口权限
          NOTENOUGH余额不足用户帐号余额不足用户帐号余额不足,请用户充值或更换支付卡后再支付
          ORDERPAID商户订单已支付商户订单已支付,无需重复操作商户订单已支付,无需更多操作
          ORDERCLOSED订单已关闭当前订单已关闭,无法支付当前订单已关闭,请重新下单
          SYSTEMERROR系统错误系统超时系统异常,请用相同参数重新调用
          APPID_NOT_EXISTAPPID不存在参数中缺少APPID请检查APPID是否正确
          MCHID_NOT_EXISTMCHID不存在参数中缺少MCHID请检查MCHID是否正确
          APPID_MCHID_NOT_MATCHappid和mch_id不匹配appid和mch_id不匹配请确认appid和mch_id是否匹配
          LACK_PARAMS缺少参数缺少必要的请求参数请检查参数是否齐全
          OUT_TRADE_NO_USED商户订单号重复同一笔交易不能多次提交请核实商户订单号是否重复提交
          SIGNERROR签名错误参数签名结果不正确请检查签名参数和方法是否都符合签名算法要求
          XML_FORMAT_ERRORXML格式错误XML格式错误请检查XML参数格式是否正确
          REQUIRE_POST_METHOD请使用post方法未使用post传递参数请检查请求参数是否通过post方法提交
          POST_DATA_EMPTYpost数据为空post数据不能为空请检查post数据是否为空
          NOT_UTF8编码格式错误未使用指定编码格式请使用UTF-8编码格式

          示例代码

          // 云函数代码const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const res = await cloud.cloudPay.unifiedOrder({    "body" : "小秋TIT店-超市",    "outTradeNo" : "1217752501201407033233368018",    "spbillCreateIp" : "127.0.0.1",    "subMchId" : "1900009231",    "totalFee" : 1,    "envId": "test-f0b102",    "functionName": "pay_cb"  })  return res}// 小程序代码wx.cloud.callFunction({  name: '函数名',  data: {    // ...  },  success: res => {    const payment = res.result.payment    wx.requestPayment({      ...payment,      success (res) {        console.log('pay success', res)      },      fail (res) {        console.error('pay fail', err)      }    })  },  fail: console.error,})


          CloudPay.queryOrder()

          支持端:云函数 2.0.2

          查询订单

          说明

          该接口提供所有微信支付订单的查询,商户可以通过该接口主动查询订单状态,完成下一步的业务逻辑。

          需要调用查询接口的情况:

          ◆ 当商户后台、网络、服务器等出现异常,商户系统最终未接收到支付通知; ◆ 调用支付接口后,返回系统错误或未知交易状态情况; ◆ 调用被扫支付API,返回USERPAYING的状态; ◆ 调用关单或撤销接口API之前,需确认支付状态;

          参数说明

          字段名变量名必填类型示例值描述
          子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
          微信订单号transaction_id二选一String(32)1009660380201506130728806387微信的订单号,优先使用
          商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-*@ ,且在同一个商户号下唯一。
          随机字符串nonce_strString(32)C380BEC2BFD727A4B6845133519F3AD6随机字符串,不长于32位。推荐随机数生成算法

          返回值说明

          字段名变量名必填类型示例值描述
          返回状态码returnCodeString(16)SUCCESSSUCCESS/FAIL 此字段是通信标识,非交易标识,交易是否成功需要查看trade_state来判断
          返回信息returnMsgString(128)签名失败返回信息,如非空,为错误原因。如 签名失败、参数格式校验错误

          以下字段在returnCode为SUCCESS的时候有返回

          字段名变量名必填类型示例值描述
          服务商的APPIDappidString(32)wxd678efh567hg6787服务商商户的APPID
          商户号mch_idString(32)1230000109微信支付分配的商户号
          小程序的APPIDsub_appidString(32)wx8888888888888888微信分配的小程序ID
          子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
          随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
          签名signString(32)C380BEC2BFD727A4B6845133519F3AD6签名,详见签名生成算法
          业务结果result_codeString(16)SUCCESSSUCCESS/FAIL
          错误代码err_codeString(32)SYSTEMERROR错误码
          错误代码描述err_code_desString(128)系统错误结果信息描述

          以下字段在returnCode 和result_code都为SUCCESS的时候有返回

          字段名变量名必填类型示例值描述
          设备号device_infoString(32)013467007045764微信支付分配的终端设备号,
          用户标识openidString(128)oUpF8uMuAJO_M2pxb1Q9zNjWeS6o用户在商户appid下的唯一标识
          是否关注公众账号is_subscribeString(1)Y用户是否关注公众账号,Y-关注,N-未关注
          用户子标识sub_openidString(128)wxd930ea5d5a258f4f用户在子商户appid下的唯一标识
          是否关注子公众账号sub_is_subscribeString(1)Y用户是否关注子公众账号,Y-关注,N-未关注
          交易类型trade_typeString(16)JSAPI调用接口提交的交易类型,取值如下:JSAPI,NATIVE,APP,MICROPAY,详细说明见参数规定
          交易状态trade_stateString(32)SUCCESSSUCCESS—支付成功
          REFUND—转入退款
          NOTPAY—未支付
          CLOSED—已关闭
          REVOKED—已撤销(刷卡支付)
          USERPAYING--用户支付中
          PAYERROR--支付失败(其他原因,如银行返回失败)
          付款银行bank_typeString(16)CMC银行类型,采用字符串类型的银行标识
          订单金额total_feeInt100订单总金额,单位为分
          标价币种fee_typeString(8)CNY货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
          应结订单金额settlement_total_feeInt100当订单使用了免充值型优惠券后返回该参数,应结订单金额=订单金额-免充值优惠券金额。
          现金支付金额cash_feeInt100现金支付金额订单现金支付金额,详见支付金额
          现金支付货币类型cash_fee_typeString(16)CNY货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
          代金券金额coupon_feeInt100“代金券或立减优惠”金额<=订单总金额,订单总金额-“代金券或立减优惠”金额=现金支付金额,详见支付金额
          代金券使用数量coupon_countInt1代金券或立减优惠使用数量
          代金券IDcoupon_id_$nString(20)10000代金券或立减优惠ID, $n为下标,从0开始编号
          代金券类型coupon_type_$nStringCASHCASH--充值代金券
          NO_CASH---非充值优惠券
          开通免充值券功能,并且订单使用了优惠券后有返回(取值:CASH、NO_CASH)。$n为下标,从0开始编号,举例:coupon_type_$0
          单个代金券金额coupon_fee_$nInt100单个代金券或立减优惠支付金额, $n为下标,从0开始编号
          微信支付订单号transaction_idString(32)1217752501201407033233368018微信支付订单号
          商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
          商家数据包attachString(128)123456商家数据包,原样返回
          支付完成时间time_endString(14)20141030133525订单支付时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则
          交易状态描述trade_state_descString(256)支付失败,请重新下单支付对当前查询订单状态的描述和下一步操作的指引

          错误码

          名称描述原因解决方案
          ORDERNOTEXIST此交易订单号不存在查询系统中不存在此交易订单号该API只能查提交支付交易返回成功的订单,请商户检查需要查询的订单号是否正确
          SYSTEMERROR系统错误后台系统返回错误系统异常,请再调用发起查询


          CloudPay.closeOrder()

          支持端:云函数 2.0.2

          关闭订单

          说明

          以下情况需要调用关单接口:商户订单支付失败需要生成新单号重新发起支付,要对原订单号调用关单,避免重复支付;系统下单后,用户支付超时,系统退出不再受理,避免用户继续,请调用关单接口。 注意:订单生成后不能马上调用关单接口,最短调用时间间隔为5分钟。*

          参数说明

          字段名变量名必填类型示例值描述
          子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
          商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
          随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS商户系统内部的订单号,32个字符内、可包含字母, 其他说明见安全规范

          返回值说明

          字段名变量名必填类型示例值描述
          返回状态码returnCodeString(16)SUCCESSSUCCESS/FAIL
          返回信息returnMsgString(128)签名失败返回信息,如非空,为错误原因。如 签名失败、参数格式校验错误

          以下字段在returnCode为SUCCESS的时候有返回

          字段名变量名必填类型示例值描述
          服务商的APPIDappidString(32)wxd678efh567hg6787服务商商户的APPID
          商户号mch_idString(32)1230000109微信支付分配的商户号
          小程序的APPIDsub_appidString(32)wx8888888888888888微信分配的小程序ID
          子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
          随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位
          签名signString(32)C380BEC2BFD727A4B6845133519F3AD6签名,验证签名算法
          业务结果result_codeString(16)SUCCESSSUCCESS/FAIL
          业务结果描述result_msgString(32)OK对于业务执行的详细描述
          错误代码err_codeString(32)SYSTEMERROR详细参见下文错误列表
          错误代码描述err_code_desString(128)系统错误结果信息描述

          错误码

          名称描述原因解决方案
          ORDERPAID订单已支付订单已支付,不能发起关单订单已支付,不能发起关单,请当作已支付的正常交易
          SYSTEMERROR系统错误系统错误系统异常,请重新调用该API
          ORDERCLOSED订单已关闭订单已关闭,无法重复关闭订单已关闭,无需继续调用
          SIGNERROR签名错误参数签名结果不正确请检查签名参数和方法是否都符合签名算法要求
          REQUIRE_POST_METHOD请使用post方法未使用post传递参数请检查请求参数是否通过post方法提交
          XML_FORMAT_ERRORXML格式错误XML格式错误请检查XML参数格式是否正确


          CloudPay.refund()

          支持端:云函数 2.0.2

          申请退款

          说明

          当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,微信支付将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家帐号上。

          注意:

          1.交易时间超过一年的订单无法提交退款; 2、微信支付退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交,请不要更换退款单号,请使用原商户退款单号。 3、请求频率限制:150qps,即每秒钟正常的申请退款请求次数不超过150次。错误或无效请求频率限制:6qps,即每秒钟异常或错误的退款申请请求不超过6次 4、每个支付订单的部分退款次数不能超过50次

          参数说明

          字段名变量名必填类型示例值描述
          子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
          随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
          微信订单号transaction_idString(32)1217752501201407033233368018微信订单号。与商户订单号二选一填入。
          商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
          商户退款单号out_refund_noString(64)1.21775E+27商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-
          订单金额total_feeInt100订单总金额,单位为分,只能为整数,详见支付金额
          申请退款金额refund_feeInt100退款总金额,单位为分,只能为整数,可部分退款。详见支付金额
          货币种类refund_fee_typeString(8)CNY货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
          退款原因refund_descString(80)商品已售完若商户传入,会在下发给用户的退款消息中体现退款原因
          注意:若订单退款金额≤1元,且属于部分退款,则不会在退款消息中体现退款原因
          退款资金来源refund_accountString(30)REFUND_SOURCE_RECHARGE_FUNDS仅针对老资金流商户使用
          REFUND_SOURCE_UNSETTLED_FUNDS---未结算资金退款(默认使用未结算资金退款)
          REFUND_SOURCE_RECHARGE_FUNDS---可用余额退款

          返回值说明

          字段名变量名必填类型示例值描述
          返回状态码returnCodeString(16)SUCCESSSUCCESS/FAIL
          返回信息returnMsgString(128)签名失败返回信息,如非空,为错误原因。如 签名失败、参数格式校验错误

          以下字段在returnCode为SUCCESS的时候有返回

          字段名变量名必填类型示例值描述
          业务结果result_codeString(16)SUCCESSSUCCESS/FAIL
          SUCCESS退款申请接收成功,结果通过退款查询接口查询
          FAIL 提交业务失败
          错误代码err_codeString(32)SYSTEMERROR列表详见错误码列表
          错误代码描述err_code_desString(128)系统超时结果信息描述
          服务商的APPIDappidString(32)wxd678efh567hg6787服务商商户的APPID
          商户号mch_idString(32)1230000109微信支付分配的商户号
          小程序的APPIDsub_appidString(32)wx8888888888888888微信分配的小程序ID
          子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
          随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位
          签名signString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS签名,详见签名算法
          微信订单号transaction_idString(32)1217752501201407033233368018微信订单号
          商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
          商户退款单号out_refund_noString(64)1217752501201407033233368018商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-
          微信退款单号refund_idString(32)1217752501201407033233368018微信退款单号
          申请退款金额refund_feeInt100退款总金额,单位为分,可以做部分退款
          退款金额settlement_refund_feeInt100去掉非充值代金券退款金额后的退款金额,退款金额=申请退款金额-非充值代金券退款金额,退款金额<=申请退款金额
          订单金额total_feeInt100订单总金额,单位为分,只能为整数,详见支付金额
          应结订单金额settlement_total_feeInt100应结订单金额=订单金额-免充值代金券金额,应结订单金额<=订单金额。
          货币种类fee_typeString(8)CNY订单金额货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
          现金支付金额cash_feeInt100现金支付金额,单位为分,只能为整数,详见支付金额
          现金退款金额cash_refund_feeInt100现金退款金额,单位为分,只能为整数,详见支付金额
          代金券退款总金额coupon_refund_feeInt100代金券退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为现金,说明详见代金券或立减优惠
          退款代金券使用数量coupon_refund_countInt1退款代金券使用数量
          代金券类型coupon_type_$nString(8)CASHCASH--充值代金券
          NO_CASH---非充值代金券
          订单使用代金券时有返回(取值:CASH、NO_CASH)。$n为下标,从0开始编号,举例:coupon_type_0

          错误码

          名称描述原因解决方案
          SYSTEMERROR接口返回错误系统超时请不要更换商户退款单号,请使用相同参数再次调用API。
          BIZERR_NEED_RETRY退款业务流程错误,需要商户触发重试来解决并发情况下,业务被拒绝,商户重试即可解决请不要更换商户退款单号,请使用相同参数再次调用API。
          TRADE_OVERDUE订单已经超过退款期限订单已经超过可退款的最大期限(支付后一年内可退款)请选择其他方式自行退款
          ERROR业务错误申请退款业务发生错误该错误都会返回具体的错误原因,请根据实际返回做相应处理。
          USER_ACCOUNT_ABNORMAL退款请求失败用户帐号注销此状态代表退款申请失败,商户可自行处理退款。
          INVALID_REQ_TOO_MUCH无效请求过多连续错误请求数过多被系统短暂屏蔽请检查业务是否正常,确认业务正常后请在1分钟后再来重试
          NOTENOUGH余额不足商户可用退款余额不足此状态代表退款申请失败,商户可根据具体的错误提示做相应的处理。
          INVALID_TRANSACTIONID无效transaction_id请求参数未按指引进行填写请求参数错误,检查原交易号是否存在或发起支付交易接口返回失败
          PARAM_ERROR参数错误请求参数未按指引进行填写请求参数错误,请重新检查再调用退款申请
          APPID_NOT_EXISTAPPID不存在参数中缺少APPID请检查APPID是否正确
          MCHID_NOT_EXISTMCHID不存在参数中缺少MCHID请检查MCHID是否正确
          REQUIRE_POST_METHOD请使用post方法未使用post传递参数请检查请求参数是否通过post方法提交
          SIGNERROR签名错误参数签名结果不正确请检查签名参数和方法是否都符合签名算法要求
          XML_FORMAT_ERRORXML格式错误XML格式错误请检查XML参数格式是否正确
          FREQUENCY_LIMITED频率限制2个月之前的订单申请退款有频率限制该笔退款未受理,请降低频率后重试
          NOAUTH异常IP请求不予受理请求ip异常如果是动态ip,请登录商户平台后台关闭ip安全配置;
          如果是静态ip,请确认商户平台配置的请求ip 在不在配的ip列表里


          CloudPay.queryRefund()

          支持端:云函数 2.0.2

          查询退款

          说明

          提交退款申请后,通过调用该接口查询退款状态。退款有一定延时,用零钱支付的退款20分钟内到账,银行卡支付的退款3个工作日后重新查询退款状态。 注意:如果单个支付订单部分退款次数超过20次请使用退款单号查询* 分页查询*

          当一个订单部分退款超过10笔后,商户用微信订单号或商户订单号调退款查询API查询退款时,默认返回前10笔和total_refund_count(退款单总笔数)。商户需要查询同一订单下超过10笔的退款单时,可传入订单号及offset来查询,微信支付会返回offset及后面的10笔,以此类推。当商户传入的offset超过total_refund_count,则系统会返回报错PARAM_ERROR。

          举例:

          一笔订单下的退款单有36笔,当商户想查询第25笔时,可传入订单号及offset=24,微信支付平台会返回第25笔到第35笔的退款单信息,或商户可直接传入退款单号查询退款

          参数说明

          字段名变量名必填类型示例值描述
          子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
          随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
          微信订单号transaction_id四选一String(28)1217752501201407033233368018微信订单号查询的优先级是: refund_id > out_refund_no > transaction_id > out_trade_no
          商户订单号out_trade_no四选一String(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
          商户退款单号out_refund_no四选一String(64)1217752501201407033233368018商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-
          微信退款单号refund_id四选一String(32)1217752501201407033233368018微信退款单号
          偏移量offsetInt15偏移量,当部分退款次数超过10次时可使用,表示返回的查询结果从这个偏移量开始取记录

          refund_id、out_refund_no、out_trade_no、transaction_id四个参数必填一个,如果同时存在优先级为: refund_id>out_refund_no>transaction_id>out_trade_no

          返回值说明

          字段名变量名必填类型示例值描述
          返回状态码returnCodeString(16)SUCCESSSUCCESS/FAIL
          返回信息returnMsgString(128)签名失败返回信息,如非空,为错误原因。如 签名失败、参数格式校验错误

          以下字段在returnCode为SUCCESS的时候有返回

          字段名变量名必填类型示例值描述
          业务结果result_codeString(16)SUCCESSSUCCESS/FAIL
          SUCCESS退款申请接收成功,结果通过退款查询接口查询
          错误码err_codeString(32)SYSTEMERROR错误码详见第6节
          错误描述err_code_desString(128)系统错误结果信息描述
          服务商的APPIDappidString(32)wxd678efh567hg6787服务商商户的APPID
          商户号mch_idString(32)1230000109微信支付分配的商户号
          小程序的APPIDsub_appidString(32)wx8888888888888888微信分配的小程序ID
          子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
          随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位
          签名signString(32)C380BEC2BFD727A4B6845133519F3AD6签名,详见签名算法
          微信订单号transaction_idString(32)1217752501201407033233368018微信订单号
          商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
          订单金额total_feeInt100订单总金额,单位为分,只能为整数,详见支付金额
          应结订单金额settlement_total_feeInt100当订单使用了免充值型优惠券后返回该参数,应结订单金额=订单金额-免充值优惠券金额。
          货币种类fee_typeString(8)CNY订单金额货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
          现金支付金额cash_feeInt100现金支付金额,单位为分,只能为整数,详见支付金额
          退款笔数refund_countInt1当前返回退款笔数
          商户退款单号out_refund_no_$nString(64)1217752501201407033233368018商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-
          微信退款单号refund_id_$nString(32)1217752501201407033233368018微信退款单号
          退款渠道refund_channel_$nString(16)ORIGINALORIGINAL—原路退款
          BALANCE—退回到余额
          OTHER_BALANCE—原账户异常退到其他余额账户
          OTHER_BANKCARD—原银行卡异常退到其他银行卡
          订单总退款次数total_refund_countInt35订单总共已发生的部分退款次数,当请求参数传入offset后有返回
          申请退款金额refund_fee_$nInt100退款总金额,单位为分,可以做部分退款
          退款金额settlement_refund_fee_$nInt100退款金额=申请退款金额-非充值代金券退款金额,退款金额<=申请退款金额
          代金券类型coupon_type_$n_$mString(8)CASHCASH--充值代金券
          NO_CASH---非充值代金券
          订单使用代金券时有返回(取值:CASH、NO_CASH)。$n为下标,$m为下标,从0开始编号,举例:coupon_type_$0_$1
          总代金券退款金额coupon_refund_fee_$nInt100代金券退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为现金,说明详见代金券或立减优惠
          退款代金券使用数量coupon_refund_count_$nInt1退款代金券使用数量 ,$n为下标,从0开始编号
          退款代金券IDcoupon_refund_id_$n_$mString(20)10000退款代金券ID, $n为下标,$m为下标,从0开始编号
          单个代金券退款金额coupon_refund_fee_$n_$mInt100单个退款代金券支付金额, $n为下标,$m为下标,从0开始编号
          退款状态refund_status_$nString(16)SUCCESS退款状态:SUCCESS—退款成功
          REFUNDCLOSE—退款关闭。
          PROCESSING—退款处理中
          CHANGE—退款异常,退款到银行发现用户的卡作废或者冻结了,导致原路退款银行卡失败,可前往商户平台(pay.weixin.qq.com)-交易中心,手动处理此笔退款。$n为下标,从0开始编号。
          退款资金来源refund_account_$nString(30)REFUND_SOURCE_RECHARGE_FUNDSREFUND_SOURCE_RECHARGE_FUNDS---可用余额退款/基本账户
          REFUND_SOURCE_UNSETTLED_FUNDS---未结算资金退款
          $n为下标,从0开始编号。
          退款入账账户refund_recv_accout_$nString(64)招商银行信用卡0403取当前退款单的退款入账方
          1)退回银行卡:
          {银行名称}{卡类型}{卡尾号}
          2)退回支付用户零钱:
          支付用户零钱

          3)退还商户:
          商户基本账户
          商户结算银行账户
          4)退回支付用户零钱通:
          支付用户零钱通
          退款成功时间refund_success_time_$nString(20)2016-07-25 15:26:26退款成功时间,当退款状态为退款成功时有返回。$n为下标,从0开始编号。

          错误码

          名称描述原因解决方案
          SYSTEMERROR接口返回错误系统超时请尝试再次掉调用API。
          REFUNDNOTEXIST退款订单查询失败订单号错误或订单状态不正确请检查订单号是否有误以及订单状态是否正确,如:未支付、已支付未退款
          INVALID_TRANSACTIONID无效transaction_id请求参数未按指引进行填写请求参数错误,检查原交易号是否存在或发起支付交易接口返回失败
          PARAM_ERROR参数错误请求参数未按指引进行填写请求参数错误,请检查参数再调用退款申请
          APPID_NOT_EXISTAPPID不存在参数中缺少APPID请检查APPID是否正确
          MCHID_NOT_EXISTMCHID不存在参数中缺少MCHID请检查MCHID是否正确
          REQUIRE_POST_METHOD请使用post方法未使用post传递参数请检查请求参数是否通过post方法提交
          SIGNERROR签名错误参数签名结果不正确请检查签名参数和方法是否都符合签名算法要求
          XML_FORMAT_ERRORXML格式错误XML格式错误请检查XML参数格式是否正确


          CloudPay.downloadBill()

          支持端:云函数 2.0.2

          下载对账单

          说明

          商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和微信侧数据不一致,通过对账单核对后可校正支付状态。

          注意:

          1、微信侧未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中,跟原支付单订单号一致;

          2、微信在次日9点启动生成前一天的对账单,建议商户10点后再获取;

          3、对账单中涉及金额的字段单位为“元”。

          4、对账单接口只能下载三个月以内的账单。

          5、对账单是以商户号纬度来生成的,如一个商户号与多个appid有绑定关系,则使用其中任何一个appid都可以请求下载对账单。对账单中的appid取自交易时候提交的appid,与请求下载对账单时使用的appid无关。

          6、小微商户不单独提供对账单下载,如有需要,可在调取【下载对账单】API接口时不传sub_mch_id,获取服务商下全量特约商户(包括小微商户和非小微商户)的对账单。

          参数说明

          字段名变量名必填类型示例值描述
          子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号,如需下载指定的子商户号对账单,则此参数必传。
          随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
          签名signString(32)C380BEC2BFD727A4B6845133519F3AD6签名,详见签名生成算法
          对账单日期bill_dateString(8)20140603下载对账单的日期,格式:20140603
          账单类型bill_typeString(8)ALLALL,返回当日所有订单信息,默认值
          SUCCESS,返回当日成功支付的订单
          REFUND,返回当日退款订单
          压缩账单tar_typeStringGZIP非必传参数,固定值:GZIP,返回格式为.gzip的压缩包账单。不传则默认为数据流形式。

          返回值说明

          失败时,返回以下字段

          字段名变量名必填类型示例值描述
          返回状态码returnCodeString(16)FAILFAIL
          错误码描述returnMsgString(128)签名失败返回信息,如非空,为错误原因,如:签名失败 等。
          错误码errorCodeString(16)20002失败错误码,详见错误码列表

          成功时,数据以文本表格的方式返回,第一行为表头,后面各行为对应的字段内容,字段内容跟查询订单或退款结果一致,具体字段说明可查阅相应接口。

          第一行为表头,根据请求下载的对账单类型不同而不同(由bill_type决定),目前有: 当日所有订单* 交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率 当日成功支付的订单* 交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,商品名称,商户数据包,手续费,费率 当日退款的订单* 交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,退款申请时间,退款成功时间,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率

          从第二行起,为数据记录,各参数以逗号分隔,参数前增加`符号,为标准键盘1左边键的字符,字段顺序与表头一致。

          倒数第二行为订单统计标题,最后一行为统计数据

          总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额

          举例如下:

          交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率 2014-11-10 16:33:45,wx2421b1c4370ec43b,10000100,0,1000,1001690740201411100005734289,1415640626,085e9858e3ba5186aafcbaed1,MICROPAY,SUCCESS,OTHERS,CNY,0.01,0.0,0,0,0,0,,,被扫支付测试,订单额外描述,0,0.60% 2014-11-10 16:46:14,wx2421b1c4370ec43b,10000100,0,1000,1002780740201411100005729794,1415635270,085e9858e90ca40c0b5aee463,MICROPAY,SUCCESS,OTHERS,CNY,0.01,0.0,0,0,0,0,,,被扫支付测试,订单额外描述,0,0.60% 总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额 2,0.02,0.0,0.0,`0 结算对账单*

          普通结算对账单

          字段名称示例值字段说明
          交易时间2017-12-14 15:49:06指该笔交易的支付成功时间或发起退款成功时间(注:不是退款成功时间),格式为YYYY-MM-DD HH:MM:SS,如2015-01-01 10:00:00
          公众账号IDwxab8acb865bb11234发起该笔交易时使用的appid,appid是由微信平台给公众号或app分配的唯一标识、用于区分交易场景
          商户号1234567890发起该笔交易的微信支付商户号,8~10位数字
          子商户号0如果是普通受理模式下的交易,展示特约商户的商户号,8~10位数字
          如果是直连模式交易,则展示成数字0
          设备号8888该笔交易下单时在device_info字段中传入的信息,没填写则留空
          微信订单号4200000008201712143733500001微信支付为该笔订单(或该笔退款对应的订单)分配的订单号
          商户订单号test1商户传入的该笔订单(或该笔退款对应的订单)的商户订单号,对应下单接口里的out_trade_no字段
          用户标识testxt08c-XB5-QD208X1Aid0Cbs微信平台为支付用户在公众账号(appid)下分配的唯一标识(openid)
          交易类型NATIVE该笔订单(或该笔退款单对应的订单)的交易类型,使用英文缩写展示,取值和含义: 值:
          JSAPI-JSAPI支付(或小程序支付)
          NATIVE-Native支付
          APP-app支付
          MWEB-H5支付
          MICROPAY-付款码支付
          PAP-委托代扣
          交易状态SUCCESSSUCCESS—支付成功,说明该行数据为一笔支付成功的订单
          REFUND—转入退款,说明该行数据为一笔发起退款成功的退款单
          REVOKED—已撤销,说明该行数据为一笔成功撤销的撤销单
          付款银行OTHERS银行类型,采用字符串类型的银行标识,如CMC_CREDIT,完整说明见https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=4_2
          货币种类CNY货币类型,符合ISO 4217标准的三位字母代码,如CNY
          总金额0.01该笔订单的应结算金额(=订单金额-用户使用的免充值券金额),如果该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位
          代金券或立减优惠金额0.00该笔订单中使用的微信支付代金券金额(包括充值券和免充值券),如果未使用代金券、或该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位
          微信退款单号0微信支付为该笔退款分配的退款单号,如果该行数据为订单则展示0
          商户退款单号0商户发起退款时填入的商户退款单号,如果该行数据为订单则展示0
          退款金额0.00该笔退款或撤销单的应结算金额(申请退款金额-免充值券退款金额),如果该行数据为订单则展示为0.00,非负数、单位元,保留到小数点后2位
          代金券或立减优惠退款金额0.00退款金额中包含的充值券退款金额,如果该行数据为订单或没有充值券退款则展示为0.00,非负数、单位元,保留到小数点后2位
          退款类型ORIGINAL—原路退款
          BALANCE—转退到用户的微信支付零钱
          如果该行数据为订单,则留空
          退款状态生成账单文件时该笔退款的状态、后续不会更新,如果该行数据为订单,则留空
          SUCCES—退款成功
          FAIL—退款失败M
          PROCESSING—退款处理中
          商品名称中文[body]商户传入的该笔订单(或该笔退款对应的订单)的商品名称,对应下单接口里的body字段
          商户数据包测试中文[attach]商户传入的该笔订单(或该笔退款对应的订单)的商户数据包,对应下单接口里的attach字段,不传时留空
          手续费0.00000该笔订单/退款对应的手续费金额,订单对应正数、退款对应负数,单位元,保留小数点后2位
          费率0.00%该笔交易计费所使用的费率,百分数,如0.60%

          开通免充值券后的结算对账单

          字段名称示例值字段说明
          交易时间2017-12-14 15:49:06指该笔交易的支付成功时间或发起退款成功时间(注:不是退款成功时间),格式为YYYY-MM-DD HH:MM:SS,如2015-01-01 10:00:00
          公众账号IDwxab8acb865bb11234发起该笔交易时使用的appid,appid是由微信平台给公众号或app分配的唯一标识、用于区分交易场景
          商户号1234567890发起该笔交易的微信支付商户号,8~10位数字
          特约商户号0如果是普通受理模式下的交易,展示特约商户的商户号,8~10位数字
          如果是直连模式交易,则展示成数字0
          设备号8888该笔交易下单时在device_info字段中传入的信息,没填写则留空
          微信订单号4200000008201712143733500001微信支付为该笔订单(或该笔退款对应的订单)分配的订单号
          商户订单号test1商户传入的该笔订单(或该笔退款对应的订单)的商户订单号,对应下单接口里的out_trade_no字段
          用户标识testxt08c-XB5-QD208X1Aid0Cbs微信平台为支付用户在公众账号(appid)下分配的唯一标识(openid)
          交易类型NATIVE该笔订单(或该笔退款单对应的订单)的交易类型,使用英文缩写展示,取值和含义: 值:
          JSAPI-JSAPI支付(或小程序支付)
          NATIVE-Native支付
          APP-app支付
          MWEB-H5支付
          MICROPAY-付款码支付
          PAP-委托代扣
          交易状态SUCCESSSUCCESS—支付成功,说明该行数据为一笔支付成功的订单
          REFUND—转入退款,说明该行数据为一笔发起退款成功的退款单
          REVOKED—已撤销,说明该行数据为一笔成功撤销的撤销单
          付款银行OTHERS银行类型,采用字符串类型的银行标识,如CMC_CREDIT,完整说明见https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=4_2
          货币种类CNY货币类型,符合ISO 4217标准的三位字母代码,如CNY
          应结订单金额0.01该笔订单的应结算金额(=订单金额-用户使用的免充值券金额),如果该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位
          代金券金额0.00该笔订单中使用的微信支付代金券金额(包括充值券和免充值券),如果未使用代金券、或该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位
          微信退款单号0微信支付为该笔退款分配的退款单号,如果该行数据为订单则展示0
          商户退款单号0商户发起退款时填入的商户退款单号,如果该行数据为订单则展示0
          退款金额0.00该笔退款或撤销单的应结算金额(申请退款金额-免充值券退款金额),如果该行数据为订单则展示为0.00,非负数、单位元,保留到小数点后2位
          充值券退款金额0.00退款金额中包含的充值券退款金额,如果该行数据为订单或没有充值券退款则展示为0.00,非负数、单位元,保留到小数点后2位
          退款类型ORIGINAL—原路退款
          BALANCE—转退到用户的微信支付零钱
          如果该行数据为订单,则留空
          退款状态生成账单文件时该笔退款的状态、后续不会更新,如果该行数据为订单,则留空
          SUCCES—退款成功
          FAIL—退款失败M
          PROCESSING—退款处理中
          商品名称中文[body]商户传入的该笔订单(或该笔退款对应的订单)的商品名称,对应下单接口里的body字段
          商户数据包测试中文[attach]商户传入的该笔订单(或该笔退款对应的订单)的商户数据包,对应下单接口里的attach字段,不传时留空
          手续费0.00000该笔订单/退款对应的手续费金额,订单对应正数、退款对应负数,单位元,保留小数点后2位
          费率0.00%该笔交易计费所使用的费率,百分数,如0.60%
          订单金额0.01该笔订单的金额,包括用户支付金额、充值券金额、免充值券金额,如果该行数据为退款或撤销则填0.00,单位元,保留到小数点后2位
          申请退款金额0.00商户发起退款的金额,包括退给用户的金额、充值券退款金额、免充值券退款金额,如果该行数据订单则填0.00,单位元,保留到小数点后2位
          费率备注如果有特殊费率规则时则加以说明,默认留空

          错误码

          错误码名称描述原因解决方案
          20003SYSTEMERROR下载失败系统超时请尝试再次查询。
          20001sign error签名错误请求参数未按要求进行填写签名错误,请重新检查参数和签名密钥是否正确
          20001nonce_str too long参数nonce_str错误请求参数未按要求填写参数nonce_str长度超长
          20001invalid tar_type, Only GZIP supported参数tar_type错误请求参数未按指引进行填写请重新检查参数invalid tar_typ是否正确
          20001invalid bill_type参数bill_type错误请求参数未按指引进行填写请重新检查参数bill_type是否正确
          20001invalid bill_date参数bill_date错误请求参数未按指引进行填写请重新检查参数bill_date是否符合要求
          20001require POST method请求方式错误请求方式不符合要求请求检查参数请求方式是否为post
          20001empty post data请求报文错误请求报文为空请重新检查请求报文是否正确
          20001data format error参数格式错误请求参数要求为xml格式请重新检查请求参数格式是否为xml
          20001missing parameter缺少参数有必传的参数未上传请重新检查是否所有必传参数都上传了,且不为空
          20001invalid appidappid错误请求参数appid有误请重新检查参数appid是否正确
          20001invalid parameter参数错误有未知的请求参数请重新检查是否所有参数都与文档相符
          20001sub_mch not allow特约商户号权限错误无该特约商户账单的下载权限请检查特约商户号是否正确。若是小微商户,可不传sub_mch_id以获取服务商下全量特约商户的账单
          20002NO Bill Exist账单不存在当前商户号没有已成交的订单,不生成对账单请检查当前商户号在指定日期内是否有成功的交易。
          20002Bill Creating账单未生成当前商户号没有已成交的订单或对账单尚未生成请先检查当前商户号在指定日期内是否有成功的交易,如指定日期有交易则表示账单正在生成中,请在上午10点以后再下载。
          20007当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭,请联系微信支付解决
          20100system error下载失败系统超时请尝试再次查询。


          Cloud.database(options: Object): Database

          支持端:小程序 , 云函数 , Web

          获取数据库实例

          参数

          options: Object

          属性类型默认值必填说明
          envstring环境 ID,若不填则采用 init 中的值
          throwOnNotFoundboolean在调用获取记录(doc.get)时,如果获取不到,是否抛出异常,如果不抛出异常,doc.get 返回空。默认 true。云函数 wx-server-sdk 1.7.0 开始支持。

          返回值

          Database

          小程序端示例

          以下调用获取默认环境的数据库的引用:

          const db = wx.cloud.database()

          假设有一个环境名为 test-123,用做测试环境,那么可以如下获取测试环境数据库:

          const testDB = wx.cloud.database({  env: 'test-123'})

          云函数端示例

          env 设置示例*

          以下调用获取和云函数当前所在环境相同的数据库的引用:

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()

          假设有一个环境名为 test,用做测试环境,那么可以如下获取测试环境数据库:

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const testDB = cloud.database({  env: 'test'})

          也可以通过 init 传入默认环境的方式使得获取数据库时默认是默认环境数据库:

          const cloud = require('wx-server-sdk')cloud.init({  env: 'test'})const testDB = cloud.database()

          throwOnNotFound 设置示例*

          以下设置将 doc.get 的行为改为:如果获取不到记录,不抛出异常,而是返回空。

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV,  throwOnNotFound: false})const testDB = cloud.database()


          Database

          云开发 SDK 数据库实例

          属性

          Command command

          数据库操作符

          Geo Geo

          数据库地理位置结构

          方法

          Database.collection(name: string): Collection

          获取集合的引用。方法接受一个 name 参数,指定需引用的集合名称。

          Database.createCollection(collectionName: string): Promise<Object>

          创建集合,如果集合已经存在会创建失败

          Database.serverDate(options: Object): ServerDate

          构造一个服务端时间的引用。可用于查询条件、更新字段值或新增记录时的字段值。

          Database.runTransaction(callback: function, times: number): Promise<any>

          发起事务。仅可在云函数中使用。

          Database.startTransaction(): Promise<Transaction>

          开始事务,另一个同样可以使用的发起事务的 API 是 runTransaction。仅可在云函数中使用。

          小程序端示例

          以下调用获取默认环境的数据库的引用:

          const db = wx.cloud.database()

          假设有一个环境名为 test-123,用做测试环境,那么可以如下获取测试环境数据库:

          const testDB = wx.cloud.database({  env: 'test-123'})

          云函数端示例

          以下调用获取和云函数当前所在环境相同的数据库的引用:

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()

          假设有一个环境名为 test,用做测试环境,那么可以如下获取测试环境数据库:

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const testDB = cloud.database({  env: 'test'})

          也可以通过 init 传入默认环境的方式使得获取数据库时默认是默认环境数据库:

          const cloud = require('wx-server-sdk')cloud.init({  env: 'test'})const testDB = cloud.database()


          Database.collection(name: string): Collection

          支持端:小程序 , 云函数 , Web

          获取集合的引用。方法接受一个 name 参数,指定需引用的集合名称。

          参数

          name: string

          集合名称

          返回值

          Collection

          示例代码:小程序端

          const db = wx.cloud.database()const todosCollection = db.collection('todos')

          示例代码:云函数端

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()const todosCollection = db.collection('todos')


          Command

          数据库操作符,通过 db.command 获取

          属性

          AggregateCommand aggregate

          聚合操作符

          方法

          Command.addToSet(value: any|Object): Command

          数组更新操作符。原子操作。给定一个或多个元素,除非数组中已存在该元素,否则添加进数组。

          Command.all(values: any[]): Command

          数组查询操作符。用于数组字段的查询筛选条件,要求数组字段中包含给定数组的所有元素。

          Command.and(expressions: any[]): Command

          查询操作符,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

          Command.bit(object: Object): Command

          更新操作符。对字段进行位运算,可以进行 and/or/xor 运算。

          Command.elemMatch(condition: Object|Command): Command

          用于数组字段的查询筛选条件,要求数组中包含至少一个满足 elemMatch 给定的所有条件的元素

          Command.eq(value: any): Command

          查询筛选条件,表示字段等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

          Command.exists(value: boolean): Command

          判断字段是否存在

          Command.expr(aggregateExpression: Expression):  Command

          查询操作符,用于在查询语句中使用聚合表达式,方法接收一个参数,该参数必须为聚合表达式

          Command.geoIntersects(options: Object): Command

          找出给定的地理位置图形相交的记录

          Command.geoNear(options: Object): Command

          按从近到远的顺序,找出字段值在给定点的附近的记录。

          Command.geoWithin(options: Object): Command

          找出字段值在指定区域内的记录,无排序。指定的区域必须是多边形(Polygon)或多边形集合(MultiPolygon)。

          Command.gt(value: any): Command

          查询筛选操作符,表示需大于指定值。可以传入 Date 对象用于进行日期比较。

          Command.gte(value: any): Command

          查询筛选操作符,表示需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

          Command.in(value: any[]): Command

          查询筛选操作符,表示要求值在给定的数组内。

          Command.inc(value: number): Command

          更新操作符,原子操作,用于指示字段自增

          Command.lt(value: any): Command

          查询筛选操作符,表示需小于指定值。可以传入 Date 对象用于进行日期比较。

          Command.lte(value: any): Command

          查询筛选操作符,表示需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

          Command.max(value: any): Command

          更新操作符,给定一个值,只有该值大于字段当前值才进行更新。

          Command.min(value: any): Command

          更新操作符,给定一个值,只有该值小于字段当前值才进行更新。

          Command.mod(divisor: number, remainder: number): Command

          查询筛选操作符,给定除数 divisor 和余数 remainder,要求字段作为被除数时 value % divisor = remainder。

          Command.mul(value: number): Command

          更新操作符,原子操作,用于指示字段自乘某个值

          Command.neq(value: any): Command

          查询筛选条件,表示字段不等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

          Command.nin(value: any[]): Command

          查询筛选操作符,表示要求值不在给定的数组内。

          Command.nor(expressions: any[]): Command

          查询操作符,用于表示逻辑 "都不" 的关系,表示需不满足指定的所有条件。如果记录中没有对应的字段,则默认满足条件。

          Command.not(command: Command): Command

          查询操作符,用于表示逻辑 "非" 的关系,表示需不满足指定的条件。

          Command.or(expressions: any[]): Command

          查询操作符,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

          Command.pop(): Command

          数组更新操作符,对一个值为数组的字段,将数组尾部元素删除

          Command.pull(value: any): Command

          数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值或查询条件的元素都移除掉。

          Command.pullAll(value: any): Command

          数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值的元素都移除掉。跟 pull 的差别在于只能指定常量值、传入的是数组。

          Command.push(values: Object): Command

          数组更新操作符。对一个值为数组的字段,往数组添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

          Command.remove()Command

          更新操作符,用于表示删除某个字段。

          Command.rename(value: string): Command

          更新操作符,字段重命名。如果需要对嵌套深层的字段做重命名,需要用点路径表示法。不能对嵌套在数组里的对象的字段进行重命名。

          Command.set(value: any): Command

          更新操作符,用于设定字段等于指定值。

          Command.shift(): Command

          数组更新操作符,对一个值为数组的字段,将数组头部元素删除。

          Command.size(value: string): Command

          更新操作符,用于数组字段的查询筛选条件,要求数组长度为给定值

          Command.unshift(values: any[]): Command

          数组更新操作符,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。


          Geo

          数据库地理位置结构集

          方法

          Geo.LineString(points: GeoPoint[]): GeoPoint

          构造一个地理位置的 ”线“。一个线由两个或更多的点有序连接组成。

          Geo.MultiLineString(lineStrings: GeoLineString[]): GeoMultiLineString

          构造一个地理位置 ”线“ 集合。一个线集合由多条线组成。

          Geo.MultiPoint(points: GeoPoint[]): GeoMultiPoint

          构造一个地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

          Geo.MultiPolygon(polygons: GeoPolygon[]): GeoMultiPolygon

          构造一个地理位置 ”多边形“ 集合。一个多边形集合由多个多边形组成。

          Geo.Point(longitude: number, latitude: number): GeoPoint

          构造一个地理位置 ”点“。方法接受两个必填参数,第一个是经度(longitude),第二个是纬度(latitude),务必注意顺序。

          Geo.Polygon(lineStrings: GeoLineString[]): GeoPolygon

          构造一个地理位置 ”多边形“


          Database.serverDate(options:Object): ServerDate

          支持端:小程序 , 云函数 , Web

          构造一个服务端时间的引用。可用于查询条件、更新字段值或新增记录时的字段值。

          参数

          options: Object

          属性类型默认值必填说明
          offsetnubmer引用的服务端时间偏移量,毫秒为单位,可以是正数或负数

          返回值

          ServerDate

          示例代码

          新增记录时设置字段为服务端时间:

          db.collection('todos').add({  description: 'eat an apple',  createTime: db.serverDate()})

          更新字段为服务端时间往后一小时:

          db.collection('todos').doc('my-todo-id').update({  due: db.serverDate({    offset: 60 * 60 * 1000  })})


          Database.RegExp

          构造正则表达式,仅需在普通 js 正则表达式无法满足的情况下使用

          options 参数说明

          options 支持 i, m, s 这三个 flag,注意 JavaScript 原生正则对象构造时仅支持其中的 i, m 两个 flag,因此需要使用到 s 这个 flag 时必须使用 db.RegExp 构造器构造正则对象。flag 的含义见下表:

          flag说明
          i大小写不敏感
          m跨行匹配;让开始匹配符 ^ 或结束匹配符 $ 时除了匹配字符串的开头和结尾外,还匹配行的开头和结尾
          s让 . 可以匹配包括换行符在内的所有字符

          基础用法示例

          // 原生 JavaScript 对象db.collection('todos').where({  description: /miniprogram/i})// 数据库正则对象db.collection('todos').where({  description: db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})// 用 new 构造也是可以的db.collection('todos').where({  description: new db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})


          Database.createCollection(collectionName: string): Promise<Object>

          支持端:云函数

          创建集合,如果集合已经存在会创建失败

          参数

          collectionName: string

          返回值

          Promise.<Object>

          属性类型说明
          errMsgstring

          示例

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  return await db.createCollection('todos')}


          Database.runTransaction(callback: function, times: number): Promise<any>

          支持端:云函数

          发起事务。仅可在云函数中使用。

          参数

          callback: function

          事务执行函数,需为 async 异步函数或返回 Promise 的函数

          times: number

          事务执行最多次数,默认 3 次,成功后不重复执行,只有事务冲突时会重试,其他异常时不会重试

          返回值

          Promise.<any>

          resolve 的结果为 callback 事务执行函数的返回值,reject 的结果为事务执行过程中抛出的异常或者是 transaction.rollback 传入的值

          事务执行函数说明

          事务执行函数由开发者传入,函数接收一个参数 transaction(类型定义见 Transaction),其上提供 collection 方法和 rollback 方法。collection 方法用于取数据库集合记录引用进行操作,rollback 方法用于在不想继续执行事务时终止并回滚事务。

          事务执行函数必须为 async 异步函数或返回 Promise 的函数,当事务执行函数返回时,SDK 会认为用户逻辑已完成,自动提交(commit)事务,因此务必确保用户事务逻辑完成后才在 async 异步函数中返回或 resolve Promise。

          事务执行函数可能会被执行多次,在内部发现事务冲突时会自动重复执行,如果超过设定的执行次数上限,会报错退出。

          在事务执行函数中发生的错误,都会认为事务执行失败而抛错。

          事务执行函数返回的值会作为 runTransaction 返回的 Promise resolve 的值,在函数中抛出的异常会作为 runTransaction 返回的 Promise reject 的值,如果事务执行函数中调用了 transaction.rollback,则传入 rollback 函数的值会作为 runTransaction 返回的 Promise reject 的值。

          限制

          事务现仅支持在云函数 wx-server-sdk 使用。事务操作时为保障效率和并发性,只允许进行单记录操作,不允许进行批量操作,但可以在一个事务中对多个记录进行操作。

          注意事项

          开发者提供的事务执行函数正常返回时,SDK 会自动提交(commit)事务,请勿在事务执行函数内调用 transaction.commit 方法,该方法仅在通过 db.startTransaction 进行事务操作时使用。

          示例代码

          两个账户之间进行转账的简易示例

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database({  throwOnNotFound: false,})const _ = db.commandexports.main = async (event) => {  try {    const result = await db.runTransaction(async transaction => {      const aaaRes = await transaction.collection('account').doc('aaa').get()      const bbbRes = await transaction.collection('account').doc('bbb').get()      if (aaaRes.data && bbbRes.data) {        const updateAAARes = await transaction.collection('account').doc('aaa').update({          data: {            amount: _.inc(-10)          }        })        const updateBBBRes = await transaction.collection('account').doc('bbb').update({          data: {            amount: _.inc(10)          }        })        console.log(`transaction succeeded`)        // 会作为 runTransaction resolve 的结果返回        return {          aaaAccount: aaaRes.data.amount - 10,        }      } else {        // 会作为 runTransaction reject 的结果出去        await transaction.rollback(-100)      }    })    return {      success: true,      aaaAccount: result.aaaAccount,    }  } catch (e) {    console.error(`transaction error`, e)    return {      success: false,      error: e    }  }}


          Database.startTransaction():Promise<Transaction>

          支持端:云函数

          开始事务,另一个同样可以使用的发起事务的 API 是 runTransaction。仅可在云函数中使用。

          返回值

          Promise.<Transaction>

          resolve 的结果为事务操作对象,其上可通过 collection API 操作数据库,通过 commit 或 rollback 来结束或终止事务。

          限制

          事务现仅支持在云函数 wx-server-sdk 使用。事务操作时为保障效率和并发性,只允许进行单记录操作,不允许进行批量操作,但可以在一个事务中对多个记录进行操作。

          示例代码

          两个账户之间进行转账的简易示例

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database({  throwOnNotFound: false,})const _ = db.commandexports.main = async (event) => {  try {    const transaction = await db.startTransaction()    const aaaRes = await transaction.collection('account').doc('aaa').get()    const bbbRes = await transaction.collection('account').doc('bbb').get()    if (aaaRes.data && bbbRes.data) {      const updateAAARes = await transaction.collection('account').doc('aaa').update({        data: {          amount: _.inc(-10)        }      })      const updateBBBRes = await transaction.collection('account').doc('bbb').update({        data: {          amount: _.inc(10)        }      })      await transaction.commit()      console.log(`transaction succeeded`)      return {        success: true,        aaaAccount: aaaRes.data.amount - 10,      }    } else {      await transaction.rollback()      return {        success: false,        error: `rollback`,        rollbackCode: -100,      }    }  } catch (e) {    console.error(`transaction error`, e)    return {      success: false,      error: e    }  }}



          Collection

          数据库集合引用

          方法

          Collection.doc(id: string): Document

          获取集合中指定记录的引用。方法接受一个 id 参数,指定需引用的记录的 _id。

          Collection.add(options: Object): Promise<Object>

          新增记录,如果传入的记录对象没有 _id 字段,则由后台自动生成 _id;若指定了 _id,则不能与已有记录冲突

          Collection.aggregate(): Aggregate

          发起聚合操作,定义完聚合流水线阶段之后需调用 end 方法标志结束定义并实际发起聚合操作

          Collection.count(): Promise<Object>

          统计匹配查询条件的记录的条数

          Collection.field(projection: Object): Collection

          指定返回结果中记录需返回的字段

          Collection.get(): Promise<Object>

          获取集合数据,或获取根据查询条件筛选后的集合数据。

          Collection.limit(value: number): Collection

          指定查询结果集数量上限

          Collection.orderBy(fieldPath: string, string: order): Collection

          指定查询排序条件

          Collection.remove(): Promise<Object>

          删除多条记录。注意只支持通过匹配 where 语句来删除,不支持 skip 和 limit。

          Collection.skip(offset: number): Collection

          指定查询返回结果时从指定序列后的结果开始返回,常用于分页

          Collection.update(): Promise<Object>

          更新多条记录

          Collection.watch(options: Object): Object

          监听集合中符合查询条件的数据的更新事件。使用 watch 时,支持 where, orderBy, limit,不支持 field。

          Collection.where(condition: Object): Collection

          指定查询条件,返回带新查询条件的新的集合引用


          Collection.doc(id: string): Document

          支持端:小程序 , 云函数 , Web

          获取集合中指定记录的引用。方法接受一个 id 参数,指定需引用的记录的 _id。

          参数

          id: string

          记录 _id

          返回值

          Document

          示例代码

          const myTodo = db.collection('todos').doc('my-todo-id')


          Collection.aggregate(): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          发起聚合操作,定义完聚合流水线阶段之后需调用 end 方法标志结束定义并实际发起聚合操作

          返回值

          Aggregate

          示例代码

          const $ = db.command.aggregatedb.collection('books').aggregate()  .group({    // 按 category 字段分组    _id: '$category',    // 让输出的每组记录有一个 avgSales 字段,其值是组内所有记录的 sales 字段的平均值    avgSales: $.avg('$sales')  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

          小程序端兼容支持 callback 风格

          const $ = db.command.aggregatedb.collection('books').aggregate()  .group({    // 按 category 字段分组    _id: '$category',    // 让输出的每组记录有一个 avgSales 字段,其值是组内所有记录的 sales 字段的平均值    avgSales: $.avg('$sales')  })  .end({    success: function(res) {      console.log(res)    },    fail: function(err) {      console.error(err)    }  })


          Collection.where(condition: Object): Collection

          支持端:小程序 , 云函数 , Web

          指定查询条件,返回带新查询条件的新的集合引用

          参数

          condition: Object

          查询条件

          返回值

          Collection

          示例代码

          const _ = db.commandconst result = await db.collection('todos').where({  price: _.lt(100)}).get()


          Collection.limit(value: number): Collection

          支持端:小程序 , 云函数 , Web

          指定查询结果集数量上限

          参数

          value: number

          返回值

          Collection

          说明

          limit 在小程序端默认及最大上限为 20,在云函数端默认及最大上限为 1000

          示例代码

          db.collection('todos').limit(10)  .get()  .then(console.log)  .catch(console.error)

          Collection.orderBy(fieldPath: string, string: order): Collection

          支持端:小程序 , 云函数 , Web

          指定查询排序条件

          参数

          fieldPath: string

          string: order

          返回值

          Collection

          说明

          方法接受一个必填字符串参数 fieldName 用于定义需要排序的字段,一个字符串参数 order 定义排序顺序。order 只能取 asc 或 desc。

          如果需要对嵌套字段排序,需要用 "点表示法" 连接嵌套字段,比如 style.color 表示字段 style 里的嵌套字段 color。

          同时也支持按多个字段排序,多次调用 orderBy 即可,多字段排序时的顺序会按照 orderBy 调用顺序先后对多个字段排序

          示例代码:按一个字段排序

          按进度排升序取待办事项

          db.collection('todos').orderBy('progress', 'asc')  .get()  .then(console.log)  .catch(console.error)

          示例代码:按多个字段排序

          先按 progress 排降序(progress 越大越靠前)、再按 description 排升序(字母序越前越靠前)取待办事项:

          db.collection('todos')  .orderBy('progress', 'desc')  .orderBy('description', 'asc')  .get()  .then(console.log)  .catch(console.error)

          Collection.skip(offset: number): Collection

          支持端:小程序 , 云函数 , Web

          指定查询返回结果时从指定序列后的结果开始返回,常用于分页

          参数

          offset: number

          返回值

          Collection

          示例代码

          db.collection('todos').skip(10)  .get()  .then(console.log)  .catch(console.error)

          Collection.field(projection: Object): Collection

          支持端:小程序 , 云函数 , Web

          指定返回结果中记录需返回的字段

          参数

          projection: Object

          返回值

          Collection

          说明

          方法接受一个必填对象用于指定需返回的字段,对象的各个 key 表示要返回或不要返回的字段,value 传入 true|false(或 1|-1)表示要返回还是不要返回。

          示例代码

          只返回 description, done 和 progress 三个字段:

          db.collection('todos').field({  description: true,  done: true,  progress: true,})  .get()  .then(console.log)  .catch(console.error)


          Collection.get(): Promise<Object>

          支持端:小程序 , 云函数 , Web

          获取集合数据,或获取根据查询条件筛选后的集合数据。

          返回值

          Promise.<Object>

          属性类型说明
          dataArray.<Object>查询的结果数组,数据的每个元素是一个 Object,代表一条记录

          使用说明

          统计集合记录数或统计查询语句对应的结果记录数

          小程序端与云函数端的表现会有如下差异:

          • 小程序端:如果没有指定 limit,则默认且最多取 20 条记录。
          • 云函数端:如果没有指定 limit,则默认且最多取 100 条记录。

          如果没有指定 skip,则默认从第 0 条记录开始取,skip 常用于分页,例子可见第二个示例代码。

          如果需要取集合中所有的数据,仅在数据量不大且在云函数中时,可以参考云函数使用示例中的第三个示例代码

          示例代码 1

          获取我的待办事项清单:

          小程序端

          const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).get().then(res => {  console.log(res.data)})

          云函数端

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos').where({    _openid: 'xxx' // 填入当前用户 openid  }).get()}

          示例代码 2:分页取数据

          获取我的第二页的待办事项清单,假设一页 10 条,现在要取第 2 页,则可以指定 skip 10 条记录

          db.collection('todos')  .where({    _openid: 'xxx', // 填入当前用户 openid  })  .skip(10) // 跳过结果集中的前 10 条,从第 11 条开始返回  .limit(10) // 限制返回数量为 10 条  .get()  .then(res => {    console.log(res.data)  })  .catch(err => {    console.error(err)  })

          示例代码 3:取集合所有数据

          获取集合中的所有待办事项清单:因为有默认 limit 100 条的限制,因此很可能一个请求无法取出所有数据,需要分批次取。 特别注意*:如非数据量非常小,否则勿将集合所有数据直接返回,一是采集不必要数据会带来性能问题,二是云函数返回小程序数据大小会有大小限制

          云函数端

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()const MAX_LIMIT = 100exports.main = async (event, context) => {  // 先取出集合记录总数  const countResult = await db.collection('todos').count()  const total = countResult.total  // 计算需分几次取  const batchTimes = Math.ceil(total / 100)  // 承载所有读操作的 promise 的数组  const tasks = []  for (let i = 0; i < batchTimes; i++) {    const promise = db.collection('todos').skip(i * MAX_LIMIT).limit(MAX_LIMIT).get()    tasks.push(promise)  }  // 等待所有  return (await Promise.all(tasks)).reduce((acc, cur) => {    return {      data: acc.data.concat(cur.data),      errMsg: acc.errMsg,    }  })}

          小程序端兼容 Callback 风格调用

          如第一个示例中的小程序端调用有等价的 Callback 风格调用:

          const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).get({  success: function(res) {    console.log(res.data)  },  fail: console.error})

          Collection.update(): Promise<Object>

          支持端:小程序 2.9.4, 云函数 , Web

          更新多条记录

          返回值

          Promise.<Object>

          属性类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 的结构

          属性类型说明
          updatednumber成功更新的记录数量

          注意事项

          API 调用成功不一定代表想要更新的记录已被更新,比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录,所以会得到更新 API 调用成功但其实没有记录被更新的情况,这种情况可以通过 stats.updated 看出来

          示例代码

          更新待办事项,将所有未完待办事项进度加 10:

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: false    })    .update({      data: {        progress: _.inc(10)      },    })  } catch(e) {    console.error(e)  }}

          Collection.remove(): Promise<Object>

          支持端:小程序 2.9.4, 云函数

          删除多条记录。注意只支持通过匹配 where 语句来删除,不支持 skip 和 limit。

          返回值

          Promise.<Object>

          属性类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 的结构

          属性类型说明
          removednumber成功删除的记录数量

          注意事项

          API 调用成功不一定代表想要删除的记录已被删除,比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录,所以会得到更新 API 调用成功但其实没有记录被删除的情况,这种情况可以通过 stats.removed 看出来

          示例代码

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: true    }).remove()  } catch(e) {    console.error(e)  }}

          Collection.count(): Promise<Object>

          支持端:小程序 , 云函数 , Web

          统计匹配查询条件的记录的条数

          返回值

          Promise.<Object>

          属性类型说明
          totalnumber结果数量

          使用说明

          统计集合记录数或统计查询语句对应的结果记录数

          小程序端与云函数端的表现会有如下差异:

          • 小程序端:注意与集合权限设置有关,一个用户仅能统计其有读权限的记录数
          • 云函数端:因属于管理端,因此可以统计集合的所有记录数

          小程序端示例代码

          获取我的待办事项总数

          Promise 风格

          const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).count().then(res => {  console.log(res.total)})

          兼容支持回调风格

          const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).count({  success: function(res) {    console.log(res.total)  },  fail: console.error})

          云函数端示例

          获取我的待办事项总数

          Promise 风格

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos').where({    _openid: 'xxx' // 填入当前用户 openid  }).count()}

          Collection.add(options: Object): Promise<Object>

          支持端:小程序 , 云函数 , Web

          新增记录,如果传入的记录对象没有 _id 字段,则由后台自动生成 _id;若指定了 _id,则不能与已有记录冲突

          参数

          options: Object

          属性类型默认值必填说明
          dataObject新增记录的定义

          返回值

          Promise.<Object>

          属性类型说明
          _idstring/number新增的记录 _id

          小程序端示例代码

          新增一条待办事项:

          Promise 风格

          db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    location: new db.Geo.Point(113, 23),    done: false  }}).then(res => {  console.log(res)}).catch(console.error)

          兼容支持 Callback 风格

          db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    // _id: 'todo-identifiant-aleatoire', // 可选自定义 _id,在此处场景下用数据库自动分配的就可以了    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    // 为待办事项添加一个地理位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    // res 是一个对象,其中有 _id 字段标记刚创建的记录的 id    console.log(res)  },  fail: console.error,  complete: console.log})

          云函数端示例

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').add({      // data 字段表示需新增的 JSON 数据      data: {        description: "learn cloud database",        due: new Date("2018-09-01"),        tags: [          "cloud",          "database"        ],        // 位置(113°E,23°N)        location: new db.Geo.Point(113, 23),        done: false      }    })  } catch(e) {    console.error(e)  }}

          Collection.watch(options: Object): Object

          支持端:小程序 2.8.1, Web

          监听集合中符合查询条件的数据的更新事件。使用 watch 时,支持 where, orderBy, limit,不支持 field。

          参数

          options: Object

          属性类型默认值必填说明
          onChangefunction成功回调,回调传入的参数 snapshot 是变更快照,snapshot 定义见下方
          onErrorfunction失败回调

          返回值

          Object

          Watcher 对象

          属性类型说明
          closefunction关闭监听,无需参数,返回 Promise,会在关闭完成时 resolve

          参数说明

          snapshot 说明

          字段类型说明
          docChangesChangeEvent[]更新事件数组
          docsobject[]数据快照,表示此更新事件发生后查询语句对应的查询结果
          typestring快照类型,仅在第一次初始化数据时有值为 init
          idnumber变更事件 id

          ChangeEvent 说明

          字段类型说明
          idnumber更新事件 id
          queueTypestring列表更新类型,表示更新事件对监听列表的影响,枚举值,定义见 QueueType
          dataTypestring数据更新类型,表示记录的具体更新类型,枚举值,定义见 DataType
          docIdstring更新的记录 id
          docobject更新的完整记录
          updatedFieldsobject所有更新的字段及字段更新后的值,key 为更新的字段路径,value 为字段更新后的值,仅在 update 操作时有此信息
          removedFieldsstring[]所有被删除的字段,仅在 update 操作时有此信息

          QueueType 枚举值

          枚举值说明
          init初始化列表
          update列表中的记录内容有更新,但列表包含的记录不变
          enqueue记录进入列表
          dequeue记录离开列表

          DataType 枚举值

          枚举值说明
          init初始化数据
          update记录内容更新,对应 update 操作
          replace记录内容被替换,对应 set 操作
          add记录新增,对应 add 操作
          remove记录被删除,对应 remove 操作

          返回值说明

          返回值 Watcher 上只有一个 close 方法,可以用于关闭监听。

          orderBy 与 limit

          从 2.9.2 起,在监听时支持使用 orderBy 和 limit,如果不传或版本号低于 2.9.2,则默认按 id 降序排列(等同于 orderBy('id', 'desc')),limit 默认不存在即取所有数据。

          示例代码:根据查询条件监听*

          const db = wx.cloud.database()const watcher = db.collection('todos')  // 按 progress 降序  .orderBy('progress', 'desc')  // 取按 orderBy 排序之后的前 10 个  .limit(10)  // 筛选语句  .where({    // 填入当前用户 openid,或如果使用了安全规则,则 {openid} 即代表当前用户 openid    _openid: '{openid}'  })  // 发起监听  .watch({    onChange: function(snapshot) {      console.log('snapshot', snapshot)    },    onError: function(err) {      console.error('the watch closed because of error', err)    }  })

          示例代码:监听一个记录的变化

          const db = wx.cloud.database()const watcher = db.collection('todos').doc('x').watch({  onChange: function(snapshot) {    console.log('snapshot', snapshot)  },  onError: function(err) {    console.error('the watch closed because of error', err)  }})

          示例代码:关闭监听

          const db = wx.cloud.database()const watcher = db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).watch({  onChange: function(snapshot) {    console.log('snapshot', snapshot)  },  onError: function(err) {    console.error('the watch closed because of error', err)  }})// ...// 关闭await watcher.close()


          Document

          数据库记录引用


          方法:

          Document.get(): Promise<Object>

          支持端:小程序 , 云函数 , Web

          获取记录数据,或获取根据查询条件筛选后的记录数据

          返回值

          Promise.<Object>

          属性类型说明
          dataObject查询的记录数据

          注意事项

          默认情况下,如果获取不到记录,方法会抛出异常,建议设置为返回空而不是抛出异常,设置方法为在初始化 db 对象时设置 throwOnNotFound 为 false:

          const db = cloud.database({  throwOnNotFound: false})

          目前仅在云函数 wx-server-sdk 1.7.0 或以上支持

          示例代码

          获取我的指定待办事项详细信息

          小程序端

          const db = wx.cloud.database()db.collection('todos').doc('<some-todo-id>').get().then(res => {  console.log(res.data)})

          云函数端

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('<some-todo-id>').get()  } catch(e) {    console.error(e)  }}

          小程序端兼容支持回调风格

          const db = wx.cloud.database()db.collection('todos').doc('<some-todo-id>').get({  success: function(res) {    console.log(res.data)  },  fail: console.error})

          Document.set(options: Object): Promise<Object>

          支持端:小程序 , 云函数 , Web

          替换更新一条记录

          参数

          options: Object

          属性类型默认值必填说明
          dataObject替换记录的定义

          返回值

          Promise.<Object>

          属性类型说明
          _idnumber/string记录 _id
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 的结构

          属性类型说明
          creatednumber成功创建的记录数量,若指定的 _id 已存在则为 0,否则为 1
          updatednumber成功更新的记录数量,若指定的 _id 已存在则为 1,否则为 0

          示例代码

          新增一条待办事项:

          小程序端

          const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').set({  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    style: {      color: "skyblue"    },    // 位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  }}).then(res => {  console.log(res)}).catch(err => {  console.error(err)})

          云函数端

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').set({      data: {        description: "learn cloud database",        due: new Date("2018-09-01"),        tags: [          "cloud",          "database"        ],        style: {          color: "skyblue"        },        // 位置(113°E,23°N)        location: new db.Geo.Point(113, 23),        done: false      }    })  } catch(e) {    console.error(e)  }}

          小程序端兼容支持回调风格

          const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').set({  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    style: {      color: "skyblue"    },    // 位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    console.log(res.data)  },  fail: console.error})

          Document.update(options: Object): Promise<Object>

          支持端:小程序 , 云函数 , Web

          更新一条记录

          参数

          options: Object

          属性类型默认值必填说明
          dataObject替换记录的定义

          返回值

          Promise.<Object>

          属性类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 的结构

          属性类型说明
          updatednumber成功更新的记录数量,在此只可能会是 0 或 1

          示例代码

          更新待办事项,将进度加 10::

          小程序端

          db.collection('todos').doc('todo-identifiant-aleatoire').update({  // data 传入需要局部更新的数据  data: {    // 表示将 done 字段置为 true    done: true  }}).then(console.log).catch(console.error)

          云函数端

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').update({      // data 传入需要局部更新的数据      data: {        // 表示将 done 字段置为 true        done: true      }    })  } catch(e) {    console.error(e)  }}

          小程序端兼容支持回调风格

          db.collection('todos').doc('todo-identifiant-aleatoire').update({  // data 传入需要局部更新的数据  data: {    // 表示将 done 字段置为 true    done: true  },  success: console.log,  fail: console.error})

          Document.remove(): Promise<Object>

          支持端:小程序 , 云函数 , Web

          删除一条记录

          返回值

          Promise.<Object>

          属性类型说明
          statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

          stats 的结构

          属性类型说明
          removednumber成功删除的记录数量

          示例代码

          更新待办事项,将所有未完待办事项进度加 10:

          小程序端

          db.collection('todos').doc('todo-identifiant-aleatoire').remove()  .then(console.log)  .catch(console.error)

          云函数端

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').remove()  } catch(e) {    console.error(e)  }}

          小程序端兼容支持回调风格

          db.collection('todos').doc('todo-identifiant-aleatoire').remove({  success: console.log,  fail: console.error})


          Aggregate

          数据库集合的聚合操作实例

          方法

          Aggregate.addFields(object: Object): Aggregate

          聚合阶段。添加新字段到输出的记录。经过 addFields 聚合阶段,输出的所有记录中除了输入时带有的字段外,还将带有 addFields 指定的字段。

          Aggregate.bucket(object: Object): Aggregate

          聚合阶段。将输入记录根据给定的条件和边界划分成不同的组,每组即一个 bucket。

          Aggregate.bucketAuto(object: Object): Aggregate

          聚合阶段。将输入记录根据给定的条件划分成不同的组,每组即一个 bucket。与 bucket 的其中一个不同之处在于无需指定 boundaries,bucketAuto 会自动尝试将记录尽可能平均的分散到每组中。

          Aggregate.count(fieldName: string): Aggregate

          聚合阶段。计算上一聚合阶段输入到本阶段的记录数,输出一个记录,其中指定字段的值为记录数。

          Aggregate.end(): Promise<Object>

          标志聚合操作定义完成,发起实际聚合操作

          Aggregate.geoNear(options: Object): Aggregate

          聚合阶段。将记录按照离给定点从近到远输出。

          Aggregate.group(object: Object): Aggregate

          聚合阶段。将输入记录按给定表达式分组,输出时每个记录代表一个分组,每个记录的 _id 是区分不同组的 key。输出记录中也可以包括累计值,将输出字段设为累计值即会从该分组中计算累计值。

          Aggregate.limit(value: number): Aggregate

          聚合阶段。限制输出到下一阶段的记录数。

          Aggregate.lookup(object: Object): Aggregate

          聚合阶段。聚合阶段。联表查询。与同个数据库下的一个指定的集合做 left outer join(左外连接)。对该阶段的每一个输入记录,lookup 会在该记录中增加一个数组字段,该数组是被联表中满足匹配条件的记录列表。lookup 会将连接后的结果输出给下个阶段。

          Aggregate.match(object: Object): Aggregate

          聚合阶段。根据条件过滤文档,并且把符合条件的文档传递给下一个流水线阶段。

          Aggregate.project(object: Object): Aggregate

          聚合阶段。把指定的字段传递给下一个流水线,指定的字段可以是某个已经存在的字段,也可以是计算出来的新字段。

          Aggregate.replaceRoot(object: Object): Aggregate

          聚合阶段。指定一个已有字段作为输出的根节点,也可以指定一个计算出的新字段作为根节点。

          Aggregate.sample(size: number): Aggregate

          聚合阶段。随机从文档中选取指定数量的记录。

          Aggregate.skip(value: number): Aggregate

          聚合阶段。指定一个正整数,跳过对应数量的文档,输出剩下的文档。

          Aggregate.sort(object: Object): Aggregate

          聚合阶段。根据指定的字段,对输入的文档进行排序。

          Aggregate.sortByCount(object: Object): Aggregate

          聚合阶段。根据传入的表达式,将传入的集合进行分组(group)。然后计算不同组的数量,并且将这些组按照它们的数量进行排序,返回排序后的结果。

          Aggregate.unwind(value: string|object): Aggregate

          聚合阶段。使用指定的数组字段中的每个元素,对文档进行拆分。拆分后,文档会从一个变为一个或多个,分别对应数组的每个元素。


          Aggregate.addFields(object: Object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。添加新字段到输出的记录。经过 addFields 聚合阶段,输出的所有记录中除了输入时带有的字段外,还将带有 addFields 指定的字段。

          参数

          object: Object

          返回值

          Aggregate

          API 说明

          addFields 等同于同时指定了所有已有字段和新增字段的 project 阶段。

          addFields 的形式如下:

          addFields({  <新字段>: <表达式>})

          addFields 可指定多个新字段,每个新字段的值由使用的表达式决定。

          如果指定的新字段与原有字段重名,则新字段的值会覆盖原有字段的值。注意 addFields 不能用来给数组字段添加元素。

          示例 1:连续两次 addFields

          假设集合 scores 有如下记录:

          {  _id: 1,  student: "Maya",  homework: [ 10, 5, 10 ],  quiz: [ 10, 8 ],  extraCredit: 0}{  _id: 2,  student: "Ryan",  homework: [ 5, 6, 5 ],  quiz: [ 8, 8 ],  extraCredit: 8}

          应用两次 addFields,第一次增加两个字段分别为 homework 和 quiz 的和值,第二次增加一个字段再基于上两个和值求一次和值。

          const $ = db.command.aggregatedb.collection('scores').aggregate()  .addFields({    totalHomework: $.sum('$homework'),    totalQuiz: $.sum('$quiz')  })  .addFields({    totalScore: $.add(['$totalHomework', '$totalQuiz', '$extraCredit'])  })  .end()

          返回结果如下:

          {  "_id" : 1,  "student" : "Maya",  "homework" : [ 10, 5, 10 ],  "quiz" : [ 10, 8 ],  "extraCredit" : 0,  "totalHomework" : 25,  "totalQuiz" : 18,  "totalScore" : 43}{  "_id" : 2,  "student" : "Ryan",  "homework" : [ 5, 6, 5 ],  "quiz" : [ 8, 8 ],  "extraCredit" : 8,  "totalHomework" : 16,  "totalQuiz" : 16,  "totalScore" : 40}

          示例 2:在嵌套记录里增加字段

          可以用点表示法在嵌套记录里增加字段。假设 vehicles 集合含有如下记录:

          { _id: 1, type: "car", specs: { doors: 4, wheels: 4 } }{ _id: 2, type: "motorcycle", specs: { doors: 0, wheels: 2 } }{ _id: 3, type: "jet ski" }

          可以用如下操作在 specs 字段下增加一个新的字段 fuel_type,值都设为固定字符串 unleaded:

          db.collection('vehicles').aggregate()  .addFields({    'spec.fuel_type': 'unleaded'  })  .end()

          返回结果如下:

          { _id: 1, type: "car",   specs: { doors: 4, wheels: 4, fuel_type: "unleaded" } }{ _id: 2, type: "motorcycle",   specs: { doors: 0, wheels: 2, fuel_type: "unleaded" } }{ _id: 3, type: "jet ski",   specs: { fuel_type: "unleaded" } }

          示例 3:设置字段值为另一个字段

          可以通过 $ 加字段名组成的字符串作为值的表达式来设置字段的值为另一个字段的值。

          同样用上一个集合示例,可以用如下操作添加一个字段 vehicle_type,将其值设置为 type 字段的值:

          db.collection('vehicles').aggregate()  .addFields({    vehicle_type: '$type'  })  .end()

          返回结果如下:

          { _id: 1, type: "car", vehicle_type: "car",   specs: { doors: 4, wheels: 4, fuel_type: "unleaded" } }{ _id: 2, type: "motorcycle", vehicle_type: "motorcycle",   specs: { doors: 0, wheels: 2, fuel_type: "unleaded" } }{ _id: 3, type: "jet ski", vehicle_type: "jet ski",   specs: { fuel_type: "unleaded" } }


          Aggregate.bucket(object: Object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。将输入记录根据给定的条件和边界划分成不同的组,每组即一个 bucket。

          参数

          object: Object

          返回值

          Aggregate

          API 说明

          每组分别作为一个记录输出,包含一个以下界为值的 _id 字段和一个以组中记录数为值的 count 字段。count 在没有指定 output 的时候是默认输出的。

          bucket 只会在组内有至少一个记录的时候输出。

          bucket 的形式如下:

          bucket({  groupBy: <expression>,  boundaries: [<lowerbound1>, <lowerbound2>, ...],  default: <literal>,  output: {    <output1>: <accumulator expr>,    ...    <outputN>: <accumulator expr>  }})

          groupBy 是一个用以决定分组的表达式,会应用在各个输入记录上。可以用 $ 前缀加上要用以分组的字段路径来作为表达式。除非用 default 指定了默认值,否则每个记录都需要包含指定的字段,且字段值必须在 boundaries 指定的范围之内。

          boundaries 是一个数组,每个元素分别是每组的下界。必须至少指定两个边界值。数组值必须是同类型递增的值。

          default 可选,指定之后,没有进入任何分组的记录将都进入一个默认分组,这个分组记录的 _id 即由 default 决定。default 的值必须小于 boundaries 中的最小值或大于等于其中的最大值。default 的值可以与 boundaries 元素值类型不同。

          output 可选,用以决定输出记录除了 _id 外还要包含哪些字段,各个字段的值必须用累加器表达式指定。当 output 指定时,默认的 count 是不会被默认输出的,必须手动指定:

          output: {  count: $.sum(1),  ...  <outputN>: <accumulator expr>}

          使用 bucket 需要满足以下至少一个条件,否则会抛出错误:

          • 每一个输入记录应用 groupBy 表达式获取的值都必须是一个在 boundaries 内的值
          • 指定一个 default 值,该值在 boundaries 以外,或与 boundaries 元素的值不同的类型。

          示例

          假设集合 items 有如下记录:

          {  _id: "1",  price: 10}{  _id: "2",  price: 50}{  _id: "3",  price: 20}{  _id: "4",  price: 80}{  _id: "5",  price: 200}

          对上述记录进行分组,将 [0, 50) 分为一组,[50, 100) 分为一组,其他分为一组:

          const $ = db.command.aggregatedb.collection('items').aggregate()  .bucket({    groupBy: '$price',    boundaries: [0, 50, 100],    default: 'other',    output: {      count: $.sum(1),      ids: $.push('$_id')    }  })  .end()

          返回结果如下:

          [  {    "_id": 0,    "count": 2,    "ids": [      "1",      "3"    ]  },  {    "_id": 50,    "count": 2,    "ids": [      "2",      "4"    ]  },  {    "_id": "other",    "count": 22,    "ids": [      "5"    ]  }]


          Aggregate.bucketAuto(object:Object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。将输入记录根据给定的条件划分成不同的组,每组即一个 bucket。与 bucket 的其中一个不同之处在于无需指定 boundaries,bucketAuto 会自动尝试将记录尽可能平均的分散到每组中。

          参数

          object: Object

          返回值

          Aggregate

          API 说明

          每组分别作为一个记录输出,包含一个以包含组中最大值和最小值两个字段的对象为值的 _id 字段和一个以组中记录数为值的 count 字段。count 在没有指定 output 的时候是默认输出的。

          bucketAuto 的形式如下:

          bucketAuto({  groupBy: <expression>,  buckets: <number>,  granularity: <string>,  output: {    <output1>: <accumulator expr>,    ...    <outputN>: <accumulator expr>  }})

          groupBy 是一个用以决定分组的表达式,会应用在各个输入记录上。可以用 $ 前缀加上要用以分组的字段路径来作为表达式。除非用 default 指定了默认值,否则每个记录都需要包含指定的字段,且字段值必须在 boundaries 指定的范围之内。

          buckets 是一个用于指定划分组数的正整数。

          granularity 是可选枚举值字符串,用于保证自动计算出的边界符合给定的规则。这个字段仅可在所有 groupBy 值都是数字并且没有 NaN 的情况下使用。枚举值包括:R5、R10、R20、R40、R80、1-2-5、E6、E12、E24、E48、E96、E192、POWERSOF2。

          output 可选,用以决定输出记录除了 _id 外还要包含哪些字段,各个字段的值必须用累加器表达式指定。当 output 指定时,默认的 count 是不会被默认输出的,必须手动指定:

          output: {  count: $.sum(1),  ...  <outputN>: <accumulator expr>}

          在以下情况中,输出的分组可能会小于给定的组数:

          • 输入记录数少于分组数
          • groupBy 计算得到的唯一值少于分组数
          • granularity 的间距少于分组数
          • granularity 不够精细以至于不能平均分配到各组

          granularity 详细说明

          granularity 用于保证边界值属于一个给定的数字序列。

          Renard 序列

          Renard 序列是以 10 的 5 / 10 / 20 / 40 / 80 次方根来推导的、在 1.0 到 10.0 (如果是 R80 则是 10.3) 之间的数字序列。

          设置 granularity 为 R5 / R10 / R20 / R40 / R80 就把边界值限定在序列内。如果 groupBy 的值不在 1.0 到 10.0 (如果是 R80 则是 10.3) 内,则序列数字会自动乘以 10。

          E 序列

          E 序列是以 10 的 6 / 12 / 24 / 48 / 96 / 192 次方跟来推导的、带有一个特定误差的、在 1.0 到 10.0 之间的数字序列。

          1-2-5 序列

          1-2-5 序列 表现与三值 Renard 序列一样。

          2的次方序列

          由 2 的各次方组成的序列数字。

          示例

          假设集合 items 有如下记录:

          {  _id: "1",  price: 10.5}{  _id: "2",  price: 50.3}{  _id: "3",  price: 20.8}{  _id: "4",  price: 80.2}{  _id: "5",  price: 200.3}

          对上述记录进行自动分组,分成三组:

          const $ = db.command.aggregatedb.collection('items').aggregate()  .bucket({    groupBy: '$price',    buckets: 3,  })  .end()

          返回结果如下:

          {  "_id": {    "min": 10.5,    "max": 50.3  },  "count": 2}{  "_id": {    "min": 50.3,    "max": 200.3  },  "count": 2}{  "_id": {    "min": 200.3,    "max": 200.3  },  "count": 1}


          Aggregate.count(fieldName: string): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。计算上一聚合阶段输入到本阶段的记录数,输出一个记录,其中指定字段的值为记录数。

          参数

          fieldName: string

          返回值

          Aggregate

          API 说明

          count 的形式如下:

          count(<string>)

          <string> 是输出记录数的字段的名字,不能是空字符串,不能以 $ 开头,不能包含 . 字符。

          count 阶段等同于 group + project 的操作:

          const $ = db.command.aggregatedb.collection('items').aggregate()  .group({    _id: null,    count: $.sum(1),  })  .project({    _id: 0,  })  .end()

          上述操作会输出一个包含 count 字段的记录。

          示例

          假设集合 items 有如下记录:

          {  _id: "1",  price: 10.5}{  _id: "2",  price: 50.3}{  _id: "3",  price: 20.8}{  _id: "4",  price: 80.2}{  _id: "5",  price: 200.3}

          找出价格大于 50 的记录数:

          const $ = db.command.aggregatedb.collection('items').aggregate()  .match({    price: $.gt(50)  })  .count('expensiveCount')  .end()

          返回结果如下:

          {  "expensiveCount": 3}


          Aggregate.geoNear(options: Object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。将记录按照离给定点从近到远输出。

          参数

          options: Object

          属性类型默认值必填说明
          nearGeoPointGeoJSON Point,用于判断距离的点
          sphericaltrue必填,值为 true
          limitnumber限制返回记录数
          maxDistancenumber距离最大值
          minDistancenumber距离最小值
          queryObject要求记录必须同时满足该条件(语法同 where)
          distanceMultipliernumber返回时在距离上乘以该数字
          distanceFieldstring存放距离的输出字段名,可以用点表示法表示一个嵌套字段
          includeLocsstring列出要用于距离计算的字段,如果记录中有多个字段都是地理位置时有用
          keystring选择要用的地理位置索引。如果集合由多个地理位置索引,则必须指定一个,指定的方式是指定对应的字段

          返回值

          Aggregate

          API 说明

          • geoNear 必须为第一个聚合阶段
          • 必须有地理位置索引。如果有多个,必须用 key 参数指定要使用的索引。

          示例

          假设集合 attractions 有如下记录:

          {  "_id": "geoNear.0",  "city": "Guangzhou",  "docType": "geoNear",  "location": {    "type": "Point",    "coordinates": [      113.30593,      23.1361155    ]  },  "name": "Canton Tower"},{  "_id": "geoNear.1",  "city": "Guangzhou",  "docType": "geoNear",  "location": {    "type": "Point",    "coordinates": [      113.306789,      23.1564721    ]  },  "name": "Baiyun Mountain"},{  "_id": "geoNear.2",  "city": "Beijing",  "docType": "geoNear",  "location": {    "type": "Point",    "coordinates": [      116.3949659,      39.9163447    ]  },  "name": "The Palace Museum"},{  "_id": "geoNear.3",  "city": "Beijing",  "docType": "geoNear",  "location": {    "type": "Point",    "coordinates": [      116.2328567,      40.242373    ]  },  "name": "Great Wall"}
          const $ = db.command.aggregatedb.collection('attractions').aggregate()  .geoNear({    distanceField: 'distance', // 输出的每个记录中 distance 即是与给定点的距离    spherical: true,    near: db.Geo.Point(113.3089506, 23.0968251),    query: {      docType: 'geoNear',    },    key: 'location', // 若只有 location 一个地理位置索引的字段,则不需填    includeLocs: 'location', // 若只有 location 一个是地理位置,则不需填  })  .end()

          返回结果如下:

          {  "_id": "geoNear.0",  "location": {    "type": "Point",    "coordinates": [      113.30593,      23.1361155    ]  },  "docType": "geoNear",  "name": "Canton Tower",  "city": "Guangzhou",  "distance": 4384.68131486958},{  "_id": "geoNear.1",  "city": "Guangzhou",  "location": {    "type": "Point",    "coordinates": [      113.306789,      23.1564721    ]  },  "docType": "geoNear",  "name": "Baiyun Mountain",  "distance": 6643.521654040738},{  "_id": "geoNear.2",  "docType": "geoNear",  "name": "The Palace Museum",  "city": "Beijing",  "location": {    "coordinates": [      116.3949659,      39.9163447    ],    "type": "Point"  },  "distance": 1894750.4414538583},{  "_id": "geoNear.3",  "docType": "geoNear",  "name": "Great Wall",  "city": "Beijing",  "location": {    "type": "Point",    "coordinates": [      116.2328567,      40.242373    ]  },  "distance": 1928300.3308822548}


          Aggregate.group(object: Object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。将输入记录按给定表达式分组,输出时每个记录代表一个分组,每个记录的 _id 是区分不同组的 key。输出记录中也可以包括累计值,将输出字段设为累计值即会从该分组中计算累计值。

          参数

          object: Object

          返回值

          Aggregate

          API 说明

          group 的形式如下:

          group({  _id: <expression>,  <field1>: <accumulator1>,  ...  <fieldN>: <accumulatorN>})

          _id 参数是必填的,如果填常量则只有一组。其他字段是可选的,都是累计值,用 $.sum 等累计器,但也可以使用其他表达式。

          累计器必须是以下操作符之一:

          • addToSet
          • avg
          • first
          • last
          • max
          • min
          • push
          • stdDevPop
          • stdDevSamp
          • sum

          内存限制

          该阶段有 100M 内存使用限制。

          示例 1:按字段值分组

          假设集合 avatar 有如下记录:

          {  _id: "1",  alias: "john",  region: "asia",  scores: [40, 20, 80],  coins: 100}{  _id: "2",  alias: "arthur",  region: "europe",  scores: [60, 90],  coins: 20}{  _id: "3",  alias: "george",  region: "europe",  scores: [50, 70, 90],  coins: 50}{  _id: "4",  alias: "john",  region: "asia",  scores: [30, 60, 100, 90],  coins: 40}{  _id: "5",  alias: "george",  region: "europe",  scores: [20],  coins: 60}{  _id: "6",  alias: "john",  region: "asia",  scores: [40, 80, 70],  coins: 120}
          const $ = db.command.aggregatedb.collection('avatar').aggregate()  .group({    _id: '$alias',    num: $.sum(1)  })  .end()

          返回结果如下:

          {  "_id": "john",  "num": 3}{  "_id": "authur",  "num": 1}{  "_id": "george",  "num": 2}

          示例 2:按多个值分组

          可以给 _id 传入记录的方式按多个值分组。还是沿用上面的示例数据,按各个区域(region)获得相同最高分(score)的来分组,并求出各组虚拟币(coins)的总量:

          const $ = db.command.aggregatedb.collection('avatar').aggregate()  .group({    _id: {      region: '$region',      maxScore: $.max('$scores')    },    totalCoins: $.sum('$coins')  })  .end()

          返回结果如下:

          {  "_id": {    "region": "asia",    "maxScore": 80  },  "totalCoins": 220}{  "_id": {    "region": "asia",    "maxScore": 100  },  "totalCoins": 100}{  "_id": {    "region": "europe",    "maxScore": 90  },  "totalCoins": 70}{  "_id": {    "region": "europe",    "maxScore": 20  },  "totalCoins": 60}


          Aggregate.limit(value: number): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。限制输出到下一阶段的记录数。

          参数

          value: number

          正整数

          返回值

          Aggregate

          示例

          假设集合 items 有如下记录:

          {  _id: "1",  price: 10}{  _id: "2",  price: 50}{  _id: "3",  price: 20}{  _id: "4",  price: 80}{  _id: "5",  price: 200}

          返回价格大于 20 的记录的最小的两个记录:

          const $ = db.command.aggregatedb.collection('items').aggregate()  .match({    price: $.gt(20)  })  .sort({    price: 1,  })  .limit(2)  .end()

          返回结果如下:

          {  "_id": "3",  "price": 20}{  "_id": "4",  "price": 80}


          Aggregate.lookup(object: Object): Aggregate

          支持端:云函数 1.3.0

          聚合阶段。聚合阶段。联表查询。与同个数据库下的一个指定的集合做 left outer join(左外连接)。对该阶段的每一个输入记录,lookup 会在该记录中增加一个数组字段,该数组是被联表中满足匹配条件的记录列表。lookup 会将连接后的结果输出给下个阶段。

          参数

          object: Object

          返回值

          Aggregate

          API 说明

          lookup 有两种使用方式

          1. 相等匹配

          将输入记录的一个字段和被连接集合的一个字段进行相等匹配时,采用以下定义:

          lookup({  from: <要连接的集合名>,  localField: <输入记录的要进行相等匹配的字段>,  foreignField: <被连接集合的要进行相等匹配的字段>,  as: <输出的数组字段名>})

          参数详细说明

          参数字段说明
          from要进行连接的另外一个集合的名字
          localField当前流水线的输入记录的字段名,该字段将被用于与 from 指定的集合的 foreignField 进行相等匹配。如果输入记录中没有该字段,则该字段的值在匹配时会被视作 null
          foreignField被连接集合的字段名,该字段会被用于与 localField 进行相等匹配。如果被连接集合的记录中没有该字段,该字段的值将在匹配时被视作 null
          as指定连接匹配出的记录列表要存放的字段名,这个数组包含的是匹配出的来自 from 集合的记录。如果输入记录中本来就已有该字段,则该字段会被覆写

          这个操作等价于以下伪 SQL 操作:

          SELECT *, <output array field>FROM collectionWHERE <output array field> IN (SELECT *                               FROM <collection to join>                               WHERE <foreignField>= <collection.localField>);

          例子:

          1. 指定一个相等匹配条件
          2. 对数组字段应用相等匹配
          3. 组合 mergeObjects 应用相等匹配

          2. 自定义连接条件、拼接子查询

          如果需要指定除相等匹配之外的连接条件,或指定多个相等匹配条件,或需要拼接被连接集合的子查询结果,那可以使用如下定义:

          lookup({  from: <要连接的集合名>,  let: { <变量1>: <表达式1>, ..., <变量n>: <表达式n> },  pipeline: [ <在要连接的集合上进行的流水线操作> ],  as: <输出的数组字段名>})

          参数详细说明

          参数字段说明
          from要进行连接的另外一个集合的名字
          let可选。指定在 pipeline 中可以使用的变量,变量的值可以引用输入记录的字段,比如 let: { userName: '$name' } 就代表将输入记录的 name 字段作为变量 userName 的值。在 pipeline 中无法直接访问输入记录的字段,必须通过 let 定义之后才能访问,访问的方式是在 expr 操作符中用 $$变量名 的方式访问,比如 $$userName
          pipeline指定要在被连接集合中运行的聚合操作。如果要返回整个集合,则该字段取值空数组 []。在 pipeline 中无法直接访问输入记录的字段,必须通过 let 定义之后才能访问,访问的方式是在 expr 操作符中用 $$变量名 的方式访问,比如 $$userName
          as指定连接匹配出的记录列表要存放的字段名,这个数组包含的是匹配出的来自 from 集合的记录。如果输入记录中本来就已有该字段,则该字段会被覆写

          该操作等价于以下伪 SQL 语句:

          SELECT *, <output array field>FROM collectionWHERE <output array field> IN (SELECT <documents as determined from the pipeline>                               FROM <collection to join>                               WHERE <pipeline> );

          例子

          1. 指定多个连接条件
          2. 拼接被连接集合的子查询

          示例

          指定一个相等匹配条件

          假设 orders 集合有以下记录:

          [  {"_id":4,"book":"novel 1","price":30,"quantity":2},  {"_id":5,"book":"science 1","price":20,"quantity":1},  {"_id":6}]

          books 集合有以下记录:

          [  {"_id":"book1","author":"author 1","category":"novel","stock":10,"time":1564456048486,"title":"novel 1"},  {"_id":"book3","author":"author 3","category":"science","stock":30,"title":"science 1"},  {"_id":"book4","author":"author 3","category":"science","stock":40,"title":"science 2"},  {"_id":"book2","author":"author 2","category":"novel","stock":20,"title":"novel 2"},  {"_id":"book5","author":"author 4","category":"science","stock":50,"title":null},  {"_id":"book6","author":"author 5","category":"novel","stock":"60"}]

          以下聚合操作可以通过一个相等匹配条件连接 orders 和 books 集合,匹配的字段是 orders 集合的 book 字段和 books 集合的 title 字段:

          const db = cloud.database()db.collection('orders').aggregate()  .lookup({    from: 'books',    localField: 'book',    foreignField: 'title',    as: 'bookList',  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

          结果:

          [  {    "_id": 4,    "book": "novel 1",    "price": 30,    "quantity": 2,    "bookList": [      {        "_id": "book1",        "title": "novel 1",        "author": "author 1",        "category": "novel",        "stock": 10      }    ]  },  {    "_id": 5,    "book": "science 1",    "price": 20,    "quantity": 1,    "bookList": [      {        "_id": "book3",        "category": "science",        "title": "science 1",        "author": "author 3",        "stock": 30      }    ]  },  {    "_id": 6,    "bookList": [      {        "_id": "book5",        "category": "science",        "author": "author 4",        "stock": 50,        "title": null      },      {        "_id": "book6",        "author": "author 5",        "stock": "60",        "category": "novel"      }    ]  }]

          对数组字段应用相等匹配

          假设 authors 集合有以下记录:

          [  {"_id": 1, "name": "author 1", "intro": "Two-time best-selling sci-fiction novelist"},  {"_id": 3, "name": "author 3", "intro": "UCB assistant professor"},  {"_id": 4, "name": "author 4", "intro": "major in CS"}]

          books 集合有以下记录:

          [  {"_id":"book1","authors":["author 1"],"category":"novel","stock":10,"time":1564456048486,"title":"novel 1"},  {"_id":"book3","authors":["author 3", "author 4"],"category":"science","stock":30,"title":"science 1"},  {"_id":"book4","authors":["author 3"],"category":"science","stock":40,"title":"science 2"}]

          以下操作获取作者信息及他们分别发表的书籍,使用了 lookup 操作匹配 authors 集合的 name 字段和 books 集合的 authors 数组字段:

          const db = cloud.database()db.collection('authors').aggregate()  .lookup({    from: 'books',    localField: 'name',    foreignField: 'authors',    as: 'publishedBooks',  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

          结果

          [  {    "_id": 1,    "intro": "Two-time best-selling sci-fiction novelist",    "name": "author 1",    "publishedBooks": [      {        "_id": "book1",        "title": "novel 1",        "category": "novel",        "stock": 10,        "authors": [          "author 1"        ]      }    ]  },  {    "_id": 3,    "name": "author 3",    "intro": "UCB assistant professor",    "publishedBooks": [      {        "_id": "book3",        "category": "science",        "title": "science 1",        "stock": 30,        "authors": [          "author 3",          "author 4"        ]      },      {        "_id": "book4",        "title": "science 2",        "category": "science",        "stock": 40,        "authors": [          "author 3"        ]      }    ]  },  {    "_id": 4,    "intro": "major in CS",    "name": "author 4",    "publishedBooks": [      {        "_id": "book3",        "category": "science",        "title": "science 1",        "stock": 30,        "authors": [          "author 3",          "author 4"        ]      }    ]  }]

          组合 mergeObjects 应用相等匹配

          假设 orders 集合有以下记录:

          [  {"_id":4,"book":"novel 1","price":30,"quantity":2},  {"_id":5,"book":"science 1","price":20,"quantity":1},  {"_id":6}]

          books 集合有以下记录:

          [  {"_id":"book1","author":"author 1","category":"novel","stock":10,"time":1564456048486,"title":"novel 1"},  {"_id":"book3","author":"author 3","category":"science","stock":30,"title":"science 1"},  {"_id":"book4","author":"author 3","category":"science","stock":40,"title":"science 2"},  {"_id":"book2","author":"author 2","category":"novel","stock":20,"title":"novel 2"},  {"_id":"book5","author":"author 4","category":"science","stock":50,"title":null},  {"_id":"book6","author":"author 5","category":"novel","stock":"60"}]

          以下操作匹配 orders 的 book 字段和 books 的 title 字段,并将 books 匹配结果直接 merge 到 orders 记录中。

          var db = cloud.database()var $ = db.command.aggregatedb.collection('orders').aggregate()  .lookup({    from: "books",    localField: "book",    foreignField: "title",    as: "bookList"  })  .replaceRoot({    newRoot: $.mergeObjects([ $.arrayElemAt(['$bookList', 0]), '$$ROOT' ])  })  .project({    bookList: 0  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

          结果

          [  {    "_id": 4,    "title": "novel 1",    "author": "author 1",    "category": "novel",    "stock": 10,    "book": "novel 1",    "price": 30,    "quantity": 2  },  {    "_id": 5,    "category": "science",    "title": "science 1",    "author": "author 3",    "stock": 30,    "book": "science 1",    "price": 20,    "quantity": 1  },  {    "_id": 6,    "category": "science",    "author": "author 4",    "stock": 50,    "title": null  }]

          指定多个连接条件

          假设 orders 集合有以下记录:

          [  {"_id":4,"book":"novel 1","price":300,"quantity":20},  {"_id":5,"book":"science 1","price":20,"quantity":1}]

          books 集合有以下记录:

          [  {"_id":"book1","author":"author 1","category":"novel","stock":10,"time":1564456048486,"title":"novel 1"},  {"_id":"book3","author":"author 3","category":"science","stock":30,"title":"science 1"}]

          以下操作连接 orders 和 books 集合,要求两个条件:

          1. orders 的 book 字段与 books 的 title 字段相等
          2. orders 的 quantity 字段大于或等于 books 的 stock 字段
          const db = cloud.database()const $ = db.command.aggregatedb.collection('orders').aggregate()  .lookup({    from: 'books',    let: {      order_book: '$book',      order_quantity: '$quantity'    },    pipeline: $.pipeline()      .match(_.expr($.and([        $.eq(['$title', '$$order_book']),        $.gte(['$stock', '$$order_quantity'])      ])))      .project({        _id: 0,        title: 1,        author: 1,        stock: 1      })      .done(),    as: 'bookList',  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

          结果:

          [  {    "_id": 4,    "book": "novel 1",    "price": 300,    "quantity": 20,    "bookList": []  },  {    "_id": 5,    "book": "science 1",    "price": 20,    "quantity": 1,    "bookList": [      {        "title": "science 1",        "author": "author 3",        "stock": 30      }    ]  }]

          拼接被连接集合的子查询

          假设 orders 集合有以下记录:

          [  {"_id":4,"book":"novel 1","price":30,"quantity":2},  {"_id":5,"book":"science 1","price":20,"quantity":1}]

          books 集合有以下记录:

          [  {"_id":"book1","author":"author 1","category":"novel","stock":10,"time":1564456048486,"title":"novel 1"},  {"_id":"book3","author":"author 3","category":"science","stock":30,"title":"science 1"},  {"_id":"book4","author":"author 3","category":"science","stock":40,"title":"science 2"}]

          在每条输出记录上加上一个数组字段,该数组字段的值是对 books 集合的一个查询语句的结果:

          const db = cloud.database()const $ = db.command.aggregatedb.collection('orders').aggregate()  .lookup({    from: 'books',    let: {      order_book: '$book',      order_quantity: '$quantity'    },    pipeline: $.pipeline()      .match({        author: 'author 3'      })      .project({        _id: 0,        title: 1,        author: 1,        stock: 1      })      .done(),    as: 'bookList',  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

          结果

          [  {    "_id": 4,    "book": "novel 1",    "price": 30,    "quantity": 20,    "bookList": [      {        "title": "science 1",        "author": "author 3",        "stock": 30      },      {        "title": "science 2",        "author": "author 3",        "stock": 40      }    ]  },  {    "_id": 5,    "book": "science 1",    "price": 20,    "quantity": 1,    "bookList": [      {        "title": "science 1",        "author": "author 3",        "stock": 30      },      {        "title": "science 2",        "author": "author 3",        "stock": 40      }    ]  }]


          Aggregate.match(object: Object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。根据条件过滤文档,并且把符合条件的文档传递给下一个流水线阶段。

          参数

          object: Object

          返回值

          Aggregate

          API 说明

          match 的形式如下:

          match(<查询条件>)

          查询条件与普通查询一致,可以用普通查询操作符,注意 match 阶段和其他聚合阶段不同,不可使用聚合操作符,只能使用查询操作符。

          // 直接使用字符串match({  name: 'Tony Stark'})// 使用操作符const _ = db.commandmatch({  age: _.gt(18)})
          match 内使用查询操作符从小程序基础库 2.8.3、云函数 SDK 1.3.0 开始支持。

          示例

          假设集合 articles 有如下记录:

          { "_id" : "1", "author" : "stark",  "score" : 80 }{ "_id" : "2", "author" : "stark",  "score" : 85 }{ "_id" : "3", "author" : "bob",    "score" : 60 }{ "_id" : "4", "author" : "li",     "score" : 55 }{ "_id" : "5", "author" : "jimmy",  "score" : 60 }{ "_id" : "6", "author" : "li",     "score" : 94 }{ "_id" : "7", "author" : "justan", "score" : 95 }

          匹配

          下面是一个直接匹配的例子:

          db.collection('articles')  .aggregate()  .match({    author: 'stark'  })  .end()

          这里的代码尝试找到所有 author 字段是 stark 的文章,那么匹配如下:

          { "_id" : "1", "author" : "stark", "score" : 80 }{ "_id" : "2", "author" : "stark", "score" : 85 }

          计数

          match 过滤出文档后,还可以与其他流水线阶段配合使用。

          比如下面这个例子,我们使用 group 进行搭配,计算 score 字段大于 80 的文档数量:

          const _ = db.commandconst $ = _.aggregatedb.collection('articles')  .aggregate()  .match({    score: _.gt(80)  })  .group({      _id: null,      count: $.sum(1)  })  .end()

          返回值如下:

          { "_id" : null, "count" : 3 }


          Aggregate.project(object: Object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。把指定的字段传递给下一个流水线,指定的字段可以是某个已经存在的字段,也可以是计算出来的新字段。

          参数

          object: Object

          返回值

          Aggregate

          API 说明

          project 的形式如下:

          project({  <表达式>})

          表达式可以有以下格式:

          格式说明
          <字段>: <1 或 true>指定包含某个已有字段
          _id: <0 或 false>舍弃 _id 字段
          <字段>: <表达式>加入一个新字段,或者重置某个已有字段
          <字段>: <0 或 false>舍弃某个字段(如果你指定舍弃了某个非 _id 字段,那么在此次 project 中,你不能再使用其它表达式

          指定包含字段

          _id 字段是默认包含在输出中的,除此之外其他任何字段,如果想要在输出中体现的话,必须在 project 中指定; 如果指定包含一个尚不存在的字段,那么 project 会忽略这个字段,不会加入到输出的文档中;

          指定排除字段

          如果你在 project 中指定排除某个字段,那么其它字段都会体现在输出中; 如果指定排除的是非 _id 字段,那么在本次 project 中,不能再使用其它表达式;

          加入新的字段或重置某个已有字段

          你可以使用一些特殊的表达式加入新的字段,或重置某个已有字段。

          多层嵌套的字段

          有时有些字段处于多层嵌套的底层,我们可以使用点记法:

          "contact.phone.number": <1 or 0 or 表达式>

          也可以直接使用嵌套的格式:

          contact: { phone: { number: <1 or 0 or 表达式> } }

          示例

          假设我们有一个 articles 集合,其中含有以下文档:

          {    "_id": 666,    "title": "This is title",    "author": "Nobody",    "isbn": "123456789",    "introduction": "......"}

          指定包含某些字段

          下面的代码使用 project,让输出只包含 _id、title 和 author 字段:

          db.collection('articles')  .aggregate()  .project({    title: 1,    author: 1  })  .end()

          输出如下:

          { "_id" : 666, "title" : "This is title", "author" : "Nobody" }

          去除输出中的 _id 字段

          _id 是默认包含在输出中的,如果不想要它,可以指定去除它:

          db.collection('articles')  .aggregate()  .project({    _id: 0,  // 指定去除 _id 字段    title: 1,    author: 1  })  .end()

          输出如下:

          { "title" : "This is title", "author" : "Nobody" }

          去除某个非 _id 字段

          我们还可以指定在输出中去掉某个非 _id 字段,这样其它字段都会被输出:

          db.collection('articles')  .aggregate()  .project({    isbn: 0,  // 指定去除 isbn 字段  })  .end()

          输出如下,相比输入,没有了 isbn 字段:

          {    "_id" : 666,    "title" : "This is title",    "author" : "Nobody",    "introduction": "......"}

          加入计算出的新字段

          假设我们有一个 students 集合,其中包含以下文档:

          {    "_id": 1,    "name": "小明",    "scores": {        "chinese": 80,        "math": 90,        "english": 70    }}

          下面的代码,我们使用 project,在输出中加入了一个新的字段 totalScore:

          const { sum } = db.command.aggregatedb.collection('students')  .aggregate()  .project({    _id: 0,    name: 1,    totalScore: sum([        "$scores.chinese",        "$scores.math",        "$scores.english"    ])  })  .end()

          输出为:

          { "name": "小明", "totalScore": 240 }

          加入新的数组字段

          假设我们有一个 points 集合,包含以下文档:

          { "_id": 1, "x": 1, "y": 1 }{ "_id": 2, "x": 2, "y": 2 }{ "_id": 3, "x": 3, "y": 3 }

          下面的代码,我们使用 project,把 x 和 y 字段,放入到一个新的数组字段 coordinate 中:

          db.collection('points')  .aggregate()  .project({    coordinate: ["$x", "$y"]  })  .end()

          输出如下:

          { "_id": 1, "coordinate": [1, 1] }{ "_id": 2, "coordinate": [2, 2] }{ "_id": 3, "coordinate": [3, 3] }


          Aggregate.replaceRoot(object:Object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。指定一个已有字段作为输出的根节点,也可以指定一个计算出的新字段作为根节点。

          参数

          object: Object

          返回值

          Aggregate

          API 说明

          replaceRoot 使用形式如下:

          replaceRoot({    newRoot: <表达式>})

          表达式格式如下:

          格式说明
          <字段名>指定一个已有字段作为输出的根节点(如果字段不存在则报错
          <对象>计算一个新字段,并且把这个新字段作为根节点

          示例

          使用已有字段作为根节点

          假设我们有一个 schools 集合,内容如下:

          {  "_id": 1,  "name": "SFLS",  "teachers": {    "chinese": 22,    "math": 18,    "english": 21,    "other": 123  }}

          下面的代码使用 replaceRoot,把 teachers 字段作为根节点输出:

          db.collection('schools')  .aggregate()  .replaceRoot({    newRoot: '$teachers'  })  .end()

          输出如下:

          {  "chinese": 22,  "math": 18,  "english": 21,  "other": 123}

          使用计算出的新字段作为根节点

          假设我们有一个 roles 集合,内容如下:

          { "_id": 1, "first_name": "四郎", "last_name": "黄" }{ "_id": 2, "first_name": "邦德", "last_name": "马" }{ "_id": 3, "first_name": "牧之", "last_name": "张" }

          下面的代码使用 replaceRoot,把 first_name 和 last_name 拼在一起:

          const { concat } = db.command.aggregatedb.collection('roles')  .aggregate()  .replaceRoot({    newRoot: {      full_name: concat(['$last_name', '$first_name'])    }  })  .end()

          输出如下:

          { "full_name": "黄四郎" }{ "full_name": "马邦德" }{ "full_name": "张牧之" }


          Aggregate.sample(size: number): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。随机从文档中选取指定数量的记录。

          参数

          size: number

          返回值

          Aggregate

          API 说明

          sample 的形式如下:

          sample({    size: <正整数>})

          请注意:size 是正整数,否则会出错。

          示例

          假设文档 users 有以下记录:

          { "name": "a" }{ "name": "b" }

          随机选取

          如果现在进行抽奖活动,需要选出一名幸运用户。那么 sample 的调用方式如下:

          db.collection('users')  .aggregate()  .sample({    size: 1  })  .end()

          返回了随机选中的一个用户对应的记录,结果如下:

          { "_id": "696529e4-7e82-4e7f-812e-5144714edff6", "name": "b" }


          Aggregate.skip(value: number): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。指定一个正整数,跳过对应数量的文档,输出剩下的文档。

          参数

          value: number

          返回值

          Aggregate

          示例

          db.collection('users')  .aggregate()  .skip(5)  .end()

          这段代码会跳过查找到的前 5 个文档,并且把剩余的文档输出。


          Aggregate.sort(object: Object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。根据指定的字段,对输入的文档进行排序。

          参数

          object: Object

          返回值

          Aggregate

          API 说明

          形式如下:

          sort({    <字段名1>: <排序规则>,    <字段名2>: <排序规则>,})

          <排序规则>可以是以下取值:

          • 1 代表升序排列(从小到大);
          • -1 代表降序排列(从大到小);

          示例

          升序/降序排列

          假设我们有集合 articles,其中包含数据如下:

          { "_id": "1", "author": "stark",  "score": 80, "age": 18 }{ "_id": "2", "author": "bob",    "score": 60, "age": 18 }{ "_id": "3", "author": "li",     "score": 55, "age": 19 }{ "_id": "4", "author": "jimmy",  "score": 60, "age": 22 }{ "_id": "5", "author": "justan", "score": 95, "age": 33 }
          db.collection('articles')  .aggregate()  .sort({      age: -1,      score: -1  })  .end()

          上面的代码在 students 集合中进行聚合搜索,并且将结果排序,首先根据 age 字段降序排列,然后再根据 score 字段进行降序排列。

          输出结果如下:

          { "_id": "5", "author": "justan", "score": 95, "age": 33 }{ "_id": "4", "author": "jimmy",  "score": 60, "age": 22 }{ "_id": "3", "author": "li",     "score": 55, "age": 19 }{ "_id": "1", "author": "stark",  "score": 80, "age": 18 }{ "_id": "2", "author": "bob",    "score": 60, "age": 18 }


          Aggregate.sortByCount(object:Object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。根据传入的表达式,将传入的集合进行分组(group)。然后计算不同组的数量,并且将这些组按照它们的数量进行排序,返回排序后的结果。

          参数

          object: Object

          返回值

          Aggregate

          API 说明

          sortByCount 的调用方式如下:

          sortByCount(<表达式>)

          表达式的形式是:$ + 指定字段。请注意:不要漏写 $ 符号。

          示例

          统计基础类型

          假设集合 passages 的记录如下:

          { "category": "Web" }{ "category": "Web" }{ "category": "Life" }

          下面的代码就可以统计文章的分类信息,并且计算每个分类的数量。即对 category 字段执行 sortByCount 聚合操作。

          db.collection('passages')  .aggregate()  .sortByCount('$category')  .end()

          返回的结果如下所示:Web 分类下有2篇文章,Life 分类下有1篇文章。

          { "_id": "Web", "count": 2 }{ "_id": "Life", "count": 1 }

          解构数组类型

          假设集合 passages 的记录如下:tags 字段对应的值是数组类型。

          { "tags": [ "JavaScript", "C#" ] }{ "tags": [ "Go", "C#" ] }{ "tags": [ "Go", "Python", "JavaScript" ] }

          如何统计文章的标签信息,并且计算每个标签的数量?因为 tags 字段对应的数组,所以需要借助 unwind 操作解构 tags 字段,然后再调用 sortByCount。

          下面的代码实现了这个功能:

          db.collection('passages')  .aggregate()  .unwind(`$tags`)  .sortByCount(`$tags`)  .end()

          返回的结果如下所示:

          { "_id": "Go", "count": 2 }{ "_id": "C#", "count": 2 }{ "_id": "JavaScript", "count": 2 }{ "_id": "Python", "count": 1 }


          Aggregate.unwind(value:string|object): Aggregate

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合阶段。使用指定的数组字段中的每个元素,对文档进行拆分。拆分后,文档会从一个变为一个或多个,分别对应数组的每个元素。

          参数

          value: string|object

          返回值

          Aggregate

          API 说明

          使用指定的数组字段中的每个元素,对文档进行拆分。拆分后,文档会从一个变为一个或多个,分别对应数组的每个元素。

          unwind 有两种使用形式:

          1. 参数是一个字段名
          unwind(<字段名>)
          1. 参数是一个对象
          unwind({    path: <字段名>,    includeArrayIndex: <string>,    preserveNullAndEmptyArrays: <boolean>})
          字段类型说明
          pathstring想要拆分的数组的字段名,需要以 $ 开头。
          includeArrayIndexstring可选项,传入一个新的字段名,数组索引会保存在这个新的字段上。新的字段名不能以 $ 开头。
          preserveNullAndEmptyArraysboolean如果为 true,那么在 path 对应的字段为 null、空数组或者这个字段不存在时,依然会输出这个文档;如果为 falseunwind 将不会输出这些文档。默认为 false

          示例

          拆分数组

          假设我们有一个 products 集合,包含数据如下:

          { "_id": "1", "product": "tshirt", "size": ["S", "M", "L"] }{ "_id": "2", "product": "pants", "size": [] }{ "_id": "3", "product": "socks", "size": null }{ "_id": "4", "product": "trousers", "size": ["S"] }{ "_id": "5", "product": "sweater", "size": ["M", "L"] }

          我们根据 size 字段对这些文档进行拆分

          db.collection('products')  .aggregate()  .unwind('$size')  .end()

          输出如下:

          { "_id": "1", "product": "tshirt", "size": "S" }{ "_id": "1", "product": "tshirt", "size": "M" }{ "_id": "1", "product": "tshirt", "size": "L" }{ "_id": "4", "product": "trousers", "size": "S" }{ "_id": "5", "product": "sweater", "size": "M" }{ "_id": "5", "product": "sweater", "size": "L" }

          拆分后,保留原数组的索引

          我们根据 size 字段对文档进行拆分后,想要保留原数组索引在新的 index 字段中。

          db.collection('products')  .aggregate()  .unwind({      path: '$size',      includeArrayIndex: 'index'  })  .end()

          输出如下:

          { "_id": "1", "product": "tshirt", "size": "S", "index": 0 }{ "_id": "1", "product": "tshirt", "size": "M", "index": 1 }{ "_id": "1", "product": "tshirt", "size": "L", "index": 2 }{ "_id": "4", "product": "trousers", "size": "S", "index": 0 }{ "_id": "5", "product": "sweater", "size": "M", "index": 0 }{ "_id": "5", "product": "sweater", "size": "L", "index": 1 }

          保留字段为空的文档

          注意到我们的集合中有两行特殊的空值数据:

          ...{ "_id": "2", "product": "pants", "size": [] }{ "_id": "3", "product": "socks", "size": null }...

          如果想要在输出中保留 size 为空数组、null,或者 size 字段不存在的文档,可以使用 preserveNullAndEmptyArrays 参数

          db.collection('products')  .aggregate()  .unwind({      path: '$size',      preserveNullAndEmptyArrays: true  })  .end()

          输出如下:

          { "_id": "1", "product": "tshirt", "size": "S" }{ "_id": "1", "product": "tshirt", "size": "M" }{ "_id": "1", "product": "tshirt", "size": "L" }{ "_id": "2", "product": "pants", "size": null }{ "_id": "3", "product": "socks", "size": null }{ "_id": "4", "product": "trousers", "size": "S" }{ "_id": "5", "product": "sweater", "size": "M" }{ "_id": "5", "product": "sweater", "size": "L" }


          Aggregate.end(): Promise<Object>

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          标志聚合操作定义完成,发起实际聚合操作

          返回值

          Promise.<Object>

          属性类型说明
          listArray.<any>聚合结果列表

          示例代码

          const $ = db.command.aggregatedb.collection('books').aggregate()  .group({    // 按 category 字段分组    _id: '$category',    // 让输出的每组记录有一个 avgSales 字段,其值是组内所有记录的 sales 字段的平均值    avgSales: $.avg('$sales')  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

          小程序端兼容支持 callback 风格

          const $ = db.command.aggregatedb.collection('books').aggregate()  .group({    // 按 category 字段分组    _id: '$category',    // 让输出的每组记录有一个 avgSales 字段,其值是组内所有记录的 sales 字段的平均值    avgSales: $.avg('$sales')  })  .end({    success: function(res) {      console.log(res)    },    fail: function(err) {      console.error(err)    }  })


          Geo

          数据库地理位置结构集


          方法:

          Geo.Point(longitude: number, latitude: number): GeoPoint

          支持端:小程序 , 云函数 , Web

          构造一个地理位置 ”点“。方法接受两个必填参数,第一个是经度(longitude),第二个是纬度(latitude),务必注意顺序。

          参数

          longitude: number

          经度

          latitude: number

          纬度

          返回值

          GeoPoint

          索引

          如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: db.Geo.Point(113, 23)  }}).then(console.log).catch(console.error)

          除了使用接口构造一个点外,也可以使用等价的 GeoJSON 的 点 (Point) 的 JSON 表示,其格式如下:

          {  "type": "Point",  "coordinates": [longitude, latitude] // 数字数组:[经度, 纬度]}

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'Point',      coordinates: [113, 23]    }  }}).then(console.log).catch(console.error)


          Geo.LineString(points: GeoPoint[]): GeoPoint

          支持端:小程序 2.6.3, 云函数

          构造一个地理位置的 ”线“。一个线由两个或更多的点有序连接组成。

          参数

          points: GeoPoint[]

          “点” 数组

          返回值

          GeoPoint

          索引

          如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: db.Geo.LineString([      db.Geo.Point(113, 23),      db.Geo.Point(120, 50),      // ... 可选更多点    ])  }}).then(console.log).catch(console.error)

          除了使用接口构造一条 LineString 外,也可以使用等价的 GeoJSON 的 线 (LineString) 的 JSON 表示,其格式如下:

          {  "type": "LineString",  "coordinates": [    [p1_lng, p1_lat],    [p2_lng, p2_lng]    // ... 可选更多点  ]}

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'LineString',      coordinates: [        [113, 23],        [120, 50]      ]    }  }}).then(console.log).catch(console.error)


          Geo.Polygon(lineStrings: GeoLineString[]): GeoPolygon

          支持端:小程序 2.6.3, 云函数

          构造一个地理位置 ”多边形“

          参数

          lineStrings: GeoLineString[]

          “线” 数组

          返回值

          GeoPolygon

          索引

          如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

          说明

          一个多边形由一个或多个线性环(Linear Ring)组成,一个线性环即一个闭合的线段。一个闭合线段至少由四个点组成,其中最后一个点和第一个点的坐标必须相同,以此表示环的起点和终点。如果一个多边形由多个线性环组成,则第一个线性环表示外环(外边界),接下来的所有线性环表示内环(即外环中的洞,不计在此多边形中的区域)。如果一个多边形只有一个线性环组成,则这个环就是外环。

          多边形构造规则:

          1. 第一个线性环必须是外环
          2. 外环不能自交
          3. 所有内环必须完全在外环内
          4. 各个内环间不能相交或重叠,也不能有共同的边
          5. 外环应为逆时针,内环应为顺时针

          示例代码

          示例代码:单环多边形

          const { Polygon, LineString, Point } = db.Geodb.collection('todos').add({  data: {    description: 'eat an apple',    location: Polygon([      LineString([        Point(0, 0),        Point(3, 2),        Point(2, 3),        Point(0, 0)      ])    ])  }}).then(console.log).catch(console.error)

          示例代码:含一个外环和一个内环的多边形

          const { Polygon, LineString, Point } = db.Geodb.collection('todos').add({  data: {    description: 'eat an apple',    location: Polygon([      // 外环      LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),      // 内环      LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])    ])  }}).then(console.log).catch(console.error)

          除了使用接口构造一个 Polygon 外,也可以使用等价的 GeoJSON 的 多边形 (Polygon) 的 JSON 表示,其格式如下:

          {  "type": "Polygon",  "coordinates": [    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 外环    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 可选内环 1    ...    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 可选内环 n  ]}

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'Polygon',      coordinates: [        [ [0, 0], [30, 20], [20, 30], [0, 0] ],        [ [10, 10], [16, 14], [14, 16], [10, 10]]      ]    }  }}).then(console.log).catch(console.error)


          Geo.MultiPoint(points: GeoPoint[]): GeoMultiPoint

          支持端:小程序 2.6.3, 云函数

          构造一个地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

          参数

          points: GeoPoint[]

          “点” 数组

          返回值

          GeoMultiPoint

          索引

          如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: db.Geo.MultiPoint([      db.Geo.Point(113, 23),      db.Geo.Point(120, 50),      // ... 可选更多点    ])  }}).then(console.log).catch(console.error)

          除了使用接口构造 MultiPoint 外,也可以使用等价的 GeoJSON 的 点集合 (MultiPoint) 的 JSON 表示,其格式如下:

          {  "type": "MultiPoint",  "coordinates": [    [p1_lng, p1_lat],    [p2_lng, p2_lng]    // ... 可选更多点  ]}

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'MultiPoint',      coordinates: [        [113, 23],        [120, 50]      ]    }  }}).then(console.log).catch(console.error)


          Geo.MultiPoint(points: GeoPoint[]): GeoMultiPoint

          支持端:小程序 2.6.3, 云函数

          构造一个地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

          参数

          points: GeoPoint[]

          “点” 数组

          返回值

          GeoMultiPoint

          索引

          如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: db.Geo.MultiPoint([      db.Geo.Point(113, 23),      db.Geo.Point(120, 50),      // ... 可选更多点    ])  }}).then(console.log).catch(console.error)

          除了使用接口构造 MultiPoint 外,也可以使用等价的 GeoJSON 的 点集合 (MultiPoint) 的 JSON 表示,其格式如下:

          {  "type": "MultiPoint",  "coordinates": [    [p1_lng, p1_lat],    [p2_lng, p2_lng]    // ... 可选更多点  ]}

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'MultiPoint',      coordinates: [        [113, 23],        [120, 50]      ]    }  }}).then(console.log).catch(console.error)


          Geo.MultiLineString(lineStrings: GeoLineString[]): GeoMultiLineString

          支持端:小程序 2.6.3, 云函数

          构造一个地理位置 ”线“ 集合。一个线集合由多条线组成。

          参数

          lineStrings: GeoLineString[]

          “线” 数组

          返回值

          GeoMultiLineString

          索引

          如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

          示例代码

          const { LineString, MultiLineString, Point } = db.Geodb.collection('todos').add({  data: {    description: 'eat an apple',    location: MultiLineString([      LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),      LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])    ])  }}).then(console.log).catch(console.error)

          除了使用接口构造一个 MultiLineString 外,也可以使用等价的 GeoJSON 的 线集合 (MultiLineString) 的 JSON 表示,其格式如下:

          {  "type": "MultiLineString",  "coordinates": [    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],    ...    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]  ]}

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'MultiLineString',      coordinates: [        [ [0, 0], [3, 3] ],        [ [5, 10], [20, 30] ]      ]    }  }}).then(console.log).catch(console.error)


          Geo.MultiPolygon(polygons: GeoPolygon[]): GeoMultiPolygon

          支持端:小程序 2.6.3, 云函数

          构造一个地理位置 ”多边形“ 集合。一个多边形集合由多个多边形组成。

          参数

          polygons: GeoPolygon[]

          “多边形” 数组

          返回值

          GeoMultiPolygon

          索引

          如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

          说明

          多边形集合由多个多边形组成。一个多边形由一个或多个线性环(Linear Ring)组成,一个线性环即一个闭合的线段。一个闭合线段至少由四个点组成,其中最后一个点和第一个点的坐标必须相同,以此表示环的起点和终点。如果一个多边形由多个线性环组成,则第一个线性环表示外环(外边界),接下来的所有线性环表示内环(即外环中的洞,不计在此多边形中的区域)。如果一个多边形只有一个线性环组成,则这个环就是外环。

          多边形构造规则:

          1. 第一个线性环必须是外环
          2. 外环不能自交
          3. 所有内环必须完全在外环内
          4. 各个内环间不能相交或重叠,也不能有共同的边
          5. 外环应为逆时针,内环应为顺时针

          示例代码

          示例代码

          const { MultiPolygon, Polygon, LineString, Point } = db.Geodb.collection('todos').add({  data: {    description: 'eat an apple',    location: MultiPolygon([      Polygon([        LineString([ Point(50, 50), Point(60, 80), Point(80, 60), Point(50, 50) ]),      ]),      Polygon([        LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),        LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])      ]),    ])  }}).then(console.log).catch(console.error)

          除了使用接口构造一个 MultiPolygon 外,也可以使用等价的 GeoJSON 的 多边形 (MultiPolygon) 的 JSON 表示,其格式如下:

          {  "type": "MultiPolygon",  "coordinates": [    // polygon 1    [      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],      ...      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]    ],    ...    // polygon n    [      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],      ...      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]    ],  ]}

          示例代码

          db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'MultiPolygon',      coordinates: [        [          [ [50, 50], [60, 80], [80, 60], [50, 50] ]        ],        [          [ [0, 0], [30, 20], [20, 30], [0, 0] ],          [ [10, 10], [16, 14], [14, 16], [10, 10]]        ]      ]    }  }}).then(console.log).catch(console.error)



          类型:

          GeoPoint

          地理位置 “点”

          属性

          longitude: number

          经度

          latitude: number

          纬度

          方法

          GeoPoint.toJSON(): Object

          返回相应的 GeoJSON 结构的对象


          GeoLineString

          地理位置的 ”线“。一个线由两个或更多的点有序连接组成。

          属性

          points: GeoPoint[]

          “点” 数组

          方法

          GeoLineString.toJSON(): Object

          返回相应的 GeoJSON 结构的对象


          GeoPolygon

          地理位置 ”多边形“

          属性

          lines: GeoLineString[]

          “线” 数组

          方法

          GeoPolygon.toJSON(): Object

          返回相应的 GeoJSON 结构的对象


          GeoMultiPoint

          地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

          属性

          points: GeoPoint[]

          “点” 数组

          方法

          GeoMultiPoint.toJSON(): Object

          返回相应的 GeoJSON 结构的对象


          GeoMultiLineString

          地理位置 ”线“ 集合。一个线集合由多条线组成。

          属性

          lines: GeoLineString[]

          “线” 数组

          方法

          GeoMultiLineString.toJSON(): Object

          返回相应的 GeoJSON 结构的对象


          GeoMultiPolygon

          地理位置 ”多边形“ 集合。一个多边形集合由多个多边形组成。

          属性

          polygons: GeoPolygon[]

          “多边形” 数组

          方法

          GeoMultiPolygon.toJSON(): Object

          返回相应的 GeoJSON 结构的对象




          Transaction

          数据库事务操作对象


          方法:

          Transaction.collection(name: string): Collection

          支持端:云函数

          事务中获取集合的引用。方法接受一个 name 参数,指定需引用的集合名称。

          参数

          name: string

          集合名称

          返回值

          Collection

          集合引用

          注意事项

          在事务中仅能进行单记录操作,也就是不能使用 where、aggregate 接口,可以使用的接口如下:

          collection       获取集合引用|-- add          新增记录|-- doc          获取记录引用    |-- get      获取记录内容    |-- update   更新记录内容    |-- set      替换记录内容    |-- remove   删除记录



          Transaction.rollback(reason: any): Promise<void>

          支持端:云函数

          终止并回滚事务

          参数

          reason: any

          终止后,希望在 runTransaction 返回的 Promise reject 时接收到的值。

          返回值

          Promise.<void>

          终止完成

          示例代码

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database({  throwOnNotFound: false,})const _ = db.commandtry {  const result = await db.runTransaction(async transaction => {    const aaaRes = await transaction.collection('account').doc('aaa').get()    // ...    // 终止事务    await transaction.rollback(-100)  })} catch (e) {  // e === -100  console.error(`transaction error`, e)}


          Transaction.commit(reason: any): Promise<void>

          支持端:云函数

          提交事务

          参数

          reason: any

          终止后,希望在 runTransaction 返回的 Promise reject 时接收到的值。

          返回值

          Promise.<void>

          提交完成

          示例代码

          const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database({  throwOnNotFound: false,})const _ = db.commandexports.main = async (event) => {  try {    const transaction = await db.startTransaction()    // ...    await transaction.collection('account').doc('aaa').update({      data: {        amount: 100      }    })    // 提交事务    await transaction.commit()    return {      success: true,    }  } catch (e) {    console.error(`transaction error`, e)    return {      success: false,      error: e,    }  }}

          API 列表:

          transaction|-- collection       获取集合引用|   |-- doc          获取记录引用|   |   |-- get      获取记录内容|   |   |-- update   更新记录内容|   |   |-- set      替换记录内容|   |   |-- remove   删除记录|   |-- add          新增记录|-- rollback         终止事务并回滚|-- commit           提交事务(仅在使用 startTransaction 时可调用)


          Command

          数据库操作符,通过 db.command 获取

          属性

          AggregateCommand aggregate

          聚合操作符

          方法

          Command.addToSet(value: any|Object): Command

          数组更新操作符。原子操作。给定一个或多个元素,除非数组中已存在该元素,否则添加进数组。

          Command.all(values: any[]): Command

          数组查询操作符。用于数组字段的查询筛选条件,要求数组字段中包含给定数组的所有元素。

          Command.and(expressions: any[]): Command

          查询操作符,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

          Command.bit(object: Object): Command

          更新操作符。对字段进行位运算,可以进行 and/or/xor 运算。

          Command.elemMatch(condition: Object|Command): Command

          用于数组字段的查询筛选条件,要求数组中包含至少一个满足 elemMatch 给定的所有条件的元素

          Command.eq(value: any): Command

          查询筛选条件,表示字段等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

          Command.exists(value: boolean): Command

          判断字段是否存在

          Command.expr(aggregateExpression: Expression): Command

          查询操作符,用于在查询语句中使用聚合表达式,方法接收一个参数,该参数必须为聚合表达式

          Command.geoIntersects(options: Object): Command

          找出给定的地理位置图形相交的记录

          Command.geoNear(options: Object): Command

          按从近到远的顺序,找出字段值在给定点的附近的记录。

          Command.geoWithin(options: Object): Command

          找出字段值在指定区域内的记录,无排序。指定的区域必须是多边形(Polygon)或多边形集合(MultiPolygon)。

          Command.gt(value: any): Command

          查询筛选操作符,表示需大于指定值。可以传入 Date 对象用于进行日期比较。

          Command.gte(value: any): Command

          查询筛选操作符,表示需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

          Command.in(value: any[]): Command

          查询筛选操作符,表示要求值在给定的数组内。

          Command.inc(value: number): Command

          更新操作符,原子操作,用于指示字段自增

          Command.lt(value: any): Command

          查询筛选操作符,表示需小于指定值。可以传入 Date 对象用于进行日期比较。

          Command.lte(value: any): Command

          查询筛选操作符,表示需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

          Command.max(value: any): Command

          更新操作符,给定一个值,只有该值大于字段当前值才进行更新。

          Command.min(value: any): Command

          更新操作符,给定一个值,只有该值小于字段当前值才进行更新。

          Command.mod(divisor: number, remainder: number): Command

          查询筛选操作符,给定除数 divisor 和余数 remainder,要求字段作为被除数时 value % divisor = remainder。

          Command.mul(value: number): Command

          更新操作符,原子操作,用于指示字段自乘某个值

          Command.neq(value: any): Command

          查询筛选条件,表示字段不等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

          Command.nin(value: any[]): Command

          查询筛选操作符,表示要求值不在给定的数组内。

          Command.nor(expressions: any[]): Command

          查询操作符,用于表示逻辑 "都不" 的关系,表示需不满足指定的所有条件。如果记录中没有对应的字段,则默认满足条件。

          Command.not(command: Command): Command

          查询操作符,用于表示逻辑 "非" 的关系,表示需不满足指定的条件。

          Command.or(expressions: any[]): Command

          查询操作符,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

          Command.pop(): Command

          数组更新操作符,对一个值为数组的字段,将数组尾部元素删除

          Command.pull(value: any): Command

          数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值或查询条件的元素都移除掉。

          Command.pullAll(value: any): Command

          数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值的元素都移除掉。跟 pull 的差别在于只能指定常量值、传入的是数组。

          Command.push(values: Object): Command

          数组更新操作符。对一个值为数组的字段,往数组添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

          Command.remove(): Command

          更新操作符,用于表示删除某个字段。

          Command.rename(value: string): Command

          更新操作符,字段重命名。如果需要对嵌套深层的字段做重命名,需要用点路径表示法。不能对嵌套在数组里的对象的字段进行重命名。

          Command.set(value: any): Command

          更新操作符,用于设定字段等于指定值。

          Command.shift(): Command

          数组更新操作符,对一个值为数组的字段,将数组头部元素删除。

          Command.size(value: string): Command

          更新操作符,用于数组字段的查询筛选条件,要求数组长度为给定值

          Command.unshift(values: any[]): Command

          数组更新操作符,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。


          Command.and(expressions: any[]): Command

          支持端:小程序 , 云函数 , Web

          查询操作符,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

          参数

          expressions: any[]

          返回值

          Command

          使用说明

          and 有两种使用情况:

          1. 用在根查询条件

          此时需传入多个查询条件,表示需同时满足提供的多个完整查询条件

          const _ = db.commanddb.collection('todo').where(_.and([  {    progress: _.gt(50)  },  {    tags: 'cloud'  }])).get()

          但以上用 and 组成的查询条件是不必要的,因为传入的对象的各字段隐式组成了 “与” 的关系,上述条件等价于下方更简洁的写法:

          const _ = db.commanddb.collection('todo').where({  progress: _.gt(50),  tags: 'cloud'}).get()

          通常需要显示使用 and 是用在有跨字段或操作的时候,如以下表示 “progress 字段大于 50 或 tags 字段等于 cloud 或 tags 数组字段(如果 tags 是数组)中含有 cloud”:

          const _ = db.commanddb.collection('todo').where(_.and([  _.or({    progress: _.gt(50)  }),  _.or({    tags: 'cloud'  })])).get()

          2. 用在字段查询条件

          需传入多个查询操作符或常量,表示字段需满足或匹配给定的条件。

          如以下用前置写法的方式表示 "progress 字段值大于 50 且小于 100"

          const _ = db.commanddb.collection('todo').where({  progress: _.and(_.gt(50), _.lt(100))})

          还可以用后置写法的方式表示同样的条件:

          const _ = db.commanddb.collection('todo').where({  progress: _.gt(50).and(_.lt(100))})

          注意 Command 默认也可以直接链式调用其他 Command,默认表示多个 Command 的与操作,因此上述代码还可以精简为:

          const _ = db.commanddb.collection('todo').where({  progress: _.gt(50).lt(100)})

          调用风格

          方法接收两种传参方式,一是传入一个数组参数,二是传入多个参数,效果一样。

          // 传入数组function and(expressions: Expression[]): Command// 传入多参数function and(...expressions: Expression[]): Command



          Command.or(expressions: any[]): Command

          支持端:小程序 , 云函数 , Web

          查询操作符,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

          参数

          expressions: any[]

          返回值

          Command

          字段值的或操作

          字段值的 “或” 操作指的是指定一个字段值为多个值之一即可。

          如筛选出进度大于 80 或小于 20 的 todo:

          流式写法:

          const _ = db.commanddb.collection('todo').where({  progress: _.gt(80).or(_.lt(20))})

          前置写法:

          const _ = db.commanddb.collection('todo').where({  progress: _.or(_.gt(80), _.lt(20))})

          前置写法也可接收一个数组:

          const _ = db.commanddb.collection('todo').where({  progress: _.or([_.gt(80), _.lt(20)])})

          跨字段的或操作

          跨字段的 “或” 操作指条件 “或”,相当于可以传入多个 where 语句,满足其中一个即可。

          如筛选出进度大于 80 或已标为已完成的 todo:

          const _ = db.commanddb.collection('todo').where(_.or([  {    progress: _.gt(80)  },  {    done: true  }]))

          调用风格

          方法接收两种传参方式,一是传入一个数组参数,二是传入多个参数,效果一样。

          // 传入数组function or(expressions: Expression[]): Command// 传入多参数function or(...expressions: Expression[]): Command

          Command.not(command: Command): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          查询操作符,用于表示逻辑 "非" 的关系,表示需不满足指定的条件。

          参数

          command: Command

          返回值

          Command

          示例

          如筛选出进度不等于100的 todo:

          const _ = db.commanddb.collection('todo').where({  progress: _.not(_.eq(100))})

          not 也可搭配其他逻辑指令使用,包括 and, or, nor, not,如 or:

          const _ = db.commanddb.collection('todo').where({  progress: _.not(_.or([_.lt(50), _.eq(100)]))})

          Command.nor(expressions: any[]): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          查询操作符,用于表示逻辑 "都不" 的关系,表示需不满足指定的所有条件。如果记录中没有对应的字段,则默认满足条件。

          参数

          expressions: any[]

          返回值

          Command

          示例 1

          筛选出进度既不小于20又不大于80的 todo :

          const _ = db.commanddb.collection('todo').where({  progress: _.nor([_.lt(20), _.gt(80)])})

          以上同时会筛选出不存在 progress 字段的记录,如果要要求 progress 字段存在,可以用 exists 指令:

          const _ = db.commanddb.collection('todo').where({  progress: _.exists().nor([_.lt(20), _.gt(80)])  // 等价于以下非链式调用的写法:  // progress: _.exists().and(_.nor([_.lt(20), _.gt(80)]))}).get()

          示例 2

          筛选出 progress 不小于 20 且 tags 数组不包含 miniprogram 字符串的记录:

          const _ = db.commanddb.collection('todo').where(_.nor([{  progress: _.lt(20),}, {  tags: 'miniprogram',}])).get()

          以上会筛选出满足以下条件之一的记录:

          1. progress 不小于 20 且 tags 数组不包含 miniprogram 字符串
          2. progress 不小于 20 且 tags 字段不存在
          3. progress 字段不存在 且 tags 数组不包含 miniprogram 字符串
          4. progress 不小于 20 且 tags 字段不存在

          如果要求 progress 和 tags 字段存在,可以用 exists 指令:

          const _ = db.commanddb.collection('todo').where(  _.nor([{    progress: _.lt(20),  }, {    tags: 'miniprogram',  }])  .and({    progress: _.exists(true),    tags: _.exists(true),  }))

          调用风格

          方法接收两种传参方式,一是传入一个数组参数,二是传入多个参数,效果一样。

          // 传入数组function nor(expressions: Expression[]): Command// 传入多参数function nor(...expressions: Expression[]): Command


          Command.eq(value: any): Command

          支持端:小程序 , 云函数 , Web

          查询筛选条件,表示字段等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

          参数

          value: any

          返回值

          Command

          使用说明

          比如筛选出所有自己发表的文章,除了用传对象的方式:

          const openID = 'xxx'db.collection('articles').where({  _openid: openID})

          还可以用指令:

          const _ = db.commandconst openID = 'xxx'db.collection('articles').where({  _openid: _.eq(openid)})

          注意 eq 指令比对象的方式有更大的灵活性,可以用于表示字段等于某个对象的情况,比如:

          // 这种写法表示匹配 stat.publishYear == 2018 且 stat.language == 'zh-CN'db.collection('articles').where({  stat: {    publishYear: 2018,    language: 'zh-CN'  }})// 这种写法表示 stat 对象等于 { publishYear: 2018, language: 'zh-CN' }const _ = db.commanddb.collection('articles').where({  stat: _.eq({    publishYear: 2018,    language: 'zh-CN'  })})

          Command.neq(value: any): Command

          支持端:小程序 , 云函数 , Web

          查询筛选条件,表示字段不等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

          参数

          value: any

          返回值

          Command

          使用说明

          表示字段不等于某个值,和 eq 相反


          Command.lt(value: any): Command

          支持端:小程序 , 云函数 , Web

          查询筛选操作符,表示需小于指定值。可以传入 Date 对象用于进行日期比较。

          参数

          value: any

          返回值

          Command

          示例代码

          找出进度小于 50 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.lt(50)}).get({  success: console.log,  fail: console.error})

          Command.lte(value: any): Command

          支持端:小程序 , 云函数 , Web

          查询筛选操作符,表示需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

          参数

          value: any

          返回值

          Command

          示例代码

          找出进度小于或等于 50 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.lte(50)}).get({  success: console.log,  fail: console.error})

          Command.gt(value: any): Command

          支持端:小程序 , 云函数 , Web

          查询筛选操作符,表示需大于指定值。可以传入 Date 对象用于进行日期比较。

          参数

          value: any

          返回值

          Command

          示例代码

          找出进度大于 50 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.gt(50)}).get({  success: console.log,  fail: console.error})

          Command.gte(value: any): Command

          支持端:小程序 , 云函数 , Web

          查询筛选操作符,表示需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

          参数

          value: any

          返回值

          Command

          示例代码

          找出进度大于或等于 50 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.gte(50)}).get({  success: console.log,  fail: console.error})

          Command.in(value: any[]): Command

          支持端:小程序 , 云函数 , Web

          查询筛选操作符,表示要求值在给定的数组内。

          参数

          value: any[]

          返回值

          Command

          示例代码

          找出进度为 0 或 100 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.in([0, 100])}).get({  success: console.log,  fail: console.error})

          Command.nin(value: any[]): Command

          支持端:小程序 , 云函数 , Web

          查询筛选操作符,表示要求值不在给定的数组内。

          参数

          value: any[]

          返回值

          Command

          示例代码

          找出进度不是 0 或 100 的 todo

          const _ = db.commanddb.collection('todos').where({  progress: _.nin([0, 100])}).get({  success: console.log,  fail: console.error})


          Command.exists(value: boolean): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          判断字段是否存在

          参数

          value: boolean

          返回值

          Command

          示例代码

          找出存在 tags 字段的记录

          const _ = db.commanddb.collection('todos').where({  tags: _.exists(true)}).get({  success: console.log,  fail: console.error})

          Command.mod(divisor: number, remainder: number): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          查询筛选操作符,给定除数 divisor 和余数 remainder,要求字段作为被除数时 value % divisor = remainder。

          参数

          divisor: number

          remainder: number

          返回值

          Command

          示例代码

          找出进度为 10 的倍数的字段的记录

          const _ = db.commanddb.collection('todos').where({  progress: _.mod(10, 0)}).get({  success: console.log,  fail: console.error})


          Command.all(values: any[]): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          数组查询操作符。用于数组字段的查询筛选条件,要求数组字段中包含给定数组的所有元素。

          参数

          values: any[]

          返回值

          Command

          示例代码 1:普通数组

          找出 tags 数组字段同时包含 cloud 和 database 的记录

          const _ = db.commanddb.collection('todos').where({  tags: _.all(['cloud', 'database'])}).get({  success: console.log,  fail: console.error})

          示例代码 2:对象数组

          如果数组元素是对象,则可以用 _.elemMatch 匹配对象的部分字段

          假设有字段 places 定义如下:

          {  "type": string  "area": number  "age": number}

          找出数组字段中至少同时包含一个满足 “area 大于 100 且 age 小于 2” 的元素和一个满足 “type 为 mall 且 age 大于 5” 的元素

          const _ = db.commanddb.collection('todos').where({  places: _.all([    _.elemMatch({      area: _.gt(100),      age: _.lt(2),    }),    _.elemMatch({      name: 'mall',      age: _.gt(5),    }),  ]),}).get({  success: console.log,  fail: console.error,})




          Command.elemMatch(condition: Object|Command): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          用于数组字段的查询筛选条件,要求数组中包含至少一个满足 elemMatch 给定的所有条件的元素

          参数

          condition: Object|Command

          匹配条件

          返回值

          Command

          示例代码:数组是对象数组的情况

          假设集合示例数据如下:

          {  "_id": "a0",  "city": "x0",  "places": [{    "type": "garden",    "area": 300,    "age": 1  }, {    "type": "theatre",    "area": 50,    "age": 15  }]}

          找出 places 数组字段中至少同时包含一个满足 “area 大于 100 且 age 小于 2” 的元素

          const _ = db.commanddb.collection('todos').where({  places: _.elemMatch({    area: _.gt(100),    age: _.lt(2),  })}).get()

          注意*:如果不使用 elemMatch 而直接如下指定条件,则表示的是 places 数组字段中至少有一个元素的 area 字段大于 100 且 places 数组字段中至少有一个元素的 age 字段小于 2:

          const _ = db.commanddb.collection('todos').where({  places: {    area: _.gt(100),    age: _.lt(2),  }}).get()

          示例代码:数组元素都是普通数据类型的情况

          假设集合示例数据如下:

          {  "_id": "a0",  "scores": [60, 80, 90]}

          找出 scores 数组字段中至少同时包含一个满足 “大于 80 且小于 100” 的元素

          const _ = db.commanddb.collection('todos').where({  places: _.elemMatch(_.gt(80).lt(100))}).get()

          Command.size(value: string): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          更新操作符,用于数组字段的查询筛选条件,要求数组长度为给定值

          参数

          value: string

          返回值

          Command

          示例

          找出 tags 数组字段长度为 2 的所有记录

          const _ = db.commanddb.collection('todos').where({  places: _.size(2)}).get({  success: console.log,  fail: console.error,})


          Command.geoNear(options: Object): Command

          支持端:小程序 , 云函数 , Web

          按从近到远的顺序,找出字段值在给定点的附近的记录。

          参数

          options: Object

          属性类型默认值必填说明
          geometryGeoPoint地理位置点 (Point)
          maxDistancenumber选填,最大距离,单位为米
          minDistancenumber选填,最小距离,单位为米

          返回值

          Command

          索引要求

          需对查询字段建立地理位置索引

          示例代码

          找出离给定位置 1 公里到 5 公里范围内的记录

          const _ = db.commanddb.collection('restaurants').where({  location: _.geoNear({    geometry: db.Geo.Point(113.323809, 23.097732),    minDistance: 1000,    maxDistance: 5000,  })}).get()

          Command.geoWithin(options: Object): Command

          支持端:小程序 , 云函数 , Web

          找出字段值在指定区域内的记录,无排序。指定的区域必须是多边形(Polygon)或多边形集合(MultiPolygon)。

          参数

          options: Object

          属性类型默认值必填说明
          geometryObject地理信息结构,Polygon,MultiPolygon,或 { centerSphere }

          返回值

          Command

          索引要求

          需对查询字段建立地理位置索引

          示例代码 1:给定多边形

          const _ = db.commandconst { Point, LineString, Polygon } = db.Geodb.collection('restaurants').where({  location: _.geoWithin({    geometry: Polygon([      LineString([        Point(0, 0),        Point(3, 2),        Point(2, 3),        Point(0, 0)      ])    ]),  })})

          示例代码 2:给定圆形

          可以不用 geometry 而用 centerSphere 构建一个圆形。

          centerShpere 从公共库 2.8.3 开始支持

          centerSphere 对应的值的定义是:[ [经度, 纬度], 半径 ]

          半径需以弧度计,比如需要 10km 的半径,则用距离除以地球半径 6378.1km 得出的数字。

          const _ = db.commanddb.collection('restaurants').where({  location: _.geoWithin({    centerSphere: [      [-88, 30],      10 / 6378.1,    ]  })})

          Command.geoIntersects(options: Object): Command

          支持端:小程序 , 云函数 , Web

          找出给定的地理位置图形相交的记录

          参数

          options: Object

          属性类型默认值必填说明
          geometryObject地理信息结构,Point

          返回值

          Command

          索引要求

          需对查询字段建立地理位置索引

          示例代码:找出和一个多边形相交的记录

          const _ = db.commandconst { Point, LineString, Polygon } = db.Geodb.collection('restaurants').where({  location: _.geoIntersects({    geometry: Polygon([      LineString([        Point(0, 0),        Point(3, 2),        Point(2, 3),        Point(0, 0)      ])    ]),  })})


          Command.expr(aggregateExpression: Expression): Command

          支持端:云函数 1.4.0

          查询操作符,用于在查询语句中使用聚合表达式,方法接收一个参数,该参数必须为聚合表达式

          参数

          aggregateExpression: Expression

          要添加进数组的一个或多个元素

          返回值

          Command

          使用说明

          1. expr 可用于在聚合 match 流水线阶段中引入聚合表达式
          2. 如果聚合 match 阶段是在 lookup 阶段内,此时的 expr 表达式内可使用 lookup 中使用 let 参数定义的变量,具体示例可见 lookup 的 指定多个连接条件 例子
          3. expr 可用在普通查询语句(where)中引入聚合表达式

          示例代码 1:比较同一个记录中的两个字段

          假设 items 集合的数据结构如下:

          {  "_id": string,  "inStock": number, // 库存量  "ordered": number  // 被订量}

          找出被订量大于库存量的记录:

          const _ = db.commandconst $ = _.aggregatedb.collection('items').where(_.expr($.gt('$ordered', '$inStock'))).get()

          示例代码 2:与条件语句组合使用

          假设 items 集合的数据结构如下:

          {  "_id": string,  "price": number}

          假设加个小于等于 10 的打 8 折,大于 10 的打 5 折,让数据库查询返回打折后价格小于等于 8 的记录:

          const _ = db.commandconst $ = _.aggregatedb.collection('items').where(_.expr(  $.lt(    $.cond({      if: $.gte('$price', 10),      then: $.multiply(['$price', '0.5']),      else: $.multiply(['$price', '0.8']),    })    ,    8  )).get()


          Command.set(value: any): Command

          支持端:小程序 , 云函数 , Web

          更新操作符,用于设定字段等于指定值。

          参数

          value: any

          返回值

          Command

          使用说明

          这种方法相比传入纯 JS 对象的好处是能够指定字段等于一个对象

          示例

          // 以下方法只会更新 style.color 为 red,而不是将 style 更新为 { color: 'red' },即不影响 style 中的其他字段db.collection('todos').doc('doc-id').update({  data: {    style: {      color: 'red'    }  }})// 以下方法更新 style 为 { color: 'red', size: 'large' }db.collection('todos').doc('doc-id').update({  data: {    style: _.set({      color: 'red',      size: 'large'    })  }})

          Command.remove(): Command

          支持端:小程序 , 云函数 , Web

          更新操作符,用于表示删除某个字段。

          返回值

          Command

          示例代码

          删除 style 字段:

          const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    style: _.remove()  }})

          Command.inc(value: number): Command

          支持端:小程序 , 云函数 , Web

          更新操作符,原子操作,用于指示字段自增

          参数

          value: number

          自增量,可正可负

          返回值

          Command

          原子自增

          多个用户同时写,对数据库来说都是将字段自增,不会有后来者覆写前者的情况

          示例代码

          将一个 todo 的进度自增 10:

          const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    progress: _.inc(10)  }})

          Command.mul(value: number): Command

          支持端:小程序 , 云函数 , Web

          更新操作符,原子操作,用于指示字段自乘某个值

          参数

          value: number

          自乘量,可正可负

          返回值

          Command

          原子自乘

          多个用户同时写,对数据库来说都是将字段自乘,不会有后来者覆写前者的情况

          示例代码

          将一个 todo 的进度自乘 10:

          const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    progress: _.mul(10)  }})

          Command.min(value: any): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          更新操作符,给定一个值,只有该值小于字段当前值才进行更新。

          参数

          value: any

          返回值

          Command

          示例代码

          如果字段 progress > 50,则更新到 50

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    progress: _.min(50)  }})

          Command.max(value: any): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          更新操作符,给定一个值,只有该值大于字段当前值才进行更新。

          参数

          value: any

          返回值

          Command

          示例代码

          如果字段 progress < 50,则更新到 50

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    progress: _.max(50)  }})

          Command.rename(value: string): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          更新操作符,字段重命名。如果需要对嵌套深层的字段做重命名,需要用点路径表示法。不能对嵌套在数组里的对象的字段进行重命名。

          参数

          value: string

          返回值

          Command

          示例 1:重命名顶层字段

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    progress: _.rename('totalProgress')  }})

          示例 2:重命名嵌套字段

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    someObject: {      someField: _.rename('someObject.renamedField')    }  }})

          或:

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    'someObject.someField': _.rename('someObject.renamedField')  }})

          Command.bit(object: Object): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          更新操作符。对字段进行位运算,可以进行 and/or/xor 运算。

          参数

          object: Object

          属性类型默认值必填说明
          andnumber进行位与运算的整形
          ornumber进行位或运算的整形
          xornumber进行位异或运算的整形

          返回值

          Command

          使用说明

          and/or/xor 只能选其一

          示例代码

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    // 假设原来是 2,则运算后是 3    progress: _.bit({      or: 1    })  }})


          Command.push(values: Object): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          数组更新操作符。对一个值为数组的字段,往数组添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

          参数

          values: Object

          属性类型默认值必填说明
          eachArray.<any>要插入的所有元素
          positionnumber从哪个位置开始插入,不填则是尾部
          sortnumber对结果数组排序
          slicenumber限制结果数组长度

          返回值

          Command

          参数说明

          position 说明

          要求必须同时有 each 参数存在。

          非负数代表从数组开始位置数的位置,从 0 开始计。如果数值大于等于数组长度,则视为在尾部添加。负数代表从数组尾部倒数的位置,比如 -1 就代表倒数第二个元素的位置。如果负数数值的绝对值大于等于数组长度,则视为从数组头部添加。

          sort 说明

          要求必须同时有 each 参数存在。给定 1 代表升序,-1 代表降序。

          如果数组元素是记录,则用 { <字段>: 1 | -1 } 的格式表示根据记录中的什么字段做升降序排序。

          slice** 说明

          要求必须同时有 each 参数存在

          说明
          0将字段更新为空数组
          正数数组只保留前 n 个元素
          负数数组只保留后 n 个元素

          升级说明

          以上定义是从小程序 2.8.3 / 云函数 SDK 1.2.1 起支持,对于之前的版本,使用的是如下函数签名,新版中对旧版签名有兼容。

          旧版签名:传入一个数组,该数组的每个元素会被追加到字段数组的尾部

          function push(values: any[]): Command

          示例 1:尾部添加元素

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push(['mini-program', 'cloud'])  }})

          示例 2:从第二个位置开始插入

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: ['mini-program', 'cloud'],      position: 1,    })  }})

          示例 3:排序

          插入后对整个数组做排序

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: ['mini-program', 'cloud'],      sort: 1,    })  }})

          不插入,只对数组做排序

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: [],      sort: 1,    })  }})

          如果字段是对象数组,可以如下根据元素对象里的字段进行排序:

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: [        { name: 'miniprogram', weight: 8 },        { name: 'cloud', weight: 6 },      ],      sort: {        weight: 1,      },    })  }})

          示例 4:截断保留

          插入后只保留后 2 个元素

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: ['mini-program', 'cloud'],      slice: -2,    })  }})

          示例 5:在指定位置插入、然后排序、最后只保留前 2 个元素

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: ['mini-program', 'cloud'],      position: 1,      slice: 2,      sort: 1,    })  }})

          Command.pop(): Command

          支持端:小程序 , 云函数 , Web

          数组更新操作符,对一个值为数组的字段,将数组尾部元素删除

          返回值

          Command

          示例代码

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.pop()  }})

          Command.unshift(values: any[]): Command

          支持端:小程序 , 云函数 , Web

          数组更新操作符,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

          参数

          values: any[]

          返回值

          Command

          示例代码

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.unshift(['mini-program', 'cloud'])  }})

          Command.shift(): Command

          支持端:小程序 , 云函数 , Web

          数组更新操作符,对一个值为数组的字段,将数组头部元素删除。

          返回值

          Command

          示例代码

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.shift()  }})

          Command.pull(value: any): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值或查询条件的元素都移除掉。

          参数

          value: any

          值或查询条件

          返回值

          Command

          示例代码 1:根据常量匹配移除

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.pull('database')  }})

          示例代码 2:根据查询条件匹配移除

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.pull(_.in(['database', 'cloud']))  }})

          示例代码 3:对象数组时,根据查询条件匹配移除

          假设有字段 places 数组中的元素结构如下

          {  "type": string  "area": number  "age": number}
          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    places: _.pull({      area: _.gt(100),      age: _.lt(2),    })  }})

          示例代码 4:有嵌套对象的对象数组时,根据查询条件匹配移除

          假设有字段 cities 数组中的元素结构如下

          {  "name": string  "places": Place[]}

          Place 结构如下:

          {  "type": string  "area": number  "age": number}

          可用 elemMatch 匹配嵌套在对象数组里面的对象数组字段 places

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    cities: _.pull({      places: _.elemMatch({        area: _.gt(100),        age: _.lt(2),      })    })  }})

          Command.pullAll(value: any): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值的元素都移除掉。跟 pull 的差别在于只能指定常量值、传入的是数组。

          参数

          value: any

          值或查询条件

          返回值

          Command

          示例代码:根据常量匹配移除

          从 tags 中移除所有 database 和 cloud 字符串

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.pullAll(['database', 'cloud'])  }})

          Command.addToSet(value: any|Object): Command

          支持端:小程序 2.8.3, 云函数 1.2.1, Web

          数组更新操作符。原子操作。给定一个或多个元素,除非数组中已存在该元素,否则添加进数组。

          参数

          value: any|Object

          要添加进数组的一个或多个元素

          属性类型默认值必填说明
          eachArray.<any>数组,用于同时指定多个要插入数组的元素

          返回值

          Command

          示例代码 1:添加一个元素

          如果 tags 数组中不包含 database,添加进去

          const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.addToSet('database')  }})

          示例代码 2:添加多个元素

          需传入一个对象,其中有一个字段 each,其值为数组,每个元素就是要添加的元素

            const _ = db.command  db.collection('todos').doc('doc-id').update({    data: {      tags: _.addToSet({        each: ['database', 'cloud']      })    }  })


          AggregateCommand

          数据库聚合操作符,通过 db.command.aggregate 获取

          方法

          AggregateCommand.abs(value: Expression<number>): Object

          聚合操作符。返回一个数字的绝对值。

          AggregateCommand.add(value: Expression[]): Object

          聚合操作符。将数字相加或将数字加在日期上。如果数组中的其中一个值是日期,那么其他值将被视为毫秒数加在该日期上。

          AggregateCommand.addToSet(value: Expression): Object

          聚合操作符。聚合运算符。向数组中添加值,如果数组中已存在该值,不执行任何操作。它只能在 group stage 中使用。

          AggregateCommand.allElementsTrue(value: Expression[]): Object

          聚合操作符。输入一个数组,或者数组字段的表达式。如果数组中所有元素均为真值,那么返回 true,否则返回 false。空数组永远返回 true。

          AggregateCommand.and(value: Expression[]): Object

          聚合操作符。给定多个表达式,and 仅在所有表达式都返回 true 时返回 true,否则返回 false。

          AggregateCommand.anyElementTrue(value: Expression[]): Object

          聚合操作符。输入一个数组,或者数组字段的表达式。如果数组中任意一个元素为真值,那么返回 true,否则返回 false。空数组永远返回 false。

          AggregateCommand.arrayElemAt(value: Expression[]): Object

          聚合操作符。返回在指定数组下标的元素。

          AggregateCommand.arrayToObject(value: any): Object

          聚合操作符。将一个数组转换为对象。

          AggregateCommand.avg(value: Expression<number>): Object

          聚合操作符。返回一组集合中,指定字段对应数据的平均值。

          AggregateCommand.ceil(value: Expression<number>): Object

          聚合操作符。向上取整,返回大于或等于给定数字的最小整数。

          AggregateCommand.cmp(value: Expression[]): Object

          聚合操作符。给定两个值,返回其比较值:

          AggregateCommand.concat(value: Expression[]): Object

          聚合操作符。连接字符串,返回拼接后的字符串。

          AggregateCommand.concatArrays(value: Expression[]): Object

          聚合操作符。将多个数组拼接成一个数组。

          AggregateCommand.cond(value: any): Object

          聚合操作符。计算布尔表达式,返回指定的两个值其中之一。

          AggregateCommand.dateFromParts(value: any): Object

          聚合操作符。给定日期的相关信息,构建并返回一个日期对象。

          AggregateCommand.dateFromString(value: any): Object

          聚合操作符。将一个日期/时间字符串转换为日期对象

          AggregateCommand.dateToString(value: any): Object

          聚合操作符。根据指定的表达式将日期对象格式化为符合要求的字符串。

          AggregateCommand.dayOfMonth(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的天数(一个月中的哪一天),是一个介于 1 至 31 之间的数字。

          AggregateCommand.dayOfWeek(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的天数(一周中的第几天),是一个介于 1(周日)到 7(周六)之间的整数。

          AggregateCommand.dayOfYear(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的天数(一年中的第几天),是一个介于 1 到 366 之间的整数。

          AggregateCommand.divide(value: Expression[]): Object

          聚合操作符。传入被除数和除数,求商。

          AggregateCommand.eq(value: Expression[]): Object

          聚合操作符。匹配两个值,如果相等则返回 true,否则返回 false。

          AggregateCommand.exp(value: Expression<number>): Object

          聚合操作符。取 e(自然对数的底数,欧拉数) 的 n 次方。

          AggregateCommand.filter(value: any): Object

          聚合操作符。根据给定条件返回满足条件的数组的子集。

          AggregateCommand.first(value: Expression): Object

          聚合操作符。返回指定字段在一组集合的第一条记录对应的值。仅当这组集合是按照某种定义排序( sort )后,此操作才有意义。

          AggregateCommand.floor(value: Expression<number>): Object

          聚合操作符。向下取整,返回大于或等于给定数字的最小整数。

          AggregateCommand.gt(value: Expression[]): Object

          聚合操作符。匹配两个值,如果前者大于后者则返回 true,否则返回 false。

          AggregateCommand.gte(value: Expression[]): Object

          聚合操作符。匹配两个值,如果前者大于或等于后者则返回 true,否则返回 false。

          AggregateCommand.hour(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的小时数,是一个介于 0 到 23 之间的整数。

          AggregateCommand.ifNull(value: Expression[]): Object

          聚合操作符。计算给定的表达式,如果表达式结果为 null、undefined 或者不存在,那么返回一个替代值;否则返回原值。

          AggregateCommand.in(value: Expression[]): Object

          聚合操作符。给定一个值和一个数组,如果值在数组中则返回 true,否则返回 false。

          AggregateCommand.indexOfArray(value: Expression[]): Object

          聚合操作符。在数组中找出等于给定值的第一个元素的下标,如果找不到则返回 -1。

          AggregateCommand.indexOfBytes(value: Expression[]): Object

          聚合操作符。在目标字符串中查找子字符串,并返回第一次出现的 UTF-8 的字节索引(从0开始)。如果不存在子字符串,返回 -1。

          AggregateCommand.indexOfCP(value: Expression[]): Object

          聚合操作符。在目标字符串中查找子字符串,并返回第一次出现的 UTF-8 的 code point 索引(从0开始)。如果不存在子字符串,返回 -1。

          AggregateCommand.isArray(value: Expression): Object

          聚合操作符。判断给定表达式是否是数组,返回布尔值。

          AggregateCommand.isoDayOfWeek(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的 ISO 8601 标准的天数(一周中的第几天),是一个介于 1(周一)到 7(周日)之间的整数。

          AggregateCommand.isoWeek(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的 ISO 8601 标准的周数(一年中的第几周),是一个介于 1 到 53 之间的整数。

          AggregateCommand.isoWeekYear(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的 ISO 8601 标准的天数(一年中的第几天)。

          AggregateCommand.last(value: Expression): Object

          聚合操作符。返回指定字段在一组集合的最后一条记录对应的值。仅当这组集合是按照某种定义排序( sort )后,此操作才有意义。

          AggregateCommand.let(value: any): Object

          聚合操作符。自定义变量,并且在指定表达式中使用,返回的结果是表达式的结果。

          AggregateCommand.literal(value: any): Object

          聚合操作符。直接返回一个值的字面量,不经过任何解析和处理。

          AggregateCommand.ln(value: Expression<number>): Object

          聚合操作符。计算给定数字在自然对数值。

          AggregateCommand.log(value: Expression[]): Object

          聚合操作符。计算给定数字在给定对数底下的 log 值。

          AggregateCommand.log10(value: Expression<number>): Object

          聚合操作符。计算给定数字在对数底为 10 下的 log 值。

          AggregateCommand.lt(value: Expression[]): Object

          聚合操作符。匹配两个值,如果前者小于后者则返回 true,否则返回 false。

          AggregateCommand.lte(value: Expression[]): Object

          聚合操作符。匹配两个值,如果前者小于或等于后者则返回 true,否则返回 false。

          AggregateCommand.map(value: any): Object

          聚合操作符。类似 JavaScript Array 上的 map 方法,将给定数组的每个元素按给定转换方法转换后得出新的数组。

          AggregateCommand.max(value: Expression): Object

          聚合操作符。返回一组数值的最大值。

          AggregateCommand.mergeObjects(value: Expression<document>): Object

          聚合操作符。将多个文档合并为单个文档。

          AggregateCommand.millisecond(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的毫秒数,是一个介于 0 到 999 之间的整数。

          AggregateCommand.min(value: Expression): Object

          聚合操作符。返回一组数值的最小值。

          AggregateCommand.minute(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的分钟数,是一个介于 0 到 59 之间的整数。

          AggregateCommand.mod(value: Expression[]): Object

          聚合操作符。取模运算,取数字取模后的值。

          AggregateCommand.month(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的月份,是一个介于 1 到 12 之间的整数。

          AggregateCommand.multiply(value: Expression[]): Object

          聚合操作符。取传入的数字参数相乘的结果。

          AggregateCommand.neq(value: Expression[]): Object

          聚合操作符。匹配两个值,如果不相等则返回 true,否则返回 false。

          AggregateCommand.not(value: Expression): Object

          聚合操作符。给定一个表达式,如果表达式返回 true,则 not 返回 false,否则返回 true。注意表达式不能为逻辑表达式(and、or、nor、not)。

          AggregateCommand.objectToArray(value: Expression<object>): Object

          聚合操作符。将一个对象转换为数组。方法把对象的每个键值对都变成输出数组的一个元素,元素形如 { k: <key>, v: <value> }。

          AggregateCommand.or(value: Expression[]): Object

          聚合操作符。给定多个表达式,如果任意一个表达式返回 true,则 or 返回 true,否则返回 false。

          AggregateCommand.pow(value: Expression[]): Object

          聚合操作符。求给定基数的指数次幂。

          AggregateCommand.push(value: any): Object

          聚合操作符。在 group 阶段,返回一组中表达式指定列与对应的值,一起组成的数组。

          AggregateCommand.range(value: Expression[]): Object

          聚合操作符。返回一组生成的序列数字。给定开始值、结束值、非零的步长,range 会返回从开始值开始逐步增长、步长为给定步长、但不包括结束值的序列。

          AggregateCommand.reduce(value: any): Object

          聚合操作符。类似 JavaScript 的 reduce 方法,应用一个表达式于数组各个元素然后归一成一个元素。

          AggregateCommand.reverseArray(value: Expression<any[]>): Object

          聚合操作符。返回给定数组的倒序形式。

          AggregateCommand.second(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的秒数,是一个介于 0 到 59 之间的整数,在特殊情况下(闰秒)可能等于 60。

          AggregateCommand.setDifference(value: Expression[]): Object

          聚合操作符,输入两个集合,输出只存在于第一个集合中的元素。

          AggregateCommand.setEquals(value: Expression[]): Object

          聚合操作符,输入两个集合,判断两个集合中包含的元素是否相同(不考虑顺序、去重)。

          AggregateCommand.setIntersection(value: Expression[]): Object

          聚合操作符,输入两个集合,输出两个集合的交集。

          AggregateCommand.setIsSubset(value: Expression[]): Object

          聚合操作符,输入两个集合,判断第一个集合是否是第二个集合的子集。

          AggregateCommand.setUnion(value: Expression[]): Object

          聚合操作符,输入两个集合,输出两个集合的并集。

          AggregateCommand.size(value: Expression<any[]>): Object

          聚合操作符。返回数组长度。

          AggregateCommand.slice(value: Expression[]): Object

          聚合操作符。类似 JavaScritp 的 slice 方法。返回给定数组的指定子集。

          AggregateCommand.split(value: Expression[]): Object

          聚合操作符。按照分隔符分隔数组,并且删除分隔符,返回子字符串组成的数组。如果字符串无法找到分隔符进行分隔,返回原字符串作为数组的唯一元素。

          AggregateCommand.sqrt(value: Expression[]): Object

          聚合操作符。求平方根。

          AggregateCommand.stdDevPop(value: Expression): Object

          聚合操作符。返回一组字段对应值的标准差。

          AggregateCommand.stdDevSamp(value: Expression): Object

          聚合操作符。计算输入值的样本标准偏差。如果输入值代表数据总体,或者不概括更多的数据,请改用 db.command.aggregate.stdDevPop。

          AggregateCommand.strLenBytes(value: Expression): Object

          聚合操作符。计算并返回指定字符串中 utf-8 编码的字节数量。

          AggregateCommand.strLenCP(value: Expression): Object

          聚合操作符。计算并返回指定字符串的UTF-8 code points 数量。

          AggregateCommand.strcasecmp(value: Expression[]): Object

          聚合操作符。对两个字符串在不区分大小写的情况下进行大小比较,并返回比较的结果。

          AggregateCommand.substr(value: Expression[]): Object

          聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。它是 db.command.aggregate.substrBytes 的别名,更推荐使用后者。

          AggregateCommand.substrBytes(value: Expression[]): Object

          聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。子字符串是由字符串中指定的 UTF-8 字节索引的字符开始,长度为指定的字节数。

          AggregateCommand.substrCP(value: Expression[]): Object

          聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。子字符串是由字符串中指定的 UTF-8 字节索引的字符开始,长度为指定的字节数。

          AggregateCommand.subtract(value: Expression[]): Object

          聚合操作符。将两个数字相减然后返回差值,或将两个日期相减然后返回相差的毫秒数,或将一个日期减去一个数字返回结果的日期。

          AggregateCommand.sum(value: Expression): Object

          聚合操作符。计算并且返回一组字段所有数值的总和。

          AggregateCommand.switch(value: any): Object

          聚合操作符。根据给定的 switch-case-default 计算返回值、

          AggregateCommand.toLower(value: any): Object

          聚合操作符。将字符串转化为小写并返回。

          AggregateCommand.toUpper(value: any): Object

          聚合操作符。将字符串转化为大写并返回。

          AggregateCommand.trunc(value: Expression<number>): Object

          聚合操作符。将数字截断为整形。

          AggregateCommand.week(value: Expression<string>): Object

          聚合操作符。返回日期字段对应的周数(一年中的第几周),是一个介于 0 到 53 之间的整数。

          Expression

          聚合表达式

          说明

          表达式可以是字段路径、常量、或聚合操作符。表达式可以嵌套表达式。

          字段路径

          表达式用字段路径表示法来指定记录中的字段。字段路径的表示由一个 $ 符号加上字段名或嵌套字段名。嵌套字段名用点将嵌套的各级字段连接起来。如 $profile 就表示 profile 的字段路径,$profile.name 就表示 profile.name 的字段路径(profile 字段中嵌套的 name 字段)。

          常量

          常量可以是任意类型。默认情况下 $ 开头的字符串都会被当做字段路径处理,如果想要避免这种行为,使用 AggregateCommand.literal 声明为常量。

          聚合操作符

          AggregateCommand


          AggregateCommand.abs(value: Expression<number>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回一个数字的绝对值。

          参数

          value: Expression<number>

          number

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.abs(<number>)

          abs 传入的值除了数字常量外,也可以是任何最终解析成一个数字的表达式。

          如果表达式解析为 null 或者指向一个不存在的字段,则 abs 的结果是 null。如果值解析为 NaN,则结果是 NaN。

          示例代码

          假设集合 ratings 有如下记录:

          { _id: 1, start: 5, end: 8 }{ _id: 2, start: 4, end: 4 }{ _id: 3, start: 9, end: 7 }{ _id: 4, start: 6, end: 7 }

          ··· 可以用如下方式求得各个记录的 start 和 end 之间的绝对差异大小:

          const $ = db.command.aggregatedb.collection('ratings').aggregate()  .project({    delta: $.abs($.subtract(['$start', '$end']))  })  .end()

          返回结果如下:

          { "_id" : 1, "delta" : 3 }{ "_id" : 2, "delta" : 0 }{ "_id" : 3, "delta" : 2 }{ "_id" : 4, "delta" : 1 }

          AggregateCommand.add(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将数字相加或将数字加在日期上。如果数组中的其中一个值是日期,那么其他值将被视为毫秒数加在该日期上。

          参数

          value: Expression[]

          [<表达式1>, <表达式2>, ...]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.add([<表达式1>, <表达式2>, ...])

          表达式可以是形如 $ + 指定字段,也可以是普通字符串。只要能够被解析成字符串即可。

          示例代码

          假设集合 staff 有如下记录:

          { _id: 1, department: "x", sales: 5, engineer: 10, lastUpdate: ISODate("2019-05-01T00:00:00Z") }{ _id: 2, department: "y", sales: 10, engineer: 20, lastUpdate: ISODate("2019-05-01T02:00:00Z") }{ _id: 3, department: "z", sales: 20, engineer: 5, lastUpdate: ISODate("2019-05-02T03:00:00Z") }

          数字求和

          可以用如下方式求得各个记录人数总数:

          const $ = db.command.aggregatedb.collection('staff').aggregate()  .project({    department: 1,    total: $.add(['$sales', '$engineer'])  })  .end()

          返回结果如下:

          { _id: 1, department: "x", total: 15 }{ _id: 2, department: "y", total: 30 }{ _id: 3, department: "z", total: 25 }

          增加日期值

          如下操作可以获取各个记录的 lastUpdate 加一个小时之后的值:

          const $ = db.command.aggregatedb.collection('staff').aggregate()  .project({    department: 1,    lastUpdate: $.add(['$lastUpdate', 60*60*1000])  })  .end()

          返回结果如下:

          { _id: 1, department: "x", lastUpdate: ISODate("2019-05-01T01:00:00Z") }{ _id: 2, department: "y", lastUpdate: ISODate("2019-05-01T03:00:00Z") }{ _id: 3, department: "z", lastUpdate: ISODate("2019-05-02T04:00:00Z") }

          AggregateCommand.ceil(value: Expression<number>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。向上取整,返回大于或等于给定数字的最小整数。

          参数

          value: Expression<number>

          number

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.ceil(<number>)

          <number> 可以是任意解析为数字的表达式。如果表达式解析为 null 或指向一个不存在的字段,则返回 null,如果解析为 NaN,则返回 NaN。

          示例代码

          假设集合 sales 有如下记录:

          { _id: 1, sales: 5.2 }{ _id: 2, sales: 1.32 }{ _id: 3, sales: -3.2 }

          可以用如下方式取各个数字的向上取整值:

          const $ = db.command.aggregatedb.collection('sales').aggregate()  .project({    sales: $.ceil('$sales')  })  .end()

          返回结果如下:

          { _id: 1, sales: 6 }{ _id: 2, sales: 2 }{ _id: 3, sales: -3 }

          AggregateCommand.divide(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。传入被除数和除数,求商。

          参数

          value: Expression[]

          [<被除数表达式>, <除数表达式>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.divide([<被除数表达式>, <除数表达式>])

          表达式可以是任意解析为数字的表达式。

          示例代码

          假设集合 railroads 有如下记录:

          { _id: 1, meters: 5300 }{ _id: 2, meters: 64000 }{ _id: 3, meters: 130 }

          可以用如下方式取各个数字转换为千米之后的值:

          const $ = db.command.aggregatedb.collection('railroads').aggregate()  .project({    km: $.divide(['$meters', 1000])  })  .end()

          返回结果如下:

          { _id: 1, km: 5.3 }{ _id: 2, km: 64 }{ _id: 3, km: 0.13 }

          AggregateCommand.exp(value: Expression<number>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。取 e(自然对数的底数,欧拉数) 的 n 次方。

          参数

          value: Expression<number>

          exponent

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.exp(<exponent>)

          <exponent> 可以是任意解析为数字的表达式。如果表达式解析为 null 或指向一个不存在的字段,则返回 null,如果解析为 NaN,则返回 NaN。

          示例代码

          假设集合 math 有如下记录:

          { _id: 1, exp: 0 }{ _id: 2, exp: 1 }{ _id: 3, exp: 2 }
          const $ = db.command.aggregatedb.collection('math').aggregate()  .project({    result: $.exp('$exp')  })  .end()

          返回结果如下:

          { _id: 1, result: 1 }{ _id: 2, result: 2.71828182845905 }{ _id: 3, result: 7.38905609893065 }

          AggregateCommand.floor(value: Expression<number>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。向下取整,返回大于或等于给定数字的最小整数。

          参数

          value: Expression<number>

          number

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.floor(<number>)

          <number> 可以是任意解析为数字的表达式。如果表达式解析为 null 或指向一个不存在的字段,则返回 null,如果解析为 NaN,则返回 NaN。

          示例代码

          假设集合 sales 有如下记录:

          { _id: 1, sales: 5.2 }{ _id: 2, sales: 1.32 }{ _id: 3, sales: -3.2 }

          可以用如下方式取各个数字的向下取整值:

          const $ = db.command.aggregatedb.collection('sales').aggregate()  .project({    sales: $.floor('$sales')  })  .end()

          返回结果如下:

          { _id: 1, sales: 5 }{ _id: 2, sales: 1 }{ _id: 3, sales: -6 }

          AggregateCommand.ln(value: Expression<number>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。计算给定数字在自然对数值。

          参数

          value: Expression<number>

          number

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.ln(<number>)

          <number> 可以是任意解析为非负数字的表达式。

          ln 等价于 log([<number>, Math.E]),其中 Math.E 是 JavaScript 获取 e 的值的方法。

          示例代码

          db.command.aggregate.ln

          聚合操作符。计算给定数字在自然对数值。

          语法如下:

          db.command.aggregate.ln(<number>)

          <number> 可以是任意解析为非负数字的表达式。

          ln 等价于 log([<number>, Math.E]),其中 Math.E 是 JavaScript 获取 e 的值的方法。


          AggregateCommand.log(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。计算给定数字在给定对数底下的 log 值。

          参数

          value: Expression[]

          [<number>, <base>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.log([<number>, <base>])

          <number> 可以是任意解析为非负数字的表达式。<base> 可以是任意解析为大于 1 的数字的表达式。

          如果任一参数解析为 null 或指向任意一个不存在的字段,log 返回 null。如果任一参数解析为 NaN,log 返回 NaN。

          示例代码

          假设集合 curve 有如下记录:

          { _id: 1, x: 1 }{ _id: 2, x: 2 }{ _id: 3, x: 3 }

          计算 log2(x) 的值:

          const $ = db.command.aggregatedb.collection('staff').aggregate()  .project({    log: $.log(['$x', 2])  })  .end()

          返回结果如下:

          { _id: 1, log: 0 }{ _id: 2, log: 1 }{ _id: 3, log: 1.58496250072 }

          AggregateCommand.log10(value: Expression<number>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。计算给定数字在对数底为 10 下的 log 值。

          参数

          value: Expression<number>

          number

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.log(<number>)

          <number> 可以是任意解析为非负数字的表达式。

          log10 等同于 log 方法的第二个参数固定为 10。

          示例代码

          db.command.aggregate.log10

          聚合操作符。计算给定数字在对数底为 10 下的 log 值。

          语法如下:

          db.command.aggregate.log(<number>)

          <number> 可以是任意解析为非负数字的表达式。

          log10 等同于 log 方法的第二个参数固定为 10。


          AggregateCommand.mod(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。取模运算,取数字取模后的值。

          参数

          value: Expression[]

          [<dividend>, <divisor>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.mod([<dividend>, <divisor>])

          第一个数字是被除数,第二个数字是除数。参数可以是任意解析为数字的表达式。

          示例代码

          假设集合 shopping 有如下记录:

          { _id: 1, bags: 3, items: 5 }{ _id: 2, bags: 2, items: 8 }{ _id: 3, bags: 5, items: 16 }

          各记录取 items 除以 bags 的余数(items % bags):

          const $ = db.command.aggregatedb.collection('shopping').aggregate()  .project({    overflow: $.mod(['$items', '$bags'])  })  .end()

          返回结果如下:

          { _id: 1, log: 2 }{ _id: 2, log: 0 }{ _id: 3, log: 1 }

          AggregateCommand.multiply(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。取传入的数字参数相乘的结果。

          参数

          value: Expression[]

          [<expression1>, <expression2>, ...]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.multiply([<expression1>, <expression2>, ...])

          参数可以是任意解析为数字的表达式。

          示例代码

          假设集合 fruits 有如下记录:

          { "_id": 1, "name": "apple", "price": 10, "quantity": 100 }{ "_id": 2, "name": "orange", "price": 15, "quantity": 50 }{ "_id": 3, "name": "lemon", "price": 5, "quantity": 20 }

          求各个水果的的总价值:

          const $ = db.command.aggregatedb.collection('fruits').aggregate()  .project({    name: 1,    total: $.multiply(['$price', '$quantity']),  })  .end()

          返回结果如下:

          { "_id": 1, "name": "apple", "total": 1000 }{ "_id": 2, "name": "orange", "total": 750 }{ "_id": 3, "name": "lemo", "total": 100 }

          AggregateCommand.pow(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。求给定基数的指数次幂。

          参数

          value: Expression[]

          [<base>, <exponent>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.pow([<base>, <exponent>])

          参数可以是任意解析为数字的表达式。

          示例代码

          假设集合 stats 有如下记录:

          { "_id": 1, "x": 2, "y": 3 }{ "_id": 2, "x": 5, "y": 7 }{ "_id": 3, "x": 10, "y": 20 }

          求 x 和 y 的平方和:

          const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    sumOfSquares: $.add([$.pow(['$x', 2]), $.pow(['$y', 2])]),  })  .end()

          返回结果如下:

          { "_id": 1, "sumOfSquares": 13 }{ "_id": 2, "sumOfSquares": 74 }{ "_id": 3, "sumOfSquares": 500 }

          AggregateCommand.sqrt(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。求平方根。

          参数

          value: Expression[]

          [<number>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.sqrt([<number>])

          参数可以是任意解析为非负数字的表达式。

          示例代码

          假设直角三角形集合 triangle 有如下记录:

          { "_id": 1, "x": 2, "y": 3 }{ "_id": 2, "x": 5, "y": 7 }{ "_id": 3, "x": 10, "y": 20 }

          假设 x 和 y 分别为两直角边,则求斜边长:

          const $ = db.command.aggregatedb.collection('triangle').aggregate()  .project({    len: $.sqrt([$.add([$.pow(['$x', 2]), $.pow(['$y', 2])])]),  })  .end()

          返回结果如下:

          { "_id": 1, "len": 3.605551275463989 }{ "_id": 2, "len": 8.602325267042627 }{ "_id": 3, "len": 22.360679774997898 }

          AggregateCommand.subtract(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将两个数字相减然后返回差值,或将两个日期相减然后返回相差的毫秒数,或将一个日期减去一个数字返回结果的日期。

          参数

          value: Expression[]

          [<expression1>, <expression2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.subtract([<expression1>, <expression2>])

          参数可以是任意解析为数字或日期的表达式。

          示例代码

          假设集合 scores 有如下记录:

          { "_id": 1, "max": 10, "min": 1 }{ "_id": 2, "max": 7, "min": 5 }{ "_id": 3, "max": 6, "min": 6 }

          求各个记录的 max 和 min 的差值。:

          const $ = db.command.aggregatedb.collection('scores').aggregate()  .project({    diff: $.subtract(['$max', '$min'])  })  .end()

          返回结果如下:

          { "_id": 1, "diff": 9 }{ "_id": 2, "diff": 2 }{ "_id": 3, "diff": 0 }

          AggregateCommand.trunc(value: Expression<number>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将数字截断为整形。

          参数

          value: Expression<number>

          number

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.trunc(<number>)

          参数可以是任意解析为数字的表达式。

          示例代码

          假设集合 scores 有如下记录:

          { "_id": 1, "value": 1.21 }{ "_id": 2, "value": 3.83 }{ "_id": 3, "value": -4.94 }
          const $ = db.command.aggregatedb.collection('scores').aggregate()  .project({    int: $.trunc('$value')  })  .end()

          返回结果如下:

          { "_id": 1, "value": 1 }{ "_id": 2, "value": 3 }{ "_id": 3, "value": -4 }


          AggregateCommand.arrayElemAt(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回在指定数组下标的元素。

          参数

          value: Expression[]

          [<array>, <index>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.arrayElemAt([<array>, <index>])

          <array> 可以是任意解析为数字的表达式。

          <index> 可以是任意解析为整形的表达式。如果是正数,arrayElemAt 返回在 index 位置的元素,如果是负数,arrayElemAt 返回从数组尾部算起的 index 位置的元素。

          示例代码

          假设集合 exams 有如下记录:

          { "_id": 1, "scores": [80, 60, 65, 90] }{ "_id": 2, "scores": [78] }{ "_id": 3, "scores": [95, 88, 92] }

          求各个第一次考试的分数和和最后一次的分数:

          const $ = db.command.aggregatedb.collection('exams').aggregate()  .project({    first: $.arrayElemAt(['$scores', 0]),    last: $.arrayElemAt(['$scores', -1]),  })  .end()

          返回结果如下:

          { "_id": 1, "first": 80, "last": 90 }{ "_id": 2, "first": 78, "last": 78 }{ "_id": 3, "first": 95, "last": 92 }

          AggregateCommand.arrayToObject(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将一个数组转换为对象。

          参数

          value: any

          返回值

          Object

          API 说明

          语法可以取两种:

          第一种:传入一个二维数组,第二维的数组长度必须为 2,其第一个值为字段名,第二个值为字段值

          db.command.aggregate.arrayToObject([  [<key1>, <value1>],  [<key2>, <value2>],  ...])

          第二种:传入一个对象数组,各个对象必须包含字段 k 和 v,分别指定字段名和字段值

          db.command.aggregate.arrayToObject([  { "k": <key1>, "v": <value1> },  { "k": <key2>, "v": <value2> },  ...])

          传入 arrayToObject 的参数只要可以解析为上述两种表示法之一即可。

          示例代码

          假设集合 shops 有如下记录:

          { "_id": 1, "sales": [ ["max", 100], ["min", 50] ] }{ "_id": 2, "sales": [ ["max", 70], ["min", 60] ] }{ "_id": 3, "sales": [ { "k": "max", "v": 50 }, { "k": "min", "v": 30 } ] }

          求各个第一次考试的分数和和最后一次的分数:

          const $ = db.command.aggregatedb.collection('shops').aggregate()  .project({    sales: $.arrayToObject('$sales'),  })  .end()

          返回结果如下:

          { "_id": 1, "sales": { "max": 100, "min": 50 } }{ "_id": 2, "sales": { "max": 70, "min": 60 } }{ "_id": 3, "sales": { "max": 50, "min": 30 } }

          AggregateCommand.concatArrays(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将多个数组拼接成一个数组。

          参数

          value: Expression[]

          [ <array1>, <array2>, ... ]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.arrayToObject([ <array1>, <array2>, ... ])

          参数可以是任意解析为数组的表达式。

          示例代码

          假设集合 items 有如下记录:

          { "_id": 1, "fruits": [ "apple" ], "vegetables": [ "carrot" ] }{ "_id": 2, "fruits": [ "orange", "lemon" ], "vegetables": [ "cabbage" ] }{ "_id": 3, "fruits": [ "strawberry" ], "vegetables": [ "spinach" ] }
          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    list: $.concatArrays(['$fruits', '$vegetables']),  })  .end()

          返回结果如下:

          { "_id": 1, "list": [ "apple", "carrot" ] }{ "_id": 2, "list": [ "orange", "lemon", "cabbage" ] }{ "_id": 3, "list": [ "strawberry", "spinach" ] }

          AggregateCommand.filter(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。根据给定条件返回满足条件的数组的子集。

          参数

          value: any

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.filter({  input: <array>,  as: <string>,  cond: <expression>})
          字段说明
          input一个可以解析为数组的表达式
          as可选,用于表示数组各个元素的变量,默认为 this
          cond一个可以解析为布尔值的表达式,用于判断各个元素是否满足条件,各个元素的名字由 as 参数决定(参数名需加 $$ 前缀,如 $$this

          参数可以是任意解析为数组的表达式。

          示例代码

          假设集合 fruits 有如下记录:

          {  "_id": 1,  "stock": [    { "name": "apple", "price": 10 },    { "name": "orange", "price": 20 }  ],}{  "_id": 2,  "stock": [    { "name": "lemon", "price": 15 },  ],}
          const _ = db.commandconst $ = db.command.aggregatedb.collection('fruits').aggregate()  .project({    stock: $.filter({      input: '$stock',      as: 'item',      cond: $.gte(['$$item.price', 15])    })  })  .end()

          返回结果如下:

          { "_id": 1, "stock": [ { "name": "orange", "price": 20} ] }{ "_id": 2, "stock": [ { "name": "lemon", "price": 15 } ] }

          AggregateCommand.in(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。给定一个值和一个数组,如果值在数组中则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value>, <array>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.in([<value>, <array>])

          <value> 可以是任意表达式。

          <array> 可以是任意解析为数组的表达式。

          示例代码

          假设集合 shops 有如下记录:

          { "_id": 1, "topsellers": ["bread", "ice cream", "butter"] }{ "_id": 2, "topsellers": ["ice cream", "cheese", "yagurt"] }{ "_id": 3, "topsellers": ["croissant", "cucumber", "coconut"] }

          标记销量最高的商品包含 ice cream 的记录。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    included: $.in(['ice cream', '$topsellers'])  })  .end()

          返回结果如下:

          { "_id": 1, "included": true }{ "_id": 2, "included": true }{ "_id": 3, "included": false }

          AggregateCommand.indexOfArray(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。在数组中找出等于给定值的第一个元素的下标,如果找不到则返回 -1。

          参数

          value: Expression[]

          [ <array expression>, <search expression>, <start>, <end> ]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.indexOfArray([ <array expression>, <search expression>, <start>, <end> ])
          字段类型说明
          <array>string一个可以解析为数组的表达式,如果解析为 null,则 indexOfArray 返回 null
          <search>string对数据各个元素应用的条件匹配表达式
          <start>integer可选,用于指定搜索的开始下标,必须是非负整数
          <end>integer可选,用于指定搜索的结束下标,必须是非负整数,指定了 <end> 时也应指定 <start>,否则 <end> 默认当做 <start>

          参数可以是任意解析为数组的表达式。

          示例代码

          假设集合 stats 有如下记录:

          {  "_id": 1,  "sales": [ 1, 6, 2, 2, 5 ]}{  "_id": 2,  "sales": [ 4, 2, 1, 5, 2 ]}{  "_id": 3,  "sales": [ 2, 5, 3, 3, 1 ]}
          const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    index: $.indexOfArray(['$sales', 2, 2])  })  .end()

          返回结果如下:

          { "_id": 1, "index": 2 }{ "_id": 2, "index": 4 }{ "_id": 3, "index": -1 }

          AggregateCommand.isArray(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。判断给定表达式是否是数组,返回布尔值。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.isArray(<expression>)

          参数可以是任意表达式。

          示例代码

          假设集合 stats 有如下记录:

          {  "_id": 1,  "base": 10,  "sales": [ 1, 6, 2, 2, 5 ]}{  "_id": 2,  "base": 1,  "sales": 100}

          计算总销量,如果 sales 是数字,则求 sales * base,如果 sales 是数组,则求数组元素之和与 base 的乘积。

          const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    sum: $.cond({      if: $.isArray('$sales'),      then: $.multiply([$.sum(['$sales']), '$base']),      else: $.multiply(['$sales', '$base']),    })  })  .end()

          返回结果如下:

          { "_id": 1, "index": 160 }{ "_id": 2, "index": 100 }

          AggregateCommand.map(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。类似 JavaScript Array 上的 map 方法,将给定数组的每个元素按给定转换方法转换后得出新的数组。

          参数

          value: any

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.map({  input: <expression>,  as: <string>,  in: <expression>})
          字段说明
          input一个可以解析为数组的表达式
          as可选,用于表示数组各个元素的变量,默认为 this
          in一个可以应用在给定数组的各个元素上的表达式,各个元素的名字由 as 参数决定(参数名需加 $$ 前缀,如 $$this

          示例代码

          假设集合 stats 有如下记录:

          {  "_id": 1,  "sales": [ 1.32, 6.93, 2.48, 2.82, 5.74 ]}{  "_id": 2,  "sales": [ 2.97, 7.13, 1.58, 6.37, 3.69 ]}

          将各个数字截断为整形,然后求和

          const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    truncated: $.map({      input: '$sales',      as: 'num',      in: $.trunc('$$num'),    })  })  .project({    total: $.sum('$truncated')  })  .end()

          返回结果如下:

          { "_id": 1, "index": 16 }{ "_id": 2, "index": 19 }

          AggregateCommand.objectToArray(value: Expression<object>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将一个对象转换为数组。方法把对象的每个键值对都变成输出数组的一个元素,元素形如 { k: &lt;key&gt;, v: &lt;value&gt; }。

          参数

          value: Expression<object>

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.objectToArray(<object>)

          示例代码

          假设集合 items 有如下记录:

          { "_id": 1, "attributes": { "color": "red", "price": 150 } }{ "_id": 2, "attributes": { "color": "blue", "price": 50 } }{ "_id": 3, "attributes": { "color": "yellow", "price": 10 } }
          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    array: $.objectToArray('$attributes')  })  .end()

          返回结果如下:

          { "_id": 1, "array": [{ "k": "color", "v": "red" }, { "k": "price", "v": 150 }] }{ "_id": 2, "array": [{ "k": "color", "v": "blue" }, { "k": "price", "v": 50 }] }{ "_id": 3, "array": [{ "k": "color", "v": "yellow" }, { "k": "price", "v": 10 }] }

          AggregateCommand.range(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回一组生成的序列数字。给定开始值、结束值、非零的步长,range 会返回从开始值开始逐步增长、步长为给定步长、但不包括结束值的序列。

          参数

          value: Expression[]

          [<start>, <end>, <non-zero step>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.range([<start>, <end>, <non-zero step>])
          字段说明
          start开始值,一个可以解析为整形的表达式
          end结束值,一个可以解析为整形的表达式
          non-zero step可选,步长,一个可以解析为非零整形的表达式,默认为 1

          示例代码

          假设集合 stats 有如下记录:

          { "_id": 1, "max": 52 }{ "_id": 2, "max": 38 }
          const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    points: $.range([0, '$max', 10])  })  .end()

          返回结果如下:

          { "_id": 1, "points": [0, 10, 20, 30, 40, 50] }{ "_id": 2, "points": [0, 10, 20] }

          AggregateCommand.reduce(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。类似 JavaScript 的 reduce 方法,应用一个表达式于数组各个元素然后归一成一个元素。

          参数

          value: any

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.reduce({  input: <array>  initialValue: <expression>,  in: <expression>})
          字段说明
          input输入数组,可以是任意解析为数组的表达式
          initialValue初始值
          in用来作用于每个元素的表达式,在 in 中有两个可用变量,value 是表示累计值的变量,this 是表示当前数组元素的变量

          示例代码

          简易字符串拼接

          假设集合 player 有如下记录:

          { "_id": 1, "fullname": [ "Stephen", "Curry" ] }{ "_id": 2, "fullname": [ "Klay", "Thompsom" ] }

          获取各个球员的全名,并加 Player: 前缀:

          const $ = db.command.aggregatedb.collection('player').aggregate()  .project({    info: $.reduce({      input: '$fullname',      initialValue: 'Player:',      in: $.concat(['$$value', ' ', '$$this']),    })  })  .end()

          返回结果如下:

          { "_id": 1, "info": "Player: Stephen Curry" }{ "_id": 2, "info": "Player: Klay Thompson" }

          获取各个球员的全名,不加前缀:

          const $ = db.command.aggregatedb.collection('player').aggregate()  .project({    name: $.reduce({      input: '$fullname',      initialValue: '',      in: $.concat([        '$$value',        $.cond({          if: $.eq(['$$value', '']),          then: '',          else: ' ',        }),        '$$this',      ]),    })  })  .end()

          返回结果如下:

          { "_id": 1, "name": "Stephen Curry" }{ "_id": 2, "name": "Klay Thompson" }

          AggregateCommand.reverseArray(value: Expression<any[]>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回给定数组的倒序形式。

          参数

          value: Expression<any[]>

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.reverseArray(<array>)

          参数可以是任意解析为数组表达式。

          示例代码

          假设集合 stats 有如下记录:

          {  "_id": 1,  "sales": [ 1, 2, 3, 4, 5 ]}

          取 sales 倒序:

          const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    reversed: $.reverseArray('$sales'),  })  .end()

          返回结果如下:

          { "_id": 1, "reversed": [5, 4, 3, 2, 1] }

          AggregateCommand.size(value: Expression<any[]>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回数组长度。

          参数

          value: Expression<any[]>

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.size(<array>)

          <array> 可以是任意解析为数组的表达式。

          示例代码

          假设集合 shops 有如下记录:

          { "_id": 1, "staff": [ "John", "Middleton", "George" ] }{ "_id": 2, "staff": [ "Steph", "Jack" ] }

          计算各个商店的雇员数量:

          const $ = db.command.aggregatedb.collection('staff').aggregate()  .project({    totalStaff: $.size('$staff')  })  .end()

          返回结果如下:

          { "_id": 1, "totalStaff": 3 }{ "_id": 2, "totalStaff": 2 }

          AggregateCommand.slice(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。类似 JavaScritp 的 slice 方法。返回给定数组的指定子集。

          参数

          value: Expression[]

          [<array>, <n>]

          返回值

          Object

          API 说明

          语法有两种:

          返回从开头或结尾开始的 n 个元素:

          db.command.aggregate.slice([<array>, <n>])

          返回从指定位置算作数组开头、再向后或向前的 n 个元素:

          db.command.aggregate.slice([<array>, <position>, <n>])

          <array> 可以是任意解析为数组的表达式。

          <position> 可以是任意解析为整形的表达式。如果是正数,则将数组的第 <position> 个元素作为数组开始;如果 <position> 比数组长度更长,slice 返回空数组。如果是负数,则将数组倒数第 <position> 个元素作为数组开始;如果 <position> 的绝对值大于数组长度,则开始位置即为数组开始位置。

          <n> 可以是任意解析为整形的表达式。如果 <position> 有提供,则 <n> 必须为正整数。如果是正数,slice 返回前 n 个元素。如果是负数,slice 返回后 n 个元素。

          示例代码

          假设集合 people 有如下记录:

          { "_id": 1, "hobbies": [ "basketball", "football", "tennis", "badminton" ] }{ "_id": 2, "hobbies": [ "golf", "handball" ] }{ "_id": 3, "hobbies": [ "table tennis", "swimming", "rowing" ] }

          统一返回前两个爱好:

          const $ = db.command.aggregatedb.collection('fruits').aggregate()  .project({    hobbies: $.slice(['$hobbies', 2]),  })  .end()

          返回结果如下:

          { "_id": 1, "hobbies": [ "basketball", "football" ] }{ "_id": 2, "hobbies": [ "golf", "handball" ] }{ "_id": 3, "hobbies": [ "table tennis", "swimming" ] }

          AggregateCommand.zip(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。把二维数组的第二维数组中的相同序号的元素分别拼装成一个新的数组进而组装成一个新的二维数组。如可将 [ [ 1, 2, 3 ], [ &#34;a&#34;, &#34;b&#34;, &#34;c&#34; ] ] 转换成 [ [ 1, &#34;a&#34; ], [ 2, &#34;b&#34; ], [ 3, &#34;c&#34; ] ]。

          参数

          value: any

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.zip({  inputs: [<array1>, <array2>, ...],  useLongestLength: <boolean>,  defaults: <array>})

          inputs 是一个二维数组(inputs 不可以是字段引用),其中每个元素的表达式(这个可以是字段引用)都可以解析为数组。如果其中任意一个表达式返回 null,<inputs> 也返回 null。如果其中任意一个表达式不是指向一个合法的字段 / 解析为数组 / 解析为 null,则返回错误。

          useLongestLength 决定输出数组的长度是否采用输入数组中的最长数组的长度。默认为 false,即输入数组中的最短的数组的长度即是输出数组的各个元素的长度。

          defaults 是一个数组,用于指定在输入数组长度不一的情况下时采用的数组各元素默认值。指定这个字段则必须指定 useLongestLength,否则返回错误。如果 useLongestLength 是 true 但是 defaults 是空或没有指定,则 zip 用 null 做数组元素的缺省默认值。指定各元素默认值时 defaults 数组的长度必须是输入数组最大的长度。

          示例代码

          假设集合 stats 有如下记录:

          { "_id": 1, "zip1": [1, 2], "zip2": [3, 4], "zip3": [5, 6] ] }{ "_id": 2, "zip1": [1, 2], "zip2": [3], "zip3": [4, 5, 6] ] }{ "_id": 3, "zip1": [1, 2], "zip2": [3] ] }

          只传 inputs

          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    zip: $.zip({      inputs: [        '$zip1', // 字段引用        '$zip2',        '$zip3',      ],    })  })  .end()

          返回结果如下:

          { "_id": 1, "zip": [ [1, 3, 5], [2, 4, 6] ] }{ "_id": 2, "zip": [ [1, 3, 4] ] }{ "_id": 3, "zip": null }

          设置 useLongestLength

          如果设 useLongestLength 为 true:

          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    zip: $.zip({      inputs: [        '$zip1', // 字段引用        '$zip2',        '$zip3',      ],      useLongestLength: true,    })  })  .end()

          返回结果如下:

          { "_id": 1, "zip": [ [1, 3, 5], [2, 4, 6] ] }{ "_id": 2, "zip": [ [1, 3, 4], [2, null, 5], [null, null, 6] ] }{ "_id": 3, "zip": null }

          设置 defaults

          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    zip: $.zip({      inputs: [        '$zip1', // 字段引用        '$zip2',        '$zip3',      ],      useLongestLength: true,      defaults: [-300, -200, -100],    })  })  .end()

          返回结果如下:

          { "_id": 1, "zip": [ [1, 3, 5], [2, 4, 6] ] }{ "_id": 2, "zip": [ [1, 3, 4], [2, -200, 5], [-300, -200, 6] ] }{ "_id": 3, "zip": null }


          AggregateCommand.and(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。给定多个表达式,and 仅在所有表达式都返回 true 时返回 true,否则返回 false。

          参数

          value: Expression[]

          [<expression1>, <expression2>, ...]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.and([<expression1>, <expression2>, ...])

          如果表达式返回 false、null、0、或 undefined,表达式会解析为 false,否则对其他返回值都认为是 true。

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "min": 10, "max": 100 }{ "_id": 2, "min": 60, "max": 80 }{ "_id": 3, "min": 30, "max": 50 }

          求 min 大于等于 30 且 max 小于等于 80 的记录。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    fullfilled: $.and([$.gte(['$min', 30]), $.lte(['$max', 80])])  })  .end()

          返回结果如下:

          { "_id": 1, "fullfilled": false }{ "_id": 2, "fullfilled": true }{ "_id": 3, "fullfilled": true }

          AggregateCommand.not(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。给定一个表达式,如果表达式返回 true,则 not 返回 false,否则返回 true。注意表达式不能为逻辑表达式(and、or、nor、not)。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.not(<expression>)

          如果表达式返回 false、null、0、或 undefined,表达式会解析为 false,否则对其他返回值都认为是 true。

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "min": 10, "max": 100 }{ "_id": 2, "min": 60, "max": 80 }{ "_id": 3, "min": 30, "max": 50 }

          求 min 不大于 40 的记录。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    fullfilled: $.not($.gt(['$min', 40]))  })  .end()

          返回结果如下:

          { "_id": 1, "fullfilled": true }{ "_id": 2, "fullfilled": false }{ "_id": 3, "fullfilled": true }

          AggregateCommand.or(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。给定多个表达式,如果任意一个表达式返回 true,则 or 返回 true,否则返回 false。

          参数

          value: Expression[]

          [<expression1>, <expression2>, ...]

          返回值

          Objectu

          API 说明

          语法如下:

          db.command.aggregate.or([<expression1>, <expression2>, ...])

          如果表达式返回 false、null、0、或 undefined,表达式会解析为 false,否则对其他返回值都认为是 true。

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "min": 10, "max": 100 }{ "_id": 2, "min": 60, "max": 80 }{ "_id": 3, "min": 30, "max": 50 }

          求 min 小于 40 且 max 大于 60 的记录。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    fullfilled: $.or([$.lt(['$min', 30]), $.gt(['$max', 60])])  })  .end()

          返回结果如下:

          { "_id": 1, "fullfilled": true }{ "_id": 2, "fullfilled": false }{ "_id": 3, "fullfilled": true }


          AggregateCommand.cmp(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。给定两个值,返回其比较值:

          参数

          value: Expression[]

          [<expression1>, <expression2>]

          返回值

          Object

          API 说明

          如果第一个值小于第二个值,返回 -1 如果第一个值大于第二个值,返回 1 如果两个值相等,返回 0

          语法如下:

          db.command.aggregate.cmp([<expression1>, <expression2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "shop1": 10, "shop2": 100 }{ "_id": 2, "shop1": 80, "shop2": 20 }{ "_id": 3, "shop1": 50, "shop2": 50 }

          求 shop1 和 shop2 的各个物品的价格对比。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    compare: $.cmp(['$shop1', '$shop2']))  })  .end()

          返回结果如下:

          { "_id": 1, "compare": -1 }{ "_id": 2, "compare": 1 }{ "_id": 3, "compare": 0 }

          AggregateCommand.eq(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果相等则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.eq([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          求 value 等于 50 的记录。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.eq(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": false }{ "_id": 2, "matched": false }{ "_id": 3, "matched": true }

          AggregateCommand.gt(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果前者大于后者则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.gt([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          判断 value 是否大于 50。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.gt(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": false }{ "_id": 2, "matched": true }{ "_id": 3, "matched": false }

          AggregateCommand.gte(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果前者大于或等于后者则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.gte([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          判断 value 是否大于或等于 50。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.gte(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": false }{ "_id": 2, "matched": true }{ "_id": 3, "matched": true }

          AggregateCommand.lt(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果前者小于后者则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.lt([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          判断 value 是否小于 50。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.lt(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": true }{ "_id": 2, "matched": false }{ "_id": 3, "matched": false }

          AggregateCommand.lte(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果前者小于或等于后者则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.lte([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          判断 value 是否小于 50。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.lte(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": true }{ "_id": 2, "matched": false }{ "_id": 3, "matched": true }

          AggregateCommand.neq(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果不相等则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.neq([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          求 value 不等于 50 的记录。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.neq(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": true }{ "_id": 2, "matched": true }{ "_id": 3, "matched": false }


          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。给定两个值,返回其比较值:

          参数

          value: Expression[]

          [<expression1>, <expression2>]

          返回值

          Object

          API 说明

          如果第一个值小于第二个值,返回 -1 如果第一个值大于第二个值,返回 1 如果两个值相等,返回 0

          语法如下:

          db.command.aggregate.cmp([<expression1>, <expression2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "shop1": 10, "shop2": 100 }{ "_id": 2, "shop1": 80, "shop2": 20 }{ "_id": 3, "shop1": 50, "shop2": 50 }

          求 shop1 和 shop2 的各个物品的价格对比。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    compare: $.cmp(['$shop1', '$shop2']))  })  .end()

          返回结果如下:

          { "_id": 1, "compare": -1 }{ "_id": 2, "compare": 1 }{ "_id": 3, "compare": 0 }

          AggregateCommand.eq(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果相等则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.eq([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          求 value 等于 50 的记录。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.eq(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": false }{ "_id": 2, "matched": false }{ "_id": 3, "matched": true }

          AggregateCommand.gt(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果前者大于后者则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.gt([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          判断 value 是否大于 50。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.gt(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": false }{ "_id": 2, "matched": true }{ "_id": 3, "matched": false }

          AggregateCommand.gte(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果前者大于或等于后者则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.gte([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          判断 value 是否大于或等于 50。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.gte(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": false }{ "_id": 2, "matched": true }{ "_id": 3, "matched": true }

          AggregateCommand.lt(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果前者小于后者则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.lt([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          判断 value 是否小于 50。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.lt(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": true }{ "_id": 2, "matched": false }{ "_id": 3, "matched": false }

          AggregateCommand.lte(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果前者小于或等于后者则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.lte([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          判断 value 是否小于 50。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.lte(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": true }{ "_id": 2, "matched": false }{ "_id": 3, "matched": true }

          AggregateCommand.neq(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。匹配两个值,如果不相等则返回 true,否则返回 false。

          参数

          value: Expression[]

          [<value1>, <value2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.neq([<value1>, <value2>])

          示例代码

          假设集合 price 有如下记录:

          { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

          求 value 不等于 50 的记录。

          const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.neq(['$value', 50])  })  .end()

          返回结果如下:

          { "_id": 1, "matched": true }{ "_id": 2, "matched": true }{ "_id": 3, "matched": false }


          AggregateCommand.cond(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。计算布尔表达式,返回指定的两个值其中之一。

          参数

          value: any

          返回值

          Object

          API 说明

          cond 的使用形式如下:

          cond({ if: <布尔表达式>, then: <真值>, else: <假值>  })

          或者:

          cond([ <布尔表达式>, <真值>, <假值> ])

          两种形式中,三个参数(if、then、else)都是必须的。

          如果布尔表达式为真,那么 $cond 将会返回 <真值>,否则会返回 <假值>

          示例代码

          假设集合 items 的记录如下:

          { "_id": "0", "name": "item-a", "amount": 100 }{ "_id": "1", "name": "item-b", "amount": 200 }{ "_id": "2", "name": "item-c", "amount": 300 }

          我们可以使用 cond,根据 amount 字段,来生成新的字段 discount:

          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    name: 1,    discount: $.cond({        if: $.gte(['$amount', 200]),        then: 0.7,        else: 0.9    })  })  .end()

          输出如下:

          { "_id": "0", "name": "item-a", "discount": 0.9 }{ "_id": "1", "name": "item-b", "discount": 0.7 }{ "_id": "2", "name": "item-c", "discount": 0.7 }

          AggregateCommand.ifNull(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。计算给定的表达式,如果表达式结果为 null、undefined 或者不存在,那么返回一个替代值;否则返回原值。

          参数

          value: Expression[]

          [ <表达式>, <替代值> ]

          返回值

          Object

          API 说明

          ifNull 的使用形式如下:

          ifNull([ <表达式>, <替代值> ])

          示例代码

          假设集合 items 的记录如下:

          { "_id": "0", "name": "A", "description": "这是商品A" }{ "_id": "1", "name": "B", "description": null }{ "_id": "2", "name": "C" }

          我们可以使用 ifNull,对不存在 desc 字段的文档,或者 desc 字段为 null 的文档,补充一个替代值。

          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    _id: 0,    name: 1,    description: $.ifNull(['$description', '商品描述空缺'])  })  .end()

          输出如下:

          { "name": "A", "description": "这是商品A" }{ "name": "B", "description": "商品描述空缺" }{ "name": "C", "description": "商品描述空缺" }

          AggregateCommand.switch(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。根据给定的 switch-case-default 计算返回值、

          参数

          value: any

          返回值

          Object

          API 说明

          switch 的使用形式如下:

          switch({    branches: [        case: <表达式>, then: <表达式>,        case: <表达式>, then: <表达式>,        ...    ],    default: <表达式>})

          示例代码

          假设集合 items 的记录如下:

          { "_id": "0", "name": "item-a", "amount": 100 }{ "_id": "1", "name": "item-b", "amount": 200 }{ "_id": "2", "name": "item-c", "amount": 300 }

          我们可以使用 switch,根据 amount 字段,来生成新的字段 discount:

          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    name: 1,    discount: $.switch({        branches: [            { case: $.gt(['$amount', 250]), then: 0.8 },            { case: $.gt(['$amount', 150]), then: 0.9 }        ],        default: 1    })  })  .end()

          输出如下:

          { "_id": "0", "name": "item-a", "discount": 1 }{ "_id": "1", "name": "item-b", "discount": 0.9 }{ "_id": "2", "name": "item-c", "discount": 0.8 }


          AggregateCommand.dateFromParts(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。给定日期的相关信息,构建并返回一个日期对象。

          参数

          value: any

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.dateFromParts({    year: <year>,    month: <month>,    day: <day>,    hour: <hour>,    minute: <minute>,    second: <second>,    millisecond: <ms>,    timezone: <tzExpression>})

          你也可以使用 ISO 8601 的标准:

          db.command.aggregate.dateFromParts({    isoWeekYear: <year>,    isoWeek: <week>,    isoDayOfWeek: <day>,    hour: <hour>,    minute: <minute>,    second: <second>,    millisecond: <ms>,    timezone: <tzExpression>})

          示例代码

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    date: $.dateFromParts({        year: 2017,        month: 2,        day: 8,        hour: 12,        timezone: 'America/New_York'    }),  })  .end()

          输出如下:

          {    "date": ISODate("2017-02-08T17:00:00.000Z")}

          AggregateCommand.dateFromString(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将一个日期/时间字符串转换为日期对象

          参数

          value: any

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.dateFromString({    dateString: <dateStringExpression>,    timezone: <tzExpression>})

          示例代码

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    date: $.dateFromString({        dateString: "2019-05-14T09:38:51.686Z"    })  })  .end()

          输出如下:

          {    "date": ISODate("2019-05-14T09:38:51.686Z")}

          AggregateCommand.dateToString(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。根据指定的表达式将日期对象格式化为符合要求的字符串。

          参数

          value: any

          返回值

          Object

          API 说明

          dateToString 的调用形式如下:

          db.command.aggregate.dateToString({  date: <日期表达式>,  format: <格式化表达式>,  timezone: <时区表达式>,  onNull: <空值表达式>})

          下面是四种表达式的详细说明:

          名称描述
          日期表达式必选。指定字段值应该是能转化为字符串的日期。
          格式化表达式可选。它可以是任何包含“格式说明符”的有效字符串。
          时区表达式可选。指明运算结果的时区。它可以解析格式为 UTC Offset 或者 Olson Timezone Identifier 的字符串。
          空值表达式可选。当 <日期表达式> 返回空或者不存在的时候,会返回此表达式指明的值。

          下面是格式说明符的详细说明:

          说明符描述合法值
          %d月份的日期(2位数,0填充)01 - 31
          %GISO 8601 格式的年份0000 - 9999
          %H小时(2位数,0填充,24小时制)00 - 23
          %j一年中的一天(3位数,0填充)001 - 366
          %L毫秒(3位数,0填充)000 - 999
          %m月份(2位数,0填充)01 - 12
          %M分钟(2位数,0填充)00 - 59
          %S秒(2位数,0填充)00 - 60
          %w星期几1 - 7
          %uISO 8601 格式的星期几1 - 7
          %U一年中的一周(2位数,0填充)00 - 53
          %VISO 8601 格式的一年中的一周1 - 53
          %Y年份(4位数,0填充)0000 - 9999
          %z与 UTC 的时区偏移量+/-[hh][mm]
          %Z以分钟为单位,与 UTC 的时区偏移量+/-mmm
          %%百分号作为字符%

          示例代码

          假设集合 students 有如下记录:

          { "date": "1999-12-11T16:00:00.000Z", "firstName": "Yuanxin", "lastName": "Dong" }{ "date": "1998-11-10T16:00:00.000Z", "firstName": "Weijia", "lastName": "Wang" }{ "date": "1997-10-09T16:00:00.000Z", "firstName": "Chengxi", "lastName": "Li" }

          格式化日期

          下面是将 date 字段的值,格式化成形如 年份-月份-日期 的字符串:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$date',      format: '%Y-%m-%d'    })  })  .end()

          返回的结果如下:

          { "formatDate": "1999-12-11" }{ "formatDate": "1998-11-10" }{ "formatDate": "1997-10-09" }

          时区时间

          下面是将 date 字段值格式化为上海时区时间的例子:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$date',      format: '%H:%M:%S',      timezone: 'Asia/Shanghai'    })  })  .end()

          返回的结果如下:

          { "formatDate": "00:00:00" }{ "formatDate": "00:00:00" }{ "formatDate": "00:00:00" }

          缺失情况的默认值

          当指定的 <日期表达式> 返回空或者不存在的时候,可以设置缺失情况下的默认值:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$empty',      onNull: 'null'    })  })  .end()

          返回的结果如下:

          { "formatDate": "null" }{ "formatDate": "null" }{ "formatDate": "null" }

          AggregateCommand.dayOfMonth(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的天数(一个月中的哪一天),是一个介于 1 至 31 之间的数字。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.dayOfMonth(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 dayOfMonth() 对 date 字段进行投影,获取对应的日期:

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    dayOfMonth: $.dayOfMonth('$date')  })  .end()

          输出如下:

          {    "dayOfMonth": 14}

          AggregateCommand.dayOfWeek(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的天数(一周中的第几天),是一个介于 1(周日)到 7(周六)之间的整数。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          注意:周日是每周的第 1 天*

          语法如下:

          db.command.aggregate.dayOfWeek(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 dayOfWeek() 对 date 字段进行投影,获取对应的天数(一周中的第几天):

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    dayOfWeek: $.dayOfWeek('$date')  })  .end()

          输出如下:

          {    "dayOfWeek": 3}

          AggregateCommand.dayOfYear(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的天数(一年中的第几天),是一个介于 1 到 366 之间的整数。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.dayOfYear(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 dayOfYear() 对 date 字段进行投影,获取对应的天数(一年中的第几天):

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    dayOfYear: $.dayOfYear('$date')  })  .end()

          输出如下:

          {    "dayOfYear": 134}

          AggregateCommand.hour(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的小时数,是一个介于 0 到 23 之间的整数。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.hour(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 hour() 对 date 字段进行投影,获取对应的小时数:

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    hour: $.hour('$date')  })  .end()

          输出如下:

          {    "hour": 9}

          AggregateCommand.isoDayOfWeek(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的 ISO 8601 标准的天数(一周中的第几天),是一个介于 1(周一)到 7(周日)之间的整数。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.month(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 month() 对 date 字段进行投影,获取对应的 ISO 8601 标准的天数(一周中的第几天):

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    isoDayOfWeek: $.isoDayOfWeek('$date')  })  .end()

          输出如下:

          {    "isoDayOfWeek": 2}

          AggregateCommand.isoWeek(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的 ISO 8601 标准的周数(一年中的第几周),是一个介于 1 到 53 之间的整数。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          根据 ISO 8601 标准,周一到周日视为一周,本年度第一个周四所在的那周,视为本年度的第 1 周。

          例如:2016 年 1 月 7 日是那年的第一个周四,那么 2016.01.04(周一)到 2016.01.10(周日) 即为第 1 周。同理,2016 年 1 月 1 日的周数为 53。

          语法如下:

          db.command.aggregate.isoWeek(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 isoWeek() 对 date 字段进行投影,获取对应的 ISO 8601 标准的周数(一年中的第几周):

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    isoWeek: $.isoWeek('$date')  })  .end()

          输出如下:

          {    "isoWeek": 20}

          AggregateCommand.isoWeekYear(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的 ISO 8601 标准的天数(一年中的第几天)。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          此处的“年”以第一周的周一为开始,以最后一周的周日为结束。

          语法如下:

          db.command.aggregate.isoWeekYear(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 isoWeekYear() 对 date 字段进行投影,获取对应的 ISO 8601 标准的天数(一年中的第几天):

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    isoWeekYear: $.isoWeekYear('$date')  })  .end()

          输出如下:

          {    "isoWeekYear": 2019}

          AggregateCommand.millisecond(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的毫秒数,是一个介于 0 到 999 之间的整数。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.millisecond(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 millisecond() 对 date 字段进行投影,获取对应的毫秒数:

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    millisecond: $.millisecond('$date'),  })  .end()

          输出如下:

          {    "millisecond": 686}

          AggregateCommand.minute(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的分钟数,是一个介于 0 到 59 之间的整数。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.minute(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 minute() 对 date 字段进行投影,获取对应的分钟数:

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    minute: $.minute('$date')  })  .end()

          输出如下:

          {    "minute": 38}

          AggregateCommand.month(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的月份,是一个介于 1 到 12 之间的整数。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.month(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 month() 对 date 字段进行投影,获取对应的月份:

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    month: $.month('$date')  })  .end()

          输出如下:

          {    "month": 5}

          AggregateCommand.second(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的秒数,是一个介于 0 到 59 之间的整数,在特殊情况下(闰秒)可能等于 60。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.second(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 second() 对 date 字段进行投影,获取对应的秒数:

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    second: $.second('$date')  })  .end()

          输出如下:

          {    "second": 51}

          AggregateCommand.week(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的周数(一年中的第几周),是一个介于 0 到 53 之间的整数。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          每周以周日为开头,每年的第一个周日即为 week 1 的开始,这天之前是 week 0。

          语法如下:

          db.command.aggregate.week(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 week() 对 date 字段进行投影,获取对应的周数(一年中的第几周):

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    week: $.week('$date')  })  .end()

          输出如下:

          {    "week": 19}

          AggregateCommand.year(value: Expression<string>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回日期字段对应的年份。

          参数

          value: Expression<string>

          日期字段

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.year(<日期字段>)

          示例代码

          假设集合 dates 有以下文档:

          {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

          我们使用 year() 对 date 字段进行投影,获取对应的年份:

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    year: $.year('$date')  })  .end()

          输出如下:

          {    "year": 2019}

          AggregateCommand.subtract(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将两个数字相减然后返回差值,或将两个日期相减然后返回相差的毫秒数,或将一个日期减去一个数字返回结果的日期。

          参数

          value: Expression[]

          [<expression1>, <expression2>]

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.subtract([<expression1>, <expression2>])

          参数可以是任意解析为数字或日期的表达式。

          示例代码

          假设集合 scores 有如下记录:

          { "_id": 1, "max": 10, "min": 1 }{ "_id": 2, "max": 7, "min": 5 }{ "_id": 3, "max": 6, "min": 6 }

          求各个记录的 max 和 min 的差值。:

          const $ = db.command.aggregatedb.collection('scores').aggregate()  .project({    diff: $.subtract(['$max', '$min'])  })  .end()

          返回结果如下:

          { "_id": 1, "diff": 9 }{ "_id": 2, "diff": 2 }{ "_id": 3, "diff": 0 }


          AggregateCommand.literal(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。直接返回一个值的字面量,不经过任何解析和处理。

          参数

          value: any

          返回值

          Object

          API 说明

          literal 使用形式如下:

          literal(<值>)

          如果 <值> 是一个表达式,那么 literal 不会解析或者计算这个表达式,而是直接返回这个表达式。

          示例代码

          比如我们有一个 items 集合,其中数据如下:

          { "_id": "0", "price": "$1" }{ "_id": "1", "price": "$5.60" }{ "_id": "2", "price": "$8.90" }

          以字面量的形式使用 $

          下面的代码使用 literal,生成了一个新的字段 isOneDollar,表示 price 字段是否严格等于 "$1"。

          注意:我们这里无法使用 eq(['$price', '$1']),因为 "$1" 是一个表达式,代表 "1" 字段对应的值,而不是字符串字面量 "$1"。

          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    isOneDollar: $.eq(['$price', $.literal('$1')])  })  .end()

          输出如下:

          { "_id": "0", "isOneDollar": true }{ "_id": "1", "isOneDollar": false }{ "_id": "2", "isOneDollar": false }

          投影一个字段,对应的值为 1

          下面的代码使用 literal,投影了一个新的字段 amount,其值为 1。

          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    price: 1,    amount: $.literal(1)  })  .end()

          输出如下:

          { "_id": "0", "price": "$1", "amount": 1 }{ "_id": "1", "price": "$5.60", "amount": 1 }{ "_id": "2", "price": "$8.90", "amount": 1 }


          AggregateCommand.mergeObjects(value: Expression<document>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将多个文档合并为单个文档。

          参数

          value: Expression<document>

          Document 表达式

          返回值

          Object

          API 说明

          使用形式如下: 在 group() 中使用时:

          mergeObjects(<document>)

          在其它表达式中使用时:

          mergeObjects([<document1>, <document2>, ...])

          示例代码

          搭配 group() 使用

          假设集合 sales 存在以下文档:

          { "_id": 1, "year": 2018, "name": "A", "volume": { "2018Q1": 500, "2018Q2": 500 } }{ "_id": 2, "year": 2017, "name": "A", "volume": { "2017Q1": 400, "2017Q2": 300, "2017Q3": 0, "2017Q4": 0 } }{ "_id": 3, "year": 2018, "name": "B", "volume": { "2018Q1": 100 } }{ "_id": 4, "year": 2017, "name": "B", "volume": { "2017Q3": 100, "2017Q4": 250 } }

          下面的代码使用 mergeObjects(),将用相同 name 的文档合并:

          const $ = db.command.aggregatedb.collection('sales').aggregate()  .group({    _id: '$name',    mergedVolume: $.mergeObjects('$volume')  })  .end()

          输出如下:

          { "_id": "A", "mergedVolume": { "2017Q1": 400, "2017Q2": 300, "2017Q3": 0, "2017Q4": 0, "2018Q1": 500, "2018Q2": 500 } }{ "_id": "B", "mergedVolume": { "2017Q3": 100, "2017Q4": 250, "2018Q1": 100 } }

          一般用法

          假设集合 test 存在以下文档:

          { "_id": 1, "foo": { "a": 1 }, "bar": { "b": 2 } }{ "_id": 2, "foo": { "c": 1 }, "bar": { "d": 2 } }{ "_id": 3, "foo": { "e": 1 }, "bar": { "f": 2 } }

          下面的代码使用 mergeObjects(),将文档中的 foo 和 bar 字段合并为 foobar:

          const $ = db.command.aggregatedb.collection('sales').aggregate()  .project({    foobar: $.mergeObjects(['$foo', '$bar'])  })  .end()

          输出结果如下:

          { "_id": 1, "foobar": { "a": 1, "b": 2 } }{ "_id": 2, "foobar": { "c": 1, "d": 2 } }{ "_id": 3, "foobar": { "e": 1, "f": 2 } }

          AggregateCommand.objectToArray(value: Expression<object>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将一个对象转换为数组。方法把对象的每个键值对都变成输出数组的一个元素,元素形如 { k: &lt;key&gt;, v: &lt;value&gt; }。

          参数

          value: Expression<object>

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.objectToArray(<object>)

          示例代码

          假设集合 items 有如下记录:

          { "_id": 1, "attributes": { "color": "red", "price": 150 } }{ "_id": 2, "attributes": { "color": "blue", "price": 50 } }{ "_id": 3, "attributes": { "color": "yellow", "price": 10 } }
          const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    array: $.objectToArray('$attributes')  })  .end()

          返回结果如下:

          { "_id": 1, "array": [{ "k": "color", "v": "red" }, { "k": "price", "v": 150 }] }{ "_id": 2, "array": [{ "k": "color", "v": "blue" }, { "k": "price", "v": 50 }] }{ "_id": 3, "array": [{ "k": "color", "v": "yellow" }, { "k": "price", "v": 10 }] }


          AggregateCommand.allElementsTrue(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。输入一个数组,或者数组字段的表达式。如果数组中所有元素均为真值,那么返回 true,否则返回 false。空数组永远返回 true。

          参数

          value: Expression[]

          [<expression>]

          返回值

          Object

          API 说明

          语法如下:

          allElementsTrue([<expression>])

          示例代码

          假设集合 test 有如下记录:

          { "_id": 1, "array": [ true ] }{ "_id": 2, "array": [ ] }{ "_id": 3, "array": [ false ] }{ "_id": 4, "array": [ true, false ] }{ "_id": 5, "array": [ 0 ] }{ "_id": 6, "array": [ "stark" ] }

          下面的代码使用 allElementsTrue(),判断 array 字段中是否均为真值:

          const $ = db.command.aggregatedb.collection('price')  .aggregate()  .project({    isAllTrue: $.allElementsTrue(['$array'])  })  .end()

          返回结果如下:

          { "_id": 1, "isAllTrue": true }{ "_id": 2, "isAllTrue": true }{ "_id": 3, "isAllTrue": false }{ "_id": 4, "isAllTrue": false }{ "_id": 5, "isAllTrue": false }{ "_id": 6, "isAllTrue": true }

          AggregateCommand.anyElementTrue(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。输入一个数组,或者数组字段的表达式。如果数组中任意一个元素为真值,那么返回 true,否则返回 false。空数组永远返回 false。

          参数

          value: Expression[]

          [<expression>]

          返回值

          Object

          API 说明

          语法如下:

          anyElementTrue([<expression>])

          示例代码

          假设集合 test 有如下记录:

          { "_id": 1, "array": [ true ] }{ "_id": 2, "array": [ ] }{ "_id": 3, "array": [ false ] }{ "_id": 4, "array": [ true, false ] }{ "_id": 5, "array": [ 0 ] }{ "_id": 6, "array": [ "stark" ] }

          下面的代码使用 anyElementTrue(),判断 array 字段中是否含有真值:

          const $ = db.command.aggregatedb.collection('price')  .aggregate()  .project({    isAnyTrue: $.anyElementTrue(['$array'])  })  .end()

          返回结果如下:

          { "_id": 1, "isAnyTrue": true }{ "_id": 2, "isAnyTrue": false }{ "_id": 3, "isAnyTrue": false }{ "_id": 4, "isAnyTrue": true }{ "_id": 5, "isAnyTrue": false }{ "_id": 6, "isAnyTrue": true }

          AggregateCommand.setDifference(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符,输入两个集合,输出只存在于第一个集合中的元素。

          参数

          value: Expression[]

          [<expression1>, <expression2>]

          返回值

          Object

          API 说明

          使用形式如下:

          setDifference([<expression1>, <expression2>])

          示例代码

          假设集合 test 存在以下数据:

          { "_id": 1, "A": [ 1, 2 ], "B": [ 1, 2 ] }{ "_id": 2, "A": [ 1, 2 ], "B": [ 2, 1, 2 ] }{ "_id": 3, "A": [ 1, 2 ], "B": [ 1, 2, 3 ] }{ "_id": 4, "A": [ 1, 2 ], "B": [ 3, 1 ] }{ "_id": 5, "A": [ 1, 2 ], "B": [ ] }{ "_id": 6, "A": [ 1, 2 ], "B": [ {}, [] ] }{ "_id": 7, "A": [ ], "B": [ ] }{ "_id": 8, "A": [ ], "B": [ 1 ] }

          下面的代码使用 setDifference,找到只存在于 B 中的数字:

          db.collection('test')  .aggregate()  .project({    isBOnly: $.setDifference(['$B', '$A'])  })  .end()
          { "_id": 1, "isBOnly": [] }{ "_id": 2, "isBOnly": [3] }{ "_id": 3, "isBOnly": [3] }{ "_id": 4, "isBOnly": [5] }{ "_id": 5, "isBOnly": [] }{ "_id": 6, "isBOnly": [{}, []] }{ "_id": 7, "isBOnly": [] }{ "_id": 8, "isBOnly": [1] }

          AggregateCommand.setEquals(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符,输入两个集合,判断两个集合中包含的元素是否相同(不考虑顺序、去重)。

          参数

          value: Expression[]

          [<expression1>, <expression2>]

          返回值

          Object

          API 说明

          使用形式如下:

          setEquals([<expression1>, <expression2>])

          示例代码

          假设集合 test 存在以下数据:

          { "_id": 1, "A": [ 1, 2 ], "B": [ 1, 2 ] }{ "_id": 2, "A": [ 1, 2 ], "B": [ 2, 1, 2 ] }{ "_id": 3, "A": [ 1, 2 ], "B": [ 1, 2, 3 ] }{ "_id": 4, "A": [ 1, 2 ], "B": [ 3, 1 ] }{ "_id": 5, "A": [ 1, 2 ], "B": [ ] }{ "_id": 6, "A": [ 1, 2 ], "B": [ {}, [] ] }{ "_id": 7, "A": [ ], "B": [ ] }{ "_id": 8, "A": [ ], "B": [ 1 ] }

          下面的代码使用 setEquals,判断两个集合中包含的元素是否相同:

          db.collection('test')  .aggregate()  .project({    sameElements: $.setEquals(['$A', '$B'])  })  .end()
          { "_id": 1, "sameElements": true }{ "_id": 2, "sameElements": true }{ "_id": 3, "sameElements": false }{ "_id": 4, "sameElements": false }{ "_id": 5, "sameElements": false }{ "_id": 6, "sameElements": false }{ "_id": 7, "sameElements": true }{ "_id": 8, "sameElements": false }

          AggregateCommand.setIntersection(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符,输入两个集合,输出两个集合的交集。

          参数

          value: Expression[]

          [<expression1>, <expression2>]

          返回值

          Object

          API 说明

          使用形式如下:

          setIntersection([<expression1>, <expression2>])

          示例代码

          假设集合 test 存在以下数据:

          { "_id": 1, "A": [ 1, 2 ], "B": [ 1, 2 ] }{ "_id": 2, "A": [ 1, 2 ], "B": [ 2, 1, 2 ] }{ "_id": 3, "A": [ 1, 2 ], "B": [ 1, 2, 3 ] }{ "_id": 4, "A": [ 1, 2 ], "B": [ 3, 1 ] }{ "_id": 5, "A": [ 1, 2 ], "B": [ ] }{ "_id": 6, "A": [ 1, 2 ], "B": [ {}, [] ] }{ "_id": 7, "A": [ ], "B": [ ] }{ "_id": 8, "A": [ ], "B": [ 1 ] }

          下面的代码使用 setIntersection,输出两个集合的交集:

          db.collection('test')  .aggregate()  .project({    commonToBoth: $.setIntersection(['$A', '$B'])  })  .end()

          输出如下:

          { "_id": 1, "commonToBoth": [ 1, 2 ] }{ "_id": 2, "commonToBoth": [ 1, 2 ] }{ "_id": 3, "commonToBoth": [ 1, 2 ] }{ "_id": 4, "commonToBoth": [ 1 ] }{ "_id": 5, "commonToBoth": [ ] }{ "_id": 6, "commonToBoth": [ ] }{ "_id": 7, "commonToBoth": [ ] }{ "_id": 8, "commonToBoth": [ ] }

          AggregateCommand.setIsSubset(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符,输入两个集合,判断第一个集合是否是第二个集合的子集。

          参数

          value: Expression[]

          [<expression1>, <expression2>]

          返回值

          Object

          API 说明

          使用形式如下:

          setIsSubset([<expression1>, <expression2>])

          示例代码

          假设集合 test 存在以下数据:

          { "_id": 1, "A": [ 1, 2 ], "B": [ 1, 2 ] }{ "_id": 2, "A": [ 1, 2 ], "B": [ 2, 1, 2 ] }{ "_id": 3, "A": [ 1, 2 ], "B": [ 1, 2, 3 ] }{ "_id": 4, "A": [ 1, 2 ], "B": [ 3, 1 ] }{ "_id": 5, "A": [ 1, 2 ], "B": [ ] }{ "_id": 6, "A": [ 1, 2 ], "B": [ {}, [] ] }{ "_id": 7, "A": [ ], "B": [ ] }{ "_id": 8, "A": [ ], "B": [ 1 ] }

          下面的代码使用 setIsSubset,判断第一个集合是否是第二个集合的子集:

          db.collection('test')  .aggregate()  .project({    AisSubsetOfB: $.setIsSubset(['$A', '$B'])  })  .end()
          { "_id": 1, "AisSubsetOfB": true }{ "_id": 2, "AisSubsetOfB": true }{ "_id": 3, "AisSubsetOfB": true }{ "_id": 4, "AisSubsetOfB": false }{ "_id": 5, "AisSubsetOfB": false }{ "_id": 6, "AisSubsetOfB": false }{ "_id": 7, "AisSubsetOfB": true }{ "_id": 8, "AisSubsetOfB": true }

          AggregateCommand.setUnion(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符,输入两个集合,输出两个集合的并集。

          参数

          value: Expression[]

          [<expression1>, <expression2>]

          返回值

          Object

          API 说明

          使用形式如下:

          setUnion([<expression1>, <expression2>])

          示例代码

          假设集合 test 存在以下数据:

          { "_id": 1, "A": [ 1, 2 ], "B": [ 1, 2 ] }{ "_id": 2, "A": [ 1, 2 ], "B": [ 2, 1, 2 ] }{ "_id": 3, "A": [ 1, 2 ], "B": [ 1, 2, 3 ] }{ "_id": 4, "A": [ 1, 2 ], "B": [ 3, 1 ] }{ "_id": 5, "A": [ 1, 2 ], "B": [ ] }{ "_id": 6, "A": [ 1, 2 ], "B": [ {}, [] ] }{ "_id": 7, "A": [ ], "B": [ ] }{ "_id": 8, "A": [ ], "B": [ 1 ] }

          下面的代码使用 setUnion,输出两个集合的并集:

          db.collection('test')  .aggregate()  .project({    AB: $.setUnion(['$A', '$B'])  })  .end()

          输出如下:

          { "_id": 1, "AB": [ 1, 2 ] }{ "_id": 2, "AB": [ 1, 2 ] }{ "_id": 3, "AB": [ 1, 2, 3 ] }{ "_id": 4, "AB": [ 1, 2, 3 ] }{ "_id": 5, "AB": [ 1, 2 ] }{ "_id": 6, "AB": [ 1, 2, {}, [] ] }{ "_id": 7, "AB": [ ] }{ "_id": 8, "AB": [ 1 ] }


          AggregateCommand.concat(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。连接字符串,返回拼接后的字符串。

          参数

          value: Expression[]

          [<表达式1>, <表达式2>, ...]

          返回值

          Object

          API 说明

          concat 的语法如下:

          db.command.aggregate.concat([<表达式1>, <表达式2>, ...])

          表达式可以是形如 $ + 指定字段,也可以是普通字符串。只要能够被解析成字符串即可。

          示例代码

          假设集合 students 的记录如下:

          { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

          借助 concat 可以拼接 lastName 和 firstName 字段,得到每位学生的名字全称:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    fullName: $.concat(['$firstName', ' ', '$lastName'])  })  .end()

          返回的结果如下:

          { "fullName": "Yuanxin Dong" }{ "fullName": "Weijia Wang" }{ "fullName": "Chengxi Li" }

          AggregateCommand.dateFromString(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将一个日期/时间字符串转换为日期对象

          参数

          value: any

          返回值

          Object

          API 说明

          语法如下:

          db.command.aggregate.dateFromString({    dateString: <dateStringExpression>,    timezone: <tzExpression>})

          示例代码

          const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    date: $.dateFromString({        dateString: "2019-05-14T09:38:51.686Z"    })  })  .end()

          输出如下:

          {    "date": ISODate("2019-05-14T09:38:51.686Z")}

          AggregateCommand.dateToString(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。根据指定的表达式将日期对象格式化为符合要求的字符串。

          参数

          value: any

          返回值

          Object

          API 说明

          dateToString 的调用形式如下:

          db.command.aggregate.dateToString({  date: <日期表达式>,  format: <格式化表达式>,  timezone: <时区表达式>,  onNull: <空值表达式>})

          下面是四种表达式的详细说明:

          名称描述
          日期表达式必选。指定字段值应该是能转化为字符串的日期。
          格式化表达式可选。它可以是任何包含“格式说明符”的有效字符串。
          时区表达式可选。指明运算结果的时区。它可以解析格式为 UTC Offset 或者 Olson Timezone Identifier 的字符串。
          空值表达式可选。当 <日期表达式> 返回空或者不存在的时候,会返回此表达式指明的值。

          下面是格式说明符的详细说明:

          说明符描述合法值
          %d月份的日期(2位数,0填充)01 - 31
          %GISO 8601 格式的年份0000 - 9999
          %H小时(2位数,0填充,24小时制)00 - 23
          %j一年中的一天(3位数,0填充)001 - 366
          %L毫秒(3位数,0填充)000 - 999
          %m月份(2位数,0填充)01 - 12
          %M分钟(2位数,0填充)00 - 59
          %S秒(2位数,0填充)00 - 60
          %w星期几1 - 7
          %uISO 8601 格式的星期几1 - 7
          %U一年中的一周(2位数,0填充)00 - 53
          %VISO 8601 格式的一年中的一周1 - 53
          %Y年份(4位数,0填充)0000 - 9999
          %z与 UTC 的时区偏移量+/-[hh][mm]
          %Z以分钟为单位,与 UTC 的时区偏移量+/-mmm
          %%百分号作为字符%

          示例代码

          假设集合 students 有如下记录:

          { "date": "1999-12-11T16:00:00.000Z", "firstName": "Yuanxin", "lastName": "Dong" }{ "date": "1998-11-10T16:00:00.000Z", "firstName": "Weijia", "lastName": "Wang" }{ "date": "1997-10-09T16:00:00.000Z", "firstName": "Chengxi", "lastName": "Li" }

          格式化日期

          下面是将 date 字段的值,格式化成形如 年份-月份-日期 的字符串:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$date',      format: '%Y-%m-%d'    })  })  .end()

          返回的结果如下:

          { "formatDate": "1999-12-11" }{ "formatDate": "1998-11-10" }{ "formatDate": "1997-10-09" }

          时区时间

          下面是将 date 字段值格式化为上海时区时间的例子:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$date',      format: '%H:%M:%S',      timezone: 'Asia/Shanghai'    })  })  .end()

          返回的结果如下:

          { "formatDate": "00:00:00" }{ "formatDate": "00:00:00" }{ "formatDate": "00:00:00" }

          缺失情况的默认值

          当指定的 <日期表达式> 返回空或者不存在的时候,可以设置缺失情况下的默认值:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$empty',      onNull: 'null'    })  })  .end()

          返回的结果如下:

          { "formatDate": "null" }{ "formatDate": "null" }{ "formatDate": "null" }

          AggregateCommand.indexOfBytes(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。在目标字符串中查找子字符串,并返回第一次出现的 UTF-8 的字节索引(从0开始)。如果不存在子字符串,返回 -1。

          参数

          value: Expression[]

          [<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>]

          返回值

          Object

          API 说明

          indexOfBytes 的语法如下:

          db.command.aggregate.indexOfBytes([<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>])

          下面是 4 种表达式的详细描述:

          表达式描述
          目标字符串表达式任何可以被解析为字符串的表达式
          子字符串表达式任何可以被解析为字符串的表达式
          开始位置表达式任何可以被解析为非负整数的表达式
          结束位置表达式任何可以被解析为非负整数的表达式

          示例代码

          假设集合 students 的记录如下:

          { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

          借助 indexOfBytes 查找字符 "a" 在字段 firstName 中的位置:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    aStrIndex: $.indexOfBytes(['$firstName', 'a'])  })  .end()

          返回的结果如下:

          { "aStrIndex": 2 }{ "aStrIndex": 5 }{ "aStrIndex": -1 }

          AggregateCommand.indexOfCP(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。在目标字符串中查找子字符串,并返回第一次出现的 UTF-8 的 code point 索引(从0开始)。如果不存在子字符串,返回 -1。

          参数

          value: Expression[]

          [<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>]

          返回值

          Object

          API 说明

          code point 是“码位”,又名“编码位置”。这里特指 Unicode 包中的码位,范围是从0(16进制)到10FFFF(16进制)。

          indexOfCP 的语法如下:

          db.command.aggregate.indexOfCP([<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>])

          下面是 4 种表达式的详细描述:

          表达式描述
          目标字符串表达式任何可以被解析为字符串的表达式
          子字符串表达式任何可以被解析为字符串的表达式
          开始位置表达式任何可以被解析为非负整数的表达式
          结束位置表达式任何可以被解析为非负整数的表达式

          示例代码

          假设集合 students 的记录如下:

          { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

          借助 indexOfCP 查找字符 "a" 在字段 firstName 中的位置:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    aStrIndex: $.indexOfCP(['$firstName', 'a'])  })  .end()

          返回的结果如下:

          { "aStrIndex": 2 }{ "aStrIndex": 5 }{ "aStrIndex": -1 }

          AggregateCommand.split(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。按照分隔符分隔数组,并且删除分隔符,返回子字符串组成的数组。如果字符串无法找到分隔符进行分隔,返回原字符串作为数组的唯一元素。

          参数

          value: Expression[]

          [<字符串表达式>, <分隔符表达式>]

          返回值

          Object

          API 说明

          split 的语法如下:

          db.command.aggregate.split([<字符串表达式>, <分隔符表达式>])

          字符串表达式和分隔符表达式可以是任意形式的表达式,只要它可以被解析为字符串即可。

          示例代码

          假设集合 students 的记录如下:

          { "birthday": "1999/12/12" }{ "birthday": "1998/11/11" }{ "birthday": "1997/10/10" }

          通过 split 将每条记录中的 birthday 字段对应值分隔成数组,每个数组分别由代表年、月、日的3个元素组成:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    birthday: $.split(['$birthday', '/'])  })  .end()

          返回的结果如下:

          { "birthday": [ "1999", "12", "12" ] }{ "birthday": [ "1998", "11", "11" ] }{ "birthday": [ "1997", "10", "10" ] }

          AggregateCommand.strLenBytes(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。计算并返回指定字符串中 utf-8 编码的字节数量。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          strLenBytes 的语法如下:

          db.command.aggregate.strLenBytes(<表达式>)

          只要表达式可以被解析成字符串,那么它就是有效表达式。

          示例代码

          假设集合 students 的记录如下:

          { "name": "dongyuanxin", "nickname": "心谭" }

          借助 strLenBytes 计算 name 字段和 nickname 字段对应值的字节长度:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    nameLength: $.strLenBytes('$name'),    nicknameLength: $.strLenBytes('$nickname')  })  .end()

          返回结果如下:

          { "nameLength": 11, "nicknameLength": 6 }

          AggregateCommand.strLenCP(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。计算并返回指定字符串的UTF-8 code points 数量。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          strLenCP 的语法如下:

          db.command.aggregate.strLenCP(<表达式>)

          只要表达式可以被解析成字符串,那么它就是有效表达式。

          示例代码

          假设集合 students 的记录如下:

          { "name": "dongyuanxin", "nickname": "心谭" }

          借助 strLenCP 计算 name 字段和 nickname 字段对应值的UTF-8 code points的数量:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    nameLength: $.strLenCP('$name'),    nicknameLength: $.strLenCP('$nickname')  })  .end()

          返回结果如下:

          { "nameLength": 11, "nicknameLength": 2 }

          AggregateCommand.strcasecmp(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。对两个字符串在不区分大小写的情况下进行大小比较,并返回比较的结果。

          参数

          value: Expression[]

          [<表达式1>, <表达式2>]

          返回值

          Object

          API 说明

          strcasecmp 的语法如下:

          db.command.aggregate.strcasecmp([<表达式1>, <表达式2>])

          只要 表达式1和 表达式2 可以被解析成字符串,那么它们就是有效的。

          返回的比较结果有1,0和-1三种:

          • 1:表达式1 解析的字符串 > 表达式2 解析的字符串
          • 0:表达式1 解析的字符串 = 表达式2 解析的字符串
          • -1:表达式1 解析的字符串 < 表达式2 解析的字符串

          示例代码

          假设集合 students 的记录如下:

          { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

          借助 strcasecmp 比较 firstName 字段值和 lastName 字段值的大小:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    result: $.strcasecmp(['$firstName', '$lastName']),  })  .end()

          返回结果如下:

          { "result": 1 }{ "result": 1 }{ "result": -1 }

          AggregateCommand.substr(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。它是 db.command.aggregate.substrBytes 的别名,更推荐使用后者。

          参数

          value: Expression[]

          [<表达式1>, <表达式2>, <表达式3>]

          返回值

          Object

          API 说明

          substr 的语法如下:

          db.command.aggregate.substr([<表达式1>, <表达式2>, <表达式3>])

          表达式1 是任何可以解析为字符串的有效表达式,表达式2 和 表达式3 是任何可以解析为数字的有效表达式。

          如果 表达式2 是负数,返回的结果为 ""。

          如果 表达式3 是负数,返回的结果为从 表达式2 指定的开始位置以及之后其余部分的子字符串。

          示例代码

          假设集合 students 的记录如下:

          { "birthday": "1999/12/12", "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "birthday": "1998/11/11", "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "birthday": "1997/10/10", "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

          借助 substr 可以提取 birthday 中的年、月、日信息,代码如下:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    year: $.substr(['$birthday', 0, 4]),    month: $.substr(['$birthday', 5, 2]),    day: $.substr(['$birthday', 8, -1])  })  .end()

          返回的结果如下:

          { "day": "12", "month": "12", "year": "1999" }{ "day": "11", "month": "11", "year": "1998" }{ "day": "10", "month": "10", "year": "1997" }

          AggregateCommand.substrBytes(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。子字符串是由字符串中指定的 UTF-8 字节索引的字符开始,长度为指定的字节数。

          参数

          value: Expression[]

          [<表达式1>, <表达式2>, <表达式3>]

          返回值

          Object

          API 说明

          substrBytes 的语法如下:

          db.command.aggregate.substrBytes([<表达式1>, <表达式2>, <表达式3>])

          表达式1 是任何可以解析为字符串的有效表达式,表达式2 和 表达式3 是任何可以解析为数字的有效表达式。

          如果 表达式2 是负数,返回的结果为 ""。

          如果 表达式3 是负数,返回的结果为从 表达式2 指定的开始位置以及之后其余部分的子字符串。

          示例代码

          假设集合 students 的记录如下:

          { "birthday": "1999/12/12", "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "birthday": "1998/11/11", "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "birthday": "1997/10/10", "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

          借助 substrBytes 可以提取 birthday 中的年、月、日信息,代码如下:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    year: $.substrBytes(['$birthday', 0, 4]),    month: $.substrBytes(['$birthday', 5, 2]),    day: $.substrBytes(['$birthday', 8, -1])  })  .end()

          返回的结果如下:

          { "day": "12", "month": "12", "year": "1999" }{ "day": "11", "month": "11", "year": "1998" }{ "day": "10", "month": "10", "year": "1997" }

          AggregateCommand.substrCP(value: Expression[]): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。子字符串是由字符串中指定的 UTF-8 字节索引的字符开始,长度为指定的字节数。

          参数

          value: Expression[]

          [<表达式1>, <表达式2>, <表达式3>]

          返回值

          Object

          API 说明

          substrCP 的语法如下:

          db.command.aggregate.substrCP([<表达式1>, <表达式2>, <表达式3>])

          表达式1 是任何可以解析为字符串的有效表达式,表达式2 和 表达式3 是任何可以解析为数字的有效表达式。

          如果 表达式2 是负数,返回的结果为 ""。

          如果 表达式3 是负数,返回的结果为从 表达式2 指定的开始位置以及之后其余部分的子字符串。

          示例代码

          假设集合 students 的记录如下:

          { "name": "dongyuanxin", "nickname": "心谭" }

          借助 substrCP 可以提取 nickname 字段值的第一个汉字:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    firstCh: $.substrCP(['$nickname', 0, 1])  })  .end()

          返回的结果如下:

          { "firstCh": "心" }

          AggregateCommand.toLower(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将字符串转化为小写并返回。

          参数

          value: any

          返回值

          Object

          API 说明

          toLower 的语法如下:

          db.command.aggregate.toLower(表达式)

          只要表达式可以被解析成字符串,那么它就是有效表达式。例如:$ + 指定字段。

          示例代码

          假设集合 students 的记录如下:

          { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

          借助 toLower 将 firstName 的字段值转化为小写:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    result: $.toLower('$firstName'),  })  .end()

          返回的结果如下:

          { "result": "yuanxin" }{ "result": "weijia" }{ "result": "chengxi" }

          AggregateCommand.toUpper(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将字符串转化为大写并返回。

          参数

          value: any

          返回值

          Object

          API 说明

          toUpper 的语法如下:

          db.command.aggregate.toUpper(表达式)

          只要表达式可以被解析成字符串,那么它就是有效表达式。例如:$ + 指定字段。

          示例代码

          假设集合 students 的记录如下:

          { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

          借助 toUpper 将 lastName 的字段值转化为大写:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    result: $.toUpper('$lastName'),  })  .end()

          返回的结果如下:

          { "result": "DONG" }{ "result": "WANG" }{ "result": "LI" }


          AggregateCommand.addToSet(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。聚合运算符。向数组中添加值,如果数组中已存在该值,不执行任何操作。它只能在 group stage 中使用。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          addToSet 语法如下:

          db.command.aggregate.addToSet(<表达式>)

          表达式是形如 $ + 指定字段 的字符串。如果指定字段的值是数组,那么整个数组会被当作一个元素。

          示例代码

          假设集合 passages 的记录如下:

          { "category": "web", "tags": [ "JavaScript", "CSS" ], "title": "title1" }{ "category": "System", "tags": [ "C++", "C" ], "title": "title2" }

          非数组字段

          每条记录的 category 对应值的类型是非数组,利用 addToSet 统计所有分类:

          const $ = db.command.aggregatedb  .collection('passages')  .aggregate()  .group({    _id: null,    categories: $.addToSet('$category')  })  .end()

          返回的结果如下:

          { "_id": null, "categories": [ "System", "web" ] }

          数组字段

          每条记录的 tags 对应值的类型是数组,数组不会被自动展开:

          const $ = db.command.aggregatedb  .collection('passages')  .aggregate()  .group({    _id: null,    tagsList: $.addToSet('$tags')  })  .end()

          返回的结果如下:

          { "_id": null, "tagsList": [ [ "C++", "C" ], [ "JavaScript", "CSS" ] ] }

          AggregateCommand.avg(value: Expression<number>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回一组集合中,指定字段对应数据的平均值。

          参数

          value: Expression<number>

          number

          返回值

          Object

          API 说明

          avg 的语法如下:

          db.command.aggregate.avg(<number>)

          avg 传入的值除了数字常量外,也可以是任何最终解析成一个数字的表达式。它会忽略非数字值。

          示例代码

          假设集合 students 的记录如下:

          { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

          借助 avg 可以计算所有记录的 score 的平均值:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .group({    _id: null,    average: $.avg('$score')  })  .end()

          返回的结果如下:

          { "_id": null, "average": 90 }

          AggregateCommand.first(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回指定字段在一组集合的第一条记录对应的值。仅当这组集合是按照某种定义排序( sort )后,此操作才有意义。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          first 的语法如下:

          db.command.aggregate.first(<表达式>)

          表达式是形如 $ + 指定字段 的字符串。

          first 只能在 group 阶段被使用,并且需要配合 sort 才有意义。

          示例代码

          假设集合 students 的记录如下:

          { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

          如果需要得到所有记录中 score 的最小值,可以先将所有记录按照 score 排序,然后取出第一条记录的 first。

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .sort({    score: 1  })  .group({    _id: null,    min: $.first('$score')  })  .end()

          返回的数据结果如下:

          { "_id": null, "min": 80 }

          AggregateCommand.last(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回指定字段在一组集合的最后一条记录对应的值。仅当这组集合是按照某种定义排序( sort )后,此操作才有意义。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          last 的语法如下:

          db.command.aggregate.last(<表达式>)

          表达式是形如 $ + 指定字段 的字符串。

          last 只能在 group 阶段被使用,并且需要配合 sort 才有意义。

          示例代码

          假设集合 students 的记录如下:

          { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

          如果需要得到所有记录中 score 的最大值,可以先将所有记录按照 score 排序,然后取出最后一条记录的 last。

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .sort({    score: 1  })  .group({    _id: null,    max: $.last('$score')  })  .end()

          返回的数据结果如下:

          { "_id": null, "max": 100 }

          AggregateCommand.max(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回一组数值的最大值。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          max 的语法如下:

          db.command.aggregate.max(<表达式>)

          表达式是形如 $ + 指定字段 的字符串。

          示例代码

          假设集合 students 的记录如下:

          { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

          借助 max 可以统计不同组( group )中成绩的最高值,代码如下:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .group({    _id: '$group',    maxScore: $.max('$score')  })  .end()

          返回的数据结果如下:

          { "_id": "b", "maxScore": 100 }{ "_id": "a", "maxScore": 96 }```.

          AggregateCommand.mergeObjects(value: Expression<document>): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。将多个文档合并为单个文档。

          参数

          value: Expression<document>

          Document 表达式

          返回值

          Object

          API 说明

          使用形式如下: 在 group() 中使用时:

          mergeObjects(<document>)

          在其它表达式中使用时:

          mergeObjects([<document1>, <document2>, ...])

          示例代码

          搭配 group() 使用

          假设集合 sales 存在以下文档:

          { "_id": 1, "year": 2018, "name": "A", "volume": { "2018Q1": 500, "2018Q2": 500 } }{ "_id": 2, "year": 2017, "name": "A", "volume": { "2017Q1": 400, "2017Q2": 300, "2017Q3": 0, "2017Q4": 0 } }{ "_id": 3, "year": 2018, "name": "B", "volume": { "2018Q1": 100 } }{ "_id": 4, "year": 2017, "name": "B", "volume": { "2017Q3": 100, "2017Q4": 250 } }

          下面的代码使用 mergeObjects(),将用相同 name 的文档合并:

          const $ = db.command.aggregatedb.collection('sales').aggregate()  .group({    _id: '$name',    mergedVolume: $.mergeObjects('$volume')  })  .end()

          输出如下:

          { "_id": "A", "mergedVolume": { "2017Q1": 400, "2017Q2": 300, "2017Q3": 0, "2017Q4": 0, "2018Q1": 500, "2018Q2": 500 } }{ "_id": "B", "mergedVolume": { "2017Q3": 100, "2017Q4": 250, "2018Q1": 100 } }

          一般用法

          假设集合 test 存在以下文档:

          { "_id": 1, "foo": { "a": 1 }, "bar": { "b": 2 } }{ "_id": 2, "foo": { "c": 1 }, "bar": { "d": 2 } }{ "_id": 3, "foo": { "e": 1 }, "bar": { "f": 2 } }

          下面的代码使用 mergeObjects(),将文档中的 foo 和 bar 字段合并为 foobar:

          const $ = db.command.aggregatedb.collection('sales').aggregate()  .project({    foobar: $.mergeObjects(['$foo', '$bar'])  })  .end()

          输出结果如下:

          { "_id": 1, "foobar": { "a": 1, "b": 2 } }{ "_id": 2, "foobar": { "c": 1, "d": 2 } }{ "_id": 3, "foobar": { "e": 1, "f": 2 } }

          AggregateCommand.min(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回一组数值的最小值。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          min 的语法如下:

          db.command.aggregate.min(<表达式>)

          表达式是形如 $ + 指定字段 的字符串。

          示例代码

          假设集合 students 的记录如下:

          { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

          借助 min 可以统计不同组( group )中成绩的最低值,代码如下:

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .group({    _id: '$group',    minScore: $.min('$score')  })  .end()

          返回的数据结果如下:

          { "_id": "b", "minScore": 80 }{ "_id": "a", "minScore": 84 }

          AggregateCommand.push(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。在 group 阶段,返回一组中表达式指定列与对应的值,一起组成的数组。

          参数

          value: any

          返回值

          Object

          API 说明

          push 语法如下:

          db.command.aggregate.push({  <字段名1>: <指定字段1>,  <字段名2>: <指定字段2>,  ...})

          示例代码

          假设集合 students 的记录如下:

          { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

          借助 push 操作,对不同分组( group )的所有记录,聚合所有数据并且将其放入一个新的字段中,进一步结构化和语义化数据。

          const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .group({    _id: '$group',    students: $.push({      name: '$name',      score: '$score'    })  })  .end()

          输出结果如下:

          { "_id": "b", "students": [{ "name": "stu3", "score": 80 }, { "name": "stu4", "score": 100 }] }{ "_id": "a", "students": [{ "name": "stu1", "score": 84 }, { "name": "stu2", "score": 96 }] }

          AggregateCommand.stdDevPop(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。返回一组字段对应值的标准差。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          stdDevPop 的使用形式如下:

          db.command.aggregate.stdDevPop(<表达式>)

          表达式传入的是指定字段,指定字段对应的值的数据类型必须是 number ,否则结果会返回 null。

          示例代码

          假设集合 students 的记录如下:a 组同学的成绩分别是84和96,b组同学的成绩分别是80和100。

          { "group":"a", "score":84 }{ "group":"a", "score":96 }{ "group":"b", "score":80 }{ "group":"b", "score":100 }

          可以用 stdDevPop 来分别计算 a 和 b 两组同学成绩的标准差,以此来比较哪一组同学的成绩更稳定。代码如下:

          const $ = db.command.aggregatedb.collection('students').aggregate()  .group({    _id: '$group',    stdDev: $.stdDevPop('$score')  })  .end()

          返回的数据结果如下:

          { "_id": "b", "stdDev": 10 }{ "_id": "a", "stdDev": 6 }

          AggregateCommand.stdDevSamp(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。计算输入值的样本标准偏差。如果输入值代表数据总体,或者不概括更多的数据,请改用 db.command.aggregate.stdDevPop。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          stdDevSamp 的使用形式如下:

          db.command.aggregate.stdDevSamp(<表达式>)

          表达式传入的是指定字段,stdDevSamp 会自动忽略非数字值。如果指定字段所有的值均是非数字,那么结果返回 null。

          示例代码

          假设集合 students 的记录如下:

          { "score": 80 }{ "score": 100 }

          可以用 stdDevSamp 来计算成绩的标准样本偏差。代码如下:

          const $ = db.command.aggregatedb.collection('students').aggregate()  .group({    _id: null,    ageStdDev: $.stdDevSamp('$score')  })  .end()

          返回的数据结果如下:

          { "_id": null, "ageStdDev": 14.142135623730951 }

          如果向集合 students 添加一条新记录,它的 score 字段类型是 string:

          { "score": "aa" }

          用上面代码计算标准样本偏差时,stdDevSamp 会自动忽略类型不为 number 的记录,返回结果保持不变。


          AggregateCommand.sum(value: Expression): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。计算并且返回一组字段所有数值的总和。

          参数

          value: Expression

          表达式

          返回值

          Object

          API 说明

          sum 的使用形式如下:

          db.command.aggregate.sum(<表达式>)

          表达式可以传入指定字段,也可以传入指定字段组成的列表。sum 会自动忽略非数字值。如果字段下的所有值均是非数字,那么结果返回 0。若传入数字常量,则当做所有记录该字段的值都给给定常量,在聚合时相加,最终值为输入记录数乘以常量。

          示例代码

          假设代表商品的集合 goods 的记录如下:price 代表商品销售额,cost 代表商品成本

          { "cost": -10, "price": 100 }{ "cost": -15, "price": 1 }{ "cost": -10, "price": 10 }

          单独字段

          借助 sum 可以计算所有商品的销售总和,代码如下:

          const $ = db.command.aggregatedb  .collection('goods')  .aggregate()  .group({    _id: null,    totalPrice: $.sum('$price')  })  .end()

          返回的数据结果如下:销售额是 111

          { "_id": null, "totalPrice": 111 }

          字段列表

          如果需要计算所有商品的利润总额,那么需要将每条记录的 cost 和 price 相加得到此记录对应商品的利润。最后再计算所有商品的利润总额。

          借助 sum,代码如下:

          const $ = db.command.aggregatedb  .collection('goods')  .aggregate()  .group({    _id: null,    totalProfit: $.sum(      $.sum(['$price', '$cost'])    )  })  .end()

          返回的数据结果如下:利润总额为 76

          { "_id": null, "totalProfit": 76 }


          AggregateCommand.let(value: any): Object

          支持端:小程序 2.7.4, 云函数 0.8.1, Web

          聚合操作符。自定义变量,并且在指定表达式中使用,返回的结果是表达式的结果。

          参数

          value: any

          返回值

          Object

          API 说明

          let 的语法如下:

          db.command.aggregate.let({  vars: {    <变量1>: <变量表达式>,    <变量2>: <变量表达式>,    ...  },  in: <结果表达式>})

          vars 中可以定义多个变量,变量的值由 变量表达式 计算而来,并且被定义的变量只有在 in 中的 结果表达式 才可以访问。

          在 in 的结果表达式中访问自定义变量时候,请在变量名前加上双美元符号( $$ )并用引号括起来。

          示例代码

          假设代表商品的集合 goods 的记录如下:price 代表商品价格,discount 代表商品折扣率,cost 代表商品成本

          { "cost": -10, "discount": 0.95, "price": 100 }{ "cost": -15, "discount": 0.98, "price": 1 }{ "cost": -10, "discount": 1, "price": 10 }

          借助 let 可以定义并计算每件商品实际的销售价格,并将其赋值给自定义变量 priceTotal。最后再将 priceTotal 与 cost 进行取和( sum )运算,得到每件商品的利润。

          代码如下:

          const $ = db.command.aggregatedb  .collection('goods')  .aggregate()  .project({    profit: $.let({      vars: {        priceTotal: $.multiply(['$price', '$discount'])      },      in: $.sum(['$$priceTotal', '$cost'])    })  })  .end()

          返回的数据结果如下:

          { "profit": 85 }{ "profit": -14.02 }{ "profit": 0 }


          云函数

          注意: HTTP API 途径触发云函数不包含用户信息



          云开发 HTTP API 提供了以下云函数调用 API:

          触发云函数:

          invokeCloudFunction

          本接口应在服务器端调用,详细说明参见服务端API。

          触发云函数。注意:HTTP API 途径触发云函数不包含用户信息。

          请求地址

          POST https://api.weixin.qq.com/tcb/invokecloudfunction?access_token=ACCESS_TOKEN&env=ENV&name=FUNCTION_NAME

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云开发环境ID
          namestring云函数名称
          POSTBODYstring云函数的传入参数,具体结构由开发者定义。

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          resp_datastring云函数返回的buffer

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          85088该APP未开通云开发
          其他错误码云开发错误码

          示例代码

          curl -d '{}' 'https://api.weixin.qq.com/tcb/invokecloudfunction?access_token=ACCESS_TOKEN&env=ENV&name=login'

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "resp_data": "{"event":{"userInfo":{"appId":"SAMPLE_APPID"}},"appid":"SAMPLE_APPID"}"}

          Tips

          1. 使用本API触发云函数,在云函数中无法获取OpenID等用户相关信息,无法使用涉及用户登录态的其他API。
          2. 注意 POST BODY 部分会传递给云函数作为输入参数。
          3. 由 HTTP API 触发的云函数可以使用云调用。
          4. 由 HTTP API 触发云函数的超时时间为5s,请注意云函数的执行时间不能过长。


          databaseMigrateImport

          本接口应在服务器端调用,详细说明参见服务端API。

          数据库导入

          请求地址

          POST https://api.weixin.qq.com/tcb/databasemigrateimport?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          collection_namestring导入collection名
          file_pathstring导入文件路径(导入文件需先上传到同环境的存储中,可使用开发者工具或 HTTP API的上传文件 API上传)
          file_typenumber导入文件类型,文件格式参考数据库导入指引中的文件格式部分
          stop_on_errorbool是否在遇到错误时停止导入
          conflict_modenumber冲突处理模式

          file_type 的合法值

          说明最低版本
          1JSON
          2CSV

          conflict_mode 的合法值

          说明最低版本
          1INSERT
          2UPSERT

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          job_idnumber导入任务ID,可使用数据库迁移进度查询 API 查询导入进度及结果

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {	"env": "qbasetest-a5c40e",	"collection_name": "test1",	"file_path":"test_import",	"file_type":1,	"stop_on_error": false,	"conflict_mode": 2}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "job_id": 100074947}


          databaseMigrateExport

          本接口应在服务器端调用,详细说明参见服务端API。

          数据库导出

          请求地址

          POST https://api.weixin.qq.com/tcb/databasemigrateexport?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          file_pathstring导出文件路径(文件会导出到同环境的云存储中,可使用获取下载链接 API 获取下载链接)
          file_typenumber导出文件类型,文件格式参考数据库导入指引中的文件格式部分
          querystring导出条件

          file_type 的合法值

          说明最低版本
          1JSON
          2CSV

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          job_idnumber导出任务ID,使用数据库迁移进度查询 API 查询导出结果,获取文件下载链接。

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {    "env":"test2-4a89da",    "file_path":"test_export",    "file_type":1,    "query":"const Point = db.Geo.Point;db.collection('geo').where({name: 'x',age: _.gt(10).and(_.lt(20)),loc: new Point(113,23),array: [1,2]}).limit(10).skip(1).orderBy('age','asc').orderBy('name', 'desc').field({ name: true }).get()"}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "job_id": 100074947}

          导出条件说明

          查询语句语法与数据库 API相同


          databaseMigrateQueryInfo

          本接口应在服务器端调用,详细说明参见服务端API。

          数据库迁移状态查询

          请求地址

          POST https://api.weixin.qq.com/tcb/databasemigratequeryinfo?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          job_idnumber迁移任务ID

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          statusstring导出状态
          record_successnumber导出成功记录数
          record_failnumber导出失败记录数
          err_msgstring导出错误信息
          file_urlstring导出文件下载地址

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {	"env": "test2-4a89da",	"job_id": 100071736}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "status": "success",    "record_success": 3,    "record_fail": 0,    "error_msg": "导出完成.",    "file_url": "https://tcb-mongodb-data-1254135806.cos.ap-shanghai.myqcloud.com/..."


          updateIndex

          本接口应在服务器端调用,详细说明参见服务端API。

          变更数据库索引

          请求地址

          POST https://api.weixin.qq.com/tcb/updateindex?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          collection_namestring集合名称
          create_indexesArray.<Object>新增索引
          drop_indexesArray.<Object>删除索引

          create_indexes 的结构

          属性类型默认值必填说明
          namestring索引名
          uniqueboolean是否唯一
          keysArray.<Object>索引字段

          keys 的结构

          属性类型默认值必填说明
          namestring字段名
          directionstring字段排序

          direction 的合法值

          说明最低版本
          "1"升序
          "-1"降序
          "2dsphere"地理位置

          drop_indexes 的结构

          属性类型默认值必填说明
          namestring索引名

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {  "env": "test2-4a89da",  "collection_name": "counters",  "create_indexes": [    {      "name":"add_index",      "unique": true,      "keys": [        {          "name": "test",          "direction": "2dsphere"        }        ]    }    ],  "drop_indexes": [    {      "name":"del_index"    }    ]}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",}


          databaseCollectionAdd

          本接口应在服务器端调用,详细说明参见服务端API。

          新增集合

          请求地址

          POST https://api.weixin.qq.com/tcb/databasecollectionadd?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          collection_namestring集合名称

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {  "env":"test2-4a89da",  "collection_name": "test_add_collection"}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",}


          databaseCollectionDelete

          本接口应在服务器端调用,详细说明参见服务端API。

          删除集合

          请求地址

          POST https://api.weixin.qq.com/tcb/databasecollectiondelete?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          collection_namestring集合名称

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {  "env":"test2-4a89da",  "collection_name": "test_delete_collection"}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",}


          databaseCollectionGet

          本接口应在服务器端调用,详细说明参见服务端API。

          获取特定云环境下集合信息

          请求地址

          POST https://api.weixin.qq.com/tcb/databasecollectionget?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          limitnumber10获取数量限制
          offsetnumber0偏移量

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          pagerObject分页信息
          collectionsArray.<Object>集合信息

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          pager 的结构

          属性类型说明
          Offsetnumber偏移
          Limitnumber单次查询限制
          Totalnumber符合查询条件的记录总数

          collections 的结构

          属性类型说明
          namestring集合名
          countnumber表中文档数量
          sizenumber表的大小(即表中文档总大小),单位:字节
          index_countnumber索引数量
          index_sizenumber索引占用大小,单位:字节

          请求数据示例

          {  "env":"test2-4a89da",  "limit": 10,  "offset": 0}

          返回数据示例

          {  "errcode": 0,  "errmsg": "ok",  "collections": [      {          "name": "geo",          "count": 13,          "size": 2469,          "index_count": 1,          "index_size": 36864      },      {          "name": "test_collection",          "count": 1,          "size": 67,          "index_count": 1,          "index_size": 16384      }  ],  "pager": {      "Offset": 0,      "Limit": 10,      "Total": 2  }}


          databaseAdd

          本接口应在服务器端调用,详细说明参见服务端API。

          数据库插入记录

          请求地址

          POST https://api.weixin.qq.com/tcb/databaseadd?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          querystring数据库操作语句

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          id_listArray.<string>插入成功的数据集合主键_id。

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {    "env":"test2-4a89da",    "query": "db.collection("geo").add({      data: [{        description: "item1",        due: new Date("2019-09-09"),        tags: [          "cloud",          "database"        ],        location: new db.Geo.Point(113, 23),        done: false      },      {        description: "item2",        due: new Date("2019-09-09"),        tags: [          "cloud",          "database"        ],        location: new db.Geo.Point(113, 23),        done: false      }      ]    })"}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "id_list": [        "be62d9c4-43ec-4dc6-8ca1-30b206eeed24",        "0f4b8add5cdd728a003bf5c83ed99dff"    ]}

          数据库操作语句说明

          数据库操作语句语法与数据库 API相同


          databaseDelete

          本接口应在服务器端调用,详细说明参见服务端API。

          数据库删除记录

          请求地址

          POST https://api.weixin.qq.com/tcb/databasedelete?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          querystring数据库操作语句

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          deletednumber删除记录数量

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例1: 操作集合

          {  "env":"test2-4a89da",  "query": "db.collection("geo").where({done:false}).remove()"}

          返回数据示例1: 操作集合

          {    "errcode": 0,    "errmsg": "ok",    "deleted": 2}

          请求数据示例2: 操作记录

          {  "env":"test2-4a89da",  "query": "db.collection("geo").doc("be62d9c4-43ec-4dc6-8ca1-30b206eeed24").remove()"}

          返回数据示例2: 操作记录

          {    "errcode": 0,    "errmsg": "ok",    "deleted": 1}

          数据库操作语句说明

          数据库操作语句语法与数据库 API相同


          databaseUpdate

          本接口应在服务器端调用,详细说明参见服务端API。

          数据库更新记录

          请求地址

          POST https://api.weixin.qq.com/tcb/databaseupdate?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          querystring数据库操作语句

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          matchednumber更新条件匹配到的结果数
          modifiednumber修改的记录数,注意:使用set操作新插入的数据不计入修改数目
          idstring新插入记录的id,注意:只有使用set操作新插入数据时这个字段会有值

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例1: 操作集合

          {  "env":"test2-4a89da",  "query": "db.collection("geo").where({age:14}).update({data:{age: _.inc(1)}})"}

          返回数据示例1: 操作集合

          {    "errcode": 0,    "errmsg": "ok",    "matched": 1,    "modified": 1,    "id": ""}

          请求数据示例2: 更新一条记录

          {  "env":"test2-4a89da",  "query": "db.collection("geo").doc("56abd6d5-9daf-4fc7-af05-eca13933f1aa").update({data:{age: 10}})"}

          返回数据示例2: 更新一条记录

          {    "errcode": 0,    "errmsg": "ok",    "matched": 1,    "modified": 1,    "id": ""}

          请求数据示例3: 更新替换一条记录

          {  "env":"test2-4a89da",  "query": "db.collection("geo").doc("be62d9c4-43ec-4dc6-8ca1-30b206eeed24").set({data: {        description: "set",        done: true      }})"}

          返回数据示例3: 更新替换一条记录

          {    "errcode": 0,    "errmsg": "ok",    "matched": 0,    "modified": 0,    "id": "be62d9c4-43ec-4dc6-8ca1-30b206eeed24"}

          数据库操作语句说明

          数据库操作语句语法与数据库 API相同


          databaseQuery

          本接口应在服务器端调用,详细说明参见服务端API。

          数据库查询记录

          请求地址

          POST https://api.weixin.qq.com/tcb/databasequery?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          querystring数据库操作语句

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          pagerObject分页信息
          dataArray.<string>记录数组

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          pager 的结构

          属性类型说明
          Offsetnumber偏移
          Limitnumber单次查询限制
          Totalnumber符合查询条件的记录总数

          Tips

          query中应使用limit()限制单次拉取的数量,默认10条。

          请求数据示例

          {  "env":"test2-4a89da",  "query": "db.collection("geo").where({done:true}).limit(10).skip(1).get()"}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "pager": {        "Offset": 1,        "Limit": 10,        "Total": 2    },    "data": [        "{"_id":"b15498af-1a5a-40b4-a4e7-b3fc4a1df482","done":true,"name":"test"}"    ]}

          数据库操作语句说明

          数据库操作语句语法与数据库 API相同


          databaseAggregate

          本接口应在服务器端调用,详细说明参见服务端API。

          数据库聚合

          请求地址

          POST https://api.weixin.qq.com/tcb/databaseaggregate?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          Querystring数据库操作语句

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          dataArray.<string>记录数组

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {  "env":"test2-4a89da",  "query": "db.collection("test_collection").aggregate().match({tags:"cloud"}).limit(10).end()"}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "data": [    "{"_id":"f77e039f-f1cf-4aa8-bd59-16cbaa91e6ea","location":{"type":"Point","coordinates":[{"$numberDouble":"113.0"},{"$numberDouble":"23.0"}]},"done":false,"description":"learn cloud database","due":"2019-09-09","tags":["cloud","database"]}",        "{"_id":"6bb88938-49ea-42b6-a6f5-ce408970cfc6","due":"2019-09-09","tags":["cloud","database"],"location":{"type":"Point","coordinates":[{"$numberDouble":"113.0"},{"$numberDouble":"23.0"}]},"done":false,"description":"学习 cloud database"}",        "{"_id":"51f4f67e-a6a1-4c3e-a50f-827380b8da86","description":"学习 cloud database","due":"2019-09-09","tags":["cloud","database"],"location":{"coordinates":[{"$numberDouble":"113.0"},{"$numberDouble":"23.0"}],"type":"Point"},"done":false}",        "{"_id":"ee1d69da-b7ec-4e7a-bc1f-2fae31da4ce0","tags":["cloud","database"],"location":{"type":"Point","coordinates":[{"$numberDouble":"113.0"},{"$numberDouble":"23.0"}]},"done":false,"description":"学习 cloud database","due":"2019-09-09"}"    ]}

          数据库操作语句说明

          数据库操作语句语法与数据库 API相同, 聚合操作参考聚合文档


          databaseCount

          本接口应在服务器端调用,详细说明参见服务端API。

          统计集合记录数或统计查询语句对应的结果记录数

          请求地址

          POST https://api.weixin.qq.com/tcb/databasecount?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          querystring数据库操作语句

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          countnumber记录数量

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {  "env":"test2-4a89da",  "query": "db.collection("geo").where({done:true}).count()"}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "count": 3}

          数据库操作语句说明

          数据库操作语句语法与数据库 API相同


          存储

          云开发 HTTP API 提供了以下存储相关 API:


          uploadFile

          本接口应在服务器端调用,详细说明参见服务端API。

          获取文件上传链接

          请求地址

          POST https://api.weixin.qq.com/tcb/uploadfile?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          pathstring上传路径

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          urlstring上传url
          tokenstringtoken
          authorizationstringauthorization
          file_idstring文件ID
          cos_file_idstringcos文件ID

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {	"env": "test2-4a89da",	"path": "this/is/a/example/file.path"}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "url": "https://cos.ap-shanghai.myqcloud.com/7465-test2-4a89da-1258717764/testupload",    "token": "Cukha70zkXIBqkh1OhUIFqjUmXLXeSWq7dff61099221bb270522b8e0cf21d72e0aWCfGXEIDT5bKVJgykFFr9_MeQ-ExrsZ8oiFdMwyYag8h0r-EJq_EaO94KzksxH6bAeb4Y7SwZjJqoy_4g1Na797F1IEG9Dnstm_rz02AgaP5HbJwt1P-XHT4Xjw_lafla079gtQKAP-EPbE5Tc8BRXIm32esjGDDDuDyml7IJqbsPolYZ4-CHQsisdx488loGAN4f7YRMkrrP1Pgi5XOm0-iG5HbWd3tHtuE2pzsGkTobO_fyz2PfSPaeUt_735ll38yIWpAFESAsZnBj2DcRSPBT2FJ_s5mOZACS53q6-tWXPO0AR3-EhOCQpiDKsldVsCxz00Uwhgm1T6Ozw777fJEFkUIngUdZ5yajy3LA84Mpfu6CLkFjfiBtz3wpmcCQxhijo_CrVHkmaMc2JBQ",    "authorization": "q-sign-algorithm=sha1&q-ak=AKID98EDB528Sfqerp0Z_7l23we-u4Avrx04te9VvlzGihMTseysMgu7iSdh_hxEnoAy&q-sign-time=1557307130;1557308030&q-key-time=1557307130;1557308030&q-header-list=&q-url-param-list=&q-signature=ac95227b67a04157bb5e49b435c6ac3ce88e03f2",    "file_id": "cloud://test2-4a89da.7465-test2-4a89da-1258717764/testupload",    "cos_file_id": "HDze32/qZENCwWi5N5akgoXSv3U8DsccKaqCxTMGs0zFgvlD28j484/VYFPJ1l2QDh0Qy8wNbQCpxs5zEsLJln1lIY9RGYn1LzRQQQYFQm+Xwvw6S4YEZN1AIwY906mwIBgiI3gKGkU2K1+1ZEnEYEM4Uh/C1JxB4Q=="}

          上传链接使用说明

          用户获取到返回数据后,需拼装一个 HTTP POST 请求,其中 url 为返回包的 url 字段,Body 部分格式为 multipart/form-data,具体内容如下:

          keyvalue说明
          keythis/is/a/example/file.path请求包中的 path 字段
          Signatureq-sign-algorithm=sha1&q-ak=AKID9...返回数据的 authorization 字段
          x-cos-security-tokenCukha70zkXIBqkh1Oh...返回数据的 token 字段
          x-cos-meta-fileidHDze32/qZENCwWi5...返回数据的 cos_file_id 字段
          file文件内容文件的二进制内容

          batchDownloadFile

          本接口应在服务器端调用,详细说明参见服务端API。

          获取文件下载链接

          请求地址

          POST https://api.weixin.qq.com/tcb/batchdownloadfile?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          file_listArray.<Object>文件列表

          file_list 的结构

          属性类型默认值必填说明
          fileidstring文件ID
          max_agenumber下载链接有效期

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          file_listArray.<Object>文件列表

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          file_list 的结构

          属性类型说明
          fileidstring文件ID
          download_urlstring下载链接
          statusnumber状态码
          errmsgstring该文件错误信息

          请求数据示例

          {	"env": "test2-4a89da",	"file_list": [		{			"fileid":"cloud://test2-4a89da.7465-test2-4a89da/A.png",			"max_age":7200		}		]}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "file_list": [        {            "fileid": "cloud://test2-4a89da.7465-test2-4a89da/A.png",            "download_url": "https://7465-test2-4a89da-1258717764.tcb.qcloud.la/A.png",            "status": 0,            "errmsg": "ok"        }    ]}

          batchDeleteFile

          本接口应在服务器端调用,详细说明参见服务端API。

          删除文件

          请求地址

          POST https://api.weixin.qq.com/tcb/batchdeletefile?access_token=ACCESS_TOKEN

          请求参数

          属性类型默认值必填说明
          access_tokenstring接口调用凭证
          envstring云环境ID
          fileid_listArray.<string>文件ID列表

          返回值

          Object

          返回的 JSON 数据包

          属性类型说明
          errcodenumber错误码
          errmsgstring错误信息
          delete_listArray.<string>文件列表

          errcode 的合法值

          说明最低版本
          0请求成功
          -1系统错误
          -1000系统错误
          40014AccessToken 不合法
          40097请求参数错误
          40101缺少必填参数
          41001缺少AccessToken
          42001AccessToken过期
          43002HTTP METHOD 错误
          44002POST BODY 为空
          47001POST BODY 格式错误
          85088该APP未开通云开发
          其他错误码云开发错误码

          请求数据示例

          {	"env": "test2-4a89da",	"fileid_list": [		"cloud://test2-4a89da.7465-test2-4a89da/A.png"	]}

          返回数据示例

          {    "errcode": 0,    "errmsg": "ok",    "delete_list": [        {            "fileid": "cloud://test2-4a89da.7465-test2-4a89da/A.png",            "status": 0,            "errmsg": "ok"        }    ]}


          快速上手

          使用之前

          扩展组件库基于小程序自定义组件构建,在使用扩展组件库之前,建议先阅读熟悉小程序自定义组件。

          引入组件

          1. 通过 useExtendedLib 扩展库 的方式引入,这种方式引入的组件将不会计入代码包大小。
          2. 可以通过npm方式下载构建,npm包名为weui-miniprogram

          如何使用

          首先要在 app.wxss 里面引入 weui.wxss,如果是通过 npm 引入,需要先构建 npm(“工具”菜单 --> “构建 npm”)

          通过 useExtendedLib 扩展库 的方式引入,可省略 import 步骤

          @import '/miniprogram_npm/weui-miniprogram/weui-wxss/dist/style/weui.wxss';

          然后可以在页面中引入 dialog 弹窗组件

          1. 首先在页面的 json 文件加入 usingComponents 配置字段
          {  "usingComponents": {    "mp-dialog": "/miniprogram_npm/weui-miniprogram/dialog/dialog"  }}
          1. 然后可以在对应页面的 wxml 中直接使用该组件
          <mp-dialog title="test" show="{{true}}" bindbuttontap="tapDialogButton" buttons="{{[{text: '取消'}, {text: '确认'}]}}">    <view>test content</view></mp-dialog>

          完整的组件的使用文档请参考具体的组件的文档。

          修改组件内部样式

          每个组件可以设置ext-class这个属性,该属性提供设置在组件WXML顶部元素的class,组件的addGlobalClass的options都设置为true,所以可以在页面设置wxss样式来覆盖组件的内部样式。需要注意的是,如果要覆盖组件内部样式,必须wxss的样式选择器的优先级比组件内部样式优先级高。 addGlobalClass在基础库2.2.3开始支持。

          适配 DarkMode

          在根结点(或组件的外层结点)增加属性 data-weui-theme="dark",即可把 WeUI 组件切换到 DarkMode 的表现,如:

          <view data-weui-theme="dark">    ...</view>

          也可以参考库中提供的 Demo。


          Badge徽章

          出现在按钮、图标附近的数字或者状态标记。

          示例代码:

          {  "usingComponents": {    "mp-cells": "../components/cells/cells",    "mp-cell": "../components/cell/cell",    "mp-badge": "../components/badge/badge"  }}

          Gallery画廊

          用于多张图片展示,类似原生的wx.previewImage的展示。

          示例代码:

          {  "usingComponents": {    "mp-gallery": "../components/gallery/gallery"  }}

          Loading加载

          加载数据时的 loading 效果

          示例代码:

          {    "usingComponents": {        "mp-loading": "../components/loading/loading"    },    "navigationBarTitleText": "UI组件库"}

          Icon

          图标

          代码引入

          在 page.json 中引入组件

          {  "usingComponents": {    "mp-icon": "../../components/icon/icon"  }}

          示例代码

          <!--WXML示例代码--><mp-icon type="field" icon="add" color="black" size="{{25}}"></mp-icon><mp-icon icon="add" color="black" size="{{25}}"></mp-icon>

          效果展示

          属性列表

          属性类型默认值说明
          extClassstring组件类名
          typestringoutlineIcon类型,可选值 outline(描边),field(填充)
          iconstringIcon名字
          sizenumber20Icon的大小,单位 px
          colorstringblackIcon的颜色,默认黑色

          Icon 列表

           


          Form

          Form表单组件,结合Cell、Checkbox-group、Checkbox组件等做表单校验。

          示例代码:

          {  "component": true,  "usingComponents": {    "mp-toptips": "../components/toptips/toptips",    "mp-cells": "../components/cells/cells",    "mp-cell": "../components/cell/cell",    "mp-checkbox": "../components/checkbox/checkbox",    "mp-checkbox-group": "../components/checkbox-group/checkbox-group",    "mp-form": "../components/form/form"  }}
          <mp-toptips msg="{{error}}" type="error" show="{{error}}"></mp-toptips><view class="page" xmlns:wx="http://www.w3.org/1999/xhtml">    <view class="page__hd">        <view class="page__title">Form</view>        <view class="page__desc">表单输入</view>    </view>    <view class="page__bd">        <mp-form id="form" rules="{{rules}}" models="{{formData}}">            <mp-cells title="单选列表项">                <mp-checkbox-group prop="radio" multi="{{false}}" bindchange="radioChange">                    <mp-checkbox wx:for="{{radioItems}}" wx:key="value" label="{{item.name}}" value="{{item.value}}" checked="{{item.checked}}"></mp-checkbox>                </mp-checkbox-group>            </mp-cells>            <mp-cells title="复选列表项">                <mp-checkbox-group prop="checkbox" multi="{{true}}" bindchange="checkboxChange">                    <mp-checkbox wx:for="{{checkboxItems}}" wx:key="value" label="{{item.name}}" value="{{item.value}}" checked="{{item.checked}}"></mp-checkbox>                </mp-checkbox-group>            </mp-cells>            <mp-cells title="表单" footer="底部说明文字底部说明文字">                <mp-cell prop="qq" title="qq" ext-class="">                    <input bindinput="formInputChange" data-field="qq" class="weui-input" placeholder="请输入qq"/>                </mp-cell>                <mp-cell prop="mobile" title="手机号" ext-class=" weui-cell_vcode">                    <input bindinput="formInputChange" data-field="mobile" class="weui-input" placeholder="请输入手机号"/>                    <view slot="footer" class="weui-vcode-btn">获取验证码</view>                </mp-cell>                <mp-cell prop="date" title="日期" ext-class="">                    <picker data-field="date" mode="date" value="{{date}}" start="2015-09-01" end="2017-09-01" bindchange="bindDateChange">                        <view class="weui-input">{{date}}</view>                    </picker>                </mp-cell>                <mp-cell prop="vcode" title="验证码" ext-class=" weui-cell_vcode">                    <input bindinput="formInputChange" data-field="vcode" class="weui-input" placeholder="请输入验证码"/>                    <image slot="footer" class="weui-vcode-img" src="../images/vcode.jpg" style="width: 108px"></image>                </mp-cell>            </mp-cells>            <mp-cells title="提交后表单项报错">                <mp-cell show-error prop="idcard" title="卡号" ext-class="">                    <input bindinput="formInputChange" data-field="idcard" class="weui-input" placeholder="请输入卡号"/>                </mp-cell>            </mp-cells>        </mp-form>        <view class="weui-cells__title">开关</view>        <view class="weui-cells weui-cells_after-title">            <view class="weui-cell weui-cell_switch">                <view class="weui-cell__bd">标题文字</view>                <view class="weui-cell__ft">                    <switch checked />                </view>            </view>        </view>        <view class="weui-cells__title">文本框</view>        <view class="weui-cells weui-cells_after-title">            <view class="weui-cell">                <view class="weui-cell__bd">                    <input class="weui-input" placeholder="请输入文本" />                </view>            </view>        </view>        <view class="weui-cells__title">文本域</view>        <view class="weui-cells weui-cells_after-title">            <view class="weui-cell">                <view class="weui-cell__bd">                    <textarea class="weui-textarea" placeholder="请输入文本" style="height: 3.3em" />                    <view class="weui-textarea-counter">0/200</view>                </view>            </view>        </view>        <view class="weui-cells__title">选择</view>        <view class="weui-cells weui-cells_after-title">            <view class="weui-cell weui-cell_select">                <view class="weui-cell__hd" style="width: 105px">                    <picker bindchange="bindCountryCodeChange" value="{{countryCodeIndex}}" range="{{countryCodes}}">                        <view class="weui-select">{{countryCodes[countryCodeIndex]}}</view>                    </picker>                </view>                <view class="weui-cell__bd weui-cell__bd_in-select-before">                    <input class="weui-input" placeholder="请输入号码" />                </view>            </view>        </view>        <view class="weui-cells__title">选择</view>        <view class="weui-cells weui-cells_after-title">            <view class="weui-cell weui-cell_select">                <view class="weui-cell__bd">                    <picker bindchange="bindAccountChange" value="{{accountIndex}}" range="{{accounts}}">                        <view class="weui-select">{{accounts[accountIndex]}}</view>                    </picker>                </view>            </view>            <view class="weui-cell weui-cell_select">                <view class="weui-cell__hd weui-cell__hd_in-select-after">                    <view class="weui-label">国家/地区</view>                </view>                <view class="weui-cell__bd">                    <picker bindchange="bindCountryChange" value="{{countryIndex}}" range="{{countries}}">                        <view class="weui-select weui-select_in-select-after">{{countries[countryIndex]}}</view>                    </picker>                </view>            </view>        </view>        <checkbox-group bindchange="bindAgreeChange">            <label class="weui-agree" for="weuiAgree">                <view class="weui-agree__text">                    <checkbox class="weui-agree__checkbox" id="weuiAgree" value="agree" checked="{{isAgree}}" />                    <view class="weui-agree__checkbox-icon">                        <icon class="weui-agree__checkbox-icon-check" type="success_no_circle" size="9" wx:if="{{isAgree}}"></icon>                    </view>                    阅读并同意<navigator url="" class="weui-agree__link">《相关条款》</navigator>                </view>            </label>        </checkbox-group>        <view class="weui-btn-area">            <button class="weui-btn" type="primary" bindtap="submitForm">确定</button>        </view>    </view></view>
          Component({    data: {        showTopTips: false,        radioItems: [            {name: 'cell standard', value: '0', checked: true},            {name: 'cell standard', value: '1'}        ],        checkboxItems: [            {name: 'standard is dealt for u.', value: '0', checked: true},            {name: 'standard is dealicient for u.', value: '1'}        ],        items: [            {name: 'USA', value: '美国'},            {name: 'CHN', value: '中国', checked: 'true'},            {name: 'BRA', value: '巴西'},            {name: 'JPN', value: '日本'},            {name: 'ENG', value: '英国'},            {name: 'TUR', value: '法国'},        ],        date: "2016-09-01",        time: "12:01",        countryCodes: ["+86", "+80", "+84", "+87"],        countryCodeIndex: 0,        countries: ["中国", "美国", "英国"],        countryIndex: 0,        accounts: ["微信号", "QQ", "Email"],        accountIndex: 0,        isAgree: false,        formData: {        },        rules: [{            name: 'radio',            rules: {required: true, message: '单选列表是必选项'},        }, {            name: 'checkbox',            rules: {required: true, message: '多选列表是必选项'},        }, {            name: 'qq',            rules: {required: true, message: 'qq必填'},        }, {            name: 'mobile',            rules: [{required: true, message: 'mobile必填'}, {mobile: true, message: 'mobile格式不对'}],        }, {            name: 'vcode',            rules: {required: true, message: '验证码必填'},        }, {            name: 'idcard',            rules: {required: true, message: 'idcard必填'},        }]    },    methods: {        radioChange: function (e) {            console.log('radio发生change事件,携带value值为:', e.detail.value);                var radioItems = this.data.radioItems;            for (var i = 0, len = radioItems.length; i < len; ++i) {                radioItems[i].checked = radioItems[i].value == e.detail.value;            }                this.setData({                radioItems: radioItems,                [`formData.radio`]: e.detail.value            });        },        checkboxChange: function (e) {            console.log('checkbox发生change事件,携带value值为:', e.detail.value);                var checkboxItems = this.data.checkboxItems, values = e.detail.value;            for (var i = 0, lenI = checkboxItems.length; i < lenI; ++i) {                checkboxItems[i].checked = false;                    for (var j = 0, lenJ = values.length; j < lenJ; ++j) {                    if(checkboxItems[i].value == values[j]){                        checkboxItems[i].checked = true;                        break;                    }                }            }                this.setData({                checkboxItems: checkboxItems,                [`formData.checkbox`]: e.detail.value            });        },        bindDateChange: function (e) {            this.setData({                date: e.detail.value,                [`formData.date`]: e.detail.value            })        },        formInputChange(e) {            const {field} = e.currentTarget.dataset            this.setData({                [`formData.${field}`]: e.detail.value            })        },        bindTimeChange: function (e) {            this.setData({                time: e.detail.value            })        },        bindCountryCodeChange: function(e){            console.log('picker country code 发生选择改变,携带值为', e.detail.value);                this.setData({                countryCodeIndex: e.detail.value            })        },        bindCountryChange: function(e) {            console.log('picker country 发生选择改变,携带值为', e.detail.value);                this.setData({                countryIndex: e.detail.value            })        },        bindAccountChange: function(e) {            console.log('picker account 发生选择改变,携带值为', e.detail.value);                this.setData({                accountIndex: e.detail.value            })        },        bindAgreeChange: function (e) {            this.setData({                isAgree: !!e.detail.value.length            });        },        submitForm() {            this.selectComponent('#form').validate((valid, errors) => {                console.log('valid', valid, errors)                if (!valid) {                    const firstError = Object.keys(errors)                    if (firstError.length) {                        this.setData({                            error: errors[firstError[0]].message                        })                        }                } else {                    wx.showToast({                        title: '校验通过'                    })                }            })        }    }});

          FormPage

          表单页面,规定了标准表单的顶部的标题和底部的按钮提示等区域的规范

          代码引入

          在 page.json 中引入组件

          {  "usingComponents": {    "mp-form-page": "../../components/form-page/form-page",    "mp-form": "../../components/form/form"  }}

          示例代码

          <!--WXML示例代码--><mp-form-page title="表单结构" subtitle="展示表单页面的信息结构样式, 分别由头部区域/控件区域/提示区域/操作区域和底部信息区域组成。">    <mp-form id="form" rules="{{rules}}" models="{{formData}}">    </mp-form>    <checkbox-group slot="tips" bindchange="bindAgreeChange">        <label class="weui-agree" for="weuiAgree">            <view class="weui-agree__text">                <checkbox class="weui-agree__checkbox" id="weuiAgree" value="agree" checked="{{isAgree}}" />                <view class="weui-agree__checkbox-icon">                    <icon class="weui-agree__checkbox-icon-check" type="success_no_circle" size="9" wx:if="{{isAgree}}"></icon>                </view>                阅读并同意<navigator url="" class="weui-agree__link">《相关条款》</navigator>            </view>        </label>    </checkbox-group>    <view slot="button">        <button class="weui-btn" type="primary" bindtap="submitForm">确定</button>    </view></mp-form-page>

          效果展示

          属性列表

          属性类型默认值必填说明
          titlestring标题
          subtitleboolean副标题

          Slot

          名称描述
          title标题区域slot和title属性互斥
          tips底部确认按钮前面的提示区域
          button底部提交按钮区域
          suffixtips提交按钮下面的提示区域
          footer页脚的内容区域


          Cell

          Cell是列表或者是表单的一项,常用于设置页的展示,或者用在表单中,作为表单的每一个要填写的项,Cell必须要放在Cells组件的下面。

          示例代码:

          {  "usingComponents": {    "mp-cells": "../components/cells/cells",    "mp-cell": "../components/cell/cell",    "mp-slideview": "../components/slideview/slideview"  }}
          <view class="page">    <view class="page__hd">        <view class="page__title">Cell</view>        <view class="page__desc">列表</view>    </view>    <view class="page__bd">        <mp-cells ext-class="my-cells" title="带说明的列表项">            <mp-cell value="标题文字" footer="说明文字"></mp-cell>            <mp-cell>                <view>标题文字(使用slot)</view>                <view slot="footer">说明文字</view>            </mp-cell>            <mp-slideview buttons="{{slideButtons}}" bindbuttontap="slideButtonTap">                <mp-cell value="左滑可以删除" footer="说明文字"></mp-cell>            </mp-slideview>        </mp-cells>        <mp-cells title="带图标、说明的列表项" footer="底部说明文字">            <mp-cell value="标题文字" footer="说明文字">                <image slot="icon" src="{{icon}}" style="margin-right: 16px;vertical-align: middle;width:20px; height: 20px;"></image>            </mp-cell>            <mp-cell value="标题文字" footer="说明文字">                <image slot="icon" src="{{icon}}" style="margin-right: 16px;vertical-align: middle;width:20px; height: 20px;"></image>            </mp-cell>        </mp-cells>        <mp-cells title="带跳转的列表项">            <mp-cell link hover value="有hover效果" footer="说明文字">                <image slot="title" src="{{icon}}" style="margin-right: 16px;vertical-align: middle;width:20px; height: 20px;"></image>            </mp-cell>            <mp-cell link value="无hover效果" footer="说明文字">                <image slot="icon" src="{{icon}}" style="margin-right: 16px;vertical-align: middle;width:20px; height: 20px;"></image>            </mp-cell>            <mp-cell link url="../index" value="无hover效果,带跳转URL" footer="说明文字">                <image slot="icon" src="{{icon}}" style="margin-right: 16px;vertical-align: middle;width:20px; height: 20px;"></image>            </mp-cell>        </mp-cells>    </view></view>
          var base64 = require("../images/base64");Page({    onLoad: function(){        this.setData({            icon: base64.icon20,            slideButtons: [{              text: '普通',              src: '/page/weui/cell/icon_love.svg', // icon的路径            },{              text: '普通',              extClass: 'test',                src: '/page/weui/cell/icon_star.svg', // icon的路径            },{              type: 'warn',              text: '警示',              extClass: 'test',                src: '/page/weui/cell/icon_del.svg', // icon的路径            }],        });    },    slideButtonTap(e) {        console.log('slide button tap', e.detail)    }});


          属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          iconstringCell的最左侧的icon,是本地图片的路径,icon和名为icon的slot互斥
          titlestringCell最左侧的标题,一般用在Form表单组件里面,icon和title二选一,title和名为title的slot互斥
          hoverbooleanfalse是否有hover效果
          linkbooleanfalse右侧是有跳转的箭头,v1.0后的版本,link: true 会自带 hover 效果
          valuestringCell的值,和默认的slot互斥
          show-errorbooleanfalse用在Form表单组件里面,在表单校验出错的时候是否把Cell标为warn状态
          propstring用在Form表单组件里面,需要校验的表单的字段名
          footerstringCell右侧区域的内容,和名为footer的slot互斥
          inlineboolean用在Form表单组件里面,表示表单项是左右显示还是上下显示

          Slot

          名称描述
          icon左侧图标slot
          title标题slot
          默认内容slot
          footer右侧区域slot


          Cells

          Cells是列表分组,常用于嵌套一组Cell或者Checkbox,注意,Checkbox-group和Cell组件都必须放在Cells组件下面,Cells效果如下图所示。

          引入组件

          在 page.json 中引入组件

          {  "usingComponents": {    "mp-cell": "../../components/cell/cell",    "mp-cells": "../../components/cells/cells"  }}

          示例代码

          <!--WXML示例代码--><mp-cells ext-class="my-cells" title="带说明的列表项">    <mp-cell value="标题文字" footer="说明文字"></mp-cell>    <mp-cell>        <view>标题文字(使用slot)</view>        <view slot="footer">说明文字</view>    </mp-cell></mp-cells>
          // page.js示例代码Page({});

          属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          titlestringCells的标题
          footerstringCells底部的文字

          Slot

          名称描述
          默认内容slot


          Checkbox-group和Checkbox

          Checkbox-group是由一组单选或者多选Checkbox组件组成,效果如下图所示。

          引入组件

          在 page.json 中引入组件

          {  "usingComponents": {    "mp-checkbox-group": "../../components/checkbox-group/checkbox-group",    "mp-checkbox": "../../components/checkbox/checkbox",    "mp-cells": "../../components/cells/cells"  }}

          示例代码

          <!--WXML示例代码--><mp-cells title="单选列表项">    <mp-checkbox-group prop="radio" multi="{{false}}" bindchange="radioChange">        <mp-checkbox wx:for="{{radioItems}}" wx:key="value" label="{{item.name}}" value="{{item.value}}" checked="{{item.checked}}"></mp-checkbox>    </mp-checkbox-group></mp-cells><mp-cells title="复选列表项">    <mp-checkbox-group prop="checkbox" multi="{{true}}" bindchange="checkboxChange">        <mp-checkbox wx:for="{{checkboxItems}}" wx:key="value" label="{{item.name}}" value="{{item.value}}" checked="{{item.checked}}"></mp-checkbox>    </mp-checkbox-group></mp-cells>
          // page.js示例代码Page({    data: {        radioItems: [            {name: 'cell standard', value: '0', checked: true},            {name: 'cell standard', value: '1'}        ],        checkboxItems: [            {name: 'standard is dealt for u.', value: '0', checked: true},            {name: 'standard is dealicient for u.', value: '1'}        ],    },    radioChange: function (e) {        console.log('radio发生change事件,携带value值为:', e.detail.value);        var radioItems = this.data.radioItems;        for (var i = 0, len = radioItems.length; i < len; ++i) {            radioItems[i].checked = radioItems[i].value == e.detail.value;        }        this.setData({            radioItems: radioItems,            [`formData.radio`]: e.detail.value        });    },    checkboxChange: function (e) {        console.log('checkbox发生change事件,携带value值为:', e.detail.value);        var checkboxItems = this.data.checkboxItems, values = e.detail.value;        for (var i = 0, lenI = checkboxItems.length; i < lenI; ++i) {            checkboxItems[i].checked = false;            for (var j = 0, lenJ = values.length; j < lenJ; ++j) {                if(checkboxItems[i].value == values[j]){                    checkboxItems[i].checked = true;                    break;                }            }        }        this.setData({            checkboxItems: checkboxItems,            [`formData.checkbox`]: e.detail.value        });    },});

          checkbox-group组件属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          multibooleantrue单选还是多选
          propstringForm表单组件校验的字段名
          bindchangeeventhandlerCheckbox-group发生改变时候触发的事件,detail为{value},单选的value为checkbox的值,多选的value为选中的checkbox的值组成的数组

          checkbox-group的Slot

          名称描述
          默认内容slot

          checkbox组件属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          multibooleantrue单选还是多选
          checkedboolean是否选中
          valuestringcheckbox的值
          bindchangeeventhandlerCheckbox发生改变时候触发的事件,detail为{value},value为checkbox的值


          Slideview

          左滑删除组件,基础库 2.4.4 开始支持。

          示例代码:

          {  "usingComponents": {    "mp-cells": "../components/cells/cells",    "mp-cell": "../components/cell/cell",    "mp-slideview": "../components/slideview/slideview"  }}
          <view class="page">    <view class="page__hd">        <view class="page__title">Slideview</view>        <view class="page__desc">左滑操作</view>    </view>    <view class="page__bd">      <view class="weui-cells">          <mp-slideview buttons="{{slideButtons}}" bindbuttontap="slideButtonTap">              <mp-cell value="左滑可以删除" footer="说明文字"></mp-cell>          </mp-slideview>      </view>      <view class="weui-slidecells">        <mp-slideview buttons="{{slideButtons}}" icon="{{true}}" bindbuttontap="slideButtonTap">          <view class="weui-slidecell">            左滑可以删除(图标Button)          </view>        </mp-slideview>      </view>    </view></view>
          var base64 = require("../images/base64");Page({    onLoad: function(){        this.setData({            icon: base64.icon20,            slideButtons: [{              text: '普通',              src: '/page/weui/cell/icon_love.svg', // icon的路径            },{              text: '普通',              extClass: 'test',              src: '/page/weui/cell/icon_star.svg', // icon的路径            },{              type: 'warn',              text: '警示',              extClass: 'test',                src: '/page/weui/cell/icon_del.svg', // icon的路径            }],        });    },    slideButtonTap(e) {        console.log('slide button tap', e.detail)    }});



          属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          disablebooleanfalse是否禁用slideview
          buttonsarray<object>[]左滑的按钮组,建议最多3个按钮
          iconbooleanfalse按钮是否是icon
          showboolean是否显示slideview,可以控制隐藏显示
          durationboolean350slideview显示隐藏的动画的时长
          throttlenumber40手指移动距离超过该值的时候,触发slideview的显示隐藏
          bindbuttontapeventhandlerbuttons按钮组点击时触发的事件,detail为{index, data},data是按钮的配置项传入的data参数
          bindhideeventhandler隐藏时触发的事件
          bindshoweventhandler显示时触发的事件

          buttons提供按钮组配置,每一项表示一个按钮,每一项的属性为

          属性类型默认值必填说明
          extClassstring按钮的额外的class,可用于修改组件内部的样式
          typestringdefault按钮的类型,取值default和warn,warn是红色按钮
          textstring按钮的文本
          srcstring如果icon为true,此属性有效
          dataany触发bindbuttontap回传的数据


          图片上传Uploader组件。

          示例代码:

          {  "usingComponents": {    "mp-uploader": "../components/uploader/uploader",    "mp-cells": "../components/cells/cells",    "mp-cell": "../components/cell/cell"  },  "navigationBarTitleText": "UI组件库"}
          <view class="page">    <view class="page__hd">        <view class="page__title">Uploader</view>        <view class="page__desc">上传组件</view>    </view>    <view class="page__bd">        <mp-cells>            <mp-cell>                <mp-uploader bindfail="uploadError" bindsuccess="uploadSuccess" select="{{selectFile}}" upload="{{uplaodFile}}" files="{{files}}" max-count="5" title="图片上传" tips="图片上传提示"></mp-uploader>            </mp-cell>        </mp-cells>    </view></view>
          Page({    data: {        files: [{            url: 'http://mmbiz.qpic.cn/mmbiz_png/VUIF3v9blLsicfV8ysC76e9fZzWgy8YJ2bQO58p43Lib8ncGXmuyibLY7O3hia8sWv25KCibQb7MbJW3Q7xibNzfRN7A/0',        }, {            loading: true        }, {            error: true        }]    },    onLoad() {        this.setData({            selectFile: this.selectFile.bind(this),            uplaodFile: this.uplaodFile.bind(this)        })    },    chooseImage: function (e) {        var that = this;        wx.chooseImage({            sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图,默认二者都有            sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机,默认二者都有            success: function (res) {                // 返回选定照片的本地文件路径列表,tempFilePath可以作为img标签的src属性显示图片                that.setData({                    files: that.data.files.concat(res.tempFilePaths)                });            }        })    },    previewImage: function(e){        wx.previewImage({            current: e.currentTarget.id, // 当前显示图片的http链接            urls: this.data.files // 需要预览的图片http链接列表        })    },    selectFile(files) {        console.log('files', files)        // 返回false可以阻止某次文件上传    },    uplaodFile(files) {        console.log('upload files', files)        // 文件上传的函数,返回一个promise        return new Promise((resolve, reject) => {            setTimeout(() => {                reject('some error')            }, 1000)        })    },    uploadError(e) {        console.log('upload error', e.detail)    },    uploadSuccess(e) {        console.log('upload success', e.detail)    }});


          属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          titlestring组件标题
          tipsstring组件的提示
          deleteboolean是否显示删除按钮
          size-typearray和chooseImage的sizeType参数一样
          source-typearray和chooseImage的sourceType参数一样
          max-sizenumber5 * 1024 * 1024图片上传的最大文件限制,默认是5M
          max-countnumber1图片上传的个数限制
          filesarray<object>当前的图片列表
          selectfunction选择图片时的过滤函数,返回true表示图片有效
          uploadfunction图片上传的函数,返回Promise,Promise的callback里面必须resolve({urls})表示成功,否则表示失败
          bindselecteventhandler图片选择触发的事件,detail为{tempFilePaths, tempFiles, contents},其中tempFiles和tempFilePaths是chooseImage返回的字段,contents表示所选的图片的二进制Buffer列表
          bindcanceleventhandler取消图片选择的事件,detail为{}
          bindsuccesseventhandler图片上传成功的事件,detail为{urls},urls为upload函数上传成功返回的urls参数
          bindfaileventhandler图片上传失败的事件,detail为{type, errMsg},type为1表示图片超过大小限制,type为2表示选择图片失败,type为3表示图片上传失败。
          binddeleteeventhandler删除图片触发的事件,detail为{index, item},index表示删除的图片的下标,item为图片对象。

          files表示当前的图片列表,每一项的定义为

          属性类型默认值必填说明
          urlstring图片链接
          loadingboolean图片上传中
          errorboolean图片上传失败


          Dialog

          Dialog弹窗组件。

          示例代码:

          {  "usingComponents": {    "mp-dialog": "../components/dialog/dialog"  }}

          <view class="page">    <view class="page__hd">        <view class="page__title">Dialog</view>        <view class="page__desc">对话框</view>    </view>    <view class="page__bd">        <view class="weui-btn-area">            <button class="weui-btn" type="default" bindtap="openConfirm">确认取消按钮</button>            <button class="weui-btn" type="default" bindtap="tapOneDialogButton">只有确认按钮</button>        </view>    </view>    <mp-dialog title="test" show="{{dialogShow}}" bindbuttontap="tapDialogButton" buttons="{{buttons}}">        <view>test content</view>    </mp-dialog>    <mp-dialog title="test1" show="{{showOneButtonDialog}}" bindbuttontap="tapDialogButton" buttons="{{oneButton}}">        <view>test content1</view>    </mp-dialog></view>

          Page({    data: {        dialogShow: false,        showOneButtonDialog: false,        buttons: [{text: '取消'}, {text: '确定'}],        oneButton: [{text: '确定'}],    },    openConfirm: function () {        this.setData({            dialogShow: true        })    },    tapDialogButton(e) {        this.setData({            dialogShow: false,            showOneButtonDialog: false        })    },    tapOneDialogButton(e) {        this.setData({            showOneButtonDialog: true        })    }});


          属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          titlestring弹窗的标题
          buttonsarray<object>[]底部的按钮组,建议最多提供两个按钮
          maskboolean是否显示蒙层
          mask-closableboolean点击蒙层是否可以关闭
          showbooleanfalse是否显示弹窗
          bindcloseeventhandler弹窗关闭的时候触发的事件
          bindbuttontapeventhandlerbuttons按钮组点击时触发的事件,detail为{index, item},item是按钮的配置项

          buttons提供按钮组配置,每一项表示一个按钮,每一项的属性为

          属性类型默认值必填说明
          extClassstring按钮的额外的class,可用于修改组件内部的样式
          textstring按钮的文本

          Slot

          弹窗组件只有一个默认slot用于显示弹窗的内容


          Msg

          Msg组件提供操作确认页或操作成功或失败的标准的确认页的样式。

          示例代码:

          {  "usingComponents": {    "mp-msg": "../components/msg/msg"  },  "navigationBarTitleText": "UI组件库"}
          <view class="page">    <mp-msg type="success" title="操作成功">        <view slot="desc">内容详情,可根据实际需要安排,如果换行则不超过规定长度,居中展现<navigator url="" class="weui-msg__link">文字链接</navigator></view>        <view slot="extend">            <view>1. 说明1</view>            <view>2. 说明2</view>        </view>        <view slot="handle">            <button class="weui-btn" type="primary">主要操作</button>            <button class="weui-btn" type="default">辅助操作</button>        </view>        <view slot="footer">            <view class="weui-footer__links">                <navigator url="" class="weui-footer__link">底部链接文本</navigator>            </view>            <view class="weui-footer__text">Copyright © 2008-2016 weui.io</view>        </view>    </mp-msg> </view>


          属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          typestring顶部图标的样式,和icon组件的type属性用法一样
          sizenumber64type不为空的时候有效,和icon组件的size属性用法一样
          iconstringtype为空的时候,icon的值是顶部图标的路径
          titlestring标题
          descstring描述内容,和desc的slot显示在相同的位置

          Slot

          名称描述
          desc描述内容slot
          extenddesc下面的说明区域的slot
          handle操作按钮区域slot
          footer底部slot


          Toptips

          Toptips顶部错误提示组件,常用于表单校验或提交请求到后台成功或失败的错误提示,如下图所示。

          引入组件

          在 page.json 中引入组件

          {  "usingComponents": {    "mp-toptips": "../../components/toptips/toptips"  }}

          示例代码

          <!--WXML示例代码--><mp-toptips msg="{{error}}" type="error" show="{{error}}"></mp-toptips>
          // page.js示例代码Page({    data: {        error: ''    },    onShow() {        this.setData({            error: '这是一个错误提示'        })    }});

          属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          typestring提示类型,可以为info、error、success,表示三种提示颜色
          showbooleanfalse是否显示Toptips
          msgstring提示内容
          delaynumber2000提示内容显示后隐藏的ms值
          bindhideeventhandler顶部提示隐藏的时候触发的事件


          Half Screen Dialog

          半屏弹窗,辅助完成当前页面任务时;提醒用户并引导用户的下一步操作;用户主动发起的任务时。

          代码引入

          在 page.json 中引入组件

          {  "usingComponents": {    "mp-halfScreenDialog": "../../components/half-screen-dialog/half-screen-dialog"  }}

          示例代码

          <!--WXML示例代码--><mp-halfScreenDialog   bindbuttontap="buttontap"  show="{{show}}"  maskClosable="{{false}}"   title="测试标题B"   subTitle="测试标题B的副标题"  desc="辅助描述内容,可根据实际需要安排"  tips="辅助提示内容,可根据实际需要安排"  buttons="{{buttons}}"></mp-halfScreenDialog><button class="weui-btn" type="primary" bindtap="open">Open</button>
          // page.js示例代码Page({    data: {        show: false,        buttons: [            {                type: 'default',                className: '',                text: '辅助操作',                value: 0            },            {                type: 'primary',                className: '',                text: '主操作',                value: 1            }        ]    },    open: function () {        this.setData({            show: true        })    },    buttontap(e) {        console.log(e.detail)    }});

          效果展示

          属性列表

          属性类型默认值说明
          extClassstring组件类名
          closabledbooleantrue是否展示关闭按钮
          titlestring组件标题,可通过slot自定义
          subTitlestring组件副标题,可通过slot自定义
          descstring辅助操作描述内容
          tipsstring辅助操作提示内容
          maskClosablebooleantrue点击遮罩是否关闭改组件
          maskbooleantrue是否需要遮罩层
          showbooleantrue是否开启弹窗
          buttonsarray[]辅助操作按钮列表

          自定义事件

          事件名称说明回调参数
          buttontap点击辅助操作按钮时触发e.detail = { index, item }
          close组件关闭时候触发

          Slot

          名称描述
          title组件自定义标题栏
          desc组件自定义操作描述
          footer操作按钮区域slot


          ActionSheet

          底部弹起的操作按钮组件

          代码引入

          在 page.json 中引入组件

          {  "usingComponents": {    "mp-actionSheet": "../../components/actionsheet/actionsheet"  }}

          示例代码

          <!--WXML示例代码--><mp-actionSheet bindactiontap="btnClick" show="{{showActionsheet}}" actions="{{groups}}" title="这是一个标题,可以为一行或者两行。"></mp-actionSheet>
          Page({    data: {        showActionsheet: false,        groups: [            { text: '示例菜单', value: 1 },            { text: '示例菜单', value: 2 },            { text: '负向菜单', type: 'warn', value: 3 }        ]    },    close: function () {        this.setData({            showActionsheet: false        })    },    btnClick(e) {        console.log(e)        this.close()    }})

          效果展示

          属性列表

          属性类型默认值必填说明
          titlestring标题
          show-cancelbooleantrue是否显示取消按钮
          cancel-textstring取消按钮的文本
          mask-classstring背景蒙层的class
          ext-classstringActionSheet额外的class
          mask-closablebooleantrue点击背景蒙层是否可以关闭ActionSheet
          maskbooleantrue是否显示背景蒙层
          showbooleanfalse是否显示ActionSheet
          actionsArrayfalseActionSheet的按钮项的配置,每一项是包含text、value、type的Object,type的取值为warn和default,表示两种样式
          bindcloseeventhandler点击背后的mask关闭掉ActionSheet触发的事件
          bindactiontapeventhandler点击ActionSheet的按钮项触发的事件,detail为{ value, index }

          Slot

          名称描述
          title标题区域slot


          Navigation

          Navigation是小程序的顶部导航组件,当页面配置navigationStyle设置为custom的时候可以使用此组件替代原生导航栏。

          示例代码:

          {    "usingComponents": {        "mp-navigation-bar": "../components/navigation-bar/navigation-bar"    },    "navigationStyle": "custom",    "navigationBarTitleText": "UI组件库"}

          <mp-navigation-bar loading="{{loading}}" show="{{show}}" animated="{{animated}}" color="{{color}}" background="{{background}}" title="UI组件库" back="{{true}}"></mp-navigation-bar><view class="page">    <view class="page__hd">        <view class="page__title">Navigation</view>        <view class="page__desc">小程序自定义导航栏</view>    </view>    <view class="page__bd page__bd_spacing">        <button class="weui-btn" type="primary" bindtap="toggleLoading">触发loading</button>        <button class="weui-btn" type="primary" bindtap="changeColor">修改文字颜色</button>        <button class="weui-btn" type="primary" bindtap="changeBgColor">修改背景颜色</button>        <button class="weui-btn" type="primary" bindtap="toggleShow">显示 / 隐藏</button>        <button class="weui-btn" type="primary" bindtap="toggleAnimated">设置显示 / 隐藏opacity动画</button>    </view></view>

          Page({  data: {    loading: false,    color: '#000',    background: '#f8f8f8',    show: true,    animated: false  },  toggleLoading() {    this.setData({      loading: !this.data.loading    })  },  changeColor() {    this.setData({      color: '#07C160'    })  },  changeBgColor() {    this.setData({      background: '#ededed'    })  },  toggleShow() {    this.setData({      show: !this.data.show    })  },  toggleAnimated() {    this.setData({      animated: !this.data.animated,      show: !this.data.show    })  }})


          属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          titlestring导航标题,如果不提供,则名为center的slot有效
          backbooleantrue是否显示返回按钮,默认点击按钮会执行navigateBack,如果为false,则名为left的slot有效
          deltanumber1当back为true的时候有效,表示navigateBack的delta参数
          backgroundstring#f8f8f8导航背景色
          colorstring导航颜色
          loadingboolean是否显示标题左侧的loading
          showboolean显示隐藏导航,隐藏的时候navigation的高度占位还在
          animatedboolean显示隐藏导航的时候是有opacity过渡动画
          bindbackeventhandler在back为true时,点击back按钮触发此事件,detail包含delta

          Slot

          名称描述
          left左侧slot,在back按钮位置显示,当back为false的时候有效
          center标题slot,在标题位置显示,当title为空的时候有效
          right在导航的右侧显示

          Tabbar

          Tabbar组件,也可以用来作为小程序的自定义Tabbar使用

          示例代码:

          {  "usingComponents": {    "mp-tabbar": "../components/tabbar/tabbar"  },  "navigationBarTitleText": "UI组件库"}

          <view class="page">    <view class="page__hd">        <view class="page__title">Tabbar</view>        <view class="page__desc">类似小程序原生tabbar的组件,可用于自定义tabbar</view>    </view>    <mp-tabbar style="position:fixed;bottom:0;width:100%;left:0;right:0;" list="{{list}}" bindchange="tabChange"></mp-tabbar></view>

          Page({    data: {        list: [{            "text": "对话",            "iconPath": "../../images/tabbar_icon_chat_default.png",          "selectedIconPath": "../../images/tabbar_icon_chat_active.png",            dot: true        },        {            "text": "设置",          "iconPath": "../../images/tabbar_icon_setting_default.png",          "selectedIconPath": "../../images/tabbar_icon_setting_active.png",            badge: 'New'        }]    },    tabChange(e) {        console.log('tab change', e)    }});


          属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          listarray<object>Tabbar的项的数组,按照规范,至少要有2个Tabbar项
          currentnumber0当前选中的Tabbar项的下标
          bindchangeeventhandlerTabbar项发生改成的时候触发此事件,detail为{index, item},index是Tabbar下标,item是对应的Tabbar项的配置

          list属性是对象数组,每一项表示一个Tabbar项,其字段含义为

          字段名类型默认值必填说明
          textstringTabbar项的标题
          iconPathstringTabbar项的icon图片路径,建议使用绝对路径,相对路径要相对于组件所在目录的。
          selectedIconPathstringTabbar项选中时的icon,建议使用绝对路径,相对路径要相对于组件所在目录的。
          badgestring是否显示Tabbar的右上角的Badge


          Searchbar

          搜索组件Searchbar提供搜索的功能,并展示搜索的结果。

          示例代码:

          {  "usingComponents": {    "mp-searchbar": "../components/searchbar/searchbar"  },  "navigationBarTitleText": "UI组件库"}
          <view class="page">    <view class="page__hd">        <view class="page__title">SearchBar</view>        <view class="page__desc">搜索栏</view>    </view>    <view class="page__bd">        <mp-searchbar bindselectresult="selectResult" search="{{search}}"></mp-searchbar>    </view></view>
          Page({    data: {        inputShowed: false,        inputVal: ""    },    onLoad() {        this.setData({            search: this.search.bind(this)        })    },    search: function (value) {        return new Promise((resolve, reject) => {            setTimeout(() => {                resolve([{text: '搜索结果', value: 1}, {text: '搜索结果2', value: 2}])            }, 200)        })    },    selectResult: function (e) {        console.log('select result', e.detail)    },});


          属性列表

          属性类型默认值必填说明
          ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
          focusbooleanfalse是否在组件开始创建的时候focus搜索输入框
          placeholderstring搜索搜索输入框的placeholder
          valuestring搜索输入框的默认值
          searchfunction输入过程不断调用此函数得到新的搜索结果,参数是输入框的值value,返回Promise实例
          throttlenumber500调用search函数的间隔,单位ms
          cancelTextstring取消取消按钮的文本
          cancelbooleantrue是否显示取消按钮
          bindfocuseventhandle在输入框focus的时候触发事件
          bindblureventhandle在输入框blur的时候触发事件
          bindcleareventhandle在clear按钮点击的时候触发事件
          bindinputeventhandle在输入框输入过程中触发事件
          bindselectresulteventhandle在选择搜索结果的时候触发事件


          其他组件

          出于性能考虑,weui-miniprogram 并没有对所有 WeUI 组件进行封装(如:flex布局组件),可以直接使用 WeUI 中定义的组件结构(参考 Demo)。

          示例代码

          在引入 weui.wxss 后,可以直接使用 weui-wxss 中定义的 class 自定义样式,以 flex 组件为例:

          <view class="page__hd">    <view class="page__title">Flex</view>    <view class="page__desc">Flex布局</view></view><view class="page__bd page__bd_spacing">    <view class="weui-flex">        <view class="weui-flex__item"><view class="placeholder">weui</view></view>    </view>    <view class="weui-flex">        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>    </view>    <view class="weui-flex">        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>    </view>    <view class="weui-flex">        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>    </view>    <view class="weui-flex">        <view><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view><view class="placeholder">weui</view></view>    </view></view>

          渲染到页面上会得到以下结果:

          flex布局

          其他组件可以参考库中提供的 Demo


          emoji

          仿微信表情组件。使用前需将文档下方提供的表情雪碧图上传 CDN,再传入表情组件。为提升首次加载表情图片的性能,可通过 image 组件提前触发雪碧图的下载,利用浏览器的缓存机制。在不使用表情面板的页面,可将 emoji 组件隐藏或移出屏幕外,仅使用 parseEmoji 的功能。

          属性列表

          属性类型默认值必填说明
          sourcestring表情雪碧图地址
          heightnumber300表情盘高度
          background-colorstring#EDEDED表情盘背景色
          show-sendbooleantrue是否显示发送按钮
          show-delbooleantrue是否显示删除按钮
          show-historybooleantrue是否显示最近使用
          bindinsertemojieventhandle插入表情,e.detail={emotionName}
          binddelemojieventhandle点击删除按钮
          bindsendeventhandle点击发送按钮

          示例代码:

          {  "disableScroll": true,  "navigationBarTitleText": "",  "usingComponents": {    "mp-emoji": "../components/emoji/emoji"  }}

          <scroll-view scroll-y style="height: {{layoutHeight}}px" scroll-into-view="{{historyList[historyList.length - 1].id}}">  <block wx:for="{{historyList}}" wx:for-index="idx" wx:for-item="historyItem">    <view class="record" hidden="{{historyItem.length === 0}}" id="{{historyItem.id}}">      <view class="avator"></view>      <view class="comment">        <block wx:for="{{historyItem.emoji}}" wx:key="*this">          <block wx:if="{{item.type === 1}}">{{item.content}}</block>          <view             wx:if="{{item.type === 2}}"             style="display: inline-block; width: {{lineHeight}}px; height: {{lineHeight}}px">            <view               class="{{item.imageClass}}"              style="background-image: url({{emojiSource}});transform-origin: 0 0; transform: scale({{lineHeight / 64}});"></view>          </view>        </block>      </view>    </view>  </block></scroll-view>      <view class="reply_wrp" style="bottom: {{keyboardHeight}}px">      <view class="reply_tool">        <view hover-class="active" class="reply_button replay_quick_button">          <image src="./images/reply_tool_keyboard.svg" mode='aspectFit' class="reply_tool_pic"></image>        </view>        <view class="reply_form_wrp">          <label for="" class="reply_label">            <input               class="reply_input"               cursor-spacing="8px"               confirm-type="send"               adjust-position="{{false}}"               confirm-hold value="{{comment}}"               cursor="{{cursor}}"               focus="{{focus}}"               bindblur="onBlur"               bindfocus="onFocus"               bindinput="onInput"               bindconfirm="onConfirm"               bindkeyboardheightchange="onkeyboardHeightChange"            />          </label>        </view>        <view hover-class="active" class="reply_button replay_emotion_button" bindtap="showEmoji">          <image src="./images/reply_tool_emoji.svg" mode='aspectFit' class="reply_tool_pic"></image>        </view>        <view hover-class="active" class="reply_button replay_media_button" bindtap="showFunction">          <image src="./images/reply_tool_add.png" mode='aspectFit' class="reply_tool_pic"></image>        </view>      </view>      <view class="reply_panel_wrp" style="height: {{emojiShow ? 300 : 200}}px;" hidden="{{!emojiShow && !functionShow}}">        <view class="reply_panel {{emojiShow ? 'show': ''}}" hidden="{{!emojiShow}}">          <mp-emoji source="{{emojiSource}}" class="mp-emoji" bindinsertemoji="insertEmoji" binddelemoji="deleteEmoji" bindsend="onsend"></mp-emoji>        </view>        <view class="reply_panel {{functionShow ? 'show': ''}}" hidden="{{!functionShow}}">          <swiper indicator-dots="{{true}}" indicator-color="#bbbbbb" indicator-active-color="#8c8c8c">            <swiper-item>              <view class="function_list">                <view class="function_item" bindtap="chooseImage">                  <image src="./images/reply_function_image.svg" class="reply_function_pic"></image>                </view>              </view>            </swiper-item>          </swiper>        </view>      </view>    </view>


          使用方式

          点击表情图标将会获得对应的中文含义,例如????->[微笑]。在实际输入过程中,我们通常仅展示中文含义即可。

          对文字和表情混合的评论需要解析后才能展示,组件内提供了 parseEmoji 解析函数,获取方式如下:

          // .mp-emoji 为表情组件的选择器const emojiInstance = this.selectComponent('.mp-emoji')const emojiNames = emojiInstance.getEmojiNames()const parseEmoji = emojiInstance.parseEmojiconst comment = '测试[得意][偷笑]文本'const parsedCommnet = parseEmoji(comment)

          解析后的评论结构如下,文字和表情分割构成的数组,type=1 为纯文本,type=2 为表情 icon,imageClass 记录了表情在雪碧图上的位置。需注意的是组件开启了 styleIsolation: 'page-shared',组件内样式与页面共享。

          [  {type: 1, content: '测试'},  {type: 2, content: '[得意]', imageClass: 'smiley_4'},  {type: 2, content: '[偷笑]', imageClass: 'smiley_20'},  {type: 1, content: '文本'},]

          由于表情 icon 采用雪碧图生成,展示时可采用如下的结构。需要注意的是每个 icon 的实际大小为 64px,因此在段落中通过 scale 进行缩放,缩放的比例为 行高 / 64。

          <view class="comment">  <block wx:for="{{parsedComment}}" wx:key="*this">    <block wx:if="{{item.type === 1}}">{{item.content}}</block>    <view wx:if="{{item.type === 2}}" style="display: inline-block; width: {{lineHeight}}px; height: {{lineHeight}}px">      <view         class="{{item.imageClass}}"        style="background-image: url({{emojiSource}});transform-origin: 0 0; transform: scale({{lineHeight / 64}});">      </view>    </view>  </block></view>
          .comment {  font-size: 18px;  display: flex;  align-items: center;  flex-wrap: wrap;  line-height: 24px;}

          如何与 input 结合使用,参考示例代码。

          表情雪碧图

          emoji-sprite


          video-swiper

          视频滑动切换组件,可实现类似微视无限视频列表效果。

          使用说明

          video-list 的长度应当不低于 3 个,当滚动到首项或者尾项后,会进入循环。通过 setData 更改 video-list,会直接追加到之前的视频源中。可监听 bindchange 事件获取当前滚动到那一个视频,activeId 为视频源的唯一 id。

          属性列表

          属性类型默认值必填说明
          durationnumber500滑动动画时长
          easing-functionstringdefault切换缓动动画类型
          loopbooleantrue是否循环播放
          video-listArray VideoSwiperItem[]true视频源
          bindchangeeventhandle滑动切换完成时触发, e.detail={activeId}
          bindplayeventhandle开始/继续播放时触发, e.detail={activeId}
          bindpauseeventhandle暂停播放时触发, e.detail={activeId}
          bindendedeventhandle播放到末尾时触发, e.detail={activeId}
          bindtimeupdateeventhandle播放进度变化时触发,event.detail = {currentTime, duration, activeId}
          bindwaitingeventhandle视频出现缓冲时触发, e.detail={activeId}
          binderroreventhandle视频播放出错时触发, e.detail={activeId}
          bindprogresseventhandle加载进度变化时触发,只支持一段加载。event.detail={buffered, activeId}
          bindloadedmetadataeventhandle视频元数据加载完成时触发。event.detail={width, height, duration, activeId}

          VideoSwiperItem 属性列表

          属性说明
          id每个视频源的唯一 id
          url视频播放地址
          objectFit当视频大小与 video 容器大小不一致时,视频的表现形式

          objectFit 的合法值

          属性说明
          contain包含
          fill填充
          cover覆盖

          easing-function 的合法值

          属性说明
          default默认缓动函数
          linear线性动画
          easeInCubic缓入动画
          easeOutCubic缓出动画
          easeInOutCubic缓入缓出动画


          recycle-view

          小程序长列表组件

          使用此组件需要依赖小程序基础库 2.2.2 版本,同时依赖开发者工具的 npm 构建。具体详情可查阅官方 npm 文档。

          背景

          ​目前小程序会有不少的应用场景里会用到无限长列表的交互,当一个页面展示很多信息的时候,会造成小程序页面的卡顿以及白屏。原因有如下几点:

          1. 列表数据很大,首次 setData 的时候耗时高
          2. 渲染出来的列表 DOM 结构多,每次 setData 都需要创建新的虚拟树、和旧树 diff 操作耗时都比较高
          3. 渲染出来的列表 DOM 结构多,占用的内存高,造成页面被系统回收的概率变大。

          因此就有长列表组件来解决这些问题。

          实现思路

          ​核心的思路是只渲染显示在屏幕的数据,基本实现就是监听 scroll 事件,并且重新计算需要渲染的数据,不需要渲染的数据留一个空的 div 占位元素。

          假设列表数据有100个 item,知道了滚动的位置,怎么知道哪些 item 必须显示在页面?因为 item 还没渲染出来,不能通过 getComputedStyle 等 DOM 操作得到每个 item 的位置,所以无法知道哪些 item 需要渲染。为了解决这个问题,需要每个 item 固定宽高。item 的宽高的定义见下面的 API 的createRecycleContext()的参数 itemSize 的介绍。

          滚动过程中,重新渲染数据的同时,需要设置当前数据的前后的 div 占位元素高度,同时是指在同一个渲染周期内。页面渲染是通过 setData 触发的,列表数据和 div 占位高度在2个组件内进行 setData 的,为了把这2个 setData 放在同一个渲染周期,用了一个 hack 方法,所以定义 recycle-view 的 batch 属性固定为 batch="{{batchSetRecycleData}}"。

          在滚动过程中,为了避免频繁出现白屏,会多渲染当前屏幕的前后2个屏幕的内容。

          包结构

          长列表组件由2个自定义组件 recycle-view、recycle-item 和一组 API 组成,对应的代码结构如下

          ├── miniprogram-recycle-view/    └── recycle-view 组件    └── recycle-item 组件    └── index.js

          包结构详细描述如下:

          目录/文件描述
          recycle-view 组件长列表组件
          recycle-item 组件长列表每一项 item 组件
          index.js提供操作长列表数据的API

          使用方法:

          1.安装组件

          npm install --save miniprogram-recycle-view

          2.在页面的 json 配置文件中添加 recycle-view 和 recycle-item 自定义组件的配置

          {  "usingComponents": {    "recycle-view": "miniprogram-recycle-view/recycle-view",    "recycle-item": "miniprogram-recycle-view/recycle-item"  }}

          3.WXML 文件中引用 recycle-view

          <recycle-view batch="{{batchSetRecycleData}}" id="recycleId">  <view slot="before">长列表前面的内容</view>  <recycle-item wx:for="{{recycleList}}" wx:key="id">    <view>        <image style='width:80px;height:80px;float:left;' src="{{item.image_url}}"></image>      {{item.idx+1}}. {{item.title}}    </view>  </recycle-item>  <view slot="after">长列表后面的内容</view></recycle-view>

          recycle-view 的属性介绍如下:

          字段名类型必填描述
          idStringid必须是页面唯一的字符串
          batchBoolean必须设置为{{batchSetRecycleData}}才能生效
          heightNumber设置recycle-view的高度,默认为页面高度
          widthNumber设置recycle-view的宽度,默认是页面的宽度
          enable-back-to-topBoolean默认为false,同scroll-view同名字段
          scroll-topNumber默认为false,同scroll-view同名字段
          scroll-yNumber默认为true,同scroll-view同名字段
          scroll-to-indexNumber设置滚动到长列表的项
          placeholder-imageString默认占位背景图片,在渲染不及时的时候显示,不建议使用大图作为占位。建议传入SVG的Base64格式,可使用工具将SVG代码转为Base64格式。支持SVG中设置rpx。
          scroll-with-animationBoolean默认为false,同scroll-view的同名字段
          lower-thresholdNumber默认为false,同scroll-view同名字段
          upper-thresholdNumber默认为false,同scroll-view同名字段
          bindscroll事件同scroll-view同名字段
          bindscrolltolower事件同scroll-view同名字段
          bindscrolltoupper事件同scroll-view同名字段

          recycle-view 包含3个 slot,具体介绍如下:

          名称描述
          before默认 slot 的前面的非回收区域
          默认 slot长列表的列表展示区域,recycle-item 必须定义在默认 slot 中
          after默认 slot 的后面的非回收区域

          长列表的内容实际是在一个 scroll-view 滚动区域里面的,当长列表里面的内容,不止是单独的一个列表的时候,例如我们页面底部都会有一个 copyright 的声明,我们就可以把这部分的内容放在 before 和 after 这2个 slot 里面。

          recycle-item 的介绍如下:

          需要注意的是,recycle-item 中必须定义 wx:for 列表循环,不应该通过 setData 来设置 wx:for 绑定的变量,而是通过createRecycleContext方法创建RecycleContext对象来管理数据,createRecycleContext在 index.js 文件里面定义。建议同时设置 wx:key,以提升列表的渲染性能。

          4.页面 JS 管理 recycle-view 的数据

          const createRecycleContext = require('miniprogram-recycle-view')Page({    onReady: function() {        var ctx = createRecycleContext({          id: 'recycleId',          dataKey: 'recycleList',          page: this,          itemSize: { // 这个参数也可以直接传下面定义的this.itemSizeFunc函数            width: 162,            height: 182          }        })        ctx.append(newList)        // ctx.update(beginIndex, list)        // ctx.destroy()    },    itemSizeFunc: function (item, idx) {        return {            width: 162,            height: 182        }    }})

          页面必须通过 Component 构造器定义,页面引入了miniprogram-recycle-view包之后,会在 wx 对象下面新增接口createRecycleContext函数创建RecycleContext对象来管理 recycle-view 定义的的数据,createRecycleContext接收类型为1个 Object 的参数,Object 参数的每一个 key 的介绍如下:

          参数名类型描述
          idString对应 recycle-view 的 id 属性的值
          dataKeyString对应 recycle-item 的 wx:for 属性设置的绑定变量名
          pagePage/Componentrecycle-view 所在的页面或者组件的实例,页面或者组件内可以直接传 this
          itemSizeObject/Function此参数用来生成recycle-item的宽和高,前面提到过,要知道当前需要渲染哪些item,必须知道item的宽高才能进行计算
          Object必须包含{width, height}两个属性,Function的话接收item, index这2个参数,返回一个包含{width, height}的Object
          itemSize如果是函数,函数里面this指向RecycleContext
          如果样式使用了rpx,可以通过transformRpx来转化为px。
          为Object类型的时候,还有另外一种用法,详细情况见下面的itemSize章节的介绍。
          useInPageBoolean是否整个页面只有recycle-view。Page的定义里面必须至少加空的onPageScroll函数,主要是用在页面级别的长列表,并且需要用到onPullDownRefresh的效果。切必须设置root参数为当前页面对象
          rootPage当前页面对象,可以通过getCurrentPages获取, 当useInPage为true必须提供

          RecycleContext 对象提供的方法有:

          方法参数说明
          appendlist, callback在当前的长列表数据上追加list数据,callback是渲染完成的回调函数
          splicebegin, count, list, callback插入/删除长列表数据,参数同Array的splice函数,callback是渲染完成的回调函数
          updatebegin, list, callback更新长列表的数据,从索引参数begin开始,更新为参数list,参数callback同splice。
          destroy销毁RecycleContext对象,在recycle-view销毁的时候调用此方法
          forceUpdatecallback, reinitSlot重新渲染recycle-view。callback是渲染完成的回调函数,当before和after这2个slot的高度发生变化时候调用此函数,reinitSlot设置为true。当item的宽高发生变化的时候也需要调用此方法。
          getBoundingClientRectindex获取某个数据项的在长列表中的位置,返回{left, top, width, height}的Object。
          getScrollTop获取长列表的当前的滚动位置。
          transformRpxrpx将rpx转化为px,返回转化后的px整数。itemSize返回的宽高单位是px,可以在这里调用此函数将rpx转化为px,参数是Number,例如ctx.transformRpx(140),返回70。注意,transformRpx会进行四舍五入,所以transformRpx(20) + transformRpx(90)不一定等于transformRpx(110)
          getViewportItemsinViewportPx获取在视窗内的数据项,用于判断某个项是否出现在视窗内。用于曝光数据上报,菜品和类别的联动效果实现。参数inViewportPx表示距离屏幕多少像素为出现在屏幕内,可以为负值。

          其中 itemSize 的使用

          itemSize可以为包含{width, height}的Object,所有数据只有一种宽高信息。如果有多种,则可以提供一个函数,长列表组件会调用这个函数生成每条数据的宽高信息,如下所示:

          function(item, index) {    return {        width: 195,        height: item.azFirst ? 130 : 120    }}

          提示:

          1. recycle-view设置batch属性的值必须为{{batchSetRecycleData}}。
          2. recycle-item的宽高必须和itemSize设置的宽高一致,否则会出现跳动的bug。
          3. recycle-view设置的高度必须和其style里面设置的样式一致。
          4. createRecycleContext(options)的id参数必须和recycle-view的id属性一致,dataKey参数必须和recycle-item的wx:for绑定的变量名一致。
          5. 不能在recycle-item里面使用wx:for的index变量作为索引值的,请使用{{item._index_}}替代。
          6. 不要通过setData设置recycle-item的wx:for的变量值,建议recycle-item设置wx:key属性。
          7. 如果长列表里面包含图片,必须保证图片资源是有HTTP缓存的,否则在滚动过程中会发起很多的图片请求。
          8. 有些数据不一定会渲染出来,使用wx.createSelectorQuery的时候有可能会失效,可使用RecycleContext的getBoundingClientRect来替代。
          9. 当使用了useInPage参数的时候,必须在Page里面定义onPageScroll事件。
          10. transformRpx会进行四舍五入,所以transformRpx(20) + transformRpx(90)不一定等于transformRpx(110)
          11. 如果一个页面有多个长列表,必须多设置batch-key属性,每个的batch-key的值和batch属性的变量必须不一致。例如
          <recycle-view batch="{{batchSetRecycleData}}" batch-key="batchSetRecycleData"></recycle-view><recycle-view batch="{{batchSetRecycleData1}}" batch-key="batchSetRecycleData1"></recycle-view>


          sticky

          粘性布局组件。Sticky 组件与 CSS 中 position: sticky 属性实现的效果一致,当组件在屏幕范围内时,会按照正常的布局排列,当组件滚出屏幕范围时,始终会固定在屏幕顶部。

          属性列表

          属性类型默认值必填说明
          offset-topNumber0吸顶时与顶部的距离,单位px
          z-indexNumber99吸顶时的 z-index
          containerfunctionnull一个函数,返回容器对应的 NodesRef 节点
          disabledBooleanfalse是否禁用
          bindscrolleventhandle滚动时触发,{scrollTop: 距离顶部位置, isFixed: 是否吸顶 }

          代码演示

          吸顶距离

          通过 offset-top 属性可以设置组件在吸顶时与顶部的距离

          <mp-sticky offset-top="32">  <button size="mini" type="primary" style="margin-left: 115px; background-color: #1989fa">吸顶距离</button></mp-sticky>

          指定容器

          通过 container 属性可以指定组件的容器,页面滚动时,组件会始终保持在容器范围内,当组件即将超出容器底部时,会返回原位置。

          <view id="container" style="height: 250px; background-color: #E0E0E0;">  <view style="height: 100px; background-color: #FFFF99;"></view>  <mp-sticky container="{{container}}" offset-top="64">    <button size="mini" type="primary" style="margin-left: 215px; background-color: #ff976a">指定容器</button>  </mp-sticky></view>
          Page({  data: {    container: null  },  onReady() {    this.setData({      container: () => wx.createSelectorQuery().select('#container')    })  }})


          tabs

          选项卡组件。

          <view class="page">  <mp-tabs     tabs="{{tabs}}"     activeTab="{{activeTab}}"     swiperClass="weui-tabs-swiper"    bindtabclick="onTabClick"    bindchange="onChange"    activeClass="tab-bar-title__selected">    <block wx:for="{{tabs}}" wx:key="title">      <view class="tab-content" data-set="{{item}}" slot="tab-content-{{index}}" bind:tap="handleClick" >        <image src="{{item.img}}" mode="widthFix"></image>        <view class="item-title">          {{item.title2}}        </view>        <view class="item-desc">          {{item.desc}}        </view>      </view>    </block>  </mp-tabs>  </view>
          Page({  onShareAppMessage() {    return {      title: 'tabs',      path: 'page/weui/example/tabs/tabs'    }  },  data: {    tabs: [],    activeTab: 0,  },  onLoad() {    const tabs = [      {        title: '技术开发',        title2: '小程序开发进阶',        img: 'http://mmbiz.qpic.cn/sz_mmbiz_jpg/GEWVeJPFkSEV5QjxLDJaL6ibHLSZ02TIcve0ocPXrdTVqGGbqAmh5Mw9V7504dlEiatSvnyibibHCrVQO2GEYsJicPA/0?wx_fmt=jpeg',        desc: '本视频系列课程,由腾讯课堂NEXT学院与微信团队联合出品,通过实战案例,深入浅出地进行讲解。',      },      {        title: '产品解析',        title2: '微信小程序直播',        img: 'http://mmbiz.qpic.cn/sz_mmbiz_png/GEWVeJPFkSHALb0g5rCc4Jf5IqDfdwhWJ43I1IvriaV5uFr9fLAuv3uxHR7DQstbIxhNXFoQEcxGzWwzQUDBd6Q/0?wx_fmt=png',        desc: '微信小程序直播系列课程持续更新中,帮助大家更好地理解、应用微信小程序直播功能。',      },      {        title: '运营规范',        title2: '常见问题和解决方案',        img: 'http://mmbiz.qpic.cn/sz_mmbiz_jpg/GEWVeJPFkSGqys4ibO2a8L9nnIgH0ibjNXfbicNbZQQYfxxUpmicQglAEYQ2btVXjOhY9gRtSTCxKvAlKFek7sRUFA/0?wx_fmt=jpeg',        desc: '提高审核质量',      },      {        title: '营销经验',        title2: '流量主小程序',        img: 'http://mmbiz.qpic.cn/sz_mmbiz_jpg/GEWVeJPFkSH2Eic4Lt0HkZeEN08pWXTticVRgyNGgBVHMJwMtRhmB0hE4m4alSuwsBk3uBBOhdCr91bZlSFbYhFg/0?wx_fmt=jpeg',        desc: '本课程共四节,将分阶段为开发者展示如何开通流量主功能、如何接入广告组件、不同类型小程序接入的建议,以及如何通过工具调优小程序变现效率。',      },      {        title: '高校大赛',        title2:'2020中国高校计算机大赛',        img: 'http://mmbiz.qpic.cn/mmbiz_jpg/TcDuyasB5T3Eg34AYwjMw7xbEK2n01ekiaicPiaMInEMTkOQtuv1yke5KziaYF4MLia4IAbxlm0m5NxkibicFg4IZ92EA/0?wx_fmt=jpeg',        desc: '微信小程序应用开发赛',      },    ]    this.setData({ tabs })  },  onTabClick(e) {    const index = e.detail.index    this.setData({       activeTab: index     })  },  onChange(e) {    const index = e.detail.index    this.setData({       activeTab: index     })  },  handleClick(e) {    wx.navigateTo({      url: './webview',    })  }})


          属性列表

          属性类型默认值必填说明
          tabsArray[]数据项格式为 {title}
          tab-classString选项卡样式
          swiper-classString内容区域 swiper 的样式
          active-classString选中项样式
          tab-underline-colorString#07c160选中项下划线颜色
          tab-active-text-colorString#000000选中项字体颜色
          tab-inactive-text-colorString#000000未选中项字体颜色
          tab-background-colorString#ffffff选项卡背景颜色
          active-tabNumber0激活 tab 索引
          durationNumber500内容区域切换时长
          bindtabclickeventhandle点击 tab 时触发,e.detail={index}
          bindchangeeventhandle内容区域滚动导致 tab 变化时触发, e.detail={index}

          注意事项

          • 内容区域采用 <swiper>进行滚动,超出部分将被隐藏,需设置 swiperClass 的高度与子元素一致。
          • 内容区域子元素需指定 slot=tab-content-index,其中 index 为选项卡的下标(从0开始)。


          row/col 组件

          按照栅格化布局思路,再加上响应式布局的特性,提供了 row/col 两个基础布局组件,用来帮助开发者快速适配多屏应用。

          核心概念是将整个屏幕宽度分为 24 单位,每个单位的大小,由当前屏幕尺寸决定的。例如 375px 的屏幕宽度,那么 1 unit = 375/24 px.

          使用方法

          1. npm 安装
          npm i @miniprogram-component-plus/col --savenpm i @miniprogram-component-plus/row --save
          1. 开发者工具构建 npm,勾选“使用 npm 模块”,参考 npm 支持
          2. 页面 json 文件中加入 usingComponents 字段
          {  "usingComponents": {    "mp-col": "@miniprogram-component-plus/col",    "mp-row": "@miniprogram-component-plus/row"  }}
          1. 在页面中使用组件
          <view class="page__desc">三列均分布局</view>    <view>        <mp-row>          <mp-col span="{{8}}">            <view>              <view class="col">              </view>            </view>          </mp-col>          <mp-col span="{{8}}">            <view>              <view class="col">              </view>            </view>          </mp-col>          <mp-col span="{{8}}">            <view>              <view class="col">              </view>            </view>          </mp-col>        </mp-row></view>

          row 组件属性

          默认无

          col 组件属性

          属性类型默认值必填说明
          spannumber24当前 col 所占屏幕宽度的份数
          offsetnumber0距 row 左侧偏移margin 距离
          pushnumber0距左侧偏移的单位距离
          pullnumber0距右侧偏移的单位距离
          xsnumber, Object<span,offset, push, pull>当屏幕 < 768px 时,对应显示的网格规则。例如 xs="2" 或 xs="{ "span": 24, "offset": 0 }"
          smnumber, Object<span,offset, push, pull>当屏幕 >= 768px, <992px,对应显示的网格规则。
          mdnumber, Object<span,offset, push, pull>当屏幕 >= 992px, <1200px,对应显示的网格规则。
          lgnumber, Object<span,offset, push, pull>当屏幕 >= 1200px, <1920px 时,对应显示的网格规则。
          xlnumber, Object<span,offset, push, pull>当屏幕 >= 1920px 时,对应显示的网格规则。

          提示:

          • 同时设置 span 和 响应式属性时,当屏幕超过响应式属性范围时,会使用 span 属性。


          vtabs

          纵向选项卡组件,需与 <vtabs-content> 组件结合使用。

          属性列表

          属性类型默认值必填说明
          vtabsArray[]数据项格式为 {title}
          active-tabNumber0激活 tab 索引
          tab-bar-classString选项卡样式
          active-classString选中项样式
          tab-line-colorString#ff0000选中项侧划线颜色
          tab-inactive-text-colorString#000000未选中项字体颜色
          tab-active-text-colorString#ff0000选中项字体颜色
          tab-inactive-bg-colorString#eeeeee未选中项背景色
          tab-active-bg-colorString#ffffff选中项背景色
          animationBooleantrue是否开启动画
          bindtabclickeventhandle点击 tab 时触发,e.detail={index}
          bindchangeeventhandle内容区域滚动导致 tab 变化时触发, e.detail={index}

          vtabs-content

          纵向选项卡内容。

          属性类型默认值必填说明
          tab-indexNumber0vtabs 数据索引(从0开始)

          index-list

          索引列表组件,可实现类似通讯录效果。组件内节点将被添加到列表上方。

          示例代码:

          const res = {  result: [    [{      cidx: [0, 15],      fullname: "北京市",      id: "110000",      location: {        lat: 39.90469,        lng: 116.40717       },      name: "北京",      pinyin: ["bei", "jing"]    }, {      cidx: [16, 31],      fullname: "天津市",      id: "120000",      location: {lat: 39.0851, lng: 117.19937},      name: "天津",      pinyin: ["tian", "jin"]    }, {      cidx: [32, 42],      fullname: "河北省",      id: "130000",      location: {lat: 38.03599, lng: 114.46979},      name: "河北",      pinyin: ["he", "bei"],    }, {      cidx: [43, 53],      fullname: "山西省",      id: "140000",      location: {lat: 37.87343, lng: 112.56272},      name: "山西",      pinyin:  ["shan", "xi"],    }]  ]}Page({  onLoad(options) {    this.getCitys()  },  onChoose(e) {    console.log('onChoose', e)  },  getCitys() {    const _this = this    const cities = res.result[0]        // 按拼音排序        cities.sort((c1, c2) => {          let pinyin1 = c1.pinyin.join('')          let pinyin2 = c2.pinyin.join('')          return pinyin1.localeCompare(pinyin2)        })        // 添加首字母        const map = new Map()        for (const city of cities) {          const alpha = city.pinyin[0].charAt(0).toUpperCase()          if (!map.has(alpha)) map.set(alpha, [])          map.get(alpha).push({ name: city.fullname })        }            const keys = []        for (const key of map.keys()) {          keys.push(key)        }        keys.sort()            const list = []        for (const key of keys) {          list.push({            alpha: key,            subItems: map.get(key)          })        }        _this.setData({list})  }})

          <mp-indexList class="city__list" list="{{list}}" bindchoose="onChoose">    <view class="page">        <view class="page__hd">            <view class="page__title">Index List</view>            <view class="page__desc">类通讯录列表</view>        </view>        <view class="page__bd">        </view>    </view></mp-indexList>


          属性列表

          属性类型默认值必填说明
          listArray<listItem>[]列表数据
          vibratedbooleantrue索引上滑动时是否产生振动,仅 iOS 生效
          bindchooseeventhandle选择列表项, e.detail={name}

          listItem 属性列表

          属性类型说明
          alphastring首字母(大写)
          subItemsArray<subItem>子元素集合

          subItem 属性列表

          属性类型说明
          namestring名称

          注意事项

          1. demo 中省市信息为模拟数据,开发者可以使用腾讯位置服务提供的 SDK 来获取省市信息。


          Barrage for MiniProgram

          小程序弹幕组件。通过 view 的 transform 移动弹幕,覆盖在 原生组件上时,请确保组件已经同层化。参考用例

          使用方法

          1. npm 安装
          npm install --save miniprogram-barrage
          1. JSON 组件声明
          {  "usingComponents": {    "barrage": "miniprogram-barrage",  }}
          1. wxml 引入弹幕组件
          <video class="video" src="{{src}}">  <barrage class="barrage"></barrage></video>
          1. js 获取实例
           Page({  onReady() {    this.addBarrage()  },  addBarrage() {    const barrageComp = this.selectComponent('.barrage')    this.barrage = barrageComp.getBarrageInstance({      font: 'bold 16px sans-serif',      duration: 10,      lineHeight: 2,      mode: 'separate',      padding: [10, 0, 10, 0],      tunnelShow: false    })    this.barrage.open()    this.barrage.addData(data)  } })

          配置

          Barrage 默认配置

          {  duration: 10, // 弹幕动画时长 (移动 2000px 所需时长)  lineHeight: 1.2, // 弹幕行高  padding: [0, 0, 0, 0], // 弹幕区四周留白  alpha: 1, // 全局透明度  font: '10px sans-serif', // 全局字体  mode: 'separate', // 弹幕重叠 overlap  不重叠 separate  range: [0, 1], // 弹幕显示的垂直范围,支持两个值。[0,1]表示弹幕整个随机分布,  tunnelShow: false, // 显示轨道线  tunnelMaxNum: 30, // 隧道最大缓冲长度  maxLength: 30, // 弹幕最大字节长度,汉字算双字节  safeGap: 4, // 发送时的安全间隔  enableTap: false, // 点击弹幕停止动画高亮显示}

          弹幕数据配置

          {  color: '#000000', // 默认黑色  content: '', // 弹幕内容  image: {    head: {src, width, height}, // 弹幕头部添加图片    tail: {src, width, height}, // 弹幕尾部添加图片    gap: 4 // 图片与文本间隔  }  }

          接口

          barrage.open() // 开启弹幕功能barrage.close() // 关闭弹幕功能,清空弹幕barrage.addData() // 添加弹幕数据barrage.setRange() // 设置垂直方向显示范围barrage.setFont() // 设置全局字体barrage.setAlpha() // 设置全局透明度barrage.showTunnel() // 显示弹幕轨道barrage.hideTunnel() // 隐藏弹幕轨道

          说明

          1. 通过 canvas 实现弹幕组件时,对于低版本基础库由于缺失 raf 接口,动画效果不够流畅。
          2. 2.9.0 起小程序新的 canvas 接口可替代 view 的实现。


          select-text

          可选文本组件。该组件有两种使用模式:长按出现选区,与浏览器默认效果一致;长按出现复制按钮,点击复制拷贝全部内容至剪贴板,常见于聊天对话框等场景。

          需注意的时,为实现点击其它区域隐藏复制按钮,开发者可在页面最外层监听 tap 事件,并将 evt 对象赋值给 on-document-tap。

          <view bind:tap="handleTap">  <view class="demo-block">    <block wx:for="{{arr}}" wx:key="placement">      <view class="list-item">        <mp-select-text           show-copy-btn           placement="{{item.placement}}"           value="{{item.value}}"           data-id="{{index}}"           bindcopy="onCopy"          on-document-tap="{{evt}}"        >        </mp-select-text>      </view>    </block>    <view class="list-item">      <mp-select-text value="默认的长按效果与浏览器一致"></mp-select-text>    </view>  </view></view>

          Page({  data: {    arr: [{      value: '长按,上侧复制',      placement: 'top'    }, {      value: '长按,右侧复制',      placement: 'right'    }, {      value: '长按,左侧复制',      placement: 'left'    }, {      value: '长按,下侧复制',      placement: 'bottom'    }]  },  onLoad() {  },  onCopy(e) {    console.log('onCopy', e)  },    handleTouchStart(e) {    console.log('@@ touchstart', e)  },  handleTap(e) {    console.log('@@ tap', e)    this.setData({      evt: e    })  }})


          属性列表

          属性类型默认值必填说明
          valueString文本组件内容
          spaceString显示连续空格
          decodeBooleanfalse是否解码
          show-copy-btnBooleanfalse长按显示复制按钮
          z-indexNumber99复制按钮的层级
          active-bg-colorString#DEDEDE长按复制时文本区背景色
          on-document-tapObject页面监听事件

          space 的合法值

          属性类型
          ensp中文字符空格一半大小
          emsp中文字符空格大小
          nbsp根据字体设置的空格大小

          代码演示

          在开发者工具中预览效果

          <view bind:tap="handleTap">  <view class="demo-block">    <block wx:for="{{arr}}" wx:key="placement">      <view class="list-item">        <mp-select-text           show-copy-btn           placement="{{item.placement}}"           value="{{item.value}}"           data-id="{{index}}"           on-document-tap="{{evt}}"        >        </mp-select-text>      </view>    </block>    <view class="list-item">      <mp-select-text value="默认的长按效果与浏览器一致"></mp-select-text>    </view>  </view></view>
          Page({  data: {    arr: [{      value: '长按,上侧复制',      placement: 'top'    },    {      value: '长按,右侧复制',      placement: 'right'    },    {      value: '长按,左侧复制',      placement: 'left'    },    {      value: '长按,下侧复制',      placement: 'bottom'    }]  },  handleTap(e) {    this.setData({ evt: e })  }})


          wxml-to-canvas

          小程序内通过静态模板和样式绘制 canvas ,导出图片,可用于生成分享图等场景。

          使用方法

          Step1. npm 安装

          npm install --save wxml-to-canvas

          Step2. JSON 组件声明

          {  "usingComponents": {    "wxml-to-canvas": "wxml-to-canvas",  }}

          Step3. wxml 引入组件

          <video class="video" src="{{src}}">  <wxml-to-canvas class="widget"></wxml-to-canvas></video><image src="{{src}}" style="width: {{width}}px; height: {{height}}px"></image>

          Step4. js 获取实例

          const {wxml, style} = require('./demo.js')Page({  data: {    src: ''  },  onLoad() {    this.widget = this.selectComponent('.widget')  },  renderToCanvas() {    const p1 = this.widget.renderToCanvas({ wxml, style })    p1.then((res) => {      this.container = res      this.extraImage()    })  },  extraImage() {    const p2 = this.widget.canvasToTempFilePath()    p2.then(res => {      this.setData({        src: res.tempFilePath,        width: this.container.layoutBox.width,        height: this.container.layoutBox.height      })    })  }})

          wxml 模板

          支持 view、text、image 三种标签,通过 class 匹配 style 对象中的样式。

          <view class="container" >  <view class="item-box red">  </view>  <view class="item-box green" >    <text class="text">yeah!</text>  </view>  <view class="item-box blue">      <image class="img" src="https://ss0.bdstatic.com/70cFvHSh_Q1YnxGkpoWK1HF6hhy/it/u=3582589792,4046843010&fm=26&gp=0.jpg" rel="external nofollow" ></image>  </view></view>

          样式

          对象属性值为对应 wxml 标签的 cass 驼峰形式。需为每个元素指定 width 和 height 属性,否则会导致布局错误。

          存在多个 className 时,位置靠后的优先级更高,子元素会继承父级元素的可继承属性。

          元素均为 flex 布局。left/top 等 仅在 absolute 定位下生效。

          const style = {  container: {    width: 300,    height: 200,    flexDirection: 'row',    justifyContent: 'space-around',    backgroundColor: '#ccc',    alignItems: 'center',  },  itemBox: {    width: 80,    height: 60,  },  red: {    backgroundColor: '#ff0000'  },  green: {    backgroundColor: '#00ff00'  },  blue: {    backgroundColor: '#0000ff'  },  text: {    width: 80,    height: 60,    textAlign: 'center',    verticalAlign: 'middle',  }}

          接口

          f1. renderToCanvas({wxml, style}): Promise

          渲染到 canvas,传入 wxml 模板 和 style 对象,返回的容器对象包含布局和样式信息。

          f2. canvasToTempFilePath({fileType, quality}): Promise

          提取画布中容器所在区域内容生成相同大小的图片,返回临时文件地址。

          fileType 支持 jpg、png 两种格式,quality 为图片的质量,目前仅对 jpg 有效。取值范围为 (0, 1],不在范围内时当作 1.0 处理。

          支持的 css 属性

          布局相关

          属性名支持的值或类型默认值
          widthnumber0
          heightnumber0
          positionrelative, absoluterelative
          leftnumber0
          topnumber0
          rightnumber0
          bottomnumber0
          marginnumber0
          paddingnumber0
          borderWidthnumber0
          borderRadiusnumber0
          flexDirectioncolumn, rowrow
          flexShrinknumber1
          flexGrownumber
          flexWrapwrap, nowrapnowrap
          justifyContentflex-start, center, flex-end, space-between, space-aroundflex-start
          alignItems, alignSelfflex-start, center, flex-end, stretchflex-start

          支持 marginLeft、paddingLeft 等

          文字

          属性名支持的值或类型默认值
          fontSizenumber14
          lineHeightnumber / string'1.4em'
          textAlignleft, center, rightleft
          verticalAligntop, middle, bottomtop
          colorstring#000000
          backgroundColorstringtransparent

          lineHeight 可取带 em 单位的字符串或数字类型。

          变形

          属性名支持的值或类型默认值
          scalenumber1


          computed

          小程序自定义组件扩展 behavior,计算属性 computed 和监听器 watch 的实现。在 data 或者 properties 改变时,会重新计算 computed 字段并触发 watch 监听器。

          此 behavior 依赖开发者工具的 npm 构建。具体详情可查阅官方 npm 文档。

          使用方法

          需要小程序基础库版本 >= 2.6.1 的环境。

          你可以直接体验一下这个代码片段,它包含了基本用法示例:https://developers.weixin.qq.com/s/gXK31mmZ73dd

          安装

          npm install --save miniprogram-computed

          computed 基本用法

          const computedBehavior = require('miniprogram-computed')Component({  behaviors: [computedBehavior],  data: {    a: 1,    b: 1,  },  computed: {    sum(data) {      // 注意: computed 函数中不能访问 this ,只有 data 对象可供访问      // 这个函数的返回值会被设置到 this.data.sum 字段中      return data.a + data.b    },  },  methods: {    onTap() {      this.setData({        a: this.data.b,        b: this.data.a + this.data.b,      })    }  }})
          <view>A = {{a}}</view><view>B = {{b}}</view><view>SUM = {{sum}}</view><button bindtap="onTap">click</button>

          watch 基本用法

          const computedBehavior = require('miniprogram-computed')Component({  behaviors: [computedBehavior],  data: {    a: 1,    b: 1,    sum: 2,  },  watch: {    'a, b': function(a, b) {      this.setData({        sum: a + b      })    },  },  methods: {    onTap() {      this.setData({        a: this.data.b,        b: this.data.a + this.data.b,      })    }  }})
          <view>A = {{a}}</view><view>B = {{b}}</view><view>SUM = {{sum}}</view><button bindtap="onTap">click</button>

          ^1.0.0 与 ^2.0.0 版本差异

          这个 behavior 的 ^1.0.0 版本和 ^2.0.0 版本有较大差异。 ^2.0.0 版本基于小程序基础库 2.6.1 开始支持的 observers 定义段实现,具有较好的性能。以下是版本之间主要区别的比较。

          项目^1.0.0^2.0.0
          支持的基础库最低版本2.2.32.6.1
          支持 watch 定义段
          性能相对较差相对较好

          常见问题说明

          我应该使用 computed 还是 watch ?

          从原理上说, watch 的性能比 computed 更好;但 computed 的用法更简洁干净。

          此外, computed 字段状态只能依赖于 data 和其他 computed 字段,不能访问 this 。如果不可避免要访问 this ,则必须使用 watch 代替。

          watch 和小程序基础库本身的 observers 有什么区别?

          • 无论字段是否真的改变, observers 都会被触发,而 watch 只在字段值改变了的时候触发,并且触发时带有参数。

          关于 ** 通配符

          在 watch 字段上可以使用 ** 通配符,是它能够监听这个字段下的子字段的变化(类似于小程序基础库本身的 observers)。示例代码片段

          const computedBehavior = require('miniprogram-computed')Component({  behaviors: [computedBehavior],  data: {    obj: {      a: 1,      b: 2,    }  },  watch: {    'obj.**': function(obj) {      this.setData({        sum: obj.a + obj.b      })    },  },  methods: {    onTap() {      this.setData({        'obj.a': 10      })    }  }})

          除此以外:

          • 对于没有使用 ** 通配符的字段,在 watch 检查值是否发生变化时,只会进行粗略的浅比较(使用 === );
          • 对于使用了 ** 通配符的字段,则会进行深比较,来尝试精确检测对象是否真的发生了变化,这要求对象字段不能包含循环(类似于 JSON.stringify )。


          小程序的 MobX 绑定辅助库

          小程序的 MobX 绑定辅助库。

          此 behavior 依赖开发者工具的 npm 构建。具体详情可查阅 官方 npm 文档 。
          可配合 MobX 的小程序构建版 npm 模块 mobx-miniprogram 使用。

          使用方法

          需要小程序基础库版本 >= 2.2.3 的环境。

          也可以直接参考这个代码片段(在微信开发者工具中打开): https://developers.weixin.qq.com/s/36j8NZmC74ac 。

          1. 安装 mobx-miniprogram 和 mobx-miniprogram-bindings :
          npm install --save mobx-miniprogram mobx-miniprogram-bindings
          1. 创建 MobX Store。
          // store.jsimport { observable, action } from 'mobx-miniprogram'export const store = observable({  // 数据字段  numA: 1,  numB: 2,  // 计算属性  get sum() {    return this.numA + this.numB  },  // actions  update: action(function () {    const sum = this.sum    this.numA = this.numB    this.numB = sum  })})
          1. 在 Component 构造器中使用:
          import { storeBindingsBehavior } from 'mobx-miniprogram-bindings'import { store } from './store'Component({  behaviors: [storeBindingsBehavior],  data: {    someData: '...'  },  storeBindings: {    store,    fields: {      numA: () => store.numA,      numB: (store) => store.numB,      sum: 'sum'    },    actions: {      buttonTap: 'update'    },  },  methods: {    myMethod() {      this.data.sum // 来自于 MobX store 的字段    }  }})
          1. 在 Page 构造器中使用:
          import { createStoreBindings } from 'mobx-miniprogram-bindings'import { store } from './store'Page({  data: {    someData: '...'  },  onLoad() {    this.storeBindings = createStoreBindings(this, {      store,      fields: ['numA', 'numB', 'sum'],      actions: ['update'],    })  },  onUnload() {    this.storeBindings.destroyStoreBindings()  },  myMethod() {    this.data.sum // 来自于 MobX store 的字段  }})

          接口

          将页面、自定义组件和 store 绑定有两种方式: behavior 绑定 和 手工绑定 。

          behavior 绑定

          behavior 绑定 适用于 Component 构造器。做法:使用 storeBindingsBehavior 这个 behavior 和 storeBindings 定义段。

          注意:你可以用 Component 构造器构造页面, 参考文档 。

          import { storeBindingsBehavior } from 'mobx-miniprogram-bindings'Component({  behaviors: [storeBindingsBehavior],  storeBindings: {    /* 绑定配置(见下文) */  }})

          手工绑定

          手工绑定 适用于全部场景。做法:使用 createStoreBindings 创建绑定,它会返回一个包含清理函数的对象用于取消绑定。

          注意:在页面 onUnload (自定义组件 detached )时一定要调用清理函数,否则将导致内存泄漏!

          import { createStoreBindings } from 'mobx-miniprogram-bindings'Page({  onLoad() {    this.storeBindings = createStoreBindings(this, {      /* 绑定配置(见下文) */    })  },  onUnload() {    this.storeBindings.destroyStoreBindings()  }})

          绑定配置

          无论使用哪种绑定方式,都必须提供一个绑定配置对象。这个对象包含的字段如下:

          字段名类型含义
          store一个 MobX observable默认的 MobX store
          fields数组或者对象用于指定需要绑定的 data 字段
          actions数组或者对象用于指定需要映射的 actions

          fields

          fields 有三种形式:

          • 数组形式:指定 data 中哪些字段来源于 store 。例如 ['numA', 'numB', 'sum'] 。
          • 映射形式:指定 data 中哪些字段来源于 store 以及它们在 store 中对应的名字。例如 { a: 'numA', b: 'numB' } ,此时 this.data.a === store.numA this.data.b === store.numB 。
          • 函数形式:指定 data 中每个字段的计算方法。例如 { a: () => store.numA, b: () => anotherStore.numB } ,此时 this.data.a === store.numA this.data.b === anotherStore.numB 。

          上述三种形式中,映射形式和函数形式可以在一个配置中同时使用。

          如果仅使用了函数形式,那么 store 字段可以为空,否则 store 字段必填。

          actions

          actions 可以用于将 store 中的一些 actions 放入页面或自定义组件的 this 下,来方便触发一些 actions 。有两种形式:

          • 数组形式:例如 ['update'] ,此时 this.update === store.update 。
          • 映射形式:例如 { buttonTap: 'update' } ,此时 this.buttonTap === store.update 。

          只要 actions 不为空,则 store 字段必填。

          延迟更新与立刻更新

          为了提升性能,在 store 中的字段被更新后,并不会立刻同步更新到 this.data 上,而是等到下个 wx.nextTick 调用时才更新。(这样可以显著减少 setData 的调用次数。)

          如果需要立刻更新,可以调用:

          • this.updateStoreBindings() (在 behavior 绑定 中)
          • this.storeBindings.updateStoreBindings() (在 手工绑定 中)


          小程序瘦身工具

          通过剔除无用文件、压缩图片、复用代码等方式减少小程序代码包体积。开源项目地址:https://github.com/wechat-miniprogram/miniprogram-slim

          安装

          npm install -g miniprogram-slim

          使用

          Usage: miniprogram-slim <command>Options:  -v, --version                  output the version number  -h, --help                     output usage informationCommands:  cpd [options] <dir>            Detect duplications in source code  sprite [options] <input...>    Covert images into css sprites  imagemin [options] <input...>  Minify images seamlessly  analyzer [options]             Analyze dependencies of miniprogram, find out unused filesExamples:  $ miniprogram-slim analyzer -t  $ miniprogram-slim cpd src  $ miniprogram-slim imagemin images/**/*.png  $ miniprogram-slim sprite -f emoji images/**/*.png


          微信小程序定义文件

          微信小程序 API 的 TypeScript 类型定义文件

          安装

          通过 npm 安装:

          # 安装对应最新基础库的定义文件npm install miniprogram-api-typings

          或者通过版本号指定一个基础库版本:

          # 安装对应基础库版本 2.4.1 的定义文件npm install miniprogram-api-typings@2.4.1

          版本

          基础库版本npm 版本命令
          v2.6.52.6.5-2npm install miniprogram-api-typings@2.6.5-2
          v2.4.22.4.2-2npm install miniprogram-api-typings@2.4.2-2
          v2.4.12.4.1npm install miniprogram-api-typings@2.4.1
          v2.4.02.4.0-1npm install miniprogram-api-typings@2.4.0-1

          贡献

          定义文件是随 文档 一起自动生成的,所以所有的 PR 都将 不会 被接受。如果您有 bug 反馈或建议,请提一个 issue 给我们。非常感谢!


          API Promise化

          扩展微信小程序api支持promise

          安装

          npm install --save miniprogram-api-promise

          使用

          在小程序入口(app.js)调用一次promisifyAll,只需要调用一次。

          示例:

          import { promisifyAll, promisify } from 'miniprogram-api-promise';const wxp = {}// promisify all wx's apipromisifyAll(wx, wxp)console.log(wxp.getSystemInfoSync())wxp.getSystemInfo().then(console.log)wxp.showModal().then(wxp.openSetting())// compatible usagewxp.getSystemInfo({success(res) {console.log(res)}})// promisify single apipromisify(wx.getSystemInfo)().then(console.log)


          threejs-miniprogram

          Three.js 小程序 WebGL 的适配版本。

          使用

          可参考 example 目录下的示例项目或参照以下流程:

          1. 通过 npm 安装
          npm install --save threejs-miniprogram

          安装完成之后在微信开发者工具中点击构建 npm。

          1. 导入小程序适配版本的 Three.js
          import {createScopedThreejs} from 'threejs-miniprogram'Page({  onReady() {    wx.createSelectorQuery()      .select('#webgl')      .node()      .exec((res) => {        const canvas = res[0].node        // 创建一个与 canvas 绑定的 three.js        const THREE = createScopedThreejs(canvas)        // 传递并使用 THREE 变量      })  }})

          说明

          • 本项目当前使用的 Three.js 版本号为 0.108.0,如要更新 threejs 版本可发 PR 修改或 fork 后自行修改。
          • 该适配版本的 THREE 不在全局环境中,如使用 Three.js 的其他配套类库,需要自行传入 THREE 到类库中。
          • 如在使用过程中发现有适配问题,可通过 issue 反馈或发 PR 修复。


          lottie-miniprogram

          lottie 动画库适配小程序的版本。

          lottie 的相关介绍与动画生成方法等请参考 官方说明
          依赖小程序基础库版本 >= 2.8.0 的环境

          使用

          可参考该代码片段:https://developers.weixin.qq.com/s/2TYvm9mJ75bF。大致步骤如下:

          1. 通过 npm 安装:
          npm install --save lottie-miniprogram
          1. 传入 canvas 对象用于适配
          <canvas id="canvas" type="2d"></canvas>
          import lottie from 'lottie-miniprogram'Page({  onReady() {    wx.createSelectorQuery().select('#canvas').node(res => {      const canvas = res.node      lottie.setup(canvas)    }).exec()  }})
          1. 使用 lottie 接口
          lottie.setup(canvas)lottie.loadAnimation({  ...})

          接口

          目前提供两个接口:

          lottie.setup(canvas)

          需要在任何 lottie 接口调用之前调用,传入 canvas 对象

          lottie.loadAnimation(options)

          与原来的 loadAnimation 有些不同,支持的参数有:

          • loop
          • autoplay
          • animationData
          • path (只支持网络地址)
          • rendererSettings.context (必填)

          说明

          • 本项目是以 npm 的方式依赖原 lottie-web 项目,若原项目有新版本,可直接改变依赖的版本号。
          • 本项目依赖小程序基础库 2.8.0 里性能更好的 canvas 实现,由于还有些小问题没有正式开放,但目前用在此处暂无发现问题。
          • 由于小程序本身不支持动态执行脚本,因此 lottie 的 expression 功能也是不支持的。


          sm-crypto

          小程序 js 库。国密算法 sm2、sm3 和 sm4 的实现。

          使用此组件需要依赖小程序基础库 2.2.1 以上版本,同时依赖开发者工具的 npm 构建。具体详情可查阅官方 npm 文档。

          安装

          npm install --save miniprogram-sm-crypto

          sm2

          获取密钥对

          const sm2 = require('miniprogram-sm-crypto').sm2;let keypair = sm2.generateKeyPairHex();publicKey = keypair.publicKey; // 公钥privateKey = keypair.privateKey; // 私钥

          加密解密

          const sm2 = require('miniprogram-sm-crypto').sm2;const cipherMode = 1; // 1 - C1C3C2,0 - C1C2C3,默认为1let encryptData = sm2.doEncrypt(msgString, publicKey, cipherMode); // 加密结果let decryptData = sm2.doDecrypt(encryptData, privateKey, cipherMode); // 解密结果

          签名验签

          ps:理论上来说,只做纯签名是最快的。
          const sm2 = require('miniprogram-sm-crypto').sm2;// 纯签名 + 生成椭圆曲线点let sigValueHex = sm2.doSignature(msg, privateKey); // 签名let verifyResult = sm2.doVerifySignature(msg, sigValueHex, publicKey); // 验签结果// 纯签名let sigValueHex2 = sm2.doSignature(msg, privateKey, {    pointPool: [sm2.getPoint(), sm2.getPoint(), sm2.getPoint(), sm2.getPoint()], // 传入事先已生成好的椭圆曲线点,可加快签名速度}); // 签名let verifyResult2 = sm2.doVerifySignature(msg, sigValueHex2, publicKey); // 验签结果// 纯签名 + 生成椭圆曲线点 + der编解码let sigValueHex3 = sm2.doSignature(msg, privateKey, {    der: true,}); // 签名let verifyResult3 = sm2.doVerifySignature(msg, sigValueHex3, publicKey, {    der: true,}); // 验签结果// 纯签名 + 生成椭圆曲线点 + sm3杂凑let sigValueHex4 = sm2.doSignature(msg, privateKey, {    hash: true,}); // 签名let verifyResult4 = sm2.doVerifySignature(msg, sigValueHex4, publicKey, {    hash: true,}); // 验签结果// 纯签名 + 生成椭圆曲线点 + sm3杂凑(不做公钥推导)let sigValueHex5 = sm2.doSignature(msg, privateKey, {    hash: true,    publicKey, // 传入公钥的话,可以去掉sm3杂凑中推导公钥的过程,速度会比纯签名 + 生成椭圆曲线点 + sm3杂凑快});let verifyResult5 = sm2.doVerifySignature(msg, sigValueHex5, publicKey, {    hash: true,    publicKey,});

          获取椭圆曲线点

          const sm2 = require('miniprogram-sm-crypto').sm2;let poin = sm2.getPoint(); // 获取一个椭圆曲线点,可在sm2签名时传入

          sm3

          const sm3 = require('miniprogram-sm-crypto').sm3;let hashData = sm3('abc'); // 杂凑

          sm4

          加密

          const sm4 = require('miniprogram-sm-crypto').sm4;const key = [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10];let encryptData = sm4.encrypt([0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10], key); // 加密

          解密

          const sm4 = require('miniprogram-sm-crypto').sm4;const key = [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10];let decryptData = sm4.decrypt([0x68, 0x1e, 0xdf, 0x34, 0xd2, 0x06, 0x96, 0x5e, 0x86, 0xb3, 0xe9, 0x4f, 0x53, 0x6e, 0x42, 0x46], 

          国密算法实现实例:详情


          快速入门

          概览

          miniprogram-i18n 的用法主要分为四部分。分别是:构建脚本与i18配置、i18n文本定义、WXML中的用法及JavaScript中的用法。

          安装

          该方案目前需要依赖 Gulp 并且对源文件目录结构有一定的要求,需要确保小程序源文件放置在特定目录下(例如 src/ 目录)。

          1. 首先在项目根目录运行以下命令安装 gulp 及 miniprogram-i18n 的 gulp 插件。
          npm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml
          1. 在小程序运行环境下安装国际化运行时并在开发工具"构建npm"。
          npm i -S @miniprogram-i18n/core
          1. 在项目根目录新建 gulpfile.js,并编写构建脚本,可参考 examples/gulpfile.js。
          更多 Gulp 相关配置请参考 Gulp插件配置文档。

          使用

          i18n文本定义

          miniprogram-i18n 目前采用 JSON 文件对 i18n 文本进行定义。使用之前,需要在项目源文件下新建 i18n 目录。

          目录结构如下:

          ├── dist               // 小程序构建目录├── gulpfile.js├── node_modules├── package.json└── src                // 小程序源文件目录|   ├── app.js|   ├── app.json|   ├── app.wxss|   ├── i18n           // 国际化文本目录|   |   ├── en-US.json|   |   └── zh-CN.json

          i18n 目录可以放置在源文件目录下的任意位置,例如可以跟 Page 或 Component 放在一起。但是需要注意的是,多个 i18n 目录下的文件在构建时会被合并打包,因此如果翻译文本有重复的 key 可能会发生覆盖。如果分开多个 i18n 目录定义需要自行确保 key 是全局唯一的。例如使用 page.index.testKey 这样的能确保唯一的名称。

          下面我们定义文本:

          // i18n/en-US.json{  "plainText": "This is a plain text",  "withParams": "{value} is what you pass in"}
          // i18n/zh-CN.json{  "plainText": "这是一段纯文本",  "withParams": "你传入的值是{value}"}

          WXML 中的用法

          定义好 i18n 文本之后,就可以在 WXML 文件里使用了。首先,需要在 WXML 文件对应的 JavaScript 文件里引入国际化运行时。

          // pages/index/index.jsimport { I18n } from '@miniprogram-i18n/core'Component({  behaviors: [I18n]})
          注意:这里建议 Page 以及 Component 都采用 Component 构造器进行定义,这样可以使用 I18n 这个 Behavior。如果需要在 Page 构造上使用 I18n 则需要引入 I18nPage 代替 Page 构造器。

          接着可以在 WXML 文件中获取预先定义好的 i18n 文本。

          <!-- pages/index/index.wxml --><view>{{ t('plainText') }}</view><input placeholder="{{ t('withParams', {value}) }}"></input>

          在 WXML 中使用 t 函数(或其他你指定的函数名)来获取文本。 t函数签名如下:

          t(key: string, params: object)

          它可以接受两个参数,第一个参数是 i18n 文本的 key,第二个参数是需要传入的插值对象(可以是从 AppService 传过来的值)。

          JavaScript 中的用法

          在 JavaScript 里可以直接引用 @miniprogram-i18n/core 这个 NPM 包来获取翻译文本。

          import { getI18nInstance } from '@miniprogram-i18n/core'const i18n = getI18nInstance()Component({  attached() {    const text = i18n.t('withParams', { value: 'Test' })    console.log(text)    // Test is what you pass in    i18n.setLocale('en-US')  }})

          同样的,在 i18n 实例上,还暴露了其他一些接口,例如获取当前语言、动态设置当前语言等。具体接口请参考 接口文档。

          如果你的 JavaScript 对应的 WXML 里已经使用了国际化文本,换言之,即 Component 构造器已经引入了 I18n Behavior,那么所有的实例方法都会被直接挂载到 this 上,你可以通过 this 调用它们。

          import { I18n } from '@miniprogram-i18n/core'Component({  behaviors: [I18n],  attached() {    const text = this.t('withParams', { value: 'Test' })    console.log(text)    // Test is what you pass in    this.setLocale('en-US')  }})

          构建

          在编写完 i18n 文本并在 WXML 或 JavaScript 中调用之后,你需要运行 gulp 命令对 .wxml 文件进行转译并对 i18n 文本进行打包合并。

          特性

          目前 miniprogram-i18n 仅支持纯文本及文本插值,后续会对其他 i18n 特性进行支持。

          文本插值

          {  "key": "Inserted value: {value}"}
          i18n.t('key', { value: 'Hello!' })  // Inserted value: Hello!

          为了方便调用深层嵌套的对象,当前支持使用 . 点语法来访问对象属性。

          {   "dotted": "Nested value is: { obj.nested.value }"}
          const value = {  obj: {    nested: {      value: 'Catch you!'    }  }}i18n.t('dotted', value)  // Nested value is: Catch you!

          select 语句

          {  "key": "{gender, select, male {His inbox} female {Her inbox} other {Their inbox}}"}
          i18n.t('key', { gender: 'male' })    // His inboxi18n.t('key', { gender: 'female' })  // Her inboxi18n.t('key')                        // Their inbox

          select 语句支持子语句文本插值:

          {  "key": "{mood, select, good {{how} day!} sad {{how} day.} other {Whatever!}}"}
          i18n.t('key', { mood: 'good', how: 'Awesome'  })  // Awesome day!i18n.t('key', { mood: 'sad', how: 'Unhappy'  })   // Unhappy day.i18n.t('key')                                     // Whatever!
          注:select 语句支持子句嵌套 select 语句

          其他尚未支持的特性有:

          • Pseudo 字符串
          • 单复数处理
          • 日期、数字、货币处理
          • 定义文件的命名空间
          • 支持 WXML 与 JavaScript 独立定义

          接口文档

          miniprogram-i18n API 是运行时在 JavaScript 侧操作 i18n 的接口。

          接口列表

          • initI18n(localesConfig: object): I18n
          • getI18nInstance(): I18n
          • t(key: string, params: object): string
          • getLocale(): string
          • setLocale(currentLocale: string): void
          • getFallbackLocale(): string
          • onLocaleChange(handler: (currentLocale: string) => void): object

          初始化 I18n 运行时

          initI18n(localesConfig: object): I18n

          在 app.js 调用 initI18n 来加载 i18n 文本并指定默认语言。若未进行指定,i18n运行时将默认从 /i18n/locales.js 中读取文本及配置。

          // src/app.jsimport { initI18n } from '@miniprogram-i18n/core'import locales from '/i18n/locales.js'initI18n(locales)App({})

          获取 I18n 运行时

          getI18nInstance(): I18n

          该接口会返回 I18n 运行时实例。

          import { getI18nInstance } from '@miniprogram-i18n/core'const i18n = getI18nInstance()i18n.t('key')

          I18n 接口

          以下五个接口用来获取或操作 I18n,均可在 I18n 实例或 拥有 I18n Behavior 的组件或 I18nPage 上进行调用。 通过组件直接访问成员函数:

          import { I18n } from '@miniprogram-i18n/core'Component({  behaviors: [I18n],  attached() {    this.t('key')    this.getLocale()  // en-US    this.setLocale('zh-CN')    this.getFallbackLocale()  // zh-CN    this.onLocaleChange((currentLocale) => {      console.log('Locale changed to', currentLocale)    })  }})

          或从 I18n 实例调用:

          import { I18n } from '@miniprogram-i18n/core'const i18n = getI18nInstance()i18n.t('key')i18n.getLocale()  // en-USi18n.setLocale('zh-CN')i18n.getFallbackLocale()  // zh-CNi18n.onLocaleChange((currentLocale) => {  console.log('Locale changed to', currentLocale)})

          t(key: string, params: object): string

          最主要的翻译函数,通过该函数可以获得预先定义的 i18n 文本。

          getLocale(): string

          获取当前设置的语言。默认语言应在 gulp 构建脚本中配置,详见 Gulp插件配置文档。

          setLocale(currentLocale: string): void

          设置当前语言。该值应与 i18n 定义文件名相对应。

          getFallbackLocale(): string

          获取备选语言。该值在构建脚本中进行配置,一旦设置之后无法在运行时通过接口修改。详见 Gulp插件配置文档。

          onLocaleChange(handler: (currentLocale: string) => void): object

          当前语言被修改时触发的事件回调。返回值 object,可通过返回值对象取消事件监听。

          const event = i18n.onLocaleChange(() => {})event.off()

          Gulp 插件配置文档

          miniprogram-i18n 在构建阶段依赖两个 Gulp 插件,分别是 @miniprogram-i18n/gulp-i18n-wxml 和 @miniprogram-i18n/gulp-i18n-locales,gulp-i18n-wxml 负责转译 wxml 文件中的 i18n 自定义语法,gulp-i18n-locales 则负责合并 i18n 定义文件,并进行预处理生成运行时所需的文件。

          若使用 CLI 进行构建,则可忽略 Gulp 构建的配置。

          安装

          因此在使用 i18n 的构建插件之前,需要先安装相关依赖。

          npm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml

          依赖安装完成之后,需要建立 gulp 所需的配置并引入 i18n 构建插件。示例如下:

          const gulpWxmlTransformer = require('@miniprogram-i18n/gulp-i18n-wxml')const gulpLocalesLoader = require('@miniprogram-i18n/gulp-i18n-locales')function transpileWxml() {  return src('src/**/*.wxml')    .pipe(gulpWxmlTransformer())    .pipe(dest('dist/'))}function mergeAndGenerateLocales() {  return src('src/**/i18n/*.json')    .pipe(gulpLocalesLoader({ defaultLocale: 'zh-CN', fallbackLocale: 'zh-CN' }))    .pipe(dest('dist/i18n/'))}

          更详细的配置请参考 examples。

          gulp-i18n-wxml 配置

          该构建函数支持如下参数:

          interface Options {  wxsPath: string,  wxsModuleName?: string,  i18nFunctionName?: string,}
          • wxsPath指定 locales.wxs 所在路径,应与 gulp-i18n-locales 中的配置一致,默认为 src/i18n/locales.wxs。
          • wxsModuleName指定 wxs 模块名称,默认为 i18n。
          • i18nFunctionName指定 wxml 中的 i18n 函数名,默认为t,可修改为任意合法的函数名。

          gulp-i18n-locales 配置

          该构建函数支持如下参数:

          interface Options {  wxsFileName?: string  jsFileName?: string  defaultLocale?: string  fallbackLocale?: string}
          • wxsFileName指定 locales wxs 文件名,需以 .wxs 作为后缀,默认为 locales.wxs。
          • jsFileName指定 locales js 文件名,需以 .js 作为后缀,默认为locales.js。
          • defaultLocale指定默认语言,默认为 en-US。该值需与 i18n 定义文件名对应。
          • fallbackLocale指定备选语言,默认为 en-US。该值需与 i18n 定义文件名对应。在运行时无法找到对应语言下的文本时,会从备选语言中进行查找。注:该值无法在运行进行修改。


          微信同声传译

          微信同声传译插件是微信自研的语音输入,文本翻译等功能的插件封装,用于提供给第三方小程序调用。

          体验入口

          语音输入

          提供语音的实时流式识别能力。 通过获取全局唯一的语音识别管理器recordRecoManager实现

          recordRecoManager

          recordRecoManager 对象的方法列表:

          方法参数说明
          startoptions开始识别
          stop结束识别
          onStartcallback正常开始录音识别时会调用此事件
          onRecognizecallback有新的识别内容返回,则会调用此事件
          onStopcallback识别结束事件
          onErrorcallback识别错误事件

          start(options)说明:

          属性类型必填默认值说明
          durationNumber60000指定录音的时长,单位ms,最大为60000。如果传入了合法的 duration ,在到达指定的 duration 后会自动停止录音
          langStringzh_CN识别的语言,目前支持zh_CN en_US zh_HK sichuanhua

          onStart(callback)回调结果说明:

          属性类型说明
          msgString默认Ok

          onStop(callback)回调结果说明:

          属性类型说明
          tempFilePathString录音临时文件地址
          durationNumber录音总时长,单位: ms
          fileSizeNumber文件大小,单位: B
          resultString最终识别结果

          onError(callback)回调结果说明:

          属性类型说明
          retcodeInt错误码
          msgString错误信息

          onRecognize(callback)回调结果说明:

          属性类型说明
          resultString识别结果

          onError错误码说明:

          错误码说明
          -30001录音接口出错
          -30002录音暂停接口被调用,录音终止,识别终止
          -30003录音帧数据未产生或者发送失败导致的数据传输失败
          -30004因网络或者其他非正常状态导致的未查询识别结果
          -30005语音识别服务内部错误
          -30006语音识别服务未在限定时间内识别完成
          -30007start启动参数错误
          -30008查询请求时网络失败
          -30009创建鉴权内部失败
          -30010发送鉴权时网络失败
          -30011试图在识别正在进行中是再次调用start,返回错误,正在进行的识别任务正常进行
          -30012当前无识别任务进行时调用stop错误
          -30013其他未知错误
          -40001达到接口调用频率限制

          示例代码:

          //app.json{  ...  "plugins": {    ...    "WechatSI": {      "version": "0.0.7",      "provider": "wx069ba97219f66d99"        }  }}//index.jsvar plugin = requirePlugin("WechatSI")let manager = plugin.getRecordRecognitionManager()manager.onRecognize = function(res) {    console.log("current result", res.result)}manager.onStop = function(res) {    console.log("record file path", res.tempFilePath)    console.log("result", res.result)}manager.onStart = function(res) {    console.log("成功开始录音识别", res)}manager.onError = function(res) {    console.error("error msg", res.msg)}manager.start({duration:30000, lang: "zh_CN"})

          文本翻译

          文本翻译目前支持的语言有 zh_CN(中国大陆)  en_US(英语)

          translate(OBJECT)

          translate(object)说明:

          参数名类型必填说明
          lfromString文本语言 zh_CN(中国大陆)   en_US(英语)
          ltoString目标语言 zh_CN(中国大陆)  en_US(英语)
          contentString需要被翻译的文本内容,后台限制1000字节大小
          ttsBoolean是否对翻译结果进行语音合成,默认为false,不进行语音合成
          successFunction调用成功时触发的callback
          failFunction调用失败时触发的callback
          completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

          success(callback)回调结果说明

          属性类型说明
          retcodeIntretcode == 0 时翻译成功
          originString原始文本
          resultString翻译结果
          filenameString语音合成返回的语音地址,仅支持合成中文语音
          expired_timeInt语音合成链接超时时间戳 如1525930552超时后无法播放,可使用时间为3小时

          success返回码说明: 翻译成功,合成失败时调用success回调

          状态码说明
          0翻译合成成功
          -10006翻译成功,合成内部错误
          -10007翻译成功,传入了不支持的语音合成语言
          -10008翻译成功,语音合成达到频率限制

          fail(callback)回调结果说明

          属性类型说明
          retcodeInt错误码
          msgString错误信息

          fail错误码说明:

          错误码说明
          -10001语言检查错误
          -10002输入的待翻译内容格式不正确
          -10003传入过长的待翻译文本内容
          -10004翻译内部逻辑错误
          -10005请求发送失败,请检查网络
          -40001接口调用频率达到限制,请联系插件开发者

          示例代码

          plugin.translate({  lfrom:"en_US",  lto:"zh_CN",  content:"hello, this is the first time to test?",  success: function(res) {    if(res.retcode == 0) {      console.log("result", res.result)    } else {      console.warn("翻译失败", res)    }  },  fail: function(res) {    console.log("网络失败",res)  }})

          语音合成

          语音合成支持的语言有 zh_CN(中国大陆),en_US(英文)

          textToSpeech(OBJECT)

          textToSpeech(object)说明:

          参数名类型必填说明
          langString文本语言 zh_CN(中国大陆)en_US(英文)
          contentString需要被翻译的文本内容,后台限制1000字节大小
          successFunction调用成功时触发的callback
          failFunction调用失败时触发的callback

          success(callback)回调结果说明

          属性类型说明
          retcodeIntretcode == 0 时请求成功
          originString原始文本
          filenameString语音合成返回的语音地址,可自行下载使用
          expired_timeInt语音合成链接超时时间戳 如1525930552,超时后无法播放,可使用时间为3小时

          success返回码说明:

          状态码说明
          0语音合成成功

          fail(callback)回调结果说明

          属性类型说明
          retcodeInt错误码
          msgString错误信息

          fail错误码说明:

          错误码说明
          -20001语音合成语言格式出错
          -20002输入的待合成格式不正确
          -20003语音合成内部错误
          -20005网络错误
          -40001接口调用频率达到限制,请联系插件开发者

          示例代码

          plugin.textToSpeech({    lang: "zh_CN",    tts: true,    content: "一个常见的需求",    success: function(res) {        console.log("succ tts", res.filename)       },    fail: function(res) {        console.log("fail tts", res)    }})

          版本要求

          基础库版本 >= 1.9.94

          • 使用插件,需要基础库版本 >= 1.9.6
          • 插件内调用wx.getRecorderManager接口,需要基础库版本 >= 1.9.94

          配额说明

          由于资源限制,当前各个接口调用存在配额限制,如业务有特殊更多需求,请邮箱联系roytianzou@tencent.com申请,邮件配额模版如下。 语音输入配额:每个小程序250条/分钟,3w条/天。 文本翻译配额:每个小程序500次/分钟,10w次/天。 语音合成配额:每个小程序100次/分钟,2w次/天。

          配额申请模版

          公司简介:(个人则填写个人)

          小程序简介:

          小程序appid:

          申请接口名:

          当前用户量:(当前未上线可填无)

          当前调用量:(当前未上线可填无)

          申请配额: xx 次/分钟, xx次/天。

          合理的配额推导(请提供使用场景,预期用户量,用户使用频率,高峰时段,平均时长/字数):


          OCR 支持

          查看本文档前,建议先阅读《小程序插件文档》 体验工具小程序 —— 该插件完全使用此插件实现。该插件支持身份证识别,行驶证识别和银行卡识别。 小程序码 

          申请权限

          • 请在小程序后台搜索本插件(AppID=wx4418e3e031e551be) 设置-第三方服务-添加插件

          调用限制

          • 来开放社区购买,appid内的额度在插件、API、服务市场是通用的

          调用方式

          app.json中增加声明引入插件 version选择最新的

            "pages": [],  "plugins": {    "ocr-plugin": {      "version": "3.0.2",      "provider": "wx4418e3e031e551be"    }  }}

          页面的json也要增加声明

          {  "usingComponents": {    "ocr-navigator": "plugin://ocr-plugin/ocr-navigator"  }}

          组件

          对外暴露自定义组件,UI载体为button(可样式自定义) 封装了

          参数

          属性名类型默认值是否必填说明
          onSuccessHandleEvent接口调用成功的回调函数
          certificateTypeStringidCard证书类型包含四种 身份证:idCard、驾驶证:drivingLicense、银行卡:bankCard、营业执照:businessLicense

          返回结果中image_path 是用户证件照片的临时地址,开发者可以通过image_path拿到用户的证件照片

          以下具体说明四种证件类型的使用方法

          1、身份证

          certificateType='idCard' 或 无certificateType这个参数

          属性名类型默认值是否必填说明
          onSuccessHandleEvent接口调用成功的回调函数
          certificateTypeStringidCard证书类型包含四种 身份证:idCard、驾驶证:drivingLicense、银行卡:bankCard、营业执照:businessLicense
          oppositeBooleantrue是否显示身份证的反面,默认为 true显示反面

          onSuccess

          参数 e.detail

          参考身份证返回结果实例

          示例代码1

              <ocr-navigator bind:onSuccess="success" certificateType="idCard" opposite="{{false}}">      <button type="primary">身份证正面识别</button>    </ocr-navigator>    <ocr-navigator bind:onSuccess="success" certificateType="idCard" opposite="{{true}}">      <button type="primary">身份证反面识别</button>    </ocr-navigator>
          /** wxss **//*自定义按钮样式*/.ocr-wrapper {  margin: 40rpx auto;  width: 375rpx;}.intro {  margin: 40rpx;}

          身份证返回结果实例

          {"type":0,"name":{"text":"张三","pos":{"left_top":{"x":98.7780914307,"y":40.9823074341},"right_top":{"x":172.311325073,"y":41.2864379883},"right_bottom":{"x":172.190856934,"y":64.9047088623},"left_bottom":{"x":98.6072158813,"y":64.5630187988}},"label":[]},"gender":{"text":"男","pos":{"left_top":{"x":101.035919189,"y":80.7537384033},"right_top":{"x":121.421043396,"y":80.7818603516},"right_bottom":{"x":121.264938354,"y":101.272567749},"left_bottom":{"x":100.882026672,"y":101.244766235}},"label":[]},"nationality":{"text":"汉","pos":{"left_top":{"x":201.881393433,"y":81.7225189209},"right_top":{"x":222.004470825,"y":81.6959762573},"right_bottom":{"x":221.899169922,"y":101.255821228},"left_bottom":{"x":201.765304565,"y":101.291915894}},"label":[]},"address":{"text":"广州市天河区五山路483号xxxxxxxxx","pos":{"left_top":{"x":95.5787811279,"y":150.794250488},"right_top":{"x":310.358947754,"y":151.617507935},"right_bottom":{"x":310.004699707,"y":220.222885132},"left_bottom":{"x":95.1295013428,"y":219.552230835}},"label":[]},"id":{"text":"4452xxxxxxxxxxxx","pos":{"left_top":{"x":176.158676147,"y":244.072860718},"right_top":{"x":453.888336182,"y":244.978515625},"right_bottom":{"x":453.874603271,"y":266.313659668},"left_bottom":{"x":176.066543579,"y":265.342407227}},"label":[]},"card_position":{"pos":{"left_top":{"x":1085.625,"y":621.75},"right_top":{"x":338.125,"y":594.75},"right_bottom":{"x":303.625,"y":99.75},"left_bottom":{"x":1189.125,"y":126.75}},"label":[]},"image_width":1280,"image_height":960,"image_path":"http://tmp/wx4418e3e031e551be.o6zAJs-yC5ByIjnyyy09jKDZquXk.dlrc7P7WlhnGb4aca86b078fc2acb5b08e7a0f438943.jpg"}

          2、银行卡

          certificateType='bankCard'

          属性名类型默认值是否必填说明
          onSuccessHandleEvent接口调用成功的回调函数
          certificateTypeStringbankCard证书类型包含四种 身份证:idCard、驾驶证:drivingLicense、银行卡:bankCard、营业执照:businessLicense

          onSuccess

          参数 e.detail

          参考银行卡返回结果实例

          示例代码1

          <ocr-navigator bind:onSuccess="blankSuccess"  certificateType="bankCard">  <button type="primary">银行卡识别</button></ocr-navigator>
          /** wxss **//*自定义按钮样式*/.ocr-wrapper {  margin: 40rpx auto;  width: 375rpx;}.intro {  margin: 40rpx;}

          银行卡返回结果实例

          {"number":{"text":"6225xxxxxxxxxxxx","label":[]},"card_position":{"pos":{"left_top":{"x":2.19140625,"y":227.6171875},"right_top":{"x":729.50390625,"y":206.0546875},"right_bottom":{"x":769.91015625,"y":658.8671875},"left_bottom":{"x":-11.27734375,"y":680.4296875}},"label":[]},"image_width":762,"image_height":1280,"image_path":"http://tmp/wx4418e3e031e551be.o6zAJs-yC5ByIjnyyy09jKDZquXk.dlrc7P7WlhnGb4aca86b078fc2acb5b08e7a0f438943.jpg"}

          银行卡返回结果

          银行卡只支持横版储蓄卡,信用卡,并且只能识别出银行卡号,如果需要银行卡名称、过期时间需要用户手动输入

          3、行驶证

          certificateType='drivingLicense'

          属性名类型默认值是否必填说明
          onSuccessHandleEvent接口调用成功的回调函数
          certificateTypeStringdrivingLicense证书类型包含四种 身份证:idCard、驾驶证:drivingLicense、银行卡:bankCard、营业执照:businessLicense

          onSuccess

          参数 e.detail

          参考行驶证返回结果实例

          示例代码1

          <ocr-navigator bind:onSuccess="driverSuccess" certificateType="drivingLicense" selectedOptions="{{['plateNum','vehicleType','owner']}}">  <button type="primary">行驶证识别</button></ocr-navigator>
          /** wxss **//*自定义按钮样式*/.ocr-wrapper {  margin: 40rpx auto;  width: 375rpx;}.intro {  margin: 40rpx;}

          行驶证返回结果实例

          {"plate_num":{"text":"粤KDxxxx","label":[]},"vehicle_type":{"text":"小型轿车","label":[]},"owner":{"text":"周xx","label":[]},"addr":{"text":"广东省xxxxxxxx","label":[]},"use_character":{"text":"非营运","label":[]},"model":{"text":"东风日产牌xxxxxx","label":[]},"vin":{"text":"LGBH52Exxxxxx","label":[]},"engine_num":{"text":"873073Y","label":[]},"register_date":{"text":"2017-11-13","label":[]},"issue_date":{"text":"2017-11-13","label":[]},"plate_num_b":{"text":"粤R82xxxx","label":[]},"record":{"text":"4418005xxxx","label":[]},"passengers_num":{"text":"26人","label":[]},"total_quality":{"text":"6900kg","label":[]},"prepare_quality":{"text":"4480kg","label":[]},"load_quality":{"text":"","label":[]},"lead_quality":{"text":"","label":[]},"overall_size":{"text":"7725x205xxxx","label":[]},"type":2,"card_position":[{"pos":{"left_top":{"x":454.0625,"y":17.34375},"right_top":{"x":987.8125,"y":11.71875},"right_bottom":{"x":987.8125,"y":562.96875},"left_bottom":{"x":471.5625,"y":546.09375}},"label":[]},{"pos":{"left_top":{"x":-0.9375,"y":28.59375},"right_top":{"x":445.3125,"y":22.96875},"right_bottom":{"x":445.3125,"y":551.71875},"left_bottom":{"x":-0.9375,"y":546.09375}},"label":[]}],"card_position_front":{"pos":{"left_top":{"x":454.0625,"y":17.34375},"right_top":{"x":987.8125,"y":11.71875},"right_bottom":{"x":987.8125,"y":562.96875},"left_bottom":{"x":471.5625,"y":546.09375}},"label":[]},"card_position_back":{"pos":{"left_top":{"x":-0.9375,"y":28.59375},"right_top":{"x":445.3125,"y":22.96875},"right_bottom":{"x":445.3125,"y":551.71875},"left_bottom":{"x":-0.9375,"y":546.09375}},"label":[]},"image_width":1000,"image_height":600,"img_size":{"w":1000,"h":600},"image_path":"http://tmp/wx4418e3e031e551be.o6zAJs-yC5ByIjnyyy09jKDZquXk.dlrc7P7WlhnGb4aca86b078fc2acb5b08e7a0f438943.jpg"}

          行驶证返回结果

          行驶证支持正副页面在一张图片中

          4、营业执照

          certificateType='businessLicense'

          属性名类型默认值是否必填说明
          onSuccessHandleEvent接口调用成功的回调函数
          certificateTypeStringbusinessLicense证书类型包含四种 身份证:idCard、驾驶证:drivingLicense、银行卡:bankCard、营业执照:businessLicense

          onSuccess

          参数 e.detail

          参考营业执照返回结果实例

          示例代码1

          <ocr-navigator bind:onSuccess="businessSuccess"   certificateType="businessLicense">  <button type="primary">营业执照识别</button></ocr-navigator>
          /** wxss **//*自定义按钮样式*/.ocr-wrapper {  margin: 40rpx auto;  width: 375rpx;}.intro {  margin: 40rpx;}

          营业执照返回结果实例

          {"reg_num":{"text":"371400228016303","label":[]},"legal_representative":{"text":"xxxx","label":[]},"enterprise_name":{"text":"xxxxx有限公司","label":[]},"address":{"text":"xxx省xxx市xxx","label":[]},"type_of_enterprise":{"text":"有限责任公司(自然人投资或控股)","label":[]},"business_scope":{"text":"xxxxxxxxxxxx","label":[]},"registered_capital":{"text":"叁佰万元整","label":[]},"valid_period":{"text":"2008年04月12日至年月日","label":[]},"registered_date":{"text":"2008年04月12日","label":[]},"cert_position":{"pos":{"left_top":{"x":65.4609375,"y":115.640625},"right_top":{"x":567.4921875,"y":123.828125},"right_bottom":{"x":567.4921875,"y":811.578125},"left_bottom":{"x":65.4609375,"y":819.765625}},"label":[]},"img_size":{"w":630,"h":874},"image_path":"http://tmp/wx4418e3e031e551be.o6zAJs-yC5ByIjnyyy09jKDZquXk.dlrc7P7WlhnGb4aca86b078fc2acb5b08e7a0f438943.jpg"}

          说明

          本文档配合3.0.2以及以上的插件使用,并且调试基础库在2.4.0以及以上才能使用


          API


          服务平台

          除基础组件与接口能力外,「小程序·服务平台」还为小程序开发者提供更丰富的增值能力,开发者可根据需求,选购不同规格的资源包。购买后,通过调用小程序原生快捷接入服务平台内的能力,丰富小程序的功能。

          AI

          微信OCR识别

          微信OCR识别能力是微信团队推出的一套提升移动端快捷信息录入 的工具,目前支持身份证、银行卡、行驶证、营业执照的 OCR 识别。

          智能对话服务

          微信智能对话服务是以对话交互为核心, 为有客服需求的个人、企业和组织提供智能对话系统的搭建。

          夸夸话术服务

          夸夸话术服务是以对话交互为基础,为用户提供花式夸人的互动娱乐服务。用户接入服务后,可以通过相关的描述语句来唤醒夸夸技能。开发者可以将该技能应用到智能对话、客服等场景中。

          商品二分类服务

          商品二分类服务提供可灵活调用的接口,能够判断用户输入的自然语言文本是否与商品相关。开发者可以利用该接口赋能自己的智能搜索、商品服务等场景。

          多语言翻译

          提供多语言翻译能力

          讲笑话情话服务

          讲笑话情话服务是以对话交互为基础,为用户提供普通笑话、冷笑话、情话等互动娱乐服务。用户接入服务后,可以通过相关的触发语句来唤醒对应技能。开发者可以将该服务应用到智能对话、客服等场景中。

          情感分析服务

          情感分析服务是以自然语言处理技术为基础,为有文本分析需求的个人、企业或组织提供识别给定语句的情感状态的能力。具体包括正面、负面、无情感三类。开发者可以将该服务应用到商品评论分析、智能对话、舆情监控等场景中。

          商品关键词抽取服务

          商品关键词抽取服务提供可灵活调用的接口,能够从电商商品标题中抽取关键词,包括商品名、品牌名、修饰词、营销词、颜色、材质、时间季节、地点、型号、尺寸规格单位共10类。开发者可以利用该接口赋能自己的智能客服、商品服务等场景。

          人脸检测与分析

          检测给定图片中的人脸位置、相应的面部属性和人脸质量信息。面部属性包括性别、年龄、表情、魅力、眼镜、发型、口罩和姿态 ,人脸质量信息包括整体质量分、模糊分、光照分和五官遮挡分。

          人脸年龄变化

          用户上传一张人脸图片,基于人脸编辑与生成算法,输出一张人脸变老或变年轻的图片,支持实现人脸不同年龄的变化。从童年到老年,细粒度变化,效果逼真,趣味十足。

          人脸美颜

          用户上传一张人脸图片,精准定位五官,实现美肤、亮肤、祛痘等美颜功能。

          人脸试唇色

          对图片中的人脸嘴唇进行着色,最多支持同时对一张图中的3张人脸进行试唇色。

          人脸性别变换

          用户上传一张人脸图片,基于人脸编辑与生成算法,输出一张人脸性别转换的图片。男变女可实现美颜、淡妆、加刘海和长发的效果;女变男可实现加胡须、变短发的效果。

          人像分割

          识别传入图片中人体的完整轮廓,进行抠像。

          五官定位

          对请求图片进行五官定位(也称人脸关键点定位),计算构成人脸轮廓的 90 个点,包括眉毛(左右各8点)、眼睛(左右各8点)、鼻子(13点)、嘴巴(22点)、脸型轮廓(21点)、眼珠[或瞳孔](2点)。

          内容

          文本内容安全

          对文本中可能含有的色情、暴恐、时政违规等有害信息进行识别,帮助开发者大幅降低内容违规风险,有效控制审核成本投入。

          图片内容安全

          图片内容安全是基于腾讯海量数据资源和深度学习技术,为互联网企业用户提供图片内容的智能审核服务,不仅能帮助用户降低色情、暴力恐怖、时政违规等内容风险,而且能大幅度节省人工审核成本,保护业务健康发展。

          地点搜索

          基于腾讯位置服务千万级鲜活地点(POI)数据,提供结合搜索关键词的周边、城市范围、矩形范围(屏幕视野内)等多种地理位置搜索能力,同时提供分类筛选功能,满足不同场景的地点搜索需要。

          坐标转换

          实现从其它地图供应商坐标系或标准GPS坐标系,批量转换到腾讯地图坐标系,使之可以在微信小程序地图中准确标注与使用。

          关键词输入提示

          用于获取输入地点关键字的补完与提示,提供了面向创建收货/服务地址、打车目的地搜索及位置签到搜索等多种场景策略。服务基于海量点击行为挖掘、训练,准确命中用户所想,平均输入3.2个字即可获取准确结果。

          驾车路线规划

          基于驾车场景的智能路线计算引擎,支持多途经点、结合实时路况、不走高速、少收费等多种偏好设置功能,支持车牌限行避让策略,并专为网约车提供接驾、送驾场景的路线规划策略。

          步行路线规划

          结合海量步行道路、过街天桥、地下通道及人行出入口等设施数据,提供智能步行路线规划服务。

          地址解析

          提供由文字地址到经纬度坐标的转换的能力,可一定程度上兼容地址本身不规范的问题(如错别字,省市区与门牌、地点不匹配、各类干扰词等情况),同时支持返回省市区、行政区划代码信息。

          逆地址解析

          提供经纬度坐标到结构化地址的转换能力,结果包含对坐标位置的文字描述、省市区等行政区划信息、门牌号、商圈、道路与交叉口以及周边地点列表等,服务响应快速稳定,对微信、美团、快手等超级APP提供可靠支撑。

          安全

          腾讯云正版曲库直通车

          正版曲库直通车是基于腾讯音乐娱乐集团海量线上背景音乐专用曲库资源,结合腾讯云存储、内容加速分发等基础能力,为解决内容创作过程中的正版背景音乐素材应用问题设计的 PaaS 产品。


          服务平台 API

          2.9.4

          API 均在 wx.serviceMarket 对象下。invokeService 方法可以通过兼容性配置,无需依赖 2.9.4 即可使用,配置方法见底部 兼容性配置 章节说明。

          从 2.11.1 开始,插件内也可以使用 wx.serviceMarket API,在调用时,消耗的是宿主的资源而不是插件方的资源。

          invokeService

          调用服务提供商提供的 API

          入参

          接收一个对象,对象下有如下定义的字段:

          字段名类型必填默认值说明
          servicestring服务提供商 ID
          apistring服务 API 名
          dataObject传递给服务 API 的 JSON 数据

          返回值

          返回一个 Promise,如调用失败,则 reject 一个 Error 对象,如调用成功,则 resolve 结果为如下定义的对象:

          字段名类型必填默认值说明
          dataObjectString

          在 data 中,如果服务提供商要求其中某个字段为文件 URL、并且此时希望将本地文件/大数据上传成 URL 作为字段值传入,则可以使用我们提供的 CDN 方法对相应值进行标记,微信会自动在调用服务 API 的时候将其转换成 CDN URL 给到服务提供方。

          错误码

          错误码含义
          -1入参错误
          -2调用失败
          -3逻辑失败
          -6appid错误
          -7api信息错误
          -8api信息错误
          -10api扣费失败
          -11命中频率

          示例代码 1: OCR

          从手机选择图片后,调用 OCR 服务。OCR 服务要求调用方传图片,接收图片的方式是图片 URL。OCR 服务要求调用方的 data 结构如下:

          字段名类型必填默认值说明
          img_urlstring图片 URL
          data_typenumber固定为 3,表示 URL 形式的图片
          ocr_typenumberOCR 类型,1 为身份证识别

          OCR 的接口需要传入图片 URL,如果需要将手机本地选择的图片上传转换成 URL,可以使用 CDN 方法对文件路径进行标记(或用任意的存储服务和自建的存储服务,也可以使用云开发的云文件存储服务,但都没有 CDN 方法便捷),以下给出使用 CDN 方法的示例:

          // 选择图片wx.chooseImage({  count: 1,  success: async function(res) {    try {      const invokeRes = await wx.serviceMarket.invokeService({        service: 'wx79ac3de8be320b71',        api: 'OcrAllInOne',        data: {          // 用 CDN 方法标记要上传并转换成 HTTP URL 的文件          img_url: new wx.serviceMarket.CDN({            type: 'filePath',            filePath: res.tempFilePaths[0],          }),          data_type: 3,          ocr_type: 1        },      })      console.log('invokeService success', invokeRes)      wx.showModal({        title: 'success',        content: JSON.stringify(invokeRes),      })    } catch (err) {      console.error('invokeService fail', err)      wx.showModal({        title: 'fail',        content: err,      })    }  },  fail: function(res) {},  complete: function(res) {},})

          示例代码 2: 普通 JSON 协议接口

          有些服务不需要用到 CDN 辅助接口,可以直接 JSON 调用,以下任意举例:

          // 选择图片wx.chooseImage({  count: 1,  success: function(res) {    // 调用 OCR 服务    wx.serviceMarket.invokeService({      service: 'some_service_id',      api: 'test',      data: {        type: 'x',        name: 'y',      },    }).then(res => {      console.log('invokeService success', res)    }).catch(err => {      console.error('invokeService fail', err)    })  },  fail: function(err) {    console.error(err)  },})

          CDN

          标记需要上传到 CDN 的文件/大字符串然后转换成 HTTP URL 的数据,必须在 invokeService 中使用。

          CDN 方法可以接收三种参数类型:

          • String
          • ArrayBuffer
          • 文件路径定义对象

          当使用文件路径定义对象时,将在调用服务 API 时自动将相应文件路径对应的文件内容上传至 CDN 并转换成 CDN URL,对象定义如下:

          字段名 类型 必填 默认值 说明 type String 是 定义对象的类型,必填 filePath filePath String 是 文件路径

          入参

          接收一个对象,对象下有如下定义的字段:

          字段名类型必填说明
          typestring定义对象的类型,必填 filePath
          filePathstring文件路径

          兼容性配置

          可以通过兼容性配置让 wx.serviceMarket.invokeService API 的使用不受基础库版本约束,配置方式是:在 app.json / game.json 中指定顶层字段 "servicemarket": true,在预览发布时小程序代码包会自动包含此 API 的兼容代码,在 2.9.4 以下也可使用。仅在手机上使用,工具中调试请选择 2.9.4 基础库。


          多端统一开发工具——kbone

          kbone 是一个致力于微信小程序和 Web 端同构的解决方案。

          简介

          微信小程序的底层模型和 Web 端不同,我们想直接把 Web 端的代码挪到小程序环境内执行是不可能的。kbone 的诞生就是为了解决这个问题,它实现了一个适配器,在适配层里模拟出了浏览器环境,让 Web 端的代码可以不做什么改动便可运行在小程序里。

          这里有个简单的代码片段:https://developers.weixin.qq.com/s/R9Hm0Qm67Acd,可以使用开发者工具打开看看效果。

          因为 kbone 是通过提供适配器的方式来实现同构,所以它的优势很明显:

          • 大部分流行的前端框架都能够在 kbone 上运行,比如 Vue、React、Preact 等。
          • 支持更为完整的前端框架特性,因为 kbone 不会对框架底层进行删改(比如 Vue 中的 v-html 指令、Vue-router 插件)。
          • 提供了常用的 dom/bom 接口,让用户代码无需做太大改动便可从 Web 端迁移到小程序端。
          • 在小程序端运行时,仍然可以使用小程序本身的特性(比如像 live-player 内置组件、分包功能)。
          • 提供了一些 Dom 扩展接口,让一些无法完美兼容到小程序端的接口也有替代使用方案(比如 getComputedStyle 接口)。

          使用

          为了可以让开发者可以更自由地进行项目的搭建,以下提供了三种方式,任选其一即可:

          使用 kbone-cli 快速开发

          对于新项目,可以使用 kbone-cli 来创建项目,首先安装 kbone-cli:

          npm install -g kbone-cli

          创建项目:

          kbone init my-app

          进入项目,按照 README.md 的指引进行开发:

          // 开发小程序端npm run mp// 开发 Web 端npm run web// 构建 Web 端npm run build
          PS:项目基于 webpack 构建,关于 webpack 方面的配置可以点此查看,而关于小程序构建相关的详细配置细节可以参考此文档。

          使用模板快速开发

          除了使用 kbone-cli 外,也可以直接将现有模板 clone 下来,然后在模板基础上进行开发改造:

          • Vue 项目模板
          • React 项目模板
          • kbone-ui 项目模板
          • Preact 项目模板
          • Omi 项目模板

          项目 clone 下来后,按照项目中 README.md 的指引进行开发。

          手动配置开发

          此方案基于 webpack 构建实现,如果你不想要使用官方提供的模板,想要更灵活地搭建自己的项目,又或者是想对已有的项目进行改造,则需要自己补充对应配置来实现 kbone 项目的构建。

          一般需要补充两个配置:

          • 构建到小程序代码的 webpack 配置
          • 使用 webpack 构建中使用到的特殊插件 mp-webpack-plugin 配置

          点此可以查看具体配置方式和操作流程。

          kbone-ui

          kbone-ui 是一个能同时支持 小程序(kbone) 和 vue 框架开发的多端 UI 库。

          • 即可以基于 kbone 同时开发小程序和 H5,也可以单独使用开发 H5 应用。
          • 支持以 Vue 语法来支持 H5 端和小程序端运行
          • 对齐 微信weui 样式组件

          文档

          更为详细的说明和指引,可点击查看文档。

          社区

          此方案虽然将整个 Web 端框架包含进来并提供了适配层,但是也不是银弹,无法满足所有场景,具体限制可参考问题文档。使用相关问题可在 Kbone社区 发帖。如果还遇到其他问题,可在 issue 中反馈。

          选择

          业内其实已经出现了很多关于同构的解决方案了,每个方案都有自己的优劣,不存在能够完美解决所有问题的方案。kbone 也一样,它的优势在上面提到过,而它的不足也是它的实现原理带来的。kbone 是使用一定的性能损耗来换取更为全面的 Web 端特性支持。

          所以关于性能方面,如果你对小程序的性能特别苛刻,建议直接使用原生小程序开发;如果你的页面节点数量特别多(通常在 1000 节点以上),同时还要保证在节点数无限上涨时仍然有稳定的渲染性能的话,可以尝试一下业内采用静态模板转译的方案;其他情况就可以直接采用 kbone 了。

          案例

          微信开放社区


          介绍


          腾讯云为开发者提供免费的开发环境和生产环境,更加方便、快速、可靠的构建你的小程序。

          目前服务端支持 NodeJS 和 PHP 两种语言,开发者可以使用开发者工具同时进行服务端和小程序的开发。

          开发环境


          • 免费使用
          • 自动分配测试用二级域名:xxxxxxx.qcloud.la
          • 自动部署免费 HTTPS
          • 仅可用于线上调试,不可发布
          • 代码部署、运行和数据库与生产环境完全分开
          • 与微信开发工具打通,可一键部署、调试、重启和恢复代码

          生产环境


          • 免费使用
          • 用户需购买或使用已有的腾讯云域名
          • 自动部署免费 HTTPS
          • 用于线上发布,不可调试
          • 使用微信开发工具上传代码,在腾讯云控制台操作部署,上传和发布分离,降低误操作风险

          通过微信公众平台授权登录腾讯云


          打开 微信公众平台 注册并登录小程序,按如下步骤操作:

          • 单击左侧菜单栏中的【设置】
          • 单击右侧 Tab 栏中的【开发者工具】
          • 单击【腾讯云】,进入腾讯云工具页面,单击【开通】
          • 使用小程序绑定的微信扫码即可将小程序授权给腾讯云,开通之后会自动进去腾讯云微信小程序控制台,显示开发环境已开通,此时可以进行后续操作

          注意:

          此时通过小程序开发者工具查看腾讯云状态并不会显示已开通,已开通状态会在第一次部署开发环境之后才会同步到微信开发者工具上。

          进入微信公众平台后台

          开通腾讯云

          腾讯云微信小程序控制台

          安装开发工具


          下载并安装最新版本的 微信开发者工具 ,使用小程序绑定的微信号扫码登录开发者工具。

          微信开发者工具

          导入 NodeJS DEMO 和配置



          1. 打开第二步安装的微信开发者工具,点击【小程序项目】按钮。

          2. 输入小程序 AppID,项目目录选择一个 空的目录 ,接着选择【建立腾讯云 Node.js 启动模板】,点击确定创建小程序项目。

          微信开发者工具


          3. 安装依赖

          为方便本地调试,建议您在本地安装依赖。你也可以跳过这步直接使用开发者工具的“腾讯云”菜单中的“安装依赖”直接在线上安装依赖。

          在您刚刚选择的目录打开 CMD 安装依赖:


          1. cd server && npm install

            安装依赖

          4. 点击界面右上角的【腾讯云】图标,在下拉的菜单栏中选择【上传测试代码】。 


            上传按钮

            5. 首次使用推荐使用,选择【模块上传】并勾选全部选项,然后勾选【部署后自动安装依赖】,点击【确定】开始上传代码。后续修改服务端代码后,推荐选择智能上传,工具仅仅上传有修改过的代码。

            选择模块

            上传成功

            6. 上传代码完成之后,点击右上角的【详情】按钮,接着选择【腾讯云状态】即可看到腾讯云自动分配给你的开发环境域名:

            查看开发域名

            7. 如果当前小程序是首次使用腾讯云小程序服务,需要完整复制(包括 https://)开发环境 request 域名,然后在编辑器中打开 client/config.js 文件,将复制的域名填入 host 中并保存,保存之后编辑器会自动编译小程序,左边的模拟器窗口即可实时显示出客户端的 Demo:

                 修改客户端配置    

            8. 在模拟器中点击【登录】,看到显示“登录成功”,即为开通完成,可以开始你的其他开发了。

            登录测试

              导入 PHP DEMO 和配置


              1. 打开第二步安装的微信开发者工具,点击【小程序项目】按钮。

                tips:需要注意的是,如果当前小程序已经开通了 NodeJS 环境,需要点击工具右上角详情按钮,选择腾讯云状态,点击切换语言

                微信开发者工具

                在腾讯云管理后台中可以选择切换语言环境

                微信开发者工具

              2. 输入小程序 AppID,项目目录选择一个空的目录,接着选择【建立腾讯云 PHP 启动模板】,点击确定创建小程序项目。

                微信开发者工具

              3. 再次点击【确定】进入开发者工具。

                         开发者工具

              4. 点击界面右上角的【腾讯云】图标,在下拉的菜单栏中选择【上传测试代码】。

                上传按钮

              5. 上传代码完成之后,点击右上角的【详情】按钮,接着选择【腾讯云状态】即可看到腾讯云自动分配给你的开发环境域名。

                查看开发域名

              6. 完整复制(包括 https://)开发环境 request 域名,然后在编辑器中打开 client/config.js 文件,将复制的域名填入 host 中并保存,保存之后编辑器会自动编译小程序,左边的模拟器窗口即可实时显示出客户端的 Demo。修改客户端配置     

              7. 在模拟器中点击【登录】,看到显示“登录成功”,即为开通完成,可以开始你的其他开发了。

                ```登录测试

              其他具体开发文档


              服务端、客户端的 Demo、SDK 的具体文档:


              我们建议你先完整阅读该开发文档,这将有助于更快地完成开发。如果发现我们的文档有任何错漏,或者开发过程中有任何疑问,欢迎通过下列邮箱联系我们。

              weixin_developer@qq.com

              为方便定位原因,如果是开发过程中的问题,我们建议你提供更多信息,包括但不限于:

              公司名称

              mp账户

              开发者微信号

              机型

              操作系统

              是否必现

              出现时间

              操作路径

              问题描述

              问题截图

              代码片段截图

              不能直接操作 Page.data

              避免在直接对 Page.data 进行赋值修改,请使用 Page.setData 进行操作才能将数据同步到页面中进行渲染

              怎么获取用户输入


              能够获取用户输入的组件,需要使用组件的属性bindchange将用户的输入内容同步到AppService

              <input id="myInput" bindblur="bindBlur" />
              var inputContent = {}Page({    data:{      inputContent: {}    },    bindChange:function(e){        inputContent[e.currentTarget.id] = e.detail.value    }})

              为什么脚本内不能使用window对象


              页面的脚本逻辑是在JsCore中运行,JsCore是一个没有窗口对象的环境,所以不能在脚本中使用window,也无法在脚本中操作组件

              为什么zepto/jquery无法使用


              zepto/jquery会使用到window对象和document对象,所以无法使用。

              wx.navigateTo无法打开页面


              一个应用同时只能打开5个页面,当已经打开了5个页面之后,wx.navigateTo不能正常打开新页面。请避免多层级的交互方式,或者使用wx.redirectTo

              样式表不支持级联选择器


              WXSS支持以.开始的类选择器。如:

                .normal_view{    color: #000000;    padding: 10px;  }

              可以使用标签选择器,控制同一类组件的样式。如:使用input标签选择器控制<input/>的默认样式。

                input{    width: 100px;  }

              本地资源无法通过WXSS获取


              background-image:可以使用网络图片,或者base64,或者使用<image/>标签

              如何修改窗口的背景色


              使用page标签选择器,可以修改顶层节点的样式

              page{  display:block;  min-height:100%;  background-color:red;}

              HTTPS 请求不成功

              1. tls 仅支持 1.2 及以上版本
              2. 部分 Android 机型需要 tls1.0 或者 tls1.1,所以请确保服务器的 tls 版本为 1.0、1.1、1.2

              网络请求的 referer

              网络请求的 referer 是不可以设置的,格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中{appid}为小程序的 appid,{version}为小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本。

              为什么 map 组件总是在最上层

              mapcanvasvideotextarea是由客户端创建的原生组件,原生组件的层级是最高的,所以页面中的其他组件无论设置z-index为多少,都无法盖在原生组件上。 原生组件暂时还无法放在scroll-view上,也无法对原生组件设置css动画。



              微信应用号(小程序)设计规范-稀土区

              微信小程序设计的基本原则是微信设计中心针对在微信类上线的小程序页面总结的设计指南及建议。以下设计原则都是基于对用户的尊重的基础上的,旨在微信生态类建立友好、高效、一致的用户体验的同时,最大程度顺应和支持各业务需求设计,实现用户与程序的共赢。


              概要

              基于微信小程序轻快的特点,我们拟定了小程序界面设计指南和建议。 设计指南建立在充分尊重用户知情权与操作权的基础之上。旨在微信生态体系内,建立友好、高效、一致的用户体验,同时最大程度适应和支持不同需求,实现用户与小程序服务方的共赢。

              一、友好礼貌 

              为了避免用户在微信中使用小程序服务时,注意力被周围复杂环境干扰,小程序在设计时应该注意减少无关的设计元素对用户目标干扰,礼貌地向用户展示程序侧提供的服务,友好地引导用户进行操作。

              1. 重点突出

              每个页面都应有明确的重点,以便于用户每进入一个新页面的时候都能快速地理解页面内容,在确定了重点的前提下,应尽量避免页面上出现其他干扰项影响用户的决策和操作。

              反例示意

              此页面的主题是查询,却添加了诸多与查询不相关的业务入口,与用户的预期不符,易造成用户的迷失。

              微信应用号(小程序)设计规范-稀土区

              纠正示意

              去掉任何与用户目标不相关的内容,明确页面主题,在技术和页面控件允许的前提下提供有助于用户目标的帮助内容,比如最近搜索词等。

              1emphasis_do

              反例示意

              操作没有主次,让用户无从选择

              微信应用号(小程序)设计规范-稀土区

              纠正示意

              首先要避免并列过多操作让用户选择,在不得不并列多个操作时,需区分操作主次,减轻用户的选择难度。

              1emphasis_do2

              2. 流程明确

              为了让用户顺畅地使用页面,在用户进行某一个操作流程时,应避免出现用户目标流程之外的内容而打断用户。

              反例示意

              用户本打算进行搜索,在进入页面时却被突如其来的模态抽奖框所打断;对于抽奖没有兴趣的用户是非常不友好的干扰;而即便有部分用户确实被“诱人”的抽奖活动所吸引,离开主流程去抽奖之后可能就遗忘了原本的目标,进而失去了对产品真正价值的利用和认识。

              微信应用号(小程序)设计规范-稀土区


              二、清晰明确

              一旦用户进入我们的小程序页面,就有责任和义务清晰明确告知用户身在何处、又可以往何处去,确保用户在页面中游刃有余地穿梭而不迷路,这样才能为用户提供安全的愉悦的使用体验。

              1. 导航明确,来去自如

              导航是确保用户在网页中浏览跳转时不迷路的最关键因素。导航需要告诉用户,当前在哪,可以去哪,如何回去等问题。首先在微信系统内的所有小程序的全部页面,均会自带微信提供的导航栏,统一解决当前在哪,如何回去的问题。在微信层级导航保持体验一致,有助于用户在微信内形成统一的体验和交互认知,无需在各小程序和其他微信页面的切换中新增学习成本或改变使用习惯。

              微信导航栏

              微信导航栏,直接继承于客户端,除导航栏颜色之外,开发者无需亦不可对其中的内容进行自定义。但开发者需要规定小程序各个页面的跳转关系,让导航系统能够以合理的方式工作。

              微信导航栏分为导航区域、标题区域以及操作区域。其中导航区控制程序页面进程。目前导航栏分深浅两种基本配色。

              导航区(iOS)

              微信进入小程序的第一个页面,导航区通常只有一个操作——“返回”,即返回进入小程序前的微信页面。 进入小程序后的次级页面,导航区的操作为——“返回” 和“关闭”。 “返回”,即返回上一级小程序界面或微信界面。“关闭”,即在当前界面直接退出小程序,回到进入小程序前的微信页面。

              3navigation_iOS


              导航区(Android)

              导航区仅存在唯一操作——直接退出小程序,回到进入小程序前的微信或系统桌面,安卓手机自带的硬件返回键执行返回上一级页面的操作。

              3navigation_android

              安卓导航存在一类特殊情况:当用户通过操作区的菜单将小程序添加至安卓桌面,并从安卓桌面打开小程序时,小程序的首页,不展示导航按钮。仅展示小程序标题和操作区。小程序次级页面,导航区只有返回上一级页面的操作,而点击安卓手机自带的硬件返回键也起到相同作用。

              3navigation_android_special

              微信导航栏自定义颜色规则(iOS和Android)

              小程序导航栏支持基本的背景颜色自定义功能,选择的颜色需要在满足可用性前提下,和谐搭配微信提供的两套主导航栏图标。建议参考以下选色效果:

              选色方案示例

              微信应用号(小程序)设计规范-稀土区

              页面内导航

              开发者可根据自身功能合计需要在页面内添加自有导航。并保持不同页面间导航一致。但是受限于手机屏幕尺寸的限制,小程序页面的导航应尽量简单,若仅为一般线性浏览的页面建议仅使用微信导航栏即可。

              开发者可选择小程序页面添加标签分页(Tab)导航。标签分页栏可固定在页面顶部或者底部,便于用户在不同的分页间做切换。标签数量不得少于2个,最多不得超过5个,为确保点击区域,建议标签数量不超过4项。一个页面也不应出现一组以上的标签分页栏。

              其中小程序首页可选择微信提供的原生底部标签分页样式,该样式仅供小程序首页使用。开发时可自定义图标样式、标签文案以及文案颜色等,具体设置项如图标尺寸等参考可参考开发文档和WeUI基础控件库。

              3navigation_page_bottom

              顶部标签分页栏颜色可自定义。在自定义颜色选择中,务必注意保持分页栏标签的可用性、可视性和可操作性。

              3navigation_page_top_dont


              2. 减少等待,反馈及时

              页面的过长时间的等待会引起用户的不良情绪,使用微信小程序项目提供的技术已能很大程度缩短等待时间。即便如此,当不可避免的出现了加载和等待的时候,需要予以及时的反馈以舒缓用户等待的不良情绪。

              启动页加载

              小程序启动页是小程序在微信内一定程度上展现品牌特征的页面之一。本页面将突出展示小程序品牌特征和加载状态。启动页除品牌标志(Logo)展示外,页面上的其他所有元素如加载进度指示,均由微信统一提供且不能更改,无需开发者开发。

              4miniapploading

              页面下拉刷新加载

              在微信小程序内,微信提供标准的页面下拉刷新加载能力和样式,开发者无需自行开发。

              4pull-to-refresh

              页面内加载反馈

              开发者可在小程序里自定义页面内容的加载样式。建议不管是使用在局部还是全局加载,自定义加载样式都应该尽可能简洁,并使用简单动画告知用户加载过程。开发者也可以使用微信提供的,统一的页面加载样式,如图中例所示。

              微信应用号(小程序)设计规范-稀土区

              模态加载

              模态的加载样式将覆盖整个页面的,由于无法明确告知具体加载的位置或内容将可能引起用户的焦虑感,因此应谨慎使用。除了在某些全局性操作下不要使用模态的加载。

              微信应用号(小程序)设计规范-稀土区

              局部加载反馈

              局部加载反馈即只在触发加载的页面局部进行反馈,这样的反馈机制更加有针对性,页面跳动小,是微信推荐的反馈方式。例如:

              微信应用号(小程序)设计规范-稀土区

              加载反馈注意事项

              • 若载入时间较长,应提供取消操作,并使用进度条显示载入的进度。
              • 载入过程中,应保持动画效果;无动画效果的加载很容易让人产生该界面已经卡死的错觉。
              • 不要再同一个页面使用超过1个加载动画。

              结果反馈

              除了在用户等待的过程中需予以及时反馈外,对操作的结果也需要予以明确反馈。根据实际情况看,可选择不同的结果反馈样式。对于页面局部的操作,可在操作区域予以直接反馈,对于页面级操作结果,可使用弹出式提示(Toast)、模态对话框或结果页面展示。

              页面局部操作结果反馈

              对于页面局部的操作,可在操作区域予以直接反馈,例如点击多选控件前后如下图。对于常用控件,微信设计中心已提供控件库及WeUI控件库,其中的控件都已提供完整的操作反馈。

              微信应用号(小程序)设计规范-稀土区

              页面全局操作结果——弹出式提示(Toast)

              弹出式提示(Toast)适用于轻量级的成功提示,1.5秒后自动消失,并不打断流程,对用户影响较小,适用于不需要强调的操作提醒,例如成功提示。特别注意该形式不适用于错误提示,因为错误提示需明确告知用户,因而不适合使用一闪而过的弹出式提示。

              微信应用号(小程序)设计规范-稀土区

              页面全局操作结果——模态对话框

              对于需要用户明确知晓的操作结果状态可通过模态对话框来提示,并可附带下一步操作指引。

              5global_popup

              页面全局操作结果——结果页

              对于操作结果已经是当前流程的终结的情况,可使用操作结果页来反馈。这种方式最为强烈和明确的告知用户操作已经完成,并可根据实际情况给出下一步操作的指引。

              5global_result

              3. 异常可控,有路可退

              在设计任何的任务和流程时,异常状态和流程往往容易被忽略,而这些异常场景往往是用户最为沮丧和需要帮助的时候,因此需要格外注意异常状态的设计,在出现异常时予以用户必要的状态提示,并告知解决方案,使其有路可退。

              要杜绝异常状态下,用户莫名其妙又无处可去,停滞在某一个页面的情况。上文中所提到的模态对话框和结果页面都可作为异常状态的提醒方式。除此之外,在表单页面中尤其是表单项较多的页面中,还应明确指出出错项目,以便用户修改。

              异常状态——表单出错

              表单报错,在表单顶部告知错误原因,并标识出错误字段提示用户修改。

              6error

              三、便捷优雅

              从PC时代的物理键盘鼠标到移动端时代手指,虽然输入设备极大精简,但是手指操作的准确性却大大不如键盘鼠标精确。为了适应这个变化,需要开发者在设计过程中充分利用手机特性,让用户便捷优雅的操控界面。

              1. 减少输入

              由于手机键盘区域小且密集,输入困难的同时还易引起输入错误,因此在设计小程序页面时因尽量减少用户输入,利用现有接口或其他一些易于操作的选择控件来改善用户输入的体验。

              例如下图中,在添加银行卡时,采用摄像头识别接口来帮助用户输入。除此之外微信团队还对外开放例如地理位置接口等多种微信小程序接口,充分利用这些接口将大大提高用户输入的效率和准确性,进而优化体验。

              7less-input

              除了利用接口外,在不得不让用户进行手动输入时,应尽量让用户做选择而不是键盘输入。一方面,回忆易于记忆,让用户在有限的选项中做选择通常来说是容易于完全靠记忆输入;另一方面,仍然是考虑到手机键盘密集的单键输入极易造成输入错误。例如图中,在用户搜索时提供搜索历史快捷选项将帮助用户快速进行搜索,而减少或避免不必要的键盘输入。

              7less-input2

              2. 避免误操作

              因为在手机上我们通过手指触摸屏幕来操控界面,手指的点击精确度远不如鼠标,因此在设计页面上需点击的控件时,需要充分考虑到其热区面积,避免由于可点击区域过小或过于密集而造成误操作。当简单的将原本在电脑屏幕上使用的界面不做任何适配直接移植到手机上时,往往就容易出现这样的问题。由于手机屏幕分辨率各不相同,因此最适宜点击像素尺寸也不完全一致,但换算成物理尺寸后大致是在7mm-9mm之间。在微信提供的标准组件库中,各种控件元素均已考虑到了页面点击效果以及不同屏幕的适配,因此再次推荐使用或模仿标准控件尺寸进行设计。

              3. 利用接口提升性能

              微信设计中心已推出了一套网页标准控件库,包括 sketch设计控件库Photoshop设计控件库,后续还将完善小程序组件,这些控件都已充分考虑了移动端页面的特点,能够保证其在移动端页面上的可用性和操作性能; 同时微信开发团队也在不断完善和扩充微信小程序接口,并提供微信公共库,利用这些资源不但能够为用户提供更加快捷的服务,而且对页面性能的提高有极大作用,无形之中提升了用户体验。

              四、统一稳定

              除了以上所提到的种种原则,建议接入微信的小程序还应该时刻注意不同页面间的统一性和延续性,在不同的页面尽量使用一致的控件和交互方式。

              统一的页面体验和有延续性的界面元素都将帮助用最少的学习成本达成使用目标,减轻页面跳动所造成的不适感。正因如此,小程序可根据需要使用微信提供的标准控件,以达到统一稳定的目的。

              五、视觉规范

              1. 字体规范

              微信内字体的使用与所运行的系统字体保持一致,常用字号为20,18,17,16,14,13,11(pt),使用场景具体如下:

              8Font

              字体颜色

              微信应用号(小程序)设计规范-稀土区

              主内容Black黑色,次要内容Grey灰色;时间戳与表单缺省值Light灰色;大段的说明内容而且属于主要内容用Semi黑;

              微信应用号(小程序)设计规范-稀土区

              蓝色为链接用色,绿色为完成字样颜色,红色为出错用色Press与Disable状态分别降低透明度为20%与10%;

              微信应用号(小程序)设计规范-稀土区

              2. 列表视觉规范

              微信应用号(小程序)设计规范-稀土区

              3. 表单输入视觉规范

              微信应用号(小程序)设计规范-稀土区

              4. 按钮使用原则



              11button3

              11button4

              5. 图标使用原则

              微信应用号(小程序)设计规范-稀土区

              资源下载

              为方便设计师进行设计,微信提供一套可供Web设计和小程序使用的基础控件库;同时提供方便开发者调用的资源。

              预览地址:https://weui.io


              微信小程序开发目前可以说是非常火热的,很多小伙伴都在学习这方面的知识。本文将为大家带来众多微信小程序的实例源码,小伙伴们可以根据源码来进行进一步学习。


              源码使用方法:

              1、克隆项目代码到本地(git应该都要会哈,现在源码几乎都会放github上,会git才方便,不会的可以自学一下哦,不会的也没关系,gitHub上也提供直接下载的链接)

              2、打开微信开发者工具;

              3、添加项目->选择本项目目录->编译执行;


              微信小程序源码:

              微信小应用示例代码(phodal/weapp-quick)

              源码链接:https://github.com/phodal/weapp-quick


              微信小应用地图定位demo(giscafer/wechat-weapp-mapdemo)

              源码链接:https://github.com/giscafer/wechat-weapp-mapdemo


              微信小应用- 掘金主页信息流(hilongjw/weapp-gold)

              源码链接:https://github.com/hilongjw/weapp-gold


              微信小程序(应用号)示例:微信小程序豆瓣电影(zce/weapp-demo)

              源码链接:https://github.com/zce/weapp-demo


              微信小程序-豆瓣电影(hingsir/weapp-douban-film)

              源码链接:https://github.com/hingsir/weapp-douban-film


              小程序 hello world 尝鲜(kunkun12/weapp)

              源码链接:https://github.com/kunkun12/weapp


              使用微信小程序开发2048游戏(sammffl/wechat-weapp-2048)

              源码链接:https://github.com/sammffl/wechat-weapp-2048


              微信小程序-微票(wangmingjob/weapp-weipiao)

              源码链接:https://github.com/wangmingjob/weapp-weipiao


              微信小程序购物车DEMO(SeptemberMaples/wechat-weapp-demo)

              源码链接:https://github.com/SeptemberMaples/wechat-weapp-demo


              微信小程序V2EX(jectychen/wechat-v2ex)

              源码链接:https://github.com/jectychen/wechat-v2ex


              微信小程序-知乎日报(myronliu347/wechat-app-zhihudaily)

              源码链接:https://github.com/myronliu347/wechat-app-zhihudaily


              微信小程序-公众号热门文章信息流(hijiangtao/weapp-newsapp)

              源码链接:https://github.com/hijiangtao/weapp-newsapp


              微信小程序版Gank客户端  

              源码链接:https://github.com/lypeer/wechat-weapp-gank


              微信小程序集成Redux实现的Todo list  

              源码链接:https://github.com/charleyw/wechat-weapp-redux-todos


              微信小程序-番茄时钟  

              源码链接:https://github.com/kraaas/timer


              微信小程序版聊天室  

              源码链接: https://github.com/ericzyh/wechat-chat


              微信小程序-HiApp  

              源码链接: https://github.com/BelinChung/wxapp-hiapp


              小程序Redux绑定库  

              源码链接: https://github.com/charleyw/wechat-weapp-redux


              微信小程序版微信

              源码链接:  https://github.com/18380435477/WeApp


              小程序开发从布局开始

              源码链接:  https://github.com/hardog/wechat-app-flexlayout


              微信小程序-音乐播放器 

              源码链接: https://github.com/eyasliu/wechat-app-music


              微信小程序-简易计算器-适合入门

              源码链接: https://github.com/dunizb/wxapp-sCalc


              微信小程序-github 

              源码链接:  https://github.com/zhengxiaowai/weapp-github


              微信小程序-小熊の日记 

              源码链接:  https://github.com/harveyqing/BearDiary


              微信小程序

              源码链接: https://github.com/SeaHub/PigRaising


              微信小程序(WeChatMeiZhi妹子图)

              源码链接:https://github.com/brucevanfdm/WeChatMeiZhi


              以上就是W3Cschool为大家整理的微信小程序实例代码,希望能对各位小伙伴们学习微信小程序开发能够有所帮助。

              https://www.51coolma.cn/wxagame/

              小程序简介

              小程序是一种全新的连接用户与服务的方式,它可以在微信内被便捷地获取和传播,同时具有出色的使用体验。

              小程序技术发展史

              ​小程序并非凭空冒出来的一个概念。当微信中的 ​WebView ​逐渐成为移动 Web 的一个重要入口时,微信就有相关的 ​JS API​ 了。

              代码清单1-1 使用 ​WeixinJSBridge​ 预览图片

              WeixinJSBridge.invoke('imagePreview', {    current: 'http://inews.gtimg.com/newsapp_bt/0/1693121381/641',    urls: [ // 所有图片的URL列表,数组格式        'https://img1.gtimg.com/10/1048/104857/10485731_980x1200_0.jpg',        'https://img1.gtimg.com/10/1048/104857/10485726_980x1200_0.jpg',        'https://img1.gtimg.com/10/1048/104857/10485729_980x1200_0.jpg'    ]}, function(res) {    console.log(res.err_msg)})

              ​代码1-1是一个调用微信原生组件浏览图片的​JS API​,相比于额外引入一个​JS​图片预览组件库,这种调用方式显得非常简洁和高效。

              ​实际上,微信官方是没有对外暴露过如此调用的,此类 ​API​ 最初是提供给腾讯内部一些业务使用,很多外部开发者发现了之后,依葫芦画瓢地使用了,逐渐成为微信中网页的事实标准。2015年初,微信发布了一整套网页开发工具包,称之为 ​JS-SDK​,开放了拍摄、录音、语音识别、二维码、地图、支付、分享、卡券等几十个​API​。给所有的 Web 开发者打开了一扇全新的窗户,让所有开发者都可以使用到微信的原生能力,去完成一些之前做不到或者难以做到的事情。

              同样是调用原生的浏览图片,调用方式如代码清单1-2所示。

              代码清单1-2 使用 ​JS-SDK​ 调用图片预览组件

              wx.previewImage({  current: 'https://img1.gtimg.com/10/1048/104857/10485726_980x1200_0.jpg',  urls: [ // 所有图片的URL列表,数组格式    'https://img1.gtimg.com/10/1048/104857/10485731_980x1200_0.jpg',    'https://img1.gtimg.com/10/1048/104857/10485726_980x1200_0.jpg',    'https://img1.gtimg.com/10/1048/104857/10485729_980x1200_0.jpg'  ],  success: function(res) {    console.log(res)  }})

              ​JS-SDK​是对之前的 ​WeixinJSBridge​ 的一个包装,以及新能力的释放,并且由对内开放转为了对所有开发者开放,在很短的时间内获得了极大的关注。从数据监控来看,绝大部分在微信内传播的移动网页都使用到了相关的接口。

              ​JS-SDK​ 解决了移动网页能力不足的问题,通过暴露微信的接口使得 Web 开发者能够拥有更多的能力,然而在更多的能力之外,JS-SDK 的模式并没有解决使用移动网页遇到的体验不良的问题。用户在访问网页的时候,在浏览器开始显示之前都会有一个的白屏过程,在移动端,受限于设备性能和网络速度,白屏会更加明显。我们团队把很多技术精力放置在如何帮助平台上的 Web 开发者解决这个问题。因此我们设计了一个 ​JS-SDK​ 的增强版本,其中有一个重要的功能,称之为“微信 Web 资源离线存储”。

              ​以下文字引用自内部的文档(没有最终对外开放):

              微信 Web 资源离线存储是面向 Web 开发者提供的基于微信内的 Web 加速方案。通过使用微信离线存储,Web 开发者可借助微信提供的资源存储能力,直接从微信本地加载 Web 资源而不需要再从服务端拉取,从而减少网页加载时间,为微信用户提供更优质的网页浏览体验。每个公众号下所有 Web App 累计最多可缓存 5M 的资源。

              ​这个设计有点类似 HTML5 的 ​Application Cache​,但在设计上规避了一些 ​Application Cache​的不足。

              ​在内部测试中,我们发现 离线存储 能够解决一些问题,但对于一些复杂的页面依然会有白屏问题,例如页面加载了大量的 CSS 或者是 JavaScript 文件。​除了白屏,影响 Web 体验的问题还有缺少操作的反馈,主要表现在两个方面:页面切换的生硬和点击的迟滞感。

              ​微信面临的问题是如何设计一个比较好的系统,使得所有开发者在微信中都能获得比较好的体验。这个问题是之前的​ JS-SDK​ 所处理不了的,需要一个全新的系统来完成,它需要使得所有的开发者都能做到:

              - 快速的加载

              - 更强大的能力

              - 原生的体验

              - 易用且安全的微信数据开放

              - 高效和简单的开发

              这就是小程序的由来。

              小程序与普通网页开发的区别

              ​小程序的主要开发语言是 JavaScript ,小程序的开发同普通的网页开发相比有很大的相似性。对于前端开发者而言,从网页开发迁移到小程序的开发成本并不高,但是二者还是有些许区别的。

              ​网页开发渲染线程和脚本线程是互斥的,这也是为什么长时间的脚本运行可能会导致页面失去响应,而在小程序中,二者是分开的,分别运行在不同的线程中。网页开发者可以使用到各种浏览器暴露出来的 DOM API,进行 DOM 选中和操作。而如上文所述,小程序的逻辑层和渲染层是分开的,逻辑层运行在 JSCore 中,并没有一个完整浏览器对象,因而缺少相关的 DOM API 和 BOM API。这一区别导致了前端开发非常熟悉的一些库,例如 jQuery、 Zepto 等,在小程序中是无法运行的。同时 JSCore 的环境同 NodeJS 环境也是不尽相同,所以一些 NPM 的包在小程序中也是无法运行的。

              ​网页开发者需要面对的环境是各式各样的浏览器,PC 端需要面对 IE、Chrome、QQ 浏览器等,在移动端需要面​对​ Safari ​​​​、Chrome 以及 iOS、Android 系统中的各式 WebView 。而小程序开发过程中需要面对的是两大操作系统 iOS 和 Android 的微信客户端,以及用于辅助开发的小程序开发者工具,小程序中三大运行环境也是有所区别的,如表1-1所示。

              表1-1 小程序的运行环境

              运行环境逻辑层渲染层
              iOSJavaScriptCoreWKWebView
              安卓V8chromium定制内核
              小程序开发者工具NWJSChrome WebView

              ​网页开发者在开发网页的时候,只需要使用到浏览器,并且搭配上一些辅助工具或者编辑器即可。小程序的开发则有所不同,需要经过申请小程序帐号、安装小程序开发者工具、配置项目等等过程方可完成。

              体验小程序

              开发者可使用微信客户端(6.7.2 及以上版本)扫码下方小程序码,体验小程序。

              查看小程序示例源码


              开始

              开发小程序的第一步,你需要拥有一个小程序帐号,通过这个帐号你就可以管理你的小程序。

              跟随这个教程,开始你的小程序之旅吧!

              申请帐号

              进入小程序注册页 根据指引填写信息和提交相应的资料,就可以拥有自己的小程序帐号。

              在这个小程序管理平台,你可以管理你的小程序的权限,查看数据报表,发布小程序等操作。

              登录 小程序后台 ,我们可以在菜单 “开发”-“开发设置” 看到小程序的 AppID 了 。

              小程序的 AppID 相当于小程序平台的一个身份证,后续你会在很多地方要用到 AppID (注意这里要区别于服务号或订阅号的 AppID)。

              有了小程序帐号之后,我们需要一个工具来开发小程序。

              安装开发工具

              前往 开发者工具下载页面 ,根据自己的操作系统下载对应的安装包进行安装,有关开发者工具更详细的介绍可以查看 《开发者工具介绍》 。

              打开小程序开发者工具,用微信扫码登录开发者工具,准备开发你的第一个小程序吧!

              你的第一个小程序

              新建项目选择小程序项目,选择代码存放的硬盘路径,填入刚刚申请到的小程序的 AppID,给你的项目起一个好听的名字,勾选 "不使用云服务" (注意: 你要选择一个空的目录才可以创建项目),点击新建,你就得到了你的第一个小程序了,点击顶部菜单编译就可以在微信开发者工具中预览你的第一个小程序。

              接下来我们来预览一下这个小程序的效果。

              编译预览

              点击工具上的编译按钮,可以在工具的左侧模拟器界面看到这个小程序的表现,也可以点击预览按钮,通过微信的扫一扫在手机上体验你的第一个小程序。

              通过这个章节,你已经成功创建了你的第一个小程序,并且在微信客户端上体验到它流畅的表现。

              下个章节,我们一起来看看这个小程序的代码构成。


              小程序代码构成

              ​在上一章中,我们通过开发者工具快速创建了一个 QuickStart 项目。你可以留意到这个项目里边生成了不同类型的文件:

              1. .json 后缀的 JSON 配置文件
              2. .wxml 后缀的 WXML 模板文件
              3. .wxss 后缀的 WXSS 样式文件
              4. .js 后缀的 JS 脚本逻辑文件

              接下来我们分别看看这4种文件的作用。

              JSON 配置

              JSON 是一种数据格式,并不是编程语言,在小程序中,JSON扮演的静态配置的角色。

              我们可以看到在项目的根目录有一个 app.json 和 project.config.json,此外在 pages/logs 目录下还有一个 logs.json,我们依次来说明一下它们的用途。

              小程序配置 app.json

              app.json 是当前小程序的全局配置,包括了小程序的所有页面路径、界面表现、网络超时时间、底部 tab 等。QuickStart 项目里边的 app.json 配置内容如下:

              {  "pages":[    "pages/index/index",    "pages/logs/logs"  ],  "window":{    "backgroundTextStyle":"light",    "navigationBarBackgroundColor": "#fff",    "navigationBarTitleText": "WeChat",    "navigationBarTextStyle":"black"  }}

              我们简单说一下这个配置各个项的含义:

              1. pages字段 —— 用于描述当前小程序所有页面路径,这是为了让微信客户端知道当前你的小程序页面定义在哪个目录。
              2. window字段 —— 定义小程序所有页面的顶部背景颜色,文字颜色定义等。

              其他配置项细节可以参考文档 小程序的配置 app.json 。

              工具配置 project.config.json

              通常大家在使用一个工具的时候,都会针对各自喜好做一些个性化配置,例如界面颜色、编译配置等等,当你换了另外一台电脑重新安装工具的时候,你还要重新配置。

              考虑到这点,小程序开发者工具在每个项目的根目录都会生成一个 project.config.json,你在工具上做的任何配置都会写入到这个文件,当你重新安装工具或者换电脑工作时,你只要载入同一个项目的代码包,开发者工具就自动会帮你恢复到当时你开发项目时的个性化配置,其中会包括编辑器的颜色、代码上传时自动压缩等等一系列选项。

              其他配置项细节可以参考文档 开发者工具的配置 。

              页面配置 page.json

              这里的 page.json 其实用来表示 pages/logs 目录下的 logs.json 这类和小程序页面相关的配置。

              如果你整个小程序的风格是蓝色调,那么你可以在 app.json 里边声明顶部颜色是蓝色即可。实际情况可能不是这样,可能你小程序里边的每个页面都有不一样的色调来区分不同功能模块,因此我们提供了 page.json,让开发者可以独立定义每个页面的一些属性,例如刚刚说的顶部颜色、是否允许下拉刷新等等。

              其他配置项细节可以参考文档 页面配置 。

              JSON 语法

              这里说一下小程序里JSON配置的一些注意事项。

              JSON文件都是被包裹在一个大括号中 {},通过key-value的方式来表达数据。JSON的Key必须包裹在一个双引号中,在实践中,编写 JSON 的时候,忘了给 Key 值加双引号或者是把双引号写成单引号是常见错误。

              JSON的值只能是以下几种数据格式,其他任何格式都会触发报错,例如 JavaScript 中的 undefined。

              1. 数字,包含浮点数和整数
              2. 字符串,需要包裹在双引号中
              3. Bool值,true 或者 false
              4. 数组,需要包裹在方括号中 []
              5. 对象,需要包裹在大括号中 {}
              6. Null

              还需要注意的是 JSON 文件中无法使用注释,试图添加注释将会引发报错。

              WXML 模板

              从事过网页编程的人知道,网页编程采用的是 HTML + CSS + JS 这样的组合,其中 HTML 是用来描述当前这个页面的结构,CSS 用来描述页面的样子,JS 通常是用来处理这个页面和用户的交互。

              同样道理,在小程序中也有同样的角色,其中 WXML 充当的就是类似 HTML 的角色。打开 pages/index/index.wxml,你会看到以下的内容:

              <view class="container">  <view class="userinfo">    <button wx:if="{{!hasUserInfo && canIUse}}"> 获取头像昵称 </button>    <block wx:else>      <image src="{{userInfo.avatarUrl}}" background-size="cover"></image>      <text class="userinfo-nickname">{{userInfo.nickName}}</text>    </block>  </view>  <view class="usermotto">    <text class="user-motto">{{motto}}</text>  </view></view>

              和 HTML 非常相似,WXML 由标签、属性等等构成。但是也有很多不一样的地方,我们来一一阐述一下:

              1. 标签名字有点不一样往往写 HTML 的时候,经常会用到的标签是 div, p, span,开发者在写一个页面的时候可以根据这些基础的标签组合出不一样的组件,例如日历、弹窗等等。换个思路,既然大家都需要这些组件,为什么我们不能把这些常用的组件包装起来,大大提高我们的开发效率。从上边的例子可以看到,小程序的 WXML 用的标签是 view, button, text 等等,这些标签就是小程序给开发者包装好的基本能力,我们还提供了地图、视频、音频等等组件能力。更多详细的组件讲述参考下个章节 小程序的能力
              2. 多了一些 wx:if 这样的属性以及 {{ }} 这样的表达式在网页的一般开发流程中,我们通常会通过 JS 操作 DOM (对应 HTML 的描述产生的树),以引起界面的一些变化响应用户的行为。例如,用户点击某个按钮的时候,JS 会记录一些状态到 JS 变量里边,同时通过 DOM API 操控 DOM 的属性或者行为,进而引起界面一些变化。当项目越来越大的时候,你的代码会充斥着非常多的界面交互逻辑和程序的各种状态变量,显然这不是一个很好的开发模式,因此就有了 MVVM 的开发模式(例如 React, Vue),提倡把渲染和逻辑分离。简单来说就是不要再让 JS 直接操控 DOM,JS 只需要管理状态即可,然后再通过一种模板语法来描述状态和界面结构的关系即可。小程序的框架也是用到了这个思路,如果你需要把一个 Hello World 的字符串显示在界面上。WXML 是这么写 :<text>{{msg}}</text>JS 只需要管理状态即可:this.setData({ msg: "Hello World" })通过 {{ }} 的语法把一个变量绑定到界面上,我们称为数据绑定。仅仅通过数据绑定还不够完整的描述状态和界面的关系,还需要 if/else, for等控制能力,在小程序里边,这些控制能力都用 wx: 开头的属性来表达。

              更详细的文档可以参考 WXML

              WXSS 样式

              WXSS 具有 CSS 大部分的特性,小程序在 WXSS 也做了一些扩充和修改。

              1. 新增了尺寸单位。在写 CSS 样式时,开发者需要考虑到手机设备的屏幕会有不同的宽度和设备像素比,采用一些技巧来换算一些像素单位。WXSS 在底层支持新的尺寸单位 rpx ,开发者可以免去换算的烦恼,只要交给小程序底层来换算即可,由于换算采用的浮点数运算,所以运算结果会和预期结果有一点点偏差。
              2. 提供了全局的样式和局部样式。和前边 app.json, page.json 的概念相同,你可以写一个 app.wxss 作为全局样式,会作用于当前小程序的所有页面,局部页面样式 page.wxss 仅对当前页面生效。
              3. 此外 WXSS 仅支持部分 CSS 选择器

              更详细的文档可以参考 WXSS 。

              JS 逻辑交互

              一个服务仅仅只有界面展示是不够的,还需要和用户做交互:响应用户的点击、获取用户的位置等等。在小程序里边,我们就通过编写 JS 脚本文件来处理用户的操作。

              <view>{{ msg }}</view><button bindtap="clickMe">点击我</button>

              点击 button 按钮的时候,我们希望把界面上 msg 显示成 "Hello World",于是我们在 button 上声明一个属性: bindtap ,在 JS 文件里边声明了 clickMe 方法来响应这次点击操作:

              Page({  clickMe: function() {    this.setData({ msg: "Hello World" })  }})

              响应用户的操作就是这么简单,更详细的事件可以参考文档 WXML - 事件 。

              此外你还可以在 JS 中调用小程序提供的丰富的 API,利用这些 API 可以很方便的调起微信提供的能力,例如获取用户信息、本地存储、微信支付等。在前边的 QuickStart 例子中,在 pages/index/index.js 就调用了 wx.getUserInfo 获取微信用户的头像和昵称,最后通过 setData 把获取到的信息显示到界面上。更多 API 可以参考文档 小程序的API 。

              通过这个章节,你了解了小程序涉及到的文件类型以及对应的角色,在下个章节中,我们把这一章所涉及到的文件通过 “小程序的框架” 给 “串” 起来,让他们都工作起来。


              小程序宿主环境

              我们称微信客户端给小程序所提供的环境为宿主环境。小程序借助宿主环境提供的能力,可以完成许多普通网页无法完成的功能。

              上一章中我们把小程序涉及到的文件类型阐述了一遍,我们结合 QuickStart 这个项目来讲一下这些文件是怎么配合工作的。

              渲染层和逻辑层

              首先,我们来简单了解下小程序的运行环境。小程序的运行环境分成渲染层和逻辑层,其中 WXML 模板和 WXSS 样式工作在渲染层,JS 脚本工作在逻辑层。

              小程序的渲染层和逻辑层分别由2个线程管理:渲染层的界面使用了WebView 进行渲染;逻辑层采用JsCore线程运行JS脚本。一个小程序存在多个界面,所以渲染层存在多个WebView线程,这两个线程的通信会经由微信客户端(下文中也会采用Native来代指微信客户端)做中转,逻辑层发送网络请求也经由Native转发,小程序的通信模型下图所示。

              有关渲染层和逻辑层的详细文档参考 小程序框架 。

              程序与页面

              微信客户端在打开小程序之前,会把整个小程序的代码包下载到本地。

              紧接着通过 app.json 的 pages 字段就可以知道你当前小程序的所有页面路径:

              {  "pages":[    "pages/index/index",    "pages/logs/logs"  ]}

              这个配置说明在 QuickStart 项目定义了两个页面,分别位于 pages/index/index 和 pages/logs/logs。而写在 pages 字段的第一个页面就是这个小程序的首页(打开小程序看到的第一个页面)。

              于是微信客户端就把首页的代码装载进来,通过小程序底层的一些机制,就可以渲染出这个首页。

              小程序启动之后,在 app.js 定义的 App 实例的 onLaunch 回调会被执行:

              App({  onLaunch: function () {    // 小程序启动之后 触发  }})

              整个小程序只有一个 App 实例,是全部页面共享的,更多的事件回调参考文档 注册程序 App 。

              接下来我们简单看看小程序的一个页面是怎么写的。

              你可以观察到 pages/logs/logs 下其实是包括了4种文件的,微信客户端会先根据 logs.json 配置生成一个界面,顶部的颜色和文字你都可以在这个 json 文件里边定义好。紧接着客户端就会装载这个页面的 WXML 结构和 WXSS 样式。最后客户端会装载 logs.js,你可以看到 logs.js 的大体内容就是:

              Page({  data: { // 参与页面渲染的数据    logs: []  },  onLoad: function () {    // 页面渲染后 执行  }})

              Page 是一个页面构造器,这个构造器就生成了一个页面。在生成页面的时候,小程序框架会把 data 数据和 index.wxml 一起渲染出最终的结构,于是就得到了你看到的小程序的样子。

              在渲染完界面之后,页面实例就会收到一个 onLoad 的回调,你可以在这个回调处理你的逻辑。

              有关于 Page 构造器更多详细的文档参考 注册页面 Page 。

              组件

              小程序提供了丰富的基础组件给开发者,开发者可以像搭积木一样,组合各种组件拼合成自己的小程序。

              就像 HTML 的 div, p 等标签一样,在小程序里边,你只需要在 WXML 写上对应的组件标签名字就可以把该组件显示在界面上,例如,你需要在界面上显示地图,你只需要这样写即可:

              <map></map>

              使用组件的时候,还可以通过属性传递值给组件,让组件可以以不同的状态去展现,例如,我们希望地图一开始的中心的经纬度是广州,那么你需要声明地图的 longitude(中心经度) 和 latitude(中心纬度)两个属性:

              <map longitude="广州经度" latitude="广州纬度"></map>

              组件的内部行为也会通过事件的形式让开发者可以感知,例如用户点击了地图上的某个标记,你可以在 js 编写 markertap 函数来处理:

              <map bindmarkertap="markertap" longitude="广州经度" latitude="广州纬度"></map>

              当然你也可以通过 style 或者 class 来控制组件的外层样式,以便适应你的界面宽度高度等等。

              API

              为了让开发者可以很方便的调起微信提供的能力,例如获取用户信息、微信支付等等,小程序提供了很多 API 给开发者去使用。

              要获取用户的地理位置时,只需要:

              wx.getLocation({  type: 'wgs84',  success: (res) => {    var latitude = res.latitude // 纬度    var longitude = res.longitude // 经度  }})

              调用微信扫一扫能力,只需要:

              wx.scanCode({  success: (res) => {    console.log(res)  }})

              需要注意的是:多数 API 的回调都是异步,你需要处理好代码逻辑的异步问题。

              更多的 API 能力见 小程序的API

              通过这个章节你已经大概了解了小程序运行的一些基本概念,当你开发完一个小程序之后,你就需要发布你的小程序。在下个章节,你会知道发布前需要做什么准备。


              小程序协同工作和发布

              在中大型的公司里,人员的分工非常仔细,一般会有不同岗位角色的员工同时参与同一个小程序项目。为此,小程序平台设计了不同的权限管理使得项目管理者可以更加高效管理整个团队的协同工作。

              以往我们在开发完网页之后,需要把网页的代码和资源放在服务器上,让用户通过互联网来访问。在小程序的平台里,开发者完成开发之后,需要在开发者工具提交小程序的代码包,然后在小程序后台发布小程序,用户可以通过搜索或者其它入口来进入该小程序。

              在这一章我们会把团队的协同工作的注意事项和小程序发布前后涉及的概念和流程做一些介绍。

              协同工作

              如果你只是一个人开发小程序,可以暂时先跳过这部分,如果是一个团队需要先了解一些概念。

              多数情况下,一个团队多人同时参与同一个小程序项目,每个角色所承担的工作或者权限不一样,中大公司的分工更为仔细。为了更形象的表达团队不同角色的关系以及权限的管理,我们通过虚拟一个项目成员组织结构来描述日常如何协同合作完成一个小程序的发布,组织关系如图5-1所示。

              img​ 图5-1 虚拟小程序项目组

              项目管理成员负责统筹整个项目的进展和风险、把控小程序对外发布的节奏,产品组提出需求,设计组与产品讨论并对需求进行抽象,设计出可视化流程与图形,输出设计方案。开发组依据设计方案,进行程序代码的编写,代码编写完成后,产品组与设计组体验小程序的整体流程,测试组编写测试用例并对小程序进行各种边界测试。项目一般的成员构成与工作流程如图5-2所示。

              img​ 图5-2 提需求到发布小程序的流程

              小程序成员管理

              小程序成员管理包括对小程序项目成员及体验成员的管理。

              • 项目成员:表示参与小程序开发、运营的成员,可登录小程序管理后台,包括运营者、开发者及数据分析者。管理员可在“成员管理”中添加、删除项目成员,并设置项目成员的角色。
              • 体验成员:表示参与小程序内测体验的成员,可使用体验版小程序,但不属于项目成员。管理员及项目成员均可添加、删除体验成员。

              不同项目成员拥有不同的权限,从而保证小程序开发安全有序。

              权限运营者开发者数据分析者
              开发者权限
              体验者权限
              登录
              数据分析
              微信支付
              推广
              开发管理
              开发设置
              暂停服务
              解除关联公众号
              腾讯云管理
              小程序插件
              游戏运营管理

              各权限功能说明

              • 开发者权限:可使用小程序开发者工具及开发版小程序进行开发
              • 体验者权限:可使用体验版小程序
              • 登录:可登录小程序管理后台,无需管理员确认
              • 数据分析:使用小程序统计模块功能查看小程序数据
              • 微信支付:使用小程序微信支付(虚拟支付)模块
              • 推广:使用小程序流量主、广告主模块
              • 开发管理:小程序提交审核、发布、回退
              • 开发设置:设置小程序服务器域名、消息推送及扫描普通链接二维码打开小程序
              • 暂停服务设置:暂停小程序线上服务
              • 解除关联公众号:可解绑小程序已关联的公众号
              • 小程序插件:可进行小程序插件开发管理和设置
              • 游戏运营管理:可使用小游戏管理后台的素材管理、游戏圈管理等功能

              需要留意,项目管理者控制整个小程序的发布、回退、下架等敏感操作,不应把敏感操作的权限分配给不相关人员

              小程序的版本

              一般的软件开发流程,开发者编写代码自测开发版程序,直到程序达到一个稳定可体验的状态时,开发者会把这个体验版本给到产品经理和测试人员进行体验测试,最后修复完程序的Bug后发布供外部用户正式使用。小程序的版本根据这个流程设计了小程序版本的概念,如表5-3所示。

              表5-3 小程序的版本

              权限说明
              开发版本使用开发者工具,可将代码上传到开发版本中。 开发版本只保留每人最新的一份上传的代码。
              点击提交审核,可将代码提交审核。开发版本可删除,不影响线上版本和审核中版本的代码。
              体验版本可以选择某个开发版本作为体验版,并且选取一份体验版。
              审核中版本只能有一份代码处于审核中。有审核结果后可以发布到线上,也可直接重新提交审核,覆盖原审核版本。
              线上版本线上所有用户使用的代码版本,该版本代码在新版本代码发布后被覆盖更新。

              考虑到项目是协同开发的模式,一个小程序可能同时由多个开发者进行开发,往往开发者在小程序开发者工具上编写完代码后需要到手机进行真机体验,所以每个开发者拥有自己对应的一个开发版本。因为处于开发中的版本是不稳定的,开发者随时会修改代码覆盖开发版,为了让测试和产品经理有一个完整稳定的版本可以体验测试,小程序平台允许把其中一个开发版本设置成体验版,因此建议在项目开发阶段特殊分配一个开发角色,用于上传稳定可供体验测试的代码,并把他上传的开发版本设置成体验版。

              发布上线

              一个小程序从开发完到上线一般要经过 预览-> 上传代码 -> 提交审核 -> 发布等步骤。

              预览

              使用开发者工具可以预览小程序,帮助开发者检查小程序在移动客户端上的真实表现。

              点击开发者工具顶部操作栏的预览按钮,开发者工具会自动打包当前项目,并上传小程序代码至微信的服务器,成功之后会在界面上显示一个二维码。使用当前小程序开发者的微信扫码即可看到小程序在手机客户端上的真实表现。

              上传代码

              同预览不同,上传代码是用于提交体验或者审核使用的。

              点击开发者工具顶部操作栏的上传按钮,填写版本号以及项目备注,需要注意的是,这里版本号以及项目备注是为了方便管理员检查版本使用的,开发者可以根据自己的实际要求来填写这两个字段。

              上传成功之后,登录小程序管理后台 - 开发管理 - 开发版本 就可以找到刚提交上传的版本了。

              可以将这个版本设置 体验版 或者是 提交审核

              提交审核

              为了保证小程序的质量,以及符合相关的规范,小程序的发布是需要经过审核的。

              在开发者工具中上传了小程序代码之后,登录 小程序管理后台 - 开发管理 - 开发版本 找到提交上传的版本。

              在开发版本的列表中,点击 提交审核 按照页面提示,填写相关的信息,即可以将小程序提交审核。

              需要注意的是,请开发者严格测试了版本之后,再提交审核, 过多的审核不通过,可能会影响后续的时间。

              发布

              审核通过之后,管理员的微信中会收到小程序通过审核的通知,此时登录 小程序管理后台 - 开发管理 - 审核版本中可以看到通过审核的版本。

              点击发布后,即可发布小程序。小程序提供了两种发布模式:全量发布和分阶段发布。全量发布是指当点击发布之后,所有用户访问小程序时都会使用当前最新的发布版本。分阶段发布是指分不同时间段来控制部分用户使用最新的发布版本,分阶段发布我们也称为灰度发布。一般来说,普通小程序发布时采用全量发布即可,当小程序承载的功能越来越多,使用的用户数越来越多时,采用分阶段发布是一个非常好的控制风险的办法。

              小程序码

              很多场景下用户会通过扫码快速进入一个小程序,在小程序设计的初期,小程序平台提供的二维码的形式。我们发现用户在扫一个二维码时,他并不知道当前这次扫码会出现什么样的服务,因为二维码的背后有可能是公众号、小程序、网页服务、支付页面、添加好友等不同的服务。为了让用户在扫码之前就有一个明确的预期,因此微信设计了小程序码,如图5-3所示。

              img

              ​ 图5-3 “小程序数据助手”的小程序码

              小程序码在样式上更具辨识度和视觉冲击力,相对于二维码来说,小程序主题的品牌形象更加清晰明显,可以帮助开发者更好地推广小程序。在发布小程序之后,小程序管理平台会提供对应的小程序码的预览和下载,开发者可以自行下载用于线上和线下的小程序服务推广。

              运营数据

              有两种方式可以方便的看到小程序的运营数据

              方法一:

              登录 小程序管理后台 - 数据分析

              点击相应的 tab 可以看到相关的数据。

              方法二:

              使用小程序数据助手,在微信中方便的查看运营数据


              目录结构

              小程序包含一个描述整体程序的 app 和多个描述各自页面的 page。

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

              文件必需作用
              app.js小程序逻辑
              app.json小程序公共配置
              app.wxss小程序公共样式表

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

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

              注意:为了方便开发者减少配置项,描述页面的四个文件必须具有相同的路径与文件名。

              允许上传的文件

              在项目目录中,以下文件会经过编译,因此上传之后无法直接访问到:.js、app.json、.wxml、*.wxss(其中 wxml 和 wxss 文件仅针对在 app.json 中配置了的页面)。除此之外,只有后缀名在白名单内的文件可以被上传,不在白名单列表内文件在开发工具能被访问到,但无法被上传。具体白名单列表如下:

              1. wxs
              2. png
              3. jpg
              4. jpeg
              5. gif
              6. svg
              7. json
              8. cer
              9. mp3
              10. aac
              11. m4a
              12. mp4
              13. wav
              14. ogg
              15. silk


              全局配置

              小程序根目录下的 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/index",      "text": "日志"    }]  },  "networkTimeout": {    "request": 10000,    "downloadFile": 10000  },  "debug": true,  "navigateToMiniProgramAppIdList": [    "wxe5f52902cf4de896"  ]}

              完整配置项说明请参考小程序全局配置

              页面配置

              每一个小程序页面也可以使用同名 .json 文件来对本页面的窗口表现进行配置,页面中配置项会覆盖 app.json 的 window 中相同的配置项。

              完整配置项说明请参考小程序页面配置

              例如:

              {  "navigationBarBackgroundColor": "#ffffff",  "navigationBarTextStyle": "black",  "navigationBarTitleText": "微信接口功能演示",  "backgroundColor": "#eeeeee",  "backgroundTextStyle": "light"}


              全局配置

              小程序根目录下的 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/index",      "text": "日志"    }]  },  "networkTimeout": {    "request": 10000,    "downloadFile": 10000  },  "debug": true,  "navigateToMiniProgramAppIdList": [    "wxe5f52902cf4de896"  ]}

              完整配置项说明请参考小程序全局配置

              页面配置

              每一个小程序页面也可以使用同名 .json 文件来对本页面的窗口表现进行配置,页面中配置项会覆盖 app.json 的 window 中相同的配置项。

              完整配置项说明请参考小程序页面配置

              例如:

              {  "navigationBarBackgroundColor": "#ffffff",  "navigationBarTextStyle": "black",  "navigationBarTitleText": "微信接口功能演示",  "backgroundColor": "#eeeeee",  "backgroundTextStyle": "light"}


              微信现已开放小程序内搜索,开发者可以通过 sitemap.json 配置,或者管理后台页面收录开关来配置其小程序页面是否允许微信索引。当开发者允许微信索引时,微信会通过爬虫的形式,为小程序的页面内容建立索引。当用户的搜索词条触发该索引时,小程序的页面将可能展示在搜索结果中。 爬虫访问小程序内页面时,会携带特定的 user-agent:mpcrawler 及场景值:1129。需要注意的是,若小程序爬虫发现的页面数据和真实用户的呈现不一致,那么该页面将不会进入索引中。

              具体配置说明

              1. 页面收录设置:可对整个小程序的索引进行关闭,小程序管理后台-功能-页面内容接入-页面收录开关;详情
              2. sitemap 配置:可对特定页面的索引进行关闭

              sitemap 配置

              小程序根目录下的 sitemap.json 文件用来配置小程序及其页面是否允许被微信索引。

              完整配置项说明请参考小程序 sitemap 配置

              例1:

              {  "rules":[{    "action": "allow",    "page": "*"  }]}

              所有页面都会被微信索引(默认情况)

              例2:

              {  "rules":[{    "action": "disallow",    "page": "path/to/page"  }]}

              配置 path/to/page 页面不被索引,其余页面允许被索引

              例3:

              {  "rules":[{    "action": "allow",    "page": "path/to/page"  }, {    "action": "disallow",    "page": "*"  }]}

              配置 path/to/page 页面被索引,其余页面不被索引

              例4:

              {  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "inclusive"  }, {    "action": "allow",    "page": "*"  }]}

              包含 a 和 b 参数的 path/to/page 页面会被微信优先索引,其他页面都会被索引,例如:

              • path/to/page?a=1&b=2 => 优先被索引
              • path/to/page?a=1&b=2&c=3 => 优先被索引
              • path/to/page => 被索引
              • path/to/page?a=1 => 被索引
              • 其他页面都会被索引

              例5:

              {  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "inclusive"  }, {    "action": "disallow",    "page": "*"  }, {    "action": "allow",    "page": "*"  }]}
              • path/to/page?a=1&b=2 => 优先被索引
              • path/to/page?a=1&b=2&c=3 => 优先被索引
              • path/to/page => 不被索引
              • path/to/page?a=1 => 不被索引
              • 其他页面由于命中第二条规则,所以不会被索引
              • 由于优先级的问题,第三条规则是没有意义的

              注:没有 sitemap.json 则默认所有页面都能被索引

              注:{"action": "allow", "page": "*"} 是优先级最低的默认规则,未显式指明 "disallow" 的都默认被索引

              如何调试

              当在小程序项目中设置了 sitemap 的配置文件(默认为 sitemap.json)时,便可在开发者工具控制台上显示当前页面是否被索引的调试信息( 最新版本的开发者工具支持索引提示)

              sitemap.png

              注:sitemap 的索引提示是默认开启的,如需要关闭 sitemap 的索引提示,可在小程序项目配置文件 project.config.json 的 setting 中配置字段 checkSiteMap 为 false

              注: sitemap 文件内容最大为 5120 个 UTF8 字符


              场景值

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

              场景值用来描述用户进入小程序的路径。完整场景值的含义请查看场景值列表

              由于Android系统限制,目前还无法获取到按 Home 键退出到桌面,然后从桌面再次进小程序的场景值,对于这种情况,会保留上一次的场景值。

              获取场景值

              开发者可以通过下列方式获取场景值:

              • 对于小程序,可以在 App 的 onLaunch 和 onShow,或wx.getLaunchOptionsSync 中获取上述场景值。
              • 对于小游戏,可以在 wx.getLaunchOptionsSync 和 wx.onShow 中获取上述场景值

              返回来源信息的场景

              部分场景值下还可以获取来源应用、公众号或小程序的appId。获取方式请参考对应API的参考文档。

              场景值场景appId含义
              1020公众号 profile 页相关小程序列表来源公众号
              1035公众号自定义菜单来源公众号
              1036App 分享消息卡片来源App
              1037小程序打开小程序来源小程序
              1038从另一个小程序返回来源小程序
              1043公众号模板消息来源公众号


              注册小程序

              每个小程序都需要在 app.js 中调用 App 方法注册小程序实例,绑定生命周期回调函数、错误监听和页面不存在监听函数等。

              详细的参数含义和使用请参考 App 参考文档 。

              // app.jsApp({  onLaunch (options) {    // Do something initial when launch.  },  onShow (options) {    // Do something when show.  },  onHide () {    // Do something when hide.  },  onError (msg) {    console.log(msg)  },  globalData: 'I am global data'})

              整个小程序只有一个 App 实例,是全部页面共享的。开发者可以通过 getApp 方法获取到全局唯一的 App 实例,获取App上的数据或调用开发者注册在 App 上的函数。

              // xxx.jsconst appInstance = getApp()console.log(appInstance.globalData) // I am global data


              注册页面

              对于小程序中的每个页面,都需要在页面对应的 js 文件中进行注册,指定页面的初始数据、生命周期回调、事件处理函数等。

              使用 Page 构造器注册页面

              简单的页面可以使用 Page() 进行构造。

              代码示例:

              //index.jsPage({  data: {    text: "This is page data."  },  onLoad: function(options) {    // 页面创建时执行  },  onShow: function() {    // 页面出现在前台时执行  },  onReady: function() {    // 页面首次渲染完毕时执行  },  onHide: function() {    // 页面从前台变为后台时执行  },  onUnload: function() {    // 页面销毁时执行  },  onPullDownRefresh: function() {    // 触发下拉刷新时执行  },  onReachBottom: function() {    // 页面触底时执行  },  onShareAppMessage: function () {    // 页面被用户分享时执行  },  onPageScroll: function() {    // 页面滚动时执行  },  onResize: function() {    // 页面尺寸变化时执行  },  onTabItemTap(item) {    // tab 点击时执行    console.log(item.index)    console.log(item.pagePath)    console.log(item.text)  },  // 事件响应函数  viewTap: function() {    this.setData({      text: 'Set some data for updating view.'    }, function() {      // this is setData callback    })  },  // 自由数据  customData: {    hi: 'MINA'  }})

              详细的参数含义和使用请参考 Page 参考文档 。

              在页面中使用 behaviors

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

              页面可以引用 behaviors 。 behaviors 可以用来让多个页面有相同的数据字段和方法。

              // my-behavior.jsmodule.exports = Behavior({  data: {    sharedText: 'This is a piece of data shared between pages.'  },  methods: {    sharedMethod: function() {      this.data.sharedText === 'This is a piece of data shared between pages.'    }  }})
              // page-a.jsvar myBehavior = require('./my-behavior.js')Page({  behaviors: [myBehavior],  onLoad: function() {    this.data.sharedText === 'This is a piece of data shared between pages.'  }})

              具体用法参见 behaviors 。

              使用 Component 构造器构造页面

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

              Page 构造器适用于简单的页面。但对于复杂的页面, Page 构造器可能并不好用。

              此时,可以使用 Component 构造器来构造页面。 Component 构造器的主要区别是:方法需要放在 methods: { } 里面。

              代码示例:

              Component({  data: {    text: "This is page data."  },  methods: {    onLoad: function(options) {      // 页面创建时执行    },    onPullDownRefresh: function() {      // 下拉刷新时执行    },    // 事件响应函数    viewTap: function() {      // ...    }  }})

              这种创建方式非常类似于 自定义组件 ,可以像自定义组件一样使用 behaviors 等高级特性。

              具体细节请阅读 Component 构造器 章节。


              生命周期

              以下内容你不需要立马完全弄明白,不过以后它会有帮助。

              下图说明了页面 Page 实例的生命周期。


              页面路由

              在小程序中所有页面的路由全部由框架进行管理。

              页面栈

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

              路由方式页面栈表现
              初始化新页面入栈
              打开新页面新页面入栈
              页面重定向当前页面出栈,新页面入栈
              页面返回页面不断出栈,直到目标返回页
              Tab 切换页面全部出栈,只留下新的 Tab 页面
              重加载页面全部出栈,只留下新的页面

              开发者可以使用 getCurrentPages() 函数获取当前页面栈。

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

              页面栈示例:页面栈遵循先进后出的规则,当前也在最上面。

              路由方式

              对于路由的触发方式以及页面生命周期函数如下:

              路由方式触发时机路由前页面路由后页面
              初始化小程序打开的第一个页面onLoad, onShow
              打开新页面调用 API wx.navigateTo
              使用组件 <navigator open-type="navigateTo"/>
              onHideonLoad, onShow
              页面重定向调用 API wx.redirectTo
              使用组件 <navigator open-type="redirectTo"/>
              onUnloadonLoad, onShow
              页面返回调用 API wx.navigateBack
              使用组件<navigator open-type="navigateBack">
              用户按左上角返回按钮
              onUnloadonShow
              Tab 切换调用 API wx.switchTab
              使用组件 <navigator open-type="switchTab"/>
              用户切换 Tab
              各种情况请参考下表
              重启动调用 API wx.reLaunch
              使用组件 <navigator open-type="reLaunch"/>
              onUnloadonLoad, onShow

              Tab 切换对应的生命周期(以 A、B 页面为 Tabbar 页面,C 是从 A 页面打开的页面,D 页面是从 C 页面打开的页面为例):

              当前页面路由后页面触发的生命周期(按顺序)
              AANothing happend
              ABA.onHide(), B.onLoad(), B.onShow()
              AB(再次打开)A.onHide(), B.onShow()
              CAC.onUnload(), A.onShow()
              CBC.onUnload(), B.onLoad(), B.onShow()
              DBD.onUnload(), C.onUnload(), B.onLoad(), B.onShow()
              D(从转发进入)AD.onUnload(), A.onLoad(), A.onShow()
              D(从转发进入)BD.onUnload(), B.onLoad(), B.onShow()

              Tips:

              • navigateToredirectTo 只能打开非 tabBar 页面。
              • switchTab 只能打开tabBar 页面。
              • reLaunch 可以打开任意页面。
              • 页面底部的 tabBar 由页面决定,即只要是定义为 tabBar 的页面,底部都有 tabBar
              • 调用页面路由带的参数可以在目标页面的onLoad中获取。


              模块化

              可以将一些公共的代码抽离成为一个单独的 js 文件,作为一个模块。模块只有通过 module.exports 或者 exports 才能对外暴露接口。

              注意:

              • exports 是 module.exports 的一个引用,因此在模块里边随意更改 exports 的指向会造成未知的错误。所以更推荐开发者采用 module.exports 来暴露模块接口,除非你已经清晰知道这两者的关系。
              • 小程序目前不支持直接引入 node_modules , 开发者需要使用到 node_modules 时候建议拷贝出相关的代码到小程序的目录中,或者使用小程序支持的 npm 功能。
              // common.jsfunction sayHello(name) {  console.log(`Hello ${name} !`)}function sayGoodbye(name) {  console.log(`Goodbye ${name} !`)}module.exports.sayHello = sayHelloexports.sayGoodbye = sayGoodbye

              ​在需要使用这些模块的文件中,使用 require 将公共代码引入

              var common = require('common.js')Page({  helloMINA: function() {    common.sayHello('MINA')  },  goodbyeMINA: function() {    common.sayGoodbye('MINA')  }})

              文件作用域

              在 JavaScript 文件中声明的变量和函数只在该文件中有效;不同的文件中可以声明相同名字的变量和函数,不会互相影响。

              通过全局函数 getApp 可以获取全局的应用实例,如果需要全局的数据可以在 App() 中设置,如:

              // app.jsApp({  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)


              API

              小程序开发框架提供丰富的微信原生 API,可以方便的调起微信提供的能力,如获取用户信息,本地存储,支付功能等。详细介绍请参考 API 文档

              通常,在小程序 API 有以下几种类型:

              事件监听 API

              我们约定,以 on 开头的 API 用来监听某个事件是否触发,如:wx.onSocketOpenwx.onCompassChange 等。

              这类 API 接受一个回调函数作为参数,当事件触发时会调用这个回调函数,并将相关数据以参数形式传入。

              代码示例

              wx.onCompassChange(function (res) {  console.log(res.direction)})

              同步 API

              我们约定,以 Sync 结尾的 API 都是同步 API, 如 wx.setStorageSyncwx.getSystemInfoSync 等。此外,也有一些其他的同步 API,如 wx.createWorkerwx.getBackgroundAudioManager 等,详情参见 API 文档中的说明。

              同步 API 的执行结果可以通过函数返回值直接获取,如果执行出错会抛出异常。

              代码示例

              try {  wx.setStorageSync('key', 'value')} catch (e) {  console.error(e)}

              异步 API

              大多数 API 都是异步 API,如 wx.requestwx.login 等。这类 API 接口通常都接受一个 Object 类型的参数,这个参数都支持按需指定以下字段来接收接口调用结果:

              Object 参数说明

              参数名类型必填说明
              successfunction接口调用成功的回调函数
              failfunction接口调用失败的回调函数
              completefunction接口调用结束的回调函数(调用成功、失败都会执行)
              其他Any-接口定义的其他参数

              回调函数的参数

              success,fail,complete 函数调用时会传入一个 Object 类型参数,包含以下字段:

              属性类型说明
              errMsgstring错误信息,如果调用成功返回 ${apiName}:ok
              errCodenumber错误码,仅部分 API 支持,具体含义请参考对应 API 文档,成功时为 0
              其他Any接口返回的其他数据

              异步 API 的执行结果需要通过 Object 类型的参数中传入的对应回调函数获取。部分异步 API 也会有返回值,可以用来实现更丰富的功能,如 wx.requestwx.connectSocket 等。

              代码示例

              wx.login({  success(res) {    console.log(res.code)  }})

              异步 API 返回 Promise

              基础库 2.10.2 版本起,异步 API 支持 callback & promise 两种调用方式。当接口参数 Object 对象中不包含 success/fail/complete 时将默认返回 promise,否则仍按回调方式执行,无返回值。

              注意事项

              1. 部分接口如 downloadFile, request, uploadFile, connectSocket, createCamera(小游戏)本身就有返回值, 它们的 promisify 需要开发者自行封装。
              2. 当没有回调参数时,异步接口返回 promise。此时若函数调用失败进入 fail 逻辑, 会报错提示 Uncaught (in promise),开发者可通过 catch 来进行捕获。
              3. wx.onUnhandledRejection 可以监听未处理的 Promise 拒绝事件。

              代码示例

              // callback 形式调用wx.chooseImage({  success(res) {    console.log('res:', res)  }})// promise 形式调用wx.chooseImage().then(res => console.log('res: ', res))


              WXML

              WXML(WeiXin Markup Language)是框架设计的一套标签语言,结合基础组件事件系统,可以构建出页面的结构。

              要完整了解 WXML 语法,请参考WXML 语法参考

              用以下一些简单的例子来看看 WXML 具有什么能力:

              数据绑定

              <!--wxml--><view> {{message}} </view>
              // page.jsPage({  data: {    message: 'Hello MINA!'  }})

              列表渲染

              <!--wxml--><view wx:for="{{array}}"> {{item}} </view>
              // page.jsPage({  data: {    array: [1, 2, 3, 4, 5]  }})

              条件渲染

              <!--wxml--><view wx:if="{{view == 'WEBVIEW'}}"> WEBVIEW </view><view wx:elif="{{view == 'APP'}}"> APP </view><view wx:else="{{view == 'MINA'}}"> MINA </view>
              // page.jsPage({  data: {    view: 'MINA'  }})

              模板

              <!--wxml--><template name="staffName">  <view>    FirstName: {{firstName}}, LastName: {{lastName}}  </view></template><template is="staffName" data="{{...staffA}}"></template><template is="staffName" data="{{...staffB}}"></template><template is="staffName" data="{{...staffC}}"></template>
              // page.jsPage({  data: {    staffA: {firstName: 'Hulk', lastName: 'Hu'},    staffB: {firstName: 'Shang', lastName: 'You'},    staffC: {firstName: 'Gideon', lastName: 'Lin'}  }})

              引用

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

              具体的能力以及使用方式在以下章节查看:

              数据绑定列表渲染条件渲染模板引用


              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/屏幕宽度)
              iPhone51rpx = 0.42px1px = 2.34rpx
              iPhone61rpx = 0.5px1px = 2rpx
              iPhone6 Plus1rpx = 0.552px1px = 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" 的组件
              elementview选择所有 view 组件
              element, elementview, checkbox选择所有文档的 view 组件和所有的 checkbox 组件
              ::afterview::after在 view 组件后边插入内容
              ::beforeview::before在 view 组件前边插入内容

              全局样式与局部样式

              定义在 app.wxss 中的样式为全局样式,作用于每一个页面。在 page 的 wxss 文件中定义的样式为局部样式,只作用在对应的页面,并会覆盖 app.wxss 中相同的选择器。


              WXS

              WXS(WeiXin Script)是小程序的一套脚本语言,结合 WXML,可以构建出页面的结构。

              注意

              1. WXS 不依赖于运行时的基础库版本,可以在所有版本的小程序中运行。
              2. WXS 与 JavaScript 是不同的语言,有自己的语法,并不和 JavaScript 一致。
              3. WXS 的运行环境和其他 JavaScript 代码是隔离的,WXS 中不能调用其他 JavaScript 文件中定义的函数,也不能调用小程序提供的API。
              4. WXS 函数不能作为组件的事件回调。
              5. 由于运行环境的差异,在 iOS 设备上小程序内的 WXS 会比 JavaScript 代码快 2 ~ 20 倍。在 android 设备上二者运行效率无差异。

              以下是一些使用 WXS 的简单示例,要完整了解 WXS 语法,请参考WXS 语法参考

              页面渲染

              <!--wxml--><wxs module="m1">var msg = "hello world";module.exports.message = msg;</wxs><view> {{m1.message}} </view>

              页面输出:

              hello world

              数据处理

              // page.jsPage({  data: {    array: [1, 2, 3, 4, 5, 1, 2, 3, 4]  }})
              <!--wxml--><!-- 下面的 getMax 函数,接受一个数组,且返回数组中最大的元素的值 --><wxs module="m1">var getMax = function(array) {  var max = undefined;  for (var i = 0; i < array.length; ++i) {    max = max === undefined ?      array[i] :      (max >= array[i] ? max : array[i]);  }  return max;}module.exports.getMax = getMax;</wxs><!-- 调用 wxs 里面的 getMax 函数,参数为 page.js 里面的 array --><view> {{m1.getMax(array)}} </view>

              页面输出:

              5


              事件

              什么是事件

              • 事件是视图层到逻辑层的通讯方式。
              • 事件可以将用户的行为反馈到逻辑层进行处理。
              • 事件可以绑定在组件上,当达到触发事件,就会执行逻辑层中对应的事件处理函数。
              • 事件对象可以携带额外信息,如 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函数响应事件。

              事件详解

              事件分类

              事件分为冒泡事件和非冒泡事件:

              1. 冒泡事件:当一个组件上的事件被触发后,该事件会向父节点传递。
              2. 非冒泡事件:当一个组件上的事件被触发后,该事件不会向父节点传递。

              WXML的冒泡事件列表:

              类型触发条件最低版本
              touchstart手指触摸动作开始
              touchmove手指触摸后移动
              touchcancel手指触摸动作被打断,如来电提醒,弹窗
              touchend手指触摸动作结束
              tap手指触摸后马上离开
              longpress手指触摸后,超过350ms再离开,如果指定了事件回调函数并触发了这个事件,tap事件将不被触发1.5.0
              longtap手指触摸后,超过350ms再离开(推荐使用longpress事件代替)
              transitionend会在 WXSS transition 或 wx.createAnimation 动画结束后触发
              animationstart会在一个 WXSS animation 动画开始时触发
              animationiteration会在一个 WXSS animation 一次迭代结束时触发
              animationend会在一个 WXSS animation 动画完成时触发
              touchforcechange在支持 3D Touch 的 iPhone 设备,重按时会触发1.9.90

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

              普通事件绑定

              事件绑定的写法类似于组件的属性,如:

              <view bindtap="handleTap">    Click here!</view>

              如果用户点击这个 view ,则页面的 handleTap 会被调用。

              事件绑定函数可以是一个数据绑定,如:

              <view bindtap="{{ handlerName }}">    Click here!</view>

              此时,页面的 this.data.handlerName 必须是一个字符串,指定事件处理函数名;如果它是个空字符串,则这个绑定会失效(可以利用这个特性来暂时禁用一些事件)。

              自基础库版本 1.5.0 起,在大多数组件和自定义组件中, bind 后可以紧跟一个冒号,其含义不变,如 bind:tap 。基础库版本 2.8.1 起,在所有组件中开始提供这个支持。

              绑定并阻止事件冒泡

              除 bind 外,也可以用 catch 来绑定事件。与 bind 不同, catch 会阻止事件向上冒泡。

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

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

              互斥事件绑定

              自基础库版本 2.8.2 起,除 bind 和 catch 外,还可以使用 mut-bind 来绑定事件。一个 mut-bind 触发后,如果事件冒泡到其他节点上,其他节点上的 mut-bind 绑定函数不会被触发,但 bind 绑定函数和 catch 绑定函数依旧会被触发。

              换而言之,所有 mut-bind 是“互斥”的,只会有其中一个绑定函数被触发。同时,它完全不影响 bind 和 catch 的绑定效果。

              例如在下边这个例子中,点击 inner view 会先后调用 handleTap3 和 handleTap2 ,点击 middle view 会调用 handleTap2 和 handleTap1 。

              <view id="outer" mut-bind:tap="handleTap1">  outer view  <view id="middle" bindtap="handleTap2">    middle view    <view id="inner" mut-bind:tap="handleTap3">      inner view    </view>  </view></view>

              事件的捕获阶段

              自基础库版本 1.5.0 起,触摸类事件支持捕获阶段。捕获阶段位于冒泡阶段之前,且在捕获阶段中,事件到达节点的顺序与冒泡阶段恰好相反。需要在捕获阶段监听事件时,可以采用capture-bind、capture-catch关键字,后者将中断捕获阶段和取消冒泡阶段。

              在下面的代码中,点击 inner view 会先后调用handleTap2、handleTap4、handleTap3、handleTap1。

              <view id="outer" bind:touchstart="handleTap1" capture-bind:touchstart="handleTap2">  outer view  <view id="inner" bind:touchstart="handleTap3" capture-bind:touchstart="handleTap4">    inner view  </view></view>

              如果将上面代码中的第一个capture-bind改为capture-catch,将只触发handleTap2。

              <view id="outer" bind:touchstart="handleTap1" capture-catch:touchstart="handleTap2">  outer view  <view id="inner" bind:touchstart="handleTap3" capture-bind:touchstart="handleTap4">    inner view  </view></view>

              事件对象

              如无特殊说明,当组件触发事件时,逻辑层绑定该事件的处理函数会收到一个事件对象。

              BaseEvent 基础事件对象属性列表:

              属性类型说明基础库版本
              typeString事件类型
              timeStampInteger事件生成时的时间戳
              targetObject触发事件的组件的一些属性值集合
              currentTargetObject当前组件的一些属性值集合
              markObject事件标记数据2.7.1

              CustomEvent 自定义事件对象属性列表(继承 BaseEvent):

              属性类型说明
              detailObject额外的信息

              TouchEvent 触摸事件对象属性列表(继承 BaseEvent):

              属性类型说明
              touchesArray触摸事件,当前停留在屏幕中的触摸点信息的数组
              changedTouchesArray触摸事件,当前变化的触摸点信息的数组

              特殊事件: canvas 中的触摸事件不可冒泡,所以没有 currentTarget。

              type

              代表事件的类型。

              timeStamp

              页面打开到触发事件所经过的毫秒数。

              target

              触发事件的源组件。

              属性类型说明
              idString事件源组件的id
              datasetObject事件源组件上由data-开头的自定义属性组成的集合

              currentTarget

              事件绑定的当前组件。

              属性类型说明
              idString当前组件的id
              datasetObject当前组件上由data-开头的自定义属性组成的集合

              说明: target 和 currentTarget 可以参考上例中,点击 inner view 时,handleTap3 收到的事件对象 target 和 currentTarget 都是 inner,而 handleTap2 收到的事件对象 target 就是 inner,currentTarget 就是 middle。

              dataset

              在组件节点中可以附加一些自定义数据。这样,在事件中可以获取这些自定义的节点数据,用于事件的逻辑处理。

              在 WXML 中,这些自定义数据以 data- 开头,多个单词由连字符 - 连接。这种写法中,连字符写法会转换成驼峰写法,而大写字符会自动转成小写字符。如:

              • data-element-type ,最终会呈现为 event.currentTarget.dataset.elementType ;
              • data-elementType ,最终会呈现为 event.currentTarget.dataset.elementtype 。

              示例:

              <view data-alpha-beta="1" data-alphaBeta="2" bindtap="bindViewTap"> DataSet Test </view>
              Page({  bindViewTap:function(event){    event.currentTarget.dataset.alphaBeta === 1 // - 会转为驼峰写法    event.currentTarget.dataset.alphabeta === 2 // 大写会转为小写  }})

              mark

              在基础库版本 2.7.1 以上,可以使用 mark 来识别具体触发事件的 target 节点。此外, mark 还可以用于承载一些自定义数据(类似于 dataset )。

              当事件触发时,事件冒泡路径上所有的 mark 会被合并,并返回给事件回调函数。(即使事件不是冒泡事件,也会 mark 。)

              代码示例:

              <view mark:myMark="last" bindtap="bindViewTap">  <button mark:anotherMark="leaf" bindtap="bindButtonTap">按钮</button></view>

              在上述 WXML 中,如果按钮被点击,将触发 bindViewTap 和 bindButtonTap 两个事件,事件携带的 event.mark 将包含 myMark 和 anotherMark 两项。

              Page({  bindViewTap: function(e) {    e.mark.myMark === "last" // true    e.mark.anotherMark === "leaf" // true  }})

              mark 和 dataset 很相似,主要区别在于: mark 会包含从触发事件的节点到根节点上所有的 mark: 属性值;而 dataset 仅包含一个节点的 data- 属性值。

              细节注意事项:

              • 如果存在同名的 mark ,父节点的 mark 会被子节点覆盖。
              • 在自定义组件中接收事件时, mark 不包含自定义组件外的节点的 mark 。
              • 不同于 dataset ,节点的 mark 不会做连字符和大小写转换。

              touches

              touches 是一个数组,每个元素为一个 Touch 对象(canvas 触摸事件中携带的 touches 是 CanvasTouch 数组)。 表示当前停留在屏幕上的触摸点。

              Touch 对象

              属性类型说明
              identifierNumber触摸点的标识符
              pageX, pageYNumber距离文档左上角的距离,文档的左上角为原点 ,横向为X轴,纵向为Y轴
              clientX, clientYNumber距离页面可显示区域(屏幕除去导航条)左上角距离,横向为X轴,纵向为Y轴

              CanvasTouch 对象

              属性类型说明特殊说明
              identifierNumber触摸点的标识符
              x, yNumber距离 Canvas 左上角的距离,Canvas 的左上角为原点 ,横向为X轴,纵向为Y轴

              changedTouches

              changedTouches 数据格式同 touches。 表示有变化的触摸点,如从无变有(touchstart),位置变化(touchmove),从有变无(touchend、touchcancel)。

              detail

              自定义事件所携带的数据,如表单组件的提交事件会携带用户的输入,媒体的错误事件会携带错误信息,详见组件定义中各个事件的定义。

              点击事件的detail 带有的 x, y 同 pageX, pageY 代表距离文档左上角的距离。


              WXS响应事件

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

              背景

              有频繁用户交互的效果在小程序上表现是比较卡顿的,例如页面有 2 个元素 A 和 B,用户在 A 上做 touchmove 手势,要求 B 也跟随移动,movable-view 就是一个典型的例子。一次 touchmove 事件的响应过程为:

              a、touchmove 事件从视图层(Webview)抛到逻辑层(App Service)

              b、逻辑层(App Service)处理 touchmove 事件,再通过 setData 来改变 B 的位置

              一次 touchmove 的响应需要经过 2 次的逻辑层和渲染层的通信以及一次渲染,通信的耗时比较大。此外 setData 渲染也会阻塞其它脚本执行,导致了整个用户交互的动画过程会有延迟。

              实现方案

              本方案基本的思路是减少通信的次数,让事件在视图层(Webview)响应。小程序的框架分为视图层(Webview)和逻辑层(App Service),这样分层的目的是管控,开发者的代码只能运行在逻辑层(App Service),而这个思路就必须要让开发者的代码运行在视图层(Webview),如下图所示的流程:

              使用 WXS 函数用来响应小程序事件,目前只能响应内置组件的事件,不支持自定义组件事件。WXS 函数的除了纯逻辑的运算,还可以通过封装好的ComponentDescriptor 实例来访问以及设置组件的 class 和样式,对于交互动画,设置 style 和 class 足够了。WXS 函数的例子如下:

              var wxsFunction = function(event, ownerInstance) {    var instance = ownerInstance.selectComponent('.classSelector') // 返回组件的实例    instance.setStyle({        "font-size": "14px" // 支持rpx    })    instance.getDataset()    instance.setClass(className)    // ...    return false // 不往上冒泡,相当于调用了同时调用了stopPropagation和preventDefault}

              其中入参 event 是小程序事件对象基础上多了 event.instance 来表示触发事件的组件的 ComponentDescriptor 实例。ownerInstance 表示的是触发事件的组件所在的组件的 ComponentDescriptor 实例,如果触发事件的组件是在页面内的,ownerInstance 表示的是页面实例。

              ComponentDescriptor的定义如下:

              方法参数描述最低版本
              selectComponentselector对象返回组件的 ComponentDescriptor 实例。
              selectAllComponentsselector对象数组返回组件的 ComponentDescriptor 实例数组。
              setStyleObject/string设置组件样式,支持rpx。设置的样式优先级比组件 wxml 里面定义的样式高。不能设置最顶层页面的样式。
              addClass/removeClass/ hasClassstring设置组件的 class。设置的 class 优先级比组件 wxml 里面定义的 class 高。不能设置最顶层页面的 class。
              getDataset返回当前组件/页面的 dataset 对象
              callMethod(funcName:string, args:object)调用当前组件/页面在逻辑层(App Service)定义的函数。funcName表示函数名称,args表示函数的参数。
              requestAnimationFrameFunction和原生 requestAnimationFrame 一样。用于设置动画。
              getState返回一个object对象,当有局部变量需要存储起来后续使用的时候用这个方法。
              triggerEvent(eventName, detail)和组件的triggerEvent一致。
              getComputedStyleArray.<string>参数与 SelectorQuery 的 computedStyle 一致。2.11.2

              WXS 运行在视图层(Webview),里面的逻辑毕竟能做的事件比较少,需要有一个机制和逻辑层(App Service)开发者的代码通信,上面的 callMethod 是 WXS 里面调用逻辑层(App Service)开发者的代码的方法,而 WxsPropObserver 是逻辑层(App Service)开发者的代码调用 WXS 逻辑的机制。

              使用方法

              • WXML定义事件:
              <wxs module="test" src="./test.wxs"></wxs><view change:prop="{{test.propObserver}}" prop="{{propValue}}" bindtouchmove="{{test.touchmove}}" class="movable"></view>

              上面的change:prop(属性前面带change:前缀)是在 prop 属性被设置的时候触发 WXS 函数,值必须用{{}}括起来。类似 Component 定义的 properties 里面的 observer 属性,在setData({propValue: newValue})调用之后会触发。

              注意:WXS函数必须用{{}}括起来。当 prop 的值被设置 WXS 函数就会触发,而不只是值发生改变,所以在页面初始化的时候会调用一次WxsPropObserver的函数。

              • WXS文件test.wxs里面定义并导出事件处理函数和属性改变触发的函数:
              module.exports = {    touchmove: function(event, instance) {        console.log('log event', JSON.stringify(event))    },    propObserver: function(newValue, oldValue, ownerInstance, instance) {        console.log('prop observer', newValue, oldValue)    }}

              提示:

              1. 目前还不支持原生组件的事件、input和textarea组件的 bindinput 事件
              2. 1.02.1901170及以后版本的开发者工具上支持交互动画,最低版本基础库是2.4.4
              3. 目前在WXS函数里面仅支持console.log方式打日志定位问题,注意连续的重复日志会被过滤掉。


              简易双向绑定

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

              双向绑定语法

              在 WXML 中,普通的属性的绑定是单向的。例如:

              <input value="{{value}}" />

              如果使用 this.setData({ value: 'leaf' }) 来更新 value ,this.data.value 和输入框的中显示的值都会被更新为 leaf ;但如果用户修改了输入框里的值,却不会同时改变 this.data.value 。

              如果需要在用户输入的同时改变 this.data.value ,需要借助简易双向绑定机制。此时,可以在对应项目之前加入 model: 前缀:

              <input model:value="{{value}}" />

              这样,如果输入框的值被改变了, this.data.value 也会同时改变。同时, WXML 中所有绑定了 value 的位置也会被一同更新, 数据监听器 也会被正常触发。

              用于双向绑定的表达式有如下限制:

                  1.只能是一个单一字段的绑定,如

              <input model:value="值为 {{value}}" /><input model:value="{{ a + b }}" />

              都是非法的;

                  2.目前,尚不能 data 路径,如

              <input model:value="{{ a.b }}" />

              这样的表达式目前暂不支持。

              在自定义组件中传递双向绑定

              双向绑定同样可以使用在自定义组件上。如下的自定义组件:

              // custom-component.jsComponent({  properties: {    myValue: String  }})
              <!-- custom-component.wxml --><input model:value="{{myValue}}" />

              这个自定义组件将自身的 myValue 属性双向绑定到了组件内输入框的 value 属性上。这样,如果页面这样使用这个组件:

              <custom-component model:my-value="{{pageValue}}" />

              当输入框的值变更时,自定义组件的 myValue 属性会同时变更,这样,页面的 this.data.pageValue 也会同时变更,页面 WXML 中所有绑定了 pageValue 的位置也会被一同更新。

              在自定义组件中触发双向绑定更新

              自定义组件还可以自己触发双向绑定更新,做法就是:使用 setData 设置自身的属性。例如:

              // custom-component.jsComponent({  properties: {    myValue: String  },  methods: {    update: function() {      // 更新 myValue      this.setData({        myValue: 'leaf'      })    }  }})

              如果页面这样使用这个组件:

              <custom-component model:my-value="{{pageValue}}" />

              当组件使用 setData 更新 myValue 时,页面的 this.data.pageValue 也会同时变更,页面 WXML 中所有绑定了 pageValue 的位置也会被一同更新。


              基础组件

              框架为开发者提供了一系列基础组件,开发者可以通过组合这些基础组件进行快速开发。详细介绍请参考组件文档

              什么是组件:

              • 组件是视图层的基本组成单元。
              • 组件自带一些功能与微信风格一致的样式。
              • 一个组件通常包括 开始标签 和 结束标签,属性 用来修饰这个组件,内容 在两个标签之内。
              <tagname property="value">Content goes here ...</tagname>

              注意:所有组件与属性都是小写,以连字符-连接

              属性类型

              类型描述注解
              Boolean布尔值组件写上该属性,不管是什么值都被当作 true;只有组件上没有该属性时,属性值才为false
              如果属性值为变量,变量的值会被转换为Boolean类型
              Number数字12.5
              String字符串"string"
              Array数组[ 1, "string" ]
              Object对象{ key: value }
              EventHandler事件处理函数名"handlerName" 是 Page 中定义的事件处理函数名
              Any任意属性

              公共属性

              所有组件都有以下属性:

              属性名类型描述注解
              idString组件的唯一标示保持整个页面唯一
              classString组件的样式类在对应的 WXSS 中定义的样式类
              styleString组件的内联样式可以动态设置的内联样式
              hiddenBoolean组件是否显示所有组件默认显示
              data-*Any自定义属性组件上触发的事件时,会发送给事件处理函数
              bind* / catch*EventHandler组件的事件详见事件

              特殊属性

              几乎所有组件都有各自定义的属性,可以对该组件的功能或样式进行修饰,请参考各个组件的定义。


              获取界面上的节点信息

              WXML节点信息

              节点信息查询 API 可以用于获取节点属性、样式、在界面上的位置等信息。

              最常见的用法是使用这个接口来查询某个节点的当前位置,以及界面的滚动位置。

              示例代码:

              const query = wx.createSelectorQuery()query.select('#the-id').boundingClientRect(function(res){  res.top // #the-id 节点的上边界坐标(相对于显示区域)})query.selectViewport().scrollOffset(function(res){  res.scrollTop // 显示区域的竖直滚动位置})query.exec()

              上述示例中, #the-id 是一个节点选择器,与 CSS 的选择器相近但略有区别,请参见 SelectorQuery.select 的相关说明。

              在自定义组件或包含自定义组件的页面中,推荐使用 this.createSelectorQuery 来代替 wx.createSelectorQuery ,这样可以确保在正确的范围内选择节点。

              WXML节点布局相交状态

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

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

              • 参照节点:监听的参照节点,取它的布局区域作为参照区域。如果有多个参照节点,则会取它们布局区域的 交集 作为参照区域。页面显示区域也可作为参照区域之一。
              • 目标节点:监听的目标,默认只能是一个节点(使用 selectAll 选项时,可以同时监听多个节点)。
              • 相交区域:目标节点的布局区域与参照区域的相交区域。
              • 相交比例:相交区域占参照区域的比例。
              • 阈值:相交比例如果达到阈值,则会触发监听器的回调函数。阈值可以有多个。

              以下示例代码可以在目标节点(用选择器 .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 // 相交区域的高度    })  }})

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

              在自定义组件或包含自定义组件的页面中,推荐使用 this.createIntersectionObserver 来代替 wx.createIntersectionObserver ,这样可以确保在正确的范围内选择节点。


              响应显示区域变化

              显示区域尺寸

              显示区域指小程序界面中可以自由布局展示的区域。在默认情况下,小程序显示区域的尺寸自页面初始化起就不会发生变化。但以下两种方式都可以改变这一默认行为。

              在手机上启用屏幕旋转支持

              从小程序基础库版本 2.4.0 开始,小程序在手机上支持屏幕旋转。使小程序中的页面支持屏幕旋转的方法是:在 app.json 的 window 段中设置 "pageOrientation": "auto" ,或在页面 json 文件中配置 "pageOrientation": "auto" 。

              以下是在单个页面 json 文件中启用屏幕旋转的示例。

              代码示例:

              {  "pageOrientation": "auto"}

              如果页面添加了上述声明,则在屏幕旋转时,这个页面将随之旋转,显示区域尺寸也会随着屏幕旋转而变化。

              从小程序基础库版本 2.5.0 开始, pageOrientation 还可以被设置为 landscape ,表示固定为横屏显示。

              在 iPad 上启用屏幕旋转支持

              从小程序基础库版本 2.3.0 开始,在 iPad 上运行的小程序可以支持屏幕旋转。使小程序支持 iPad 屏幕旋转的方法是:在 app.json 中添加 "resizable": true 。

              代码示例:

              {  "resizable": true}

              如果小程序添加了上述声明,则在屏幕旋转时,小程序将随之旋转,显示区域尺寸也会随着屏幕旋转而变化。注意:在 iPad 上不能单独配置某个页面是否支持屏幕旋转。

              Media Query

              有时,对于不同尺寸的显示区域,页面的布局会有所差异。此时可以使用 media query 来解决大多数问题。

              代码示例:

              .my-class {  width: 40px;}@media (min-width: 480px) {  /* 仅在 480px 或更宽的屏幕上生效的样式规则 */  .my-class {    width: 200px;  }}

              在 WXML 中,可以使用 match-media 组件来根据 media query 匹配状态展示、隐藏节点。

              此外,可以在页面或者自定义组件 JS 中使用 this.createMediaQueryObserver() 方法来创建一个 MediaQueryObserver 对象,用于监听指定的 media query 的匹配状态。

              屏幕旋转事件

              有时,仅仅使用 media query 无法控制一些精细的布局变化。此时可以使用 js 作为辅助。

              在 js 中读取页面的显示区域尺寸,可以使用 selectorQuery.selectViewport 。

              页面尺寸发生改变的事件,可以使用页面的 onResize 来监听。对于自定义组件,可以使用 resize 生命周期来监听。回调函数中将返回显示区域的尺寸信息。(从基础库版本 2.4.0 开始支持。)

              代码示例:

              Page({  onResize(res) {    res.size.windowWidth // 新的显示区域宽度    res.size.windowHeight // 新的显示区域高度  }})
              Component({  pageLifetimes: {    resize(res) {      res.size.windowWidth // 新的显示区域宽度      res.size.windowHeight // 新的显示区域高度    }  }})

              此外,还可以使用 wx.onWindowResize 来监听(但这不是推荐的方式)。

              Bug & tips:

              • Bug: Android 微信版本 6.7.3 中, live-pusher 组件在屏幕旋转时方向异常。


              动画

              界面动画的常见方式

              在小程序中,通常可以使用 CSS 渐变 和 CSS 动画 来创建简易的界面动画。

              动画过程中,可以使用 bindtransitionend bindanimationstart bindanimationiteration bindanimationend 来监听动画事件。

              事件名含义
              transitionendCSS 渐变结束或 wx.createAnimation 结束一个阶段
              animationstartCSS 动画开始
              animationiterationCSS 动画结束一个阶段
              animationendCSS 动画结束

              注意:这几个事件都不是冒泡事件,需要绑定在真正发生了动画的节点上才会生效。

              同时,还可以使用 wx.createAnimation 接口来动态创建简易的动画效果。(新版小程序基础库中推荐使用下述的关键帧动画接口代替。)

              关键帧动画

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

              从小程序基础库 2.9.0 开始支持一种更友好的动画创建方式,用于代替旧的 wx.createAnimation 。它具有更好的性能和更可控的接口。

              在页面或自定义组件中,当需要进行关键帧动画时,可以使用 this.animate 接口:

              this.animate(selector, keyframes, duration, callback)

              参数说明

              属性类型默认值必填说明
              selectorString选择器(同 SelectorQuery.select 的选择器格式)
              keyframesArray关键帧信息
              durationNumber动画持续时长(毫秒为单位)
              callbackfunction动画完成后的回调函数

              keyframes 中对象的结构

              属性类型默认值必填说明
              offsetNumber关键帧的偏移,范围[0-1]
              easeStringlinear动画缓动函数
              transformOriginString基点位置,即 CSS transform-origin
              backgroundColorString背景颜色,即 CSS background-color
              bottomNumber/String底边位置,即 CSS bottom
              heightNumber/String高度,即 CSS height
              leftNumber/String左边位置,即 CSS left
              widthNumber/String宽度,即 CSS width
              opacityNumber不透明度,即 CSS opacity
              rightNumber右边位置,即 CSS right
              topNumber/String顶边位置,即 CSS top
              matrixArray变换矩阵,即 CSS transform matrix
              matrix3dArray三维变换矩阵,即 CSS transform matrix3d
              rotateNumber旋转,即 CSS transform rotate
              rotate3dArray三维旋转,即 CSS transform rotate3d
              rotateXNumberX 方向旋转,即 CSS transform rotateX
              rotateYNumberY 方向旋转,即 CSS transform rotateY
              rotateZNumberZ 方向旋转,即 CSS transform rotateZ
              scaleArray缩放,即 CSS transform scale
              scale3dArray三维缩放,即 CSS transform scale3d
              scaleXNumberX 方向缩放,即 CSS transform scaleX
              scaleYNumberY 方向缩放,即 CSS transform scaleY
              scaleZNumberZ 方向缩放,即 CSS transform scaleZ
              skewArray倾斜,即 CSS transform skew
              skewXNumberX 方向倾斜,即 CSS transform skewX
              skewYNumberY 方向倾斜,即 CSS transform skewY
              translateArray位移,即 CSS transform translate
              translate3dArray三维位移,即 CSS transform translate3d
              translateXNumberX 方向位移,即 CSS transform translateX
              translateYNumberY 方向位移,即 CSS transform translateY
              translateZNumberZ 方向位移,即 CSS transform translateZ

              示例代码

              在开发者工具中预览效果

                this.animate('#container', [    { opacity: 1.0, rotate: 0, backgroundColor: '#FF0000' },    { opacity: 0.5, rotate: 45, backgroundColor: '#00FF00'},    { opacity: 0.0, rotate: 90, backgroundColor: '#FF0000' },    ], 5000, function () {      this.clearAnimation('#container', { opacity: true, rotate: true }, function () {        console.log("清除了#container上的opacity和rotate属性")      })  }.bind(this))  this.animate('.block', [    { scale: [1, 1], rotate: 0, ease: 'ease-out'  },    { scale: [1.5, 1.5], rotate: 45, ease: 'ease-in', offset: 0.9},    { scale: [2, 2], rotate: 90 },  ], 5000, function () {    this.clearAnimation('.block', function () {      console.log("清除了.block上的所有动画属性")    })  }.bind(this))

              调用 animate API 后会在节点上新增一些样式属性覆盖掉原有的对应样式。如果需要清除这些样式,可在该节点上的动画全部执行完毕后使用 this.clearAnimation 清除这些属性。

              this.clearAnimation(selector, options, callback)

              参数说明

              属性类型默认值必填说明
              selectorString选择器(同 SelectorQuery.select 的选择器格式)
              optionsObject需要清除的属性,不填写则全部清除
              callbackFunction清除完成后的回调函数

              滚动驱动的动画

              我们发现,根据滚动位置而不断改变动画的进度是一种比较常见的场景,这类动画可以让人感觉到界面交互很连贯自然,体验更好。因此,从小程序基础库 2.9.0 开始支持一种由滚动驱动的动画机制。

              基于上述的关键帧动画接口,新增一个 ScrollTimeline 的参数,用来绑定滚动元素(目前只支持 scroll-view)。接口定义如下:

              this.animate(selector, keyframes, duration, ScrollTimeline)

              ScrollTimeline 中对象的结构

              属性类型默认值必填说明
              scrollSourceString指定滚动元素的选择器(只支持 scroll-view),该元素滚动时会驱动动画的进度
              orientationStringvertical指定滚动的方向。有效值为 horizontal 或 vertical
              startScrollOffsetNumber指定开始驱动动画进度的滚动偏移量,单位 px
              endScrollOffsetNumber指定停止驱动动画进度的滚动偏移量,单位 px
              timeRangeNumber起始和结束的滚动范围映射的时间长度,该时间可用于与关键帧动画里的时间 (duration) 相匹配,单位 ms

              示例代码

              在开发者工具中预览效果

                this.animate('.avatar', [{    borderRadius: '0',    borderColor: 'red',    transform: 'scale(1) translateY(-20px)',    offset: 0,  }, {    borderRadius: '25%',    borderColor: 'blue',    transform: 'scale(.65) translateY(-20px)',    offset: .5,  }, {    borderRadius: '50%',    borderColor: 'blue',    transform: `scale(.3) translateY(-20px)`,    offset: 1  }], 2000, {    scrollSource: '#scroller',    timeRange: 2000,    startScrollOffset: 0,    endScrollOffset: 85,  })  this.animate('.search_input', [{    opacity: '0',    width: '0%',  }, {    opacity: '1',    width: '100%',  }], 1000, {    scrollSource: '#scroller',    timeRange: 1000,    startScrollOffset: 120,    endScrollOffset: 252  })

              高级的动画方式

              在一些复杂场景下,上述的动画方法可能并不适用。

              WXS 响应事件 的方式可以通过使用 WXS 来响应事件的方法来动态调整节点的 style 属性。通过不断改变 style 属性的值可以做到动画效果。同时,这种方式也可以根据用户的触摸事件来动态地生成动画。

              连续使用 setData 来改变界面的方法也可以达到动画的效果。这样可以任意地改变界面,但通常会产生较大的延迟或卡顿,甚至导致小程序僵死。此时可以通过将页面的 setData 改为 自定义组件 中的 setData 来提升性能。下面的例子是使用 setData 来实现秒表动画的示例。


              初始渲染缓存

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

              初始渲染缓存工作原理

              小程序页面的初始化分为两个部分。

              • 逻辑层初始化:载入必需的小程序代码、初始化页面 this 对象(也包括它涉及到的所有自定义组件的 this 对象)、将相关数据发送给视图层。
              • 视图层初始化:载入必需的小程序代码,然后等待逻辑层初始化完毕并接收逻辑层发送的数据,最后渲染页面。

              在启动页面时,尤其是小程序冷启动、进入第一个页面时,逻辑层初始化的时间较长。在页面初始化过程中,用户将看到小程序的标准载入画面(冷启动时)或可能看到轻微的白屏现象(页面跳转过程中)。

              启用初始渲染缓存,可以使视图层不需要等待逻辑层初始化完毕,而直接提前将页面初始 data 的渲染结果展示给用户,这可以使得页面对用户可见的时间大大提前。它的工作原理如下:

              • 在小程序页面第一次被打开后,将页面初始数据渲染结果记录下来,写入一个持久化的缓存区域(缓存可长时间保留,但可能因为小程序更新、基础库更新、储存空间回收等原因被清除);
              • 在这个页面被第二次打开时,检查缓存中是否还存有这个页面上一次初始数据的渲染结果,如果有,就直接将渲染结果展示出来;
              • 如果展示了缓存中的渲染结果,这个页面暂时还不能响应用户事件,等到逻辑层初始化完毕后才能响应用户事件。

              利用初始渲染缓存,可以:

              • 快速展示出页面中永远不会变的部分,如导航栏;
              • 预先展示一个骨架页,提升用户体验;
              • 展示自定义的加载提示;
              • 提前展示广告,等等。

              支持的组件

              在初始渲染缓存阶段中,复杂组件不能被展示或不能响应交互。

              目前支持的内置组件:

              • <view />
              • <text />
              • <button />
              • <image />
              • <scroll-view />
              • <rich-text />

              自定义组件本身可以被展示(但它们里面用到的内置组件也遵循上述限制)。

              静态初始渲染缓存

              若想启用初始渲染缓存,最简单的方法是在页面的 json 文件中添加配置项 "initialRenderingCache": "static" :

              {  "initialRenderingCache": "static"}

              如果想要对所有页面启用,可以在 app.json 的 window 配置段中添加这个配置:

              {  "window": {    "initialRenderingCache": "static"  }}

              添加这个配置项之后,在手机中预览小程序首页,然后杀死小程序再次进入,就会通过初始渲染缓存来渲染首页。

              注意:这种情况下,初始渲染缓存记录的是页面 data 应用在页面 WXML 上的结果,不包含任何 setData 的结果。

              例如,如果想要在页面中展示出“正在加载”几个字,这几个字受到 loading 数据字段控制:

              <view wx:if="{{loading}}">正在加载</view>

              这种情况下, loading 应当在 data 中指定为 true ,如:

              // 正确的做法Page({  data: {    loading: true  }})

              而不能通过 setData 将 loading 置为 true :

              // 错误的做法!不要这么做!Page({  data: {},  onLoad: function() {    this.setData({      loading: true    })  }})

              换而言之,这种做法只包含页面 data 的渲染结果,即页面的纯静态成分。

              在初始渲染缓存中添加动态内容

              有些场景中,只是页面 data 的渲染结果会比较局限。有时会想要额外展示一些可变的内容,如展示的广告图片 URL 等。

              这种情况下可以使用“动态”初始渲染缓存的方式。首先,配置 "initialRenderingCache": "dynamic" :

              {  "initialRenderingCache": "dynamic"}

              此时,初始渲染缓存不会被自动启用,还需要在页面中调用 this.setInitialRenderingCache(dynamicData) 才能启用。其中, dynamicData 是一组数据,与 data 一起参与页面 WXML 渲染。

              Page({  data: {    loading: true  },  onReady: function() {    this.setInitialRenderingCache({      loadingHint: '正在加载' // 这一部分数据将被应用于界面上,相当于在初始 data 基础上额外进行一次 setData    })  }})
              <view wx:if="{{loading}}">{{loadingHint}}</view>

              从原理上说,在动态生成初始渲染缓存的方式下,页面会在后台使用动态数据重新渲染一次,因而开销相对较大。因而要尽量避免频繁调用 this.setInitialRenderingCache ,如果在一个页面内多次调用,仅最后一次调用生效。

              注意:

              • this.setInitialRenderingCache 调用时机不能早于 Page 的 onReady 或 Component 的 ready 生命周期,否则可能对性能有负面影响。
              • 如果想禁用初始渲染缓存,调用 this.setInitialRenderingCache(null) 。


              小程序的运行环境

              微信小程序运行在多种平台上:iOS(iPhone/iPad)微信客户端、Android 微信客户端、PC 微信客户端、Mac 微信客户端和用于调试的微信开发者工具。

              各平台脚本执行环境以及用于渲染非原生组件的环境是各不相同的:

              • 在 iOS 上,小程序逻辑层的 javascript 代码运行在 JavaScriptCore 中,视图层是由 WKWebView 来渲染的,环境有 iOS 12、iOS 13 等;
              • 在 Android 上,小程序逻辑层的 javascript 代码运行在 V8 中,视图层是由自研 XWeb 引擎基于 Mobile Chrome 内核来渲染的;
              • 在 开发工具上,小程序逻辑层的 javascript 代码是运行在 NW.js 中,视图层是由 Chromium Webview 来渲染的。

              平台差异

              尽管各运行环境是十分相似的,但是还是有些许区别:

              • JavaScript 语法和 API 支持不一致:语法上开发者可以通过开启 ES6 转 ES5 的功能来规避(详情);此外,小程序基础库内置了必要的Polyfill,来弥补API的差异(详情)。
              • WXSS 渲染表现不一致:尽管可以通过开启样式补全来规避大部分的问题,还是建议开发者需要在 iOS 和 Android 上分别检查小程序的真实表现。

              开发者工具仅供调试使用,最终的表现以客户端为准。


              JavaScript 支持情况

              运行限制

              基于安全考虑,小程序中不支持动态执行 JS 代码,即:

              • 不支持使用 eval 执行 JS 代码
              • 不支持使用 new Function 创建函数

              客户端 ES6 API 支持情况

              微信小程序已经支持了绝大部分的 ES6 API,已支持的 API 如下(部分API依赖系统版本):

              StringiOS8iOS9iOS10+Android
              codePointAt
              normalize
              includes
              startsWith
              endsWith
              repeat
              String.fromCodePoint
              ArrayiOS8iOS9iOS10+Android
              copyWithin
              find
              findIndex
              fill
              entries
              keys
              values
              includes
              Array.from
              Array.of
              NumberiOS8iOS9iOS10+Android
              isFinite
              isNaN
              parseInt
              parseFloat
              isInteger
              EPSILON
              isSafeInteger
              MathiOS8iOS9iOS10+Android
              trunc
              sign
              cbrt
              clz32
              imul
              fround
              hypot
              expm1
              log1p
              log10
              log2
              sinh
              cosh
              tanh
              asinh
              acosh
              atanh
              ObjectiOS8iOS9iOS10+Android
              is
              assign
              getOwnPropertyDescriptor
              keys
              getOwnPropertyNames
              getOwnPropertySymbols

              OtheriOS8iOS9iOS10+Android
              Symbol
              Set
              Map
              Proxy
              Reflect
              Promise


              小程序运行机制

              前台/后台状态

              小程序启动后,界面被展示给用户,此时小程序处于前台状态。

              当用户点击右上角胶囊按钮关闭小程序,或者按了设备 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 获得这些已保存数据。

              代码示例:

              {  "restartStrategy": "homePageAndLatestPage"}
              Page({  onLoad: function() {    var prevExitState = this.exitState // 尝试获得上一次退出前 onSaveExitState 保存的数据    if (prevExitState !== undefined) { // 如果是根据 restartStrategy 配置进行的冷启动,就可以获取到      prevExitState.myDataField === 'myData'     }  },  onSaveExitState: function() {    var exitState = { myDataField: 'myData' } // 需要保存的数据    return {      data: exitState,      expireTimeStamp: Date.now() + 24 * 60 * 60 * 1000 // 超时时刻    }  }})

              onSaveExitState 返回值可以包含两项:

              字段名类型含义
              dataAny需要保存的数据(只能是 JSON 兼容的数据)
              expireTimeStampNumber超时时刻,在这个时刻后,保存的数据保证一定被丢弃,默认为 (当前时刻 + 1 天)


              注意事项:

              • 如果超过 expireTimeStamp ,保存的数据将被丢弃,且冷启动时不遵循 restartStrategy 的配置,而是直接从首页冷启动。
              • expireTimeStamp 有可能被自动提前,如微信客户端需要清理数据的时候。
              • 在小程序存活期间, onSaveExitState 可能会被多次调用,此时以最后一次的调用结果作为最终结果。
              • 在某些特殊情况下(如微信客户端直接被系统杀死),这个方法将不会被调用,下次冷启动也不遵循 restartStrategy 的配置,而是直接从首页冷启动。


              小程序更新机制

              未启动时更新

              开发者在管理后台发布新版本的小程序之后,如果某个用户本地有小程序的历史版本,此时打开的可能还是旧版本。微信客户端会有若干个时机去检查本地缓存的小程序有没有更新版本,如果有则会静默更新到新版本。总的来说,开发者在后台发布新版本之后,无法立刻影响到所有现网用户,但最差情况下,也在发布之后 24 小时之内下发新版本信息到用户。用户下次打开时会先更新最新版本再打开。

              启动时更新

              小程序每次冷启动时,都会检查是否有更新版本,如果发现有新版本,将会异步下载新版本的代码包,并同时用客户端本地的包进行启动,即新版本的小程序需要等下一次冷启动才会应用上。

              如果需要马上应用最新版本,可以使用 wx.getUpdateManager API 进行处理。

              const updateManager = wx.getUpdateManager()updateManager.onCheckForUpdate(function (res) {  // 请求完新版本信息的回调  console.log(res.hasUpdate)})updateManager.onUpdateReady(function () {  wx.showModal({    title: '更新提示',    content: '新版本已经准备好,是否重启应用?',    success(res) {      if (res.confirm) {        // 新的版本已经下载好,调用 applyUpdate 应用新版本并重启        updateManager.applyUpdate()      }    }  })})updateManager.onUpdateFailed(function () {  // 新版本下载失败})


              组件模板和样式

              类似于页面,自定义组件拥有自己的 wxml 模板和 wxss 样式。

              组件模板

              组件模板的写法与页面模板相同。组件模板与组件数据结合后生成的节点树,将被插入到组件的引用位置上。

              在组件模板中可以提供一个 <slot> 节点,用于承载组件引用时提供的子节点。

              代码示例:

              <!-- 组件模板 --><view class="wrapper">  <view>这里是组件的内部节点</view>  <slot></slot></view>
              <!-- 引用组件的页面模板 --><view>  <component-tag-name>    <!-- 这部分内容将被放置在组件 <slot> 的位置上 -->    <view>这里是插入到组件slot中的内容</view>  </component-tag-name></view>

              注意,在模板中引用到的自定义组件及其对应的节点名需要在 json 文件中显式定义,否则会被当作一个无意义的节点。除此以外,节点名也可以被声明为抽象节点。

              模板数据绑定

              与普通的 WXML 模板类似,可以使用数据绑定,这样就可以向子组件的属性传递动态数据。

              代码示例:

              <!-- 引用组件的页面模板 --><view>  <component-tag-name prop-a="{{dataFieldA}}" prop-b="{{dataFieldB}}">    <!-- 这部分内容将被放置在组件 <slot> 的位置上 -->    <view>这里是插入到组件slot中的内容</view>  </component-tag-name></view>

              在以上例子中,组件的属性 propA 和 propB 将收到页面传递的数据。页面可以通过 setData 来改变绑定的数据字段。

              注意:这样的数据绑定只能传递 JSON 兼容数据。自基础库版本 2.0.9 开始,还可以在数据中包含函数(但这些函数不能在 WXML 中直接调用,只能传递给子组件)。

              组件 wxml 的 slot

              在组件的 wxml 中可以包含 slot 节点,用于承载组件使用者提供的 wxml 结构。

              默认情况下,一个组件的 wxml 中只能有一个 slot 。需要使用多 slot 时,可以在组件 js 中声明启用。

              Component({  options: {    multipleSlots: true // 在组件定义时的选项中启用多slot支持  },  properties: { /* ... */ },  methods: { /* ... */ }})

              此时,可以在这个组件的 wxml 中使用多个 slot ,以不同的 name 来区分。

              <!-- 组件模板 --><view class="wrapper">  <slot name="before"></slot>  <view>这里是组件的内部细节</view>  <slot name="after"></slot></view>

              使用时,用 slot 属性来将节点插入到不同的 slot 上。

              <!-- 引用组件的页面模板 --><view>  <component-tag-name>    <!-- 这部分内容将被放置在组件 <slot name="before"> 的位置上 -->    <view slot="before">这里是插入到组件slot name="before"中的内容</view>    <!-- 这部分内容将被放置在组件 <slot name="after"> 的位置上 -->    <view slot="after">这里是插入到组件slot name="after"中的内容</view>  </component-tag-name></view>

              组件样式

              组件对应 wxss 文件的样式,只对组件wxml内的节点生效。编写组件样式时,需要注意以下几点:

              • 组件和引用组件的页面不能使用id选择器(#a)、属性选择器([a])和标签名选择器,请改用class选择器。
              • 组件和引用组件的页面中使用后代选择器(.a .b)在一些极端情况下会有非预期的表现,如遇,请避免使用。
              • 子元素选择器(.a>.b)只能用于 view 组件与其子节点之间,用于其他组件可能导致非预期的情况。
              • 继承样式,如 font 、 color ,会从组件外继承到组件内。
              • 除继承样式外, app.wxss 中的样式、组件所在页面的的样式对自定义组件无效(除非更改组件样式隔离选项)。
              #a { } /* 在组件中不能使用 */[a] { } /* 在组件中不能使用 */button { } /* 在组件中不能使用 */.a > .b { } /* 除非 .a 是 view 组件节点,否则不一定会生效 */

              除此以外,组件可以指定它所在节点的默认样式,使用 :host 选择器(需要包含基础库 1.7.2 或更高版本的开发者工具支持)。

              代码示例:

              /* 组件 custom-component.wxss */:host {  color: yellow;}
              <!-- 页面的 WXML --><custom-component>这段文本是黄色的</custom-component>

              组件样式隔离

              默认情况下,自定义组件的样式只受到自定义组件 wxss 的影响。除非以下两种情况:

              • app.wxss 或页面的 wxss 中使用了标签名选择器(或一些其他特殊选择器)来直接指定样式,这些选择器会影响到页面和全部组件。通常情况下这是不推荐的做法。
              • 指定特殊的样式隔离选项 styleIsolation 。
              Component({  options: {    styleIsolation: 'isolated'  }})

              styleIsolation 选项从基础库版本 2.6.5 开始支持。它支持以下取值:

              • isolated 表示启用样式隔离,在自定义组件内外,使用 class 指定的样式将不会相互影响(一般情况下的默认值);
              • apply-shared 表示页面 wxss 样式将影响到自定义组件,但自定义组件 wxss 中指定的样式不会影响页面;
              • shared 表示页面 wxss 样式将影响到自定义组件,自定义组件 wxss 中指定的样式也会影响页面和其他设置了 apply-shared 或 shared 的自定义组件。(这个选项在插件中不可用。)

              使用后两者时,请务必注意组件间样式的相互影响。

              如果这个 Component 构造器用于构造页面 ,则默认值为 shared ,且还有以下几个额外的样式隔离选项可用:

              • page-isolated 表示在这个页面禁用 app.wxss ,同时,页面的 wxss 不会影响到其他自定义组件;
              • page-apply-shared 表示在这个页面禁用 app.wxss ,同时,页面 wxss 样式不会影响到其他自定义组件,但设为 shared 的自定义组件会影响到页面;
              • page-shared 表示在这个页面禁用 app.wxss ,同时,页面 wxss 样式会影响到其他设为 apply-shared 或 shared 的自定义组件,也会受到设为 shared 的自定义组件的影响。

              从小程序基础库版本 2.10.1 开始,也可以在页面或自定义组件的 json 文件中配置 styleIsolation (这样就不需在 js 文件的 options 中再配置)。例如:

              {  "styleIsolation": "isolated"}

              此外,小程序基础库版本 2.2.3 以上支持 addGlobalClass 选项,即在 Component 的 options 中设置 addGlobalClass: true 。 这个选项等价于设置 styleIsolation: apply-shared ,但设置了 styleIsolation 选项后这个选项会失效。

              代码示例:

              /* 组件 custom-component.js */Component({  options: {    addGlobalClass: true,  }})
              <!-- 组件 custom-component.wxml --><text class="red-text">这段文本的颜色由 `app.wxss` 和页面 `wxss` 中的样式定义来决定</text>
              /* app.wxss */.red-text {  color: red;}

              外部样式类

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

              有时,组件希望接受外部传入的样式类。此时可以在 Component 中用 externalClasses 定义段定义若干个外部样式类。

              这个特性可以用于实现类似于 view 组件的 hover-class 属性:页面可以提供一个样式类,赋予 view 的 hover-class ,这个样式类本身写在页面中而非 view 组件的实现中。

              注意:在同一个节点上使用普通样式类和外部样式类时,两个类的优先级是未定义的,因此最好避免这种情况。

              代码示例:

              /* 组件 custom-component.js */Component({  externalClasses: ['my-class']})
              <!-- 组件 custom-component.wxml --><custom-component class="my-class">这段文本的颜色由组件外的 class 决定</custom-component>

              这样,组件的使用者可以指定这个样式类对应的 class ,就像使用普通属性一样。在 2.7.1 之后,可以指定多个对应的 class 。

              代码示例:

              <!-- 页面的 WXML --><custom-component my-class="red-text" /><custom-component my-class="large-text" /><!-- 以下写法需要基础库版本 2.7.1 以上 --><custom-component my-class="red-text large-text" />
              .red-text {  color: red;}.large-text {  font-size: 1.5em;}

              引用页面或父组件的样式

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

              即使启用了样式隔离 isolated ,组件仍然可以在局部引用组件所在页面的样式或父组件的样式。

              例如,如果在页面 wxss 中定义了:

              .blue-text {  color: blue;}

              在这个组件中可以使用 ~ 来引用这个类的样式:

              <view class="~blue-text"> 这段文本是蓝色的 </view>

              如果在一个组件的父组件 wxss 中定义了:

              .red-text {  color: red;}

              在这个组件中可以使用 ^ 来引用这个类的样式:

              <view class="^red-text"> 这段文本是红色的 </view>

              也可以连续使用多个 ^ 来引用祖先组件中的样式。

              注意:如果组件是比较独立、通用的组件,请优先使用外部样式类的方式,而非直接引用父组件或页面的样式。

              虚拟化组件节点

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

              默认情况下,自定义组件本身的那个节点是一个“普通”的节点,使用时可以在这个节点上设置 class style 、动画、 flex 布局等,就如同普通的 view 组件节点一样。

              <!-- 页面的 WXML --><view style="display: flex">  <!-- 默认情况下,这是一个普通的节点 -->  <custom-component style="color: blue; flex: 1">蓝色、满宽的</custom-component></view>

              但有些时候,自定义组件并不希望这个节点本身可以设置样式、响应 flex 布局等,而是希望自定义组件内部的第一层节点能够响应 flex 布局或者样式由自定义组件本身完全决定。

              这种情况下,可以将这个自定义组件设置为“虚拟的”:

              Component({  options: {    virtualHost: true  },  properties: {    style: { // 定义 style 属性可以拿到 style 属性上设置的值      type: String,    }  },  externalClass: ['class'], // 可以将 class 设为 externalClass})

              这样,可以将 flex 放入自定义组件内:

              <!-- 页面的 WXML --><view style="display: flex">  <!-- 如果设置了 virtualHost ,节点上的样式将失效 -->  <custom-component style="color: blue">不是蓝色的</custom-component></view>
              <!-- custom-component.wxml --><view style="flex: 1">  满宽的  <slot></slot></view>

              需要注意的是,自定义组件节点上的 class style 和动画将不再生效,但仍可以:

              • 将 style 定义成 properties 属性来获取 style 上设置的值;
              • 将 class 定义成 externalClasses 外部样式类使得自定义组件 wxml 可以使用 class 值。


              Component 构造器

              Component 构造器可用于定义组件,调用 Component 构造器时可以指定组件的属性、数据、方法等。

              详细的参数含义和使用请参考 Component 参考文档

              Component({  behaviors: [],  properties: {    myProperty: { // 属性名      type: String,      value: ''    },    myProperty2: String // 简化的定义方式  },    data: {}, // 私有数据,可用于模板渲染  lifetimes: {    // 生命周期函数,可以为函数,或一个在methods段中定义的方法名    attached: function () { },    moved: function () { },    detached: function () { },  },  // 生命周期函数,可以为函数,或一个在methods段中定义的方法名  attached: function () { }, // 此处attached的声明会被lifetimes字段中的声明覆盖  ready: function() { },  pageLifetimes: {    // 组件所在页面的生命周期函数    show: function () { },    hide: function () { },    resize: function () { },  },  methods: {    onMyButtonTap: function(){      this.setData({        // 更新属性和数据的方法与更新页面数据的方法类似      })    },    // 内部方法建议以下划线开头    _myPrivateMethod: function(){      // 这里将 data.A[0].B 设为 'myPrivateData'      this.setData({        'A[0].B': 'myPrivateData'      })    },    _propertyChange: function(newVal, oldVal) {    }  }})

              使用 Component 构造器构造页面

              事实上,小程序的页面也可以视为自定义组件。因而,页面也可以使用 Component 构造器构造,拥有与普通组件一样的定义段与实例方法。但此时要求对应 json 文件中包含 usingComponents 定义段。

              此时,组件的属性可以用于接收页面的参数,如访问页面 /pages/index/index?paramA=123&paramB=xyz ,如果声明有属性 paramA 或 paramB ,则它们会被赋值为 123 或 xyz 。

              页面的生命周期方法(即 on 开头的方法),应写在 methods 定义段中。

              代码示例:

              {  "usingComponents": {}}
              Component({  properties: {    paramA: Number,    paramB: String,  },  methods: {    onLoad: function() {      this.data.paramA // 页面参数 paramA 的值      this.data.paramB // 页面参数 paramB 的值    }  }})

              使用 Component 构造器来构造页面的一个好处是可以使用 behaviors 来提取所有页面中公用的代码段。

              例如,在所有页面被创建和销毁时都要执行同一段代码,就可以把这段代码提取到 behaviors 中。

              代码示例:

              // page-common-behavior.jsmodule.exports = Behavior({  attached: function() {    // 页面创建时执行    console.info('Page loaded!')  },  detached: function() {    // 页面销毁时执行    console.info('Page unloaded!')  }})
              // 页面 Avar pageCommonBehavior = require('./page-common-behavior')Component({  behaviors: [pageCommonBehavior],  data: { /* ... */ },  methods: { /* ... */ },})
              // 页面 Bvar pageCommonBehavior = require('./page-common-behavior')Component({  behaviors: [pageCommonBehavior],  data: { /* ... */ },  methods: { /* ... */ },})


              组件间通信与事件

              组件间通信

              组件间的基本通信方式有以下几种。

              • 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)    }  }})

              触发事件的选项包括:

              选项名类型是否必填默认值描述
              bubblesBooleanfalse事件是否冒泡
              composedBooleanfalse事件是否可以穿越组件边界,为false时,事件将只能在引用组件的节点树上触发,不进入其他任何组件内部
              capturePhaseBooleanfalse事件是否拥有捕获阶段

              关于冒泡和捕获阶段的概念,请阅读 事件 章节中的相关说明。

              代码示例:

              在开发者工具中预览效果

              // 页面 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.jsComponent({  methods: {    onTap: function(){      this.triggerEvent('customevent', {}) // 只会触发 pageEventListener2      this.triggerEvent('customevent', {}, { bubbles: true }) // 会依次触发 pageEventListener2 、 pageEventListener1      this.triggerEvent('customevent', {}, { bubbles: true, composed: true }) // 会依次触发 pageEventListener2 、 anotherEventListener 、 pageEventListener1    }  }})

              获取组件实例

              可在父组件里调用 this.selectComponent ,获取子组件的实例对象。(插件的自定义组件将返回 null)

              调用时需要传入一个匹配选择器 selector,如:this.selectComponent(".my-component")。

              selector 详细语法可查看 selector 语法参考文档

              代码示例:

              // 父组件Page({  data: {},  getChildComponent: function () {    const child = this.selectComponent('.my-component');    console.log(child)  }})

              在上例中,父组件将会获取 class 为 my-component 的子组件实例对象,即子组件的 this 。

              若需要自定义 selectComponent 返回的数据,可使用内置 behavior: wx://component-export

              从基础库版本 2.2.3 开始提供支持。

              使自定义组件中支持 export 定义段,这个定义段可以用于指定组件被 selectComponent 调用时的返回值。

              代码示例:

              // 自定义组件 my-component 内部Component({  behaviors: ['wx://component-export'],  export() {    return { myField: 'myValue' }  }})
              <!-- 使用自定义组件时 --><my-component id="the-id" />
              // 父组件调用const child = this.selectComponent('#the-id') // 等于 { myField: 'myValue' }

              在上例中,父组件获取 id 为 the-id 的子组件实例的时候,得到的是对象 { myField: 'myValue' } 。


              组件生命周期

              组件的生命周期,指的是组件自身的一些函数,这些函数在特殊的时间点或遇到一些特殊的框架事件时被自动触发。

              其中,最重要的生命周期是 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
              errorObject Error每当组件方法抛出错误时执行2.4.1

              组件所在页面的生命周期

              还有一些特殊的生命周期,它们并非与组件有很强的关联,但有时组件需要获知,以便组件内部处理。这样的生命周期称为“组件所在页面的生命周期”,在 pageLifetimes 定义段中定义。其中可用的生命周期包括:

              生命周期参数描述最低版本
              show组件所在的页面被展示时执行2.2.3
              hide组件所在的页面被隐藏时执行2.2.3
              resizeObject Size组件所在的页面尺寸变化时执行2.4.0

              代码示例:

              Component({  pageLifetimes: {    show: function() {      // 页面被展示    },    hide: function() {      // 页面被隐藏    },    resize: function(size) {      // 页面尺寸变化    }  }})


              behaviors

              behaviors 是用于组件间代码共享的特性,类似于一些编程语言中的 “mixins” 或 “traits”。

              每个 behavior 可以包含一组属性、数据、生命周期函数和方法。组件引用它时,它的属性、数据和方法会被合并到组件中,生命周期函数也会在对应时机被调用。 每个组件可以引用多个 behavior ,behavior 也可以引用其它 behavior 。

              详细的参数含义和使用请参考 Behavior 参考文档

              组件中使用

              组件引用时,在 behaviors 定义段中将它们逐个列出即可。

              代码示例:

              // my-component.jsvar myBehavior = require('my-behavior')Component({  behaviors: [myBehavior],  properties: {    myProperty: {      type: String    }  },  data: {    myData: 'my-component-data'  },  created: function () {    console.log('[my-component] created')  },  attached: function () {     console.log('[my-component] attached')  },  ready: function () {    console.log('[my-component] ready')  },  methods: {    myMethod: function () {      console.log('[my-component] log by myMethod')    },  }})

              在上例中, my-component 组件定义中加入了 my-behavior,

              而 my-behavior 结构为:

              • 属性:myBehaviorProperty
              • 数据字段:myBehaviorData
              • 方法:myBehaviorMethod
              • 生命周期函数:attached、created、ready

              这将使 my-component 最终结构为:

              • 属性:myBehaviorProperty、myProperty
              • 数据字段:myBehaviorData、myData
              • 方法:myBehaviorMethod、myMethod
              • 生命周期函数:attached、created、ready

              当组件触发生命周期时,上例生命周期函数执行顺序为:

              1. [my-behavior] created
              2. [my-component] created
              3. [my-behavior] attached
              4. [my-component] attached
              5. [my-behavior] ready
              6. [my-component] ready

              详细规则参考 同名字段的覆盖和组合规则。

              同名字段的覆盖和组合规则

              组件和它引用的 behavior 中可以包含同名的字段,对这些字段的处理方法如下:

              • 如果有同名的属性 (properties) 或方法 (methods):若组件本身有这个属性或方法,则组件的属性或方法会覆盖 behavior 中的同名属性或方法;若组件本身无这个属性或方法,则在组件的 behaviors 字段中定义靠后的 behavior 的属性或方法会覆盖靠前的同名属性或方法;在 2 的基础上,若存在嵌套引用 behavior 的情况,则规则为:父 behavior 覆盖 子 behavior 中的同名属性或方法。
              • 如果有同名的数据字段 (data):若同名的数据字段都是对象类型,会进行对象合并;其余情况会进行数据覆盖,覆盖规则为:组件 > 父 behavior > 子 behavior 、 靠后的 behavior > 靠前的 behavior。(优先级高的覆盖优先级低的,最大的为优先级最高)
              • 生命周期函数不会相互覆盖,而是在对应触发时机被逐个调用:对于不同的生命周期函数之间,遵循组件生命周期函数的执行顺序;对于同种生命周期函数,遵循如下规则:behavior 优先于组件执行;子 behavior 优先于 父 behavior 执行;靠前的 behavior 优先于 靠后的 behavior 执行;如果同一个 behavior 被一个组件多次引用,它定义的生命周期函数只会被执行一次。

              代码示例:

              在开发者工具中预览效果

              内置 behaviors

              自定义组件可以通过引用内置的 behavior 来获得内置组件的一些行为。

              Component({  behaviors: ['wx://form-field']})

              在上例中, wx://form-field 代表一个内置 behavior ,它使得这个自定义组件有类似于表单控件的行为。

              内置 behavior 往往会为组件添加一些属性。在没有特殊说明时,组件可以覆盖这些属性来改变它的 type 或添加 observer 。

              wx://form-field

              使自定义组件有类似于表单控件的行为。 form 组件可以识别这些自定义组件,并在 submit 事件中返回组件的字段名及其对应字段值。

              详细用法以及代码示例可见:form 组件参考文档

              wx://form-field-group

              从基础库版本 2.10.2 开始提供支持。

              使 form 组件可以识别到这个自定义组件内部的所有表单控件。

              详细用法以及代码示例可见:form 组件参考文档

              wx://form-field-button

              从基础库版本 2.10.3 开始提供支持。

              使 form 组件可以识别到这个自定义组件内部的 button 。如果自定义组件内部有设置了 form-type 的 button ,它将被组件外的 form 接受。

              详细用法以及代码示例可见:form 组件参考文档

              wx://component-export

              从基础库版本 2.2.3 开始提供支持。

              使自定义组件支持 export 定义段。这个定义段可以用于指定组件被 selectComponent 调用时的返回值。

              详细用法以及代码示例可见:selectComponent 参考文档


              组件间关系

              定义和使用组件间关系

              有时需要实现这样的组件:

              <custom-ul>  <custom-li> item 1 </custom-li>  <custom-li> item 2 </custom-li></custom-ul>

              这个例子中, custom-ul 和 custom-li 都是自定义组件,它们有相互间的关系,相互间的通信往往比较复杂。此时在组件定义时加入 relations 定义段,可以解决这样的问题。示例:

              // path/to/custom-ul.jsComponent({  relations: {    './custom-li': {      type: 'child', // 关联的目标节点应为子节点      linked: function(target) {        // 每次有custom-li被插入时执行,target是该节点实例对象,触发在该节点attached生命周期之后      },      linkChanged: function(target) {        // 每次有custom-li被移动后执行,target是该节点实例对象,触发在该节点moved生命周期之后      },      unlinked: function(target) {        // 每次有custom-li被移除时执行,target是该节点实例对象,触发在该节点detached生命周期之后      }    }  },  methods: {    _getAllLi: function(){      // 使用getRelationNodes可以获得nodes数组,包含所有已关联的custom-li,且是有序的      var nodes = this.getRelationNodes('path/to/custom-li')    }  },  ready: function(){    this._getAllLi()  }})
              // path/to/custom-li.jsComponent({  relations: {    './custom-ul': {      type: 'parent', // 关联的目标节点应为父节点      linked: function(target) {        // 每次被插入到custom-ul时执行,target是custom-ul节点实例对象,触发在attached生命周期之后      },      linkChanged: function(target) {        // 每次被移动后执行,target是custom-ul节点实例对象,触发在moved生命周期之后      },      unlinked: function(target) {        // 每次被移除时执行,target是custom-ul节点实例对象,触发在detached生命周期之后      }    }  }})

              注意:必须在两个组件定义中都加入relations定义,否则不会生效。

              关联一类组件

              有时,需要关联的是一类组件,如:

              <custom-form>  <view>    input    <custom-input></custom-input>  </view>  <custom-submit> submit </custom-submit></custom-form>

              custom-form 组件想要关联 custom-input 和 custom-submit 两个组件。此时,如果这两个组件都有同一个behavior:

              // path/to/custom-form-controls.jsmodule.exports = Behavior({  // ...})
              // path/to/custom-input.jsvar customFormControls = require('./custom-form-controls')Component({  behaviors: [customFormControls],  relations: {    './custom-form': {      type: 'ancestor', // 关联的目标节点应为祖先节点    }  }})
              // path/to/custom-submit.jsvar customFormControls = require('./custom-form-controls')Component({  behaviors: [customFormControls],  relations: {    './custom-form': {      type: 'ancestor', // 关联的目标节点应为祖先节点    }  }})

              则在 relations 关系定义中,可使用这个behavior来代替组件路径作为关联的目标节点:

              // path/to/custom-form.jsvar customFormControls = require('./custom-form-controls')Component({  relations: {    'customFormControls': {      type: 'descendant', // 关联的目标节点应为子孙节点      target: customFormControls    }  }})

              relations 定义段

              relations 定义段包含目标组件路径及其对应选项,可包含的选项见下表。

              选项类型是否必填描述
              typeString目标组件的相对关系,可选的值为 parent 、 child 、 ancestor 、 descendant
              linkedFunction关系生命周期函数,当关系被建立在页面节点树中时触发,触发时机在组件attached生命周期之后
              linkChangedFunction关系生命周期函数,当关系在页面节点树中发生改变时触发,触发时机在组件moved生命周期之后
              unlinkedFunction关系生命周期函数,当关系脱离页面节点树时触发,触发时机在组件detached生命周期之后
              targetString如果这一项被设置,则它表示关联的目标节点所应具有的behavior,所有拥有这一behavior的组件节点都会被关联


              数据监听器

              数据监听器可以用于监听和响应任何属性和数据字段的变化。从小程序基础库版本 2.6.1 开始支持。

              使用数据监听器

              有时,在一些数据字段被 setData 设置时,需要执行一些操作。

              例如, this.data.sum 永远是 this.data.numberA 与 this.data.numberB 的和。此时,可以使用数据监听器进行如下实现。

              Component({  attached: function() {    this.setData({      numberA: 1,      numberB: 2,    })  },  observers: {    'numberA, numberB': function(numberA, numberB) {      // 在 numberA 或者 numberB 被设置时,执行这个函数      this.setData({        sum: numberA + numberB      })    }  }})

              监听字段语法

              数据监听器支持监听属性或内部数据的变化,可以同时监听多个。一次 setData 最多触发每个监听器一次。

              同时,监听器可以监听子数据字段,如下例所示。

              Component({  observers: {    'some.subfield': function(subfield) {      // 使用 setData 设置 this.data.some.subfield 时触发      // (除此以外,使用 setData 设置 this.data.some 也会触发)      subfield === this.data.some.subfield    },    'arr[12]': function(arr12) {      // 使用 setData 设置 this.data.arr[12] 时触发      // (除此以外,使用 setData 设置 this.data.arr 也会触发)      arr12 === this.data.arr[12]    },  }})

              如果需要监听所有子数据字段的变化,可以使用通配符 ** 。

              Component({  observers: {    'some.field.**': function(field) {      // 使用 setData 设置 this.data.some.field 本身或其下任何子数据字段时触发      // (除此以外,使用 setData 设置 this.data.some 也会触发)      field === this.data.some.field    },  },  attached: function() {    // 这样会触发上面的 observer    this.setData({      'some.field': { /* ... */ }    })    // 这样也会触发上面的 observer    this.setData({      'some.field.xxx': { /* ... */ }    })    // 这样还是会触发上面的 observer    this.setData({      'some': { /* ... */ }    })  }})

              特别地,仅使用通配符 ** 可以监听全部 setData 。

              Component({  observers: {    '**': function() {      // 每次 setData 都触发    },  },})

              提示:

              • 数据监听器监听的是 setData 涉及到的数据字段,即使这些数据字段的值没有发生变化,数据监听器依然会被触发。
              • 如果在数据监听器函数中使用 setData 设置本身监听的数据字段,可能会导致死循环,需要特别留意。
              • 数据监听器和属性的 observer 相比,数据监听器更强大且通常具有更好的性能。


              纯数据字段

              纯数据字段是一些不用于界面渲染的 data 字段,可以用于提升页面更新性能。从小程序基础库版本 2.8.2 开始支持。

              组件数据中的纯数据字段

              有些情况下,某些 data 中的字段(包括 setData 设置的字段)既不会展示在界面上,也不会传递给其他组件,仅仅在当前组件内部使用。

              此时,可以指定这样的数据字段为“纯数据字段”,它们将仅仅被记录在 this.data 中,而不参与任何界面渲染过程,这样有助于提升页面更新性能。

              指定“纯数据字段”的方法是在 Component 构造器的 options 定义段中指定 pureDataPattern 为一个正则表达式,字段名符合这个正则表达式的字段将成为纯数据字段。

              代码示例:

              Component({  options: {    pureDataPattern: /^_/ // 指定所有 _ 开头的数据字段为纯数据字段  },  data: {    a: true, // 普通数据字段    _b: true, // 纯数据字段  },  methods: {    myMethod() {      this.data._b // 纯数据字段可以在 this.data 中获取      this.setData({        c: true, // 普通数据字段        _d: true, // 纯数据字段      })    }  }})

              上述组件中的纯数据字段不会被应用到 WXML 上:

              <view wx:if="{{a}}"> 这行会被展示 </view><view wx:if="{{_b}}"> 这行不会被展示 </view>

              组件属性中的纯数据字段

              属性也可以被指定为纯数据字段(遵循 pureDataPattern 的正则表达式)。

              属性中的纯数据字段可以像普通属性一样接收外部传入的属性值,但不能将它直接用于组件自身的 WXML 中。

              代码示例:

              Component({  options: {    pureDataPattern: /^_/  },  properties: {    a: Boolean,    _b: {      type: Boolean,      observer() {        // 不要这样做!这个 observer 永远不会被触发      }    },  }})

              注意:属性中的纯数据字段的属性 observer 永远不会触发!如果想要监听属性值变化,使用 数据监听器 代替。

              从小程序基础库版本 2.10.1 开始,也可以在页面或自定义组件的 json 文件中配置 pureDataPattern (这样就不需在 js 文件的 options 中再配置)。此时,其值应当写成字符串形式:

              {  "pureDataPattern": "^_"}

              使用数据监听器监听纯数据字段

              数据监听器  可以用于监听纯数据字段(与普通数据字段一样)。这样,可以通过监听、响应纯数据字段的变化来改变界面。

              下面的示例是一个将 JavaScript 时间戳转换为可读时间的自定义组件。

              代码示例:

              Component({  options: {    pureDataPattern: /^timestamp$/ // 将 timestamp 属性指定为纯数据字段  },  properties: {    timestamp: Number,  },  observers: {    timestamp: function () {      // timestamp 被设置时,将它展示为可读时间字符串      var timeString = new Date(this.data.timestamp).toLocaleString()      this.setData({        timeString: timeString      })    }  }})
              <view>{{timeString}}</view>


              抽象节点

              这个特性自小程序基础库版本 1.9.6 开始支持。

              在组件中使用抽象节点

              有时,自定义组件模板中的一些节点,其对应的自定义组件不是由自定义组件本身确定的,而是自定义组件的调用者确定的。这时可以把这个节点声明为“抽象节点”。

              例如,我们现在来实现一个“选框组”(selectable-group)组件,它其中可以放置单选框(custom-radio)或者复选框(custom-checkbox)。这个组件的 wxml 可以这样编写:

              代码示例:

              <!-- selectable-group.wxml --><view wx:for="{{labels}}">  <label>    <selectable disabled="{{false}}"></selectable>    {{item}}  </label></view>

              其中,“selectable”不是任何在 json 文件的 usingComponents 字段中声明的组件,而是一个抽象节点。它需要在 componentGenerics 字段中声明:

              {  "componentGenerics": {    "selectable": true  }}

              使用包含抽象节点的组件

              在使用 selectable-group 组件时,必须指定“selectable”具体是哪个组件:

              <selectable-group generic:selectable="custom-radio" />

              这样,在生成这个 selectable-group 组件的实例时,“selectable”节点会生成“custom-radio”组件实例。类似地,如果这样使用:

              <selectable-group generic:selectable="custom-checkbox" />

              “selectable”节点则会生成“custom-checkbox”组件实例。

              注意:上述的 custom-radio 和 custom-checkbox 需要包含在这个 wxml 对应 json 文件的 usingComponents 定义段中。

              {  "usingComponents": {    "custom-radio": "path/to/custom/radio",    "custom-checkbox": "path/to/custom/checkbox"  }}

              抽象节点的默认组件

              抽象节点可以指定一个默认组件,当具体组件未被指定时,将创建默认组件的实例。默认组件可以在 componentGenerics 字段中指定:

              {  "componentGenerics": {    "selectable": {      "default": "path/to/default/component"    }  }}

              提示:

              • 节点的 generic 引用 generic:xxx="yyy" 中,值 yyy 只能是静态值,不能包含数据绑定。因而抽象节点特性并不适用于动态决定节点名的场景。


              自定义组件扩展

              为了更好定制自定义组件的功能,可以使用自定义组件扩展机制。从小程序基础库版本 2.2.3 开始支持。

              扩展后的效果

              为了更好的理解扩展后的效果,先举一个例子:

              // behavior.jsmodule.exports = Behavior({  definitionFilter(defFields) {    defFields.data.from = 'behavior'  },})// component.jsComponent({  data: {    from: 'component'  },  behaviors: [require('behavior.js')],  ready() {    console.log(this.data.from) // 此处会发现输出 behavior 而不是 component  }})

              通过例子可以发现,自定义组件的扩展其实就是提供了修改自定义组件定义段的能力,上述例子就是修改了自定义组件中的 data 定义段里的内容。

              使用扩展

              Behavior() 构造器提供了新的定义段 definitionFilter ,用于支持自定义组件扩展。 definitionFilter 是一个函数,在被调用时会注入两个参数,第一个参数是使用该 behavior 的 component/behavior 的定义对象,第二个参数是该 behavior 所使用的 behavior 的 definitionFilter 函数列表。

              以下举个例子来说明:

              // behavior3.jsmodule.exports = Behavior({    definitionFilter(defFields, definitionFilterArr) {},})// behavior2.jsmodule.exports = Behavior({  behaviors: [require('behavior3.js')],  definitionFilter(defFields, definitionFilterArr) {    // definitionFilterArr[0](defFields)  },})// behavior1.jsmodule.exports = Behavior({  behaviors: [require('behavior2.js')],  definitionFilter(defFields, definitionFilterArr) {},})// component.jsComponent({  behaviors: [require('behavior1.js')],})

              上述代码中声明了1个自定义组件和3个 behavior,每个 behavior 都使用了 definitionFilter 定义段。那么按照声明的顺序会有如下事情发生:

              1. 当进行 behavior2 的声明时就会调用 behavior3 的 definitionFilter 函数,其中 defFields 参数是 behavior2 的定义段, definitionFilterArr 参数即为空数组,因为 behavior3 没有使用其他的 behavior 。
              2. 当进行 behavior1 的声明时就会调用 behavior2 的 definitionFilter 函数,其中 defFields 参数是 behavior1 的定义段, definitionFilterArr 参数是一个长度为1的数组,definitionFilterArr[0] 即为 behavior3 的 definitionFilter 函数,因为 behavior2 使用了 behavior3。用户在此处可以自行决定在进行 behavior1 的声明时要不要调用 behavior3 的 definitionFilter 函数,如果需要调用,在此处补充代码 definitionFilterArr[0](defFields) 即可,definitionFilterArr 参数会由基础库补充传入。
              3. 同理,在进行 component 的声明时就会调用 behavior1 的 definitionFilter 函数。

              简单概括,definitionFilter 函数可以理解为当 A 使用了 B 时,A 声明就会调用 B 的 definitionFilter 函数并传入 A 的定义对象让 B 去过滤。此时如果 B 还使用了 C 和 D ,那么 B 可以自行决定要不要调用 C 和 D 的 definitionFilter 函数去过滤 A 的定义对象。

              真实案例

              下面利用扩展简单实现自定义组件的计算属性功能:

              // behavior.jsmodule.exports = Behavior({  lifetimes: {    created() {      this._originalSetData = this.setData // 原始 setData      this.setData = this._setData // 封装后的 setData    }  },  definitionFilter(defFields) {    const computed = defFields.computed || {}    const computedKeys = Object.keys(computed)    const computedCache = {}    // 计算 computed    const calcComputed = (scope, insertToData) => {      const needUpdate = {}      const data = defFields.data = defFields.data || {}      for (let key of computedKeys) {        const value = computed[key].call(scope) // 计算新值        if (computedCache[key] !== value) needUpdate[key] = computedCache[key] = value        if (insertToData) data[key] = needUpdate[key] // 直接插入到 data 中,初始化时才需要的操作      }      return needUpdate    }    // 重写 setData 方法    defFields.methods = defFields.methods || {}    defFields.methods._setData = function (data, callback) {      const originalSetData = this._originalSetData // 原始 setData      originalSetData.call(this, data, callback) // 做 data 的 setData      const needUpdate = calcComputed(this) // 计算 computed      originalSetData.call(this, needUpdate) // 做 computed 的 setData    }    // 初始化 computed    calcComputed(defFields, true) // 计算 computed  }})

              在组件中使用:

              const beh = require('./behavior.js')Component({  behaviors: [beh],  data: {    a: 0,  },  computed: {    b() {      return this.data.a + 100    },  },  methods: {    onTap() {      this.setData({        a: ++this.data.a,      })    }  }})
              <view>data: {{a}}</view><view>computed: {{b}}</view><button bindtap="onTap">click</button>

              实现原理很简单,对已有的 setData 进行二次封装,在每次 setData 的时候计算出 computed 里各字段的值,然后设到 data 中,已达到计算属性的效果。

              此实现只是作为一个简单案例来展示,请勿直接在生产环境中使用。

              官方扩展包


              开发第三方自定义组件

              小程序从基础库版本 2.2.1 开始支持使用 npm 安装第三方包,因此也支持开发和使用第三方自定义组件包。关于 npm 功能的详情可先阅读[相关文档]((npm 支持))。

              准备

              开发一个开源的自定义组件包给他人使用,首先需要明确他人是要如何使用这个包的,如果只是拷贝小程序目录下直接使用的话,可以跳过此文档。此文档中后续内容是以 npm 管理自定义组件包的前提下进行说明的。

              在开发之前,要求开发者具有基础的 node.js 和 npm 相关的知识,同时需要准备好支持 npm 功能的开发者工具,点此下载。

              下载模板

              为了方便开发者能够快速搭建好一个可用于开发、调试、测试的自定义组件包项目,官方提供了一个项目模板,下载使用模板的方式有三种:

              • 直接从 github 上下载 zip 文件并解压。
              • 直接将 github 上的仓库 clone 下来。
              • 使用官方提供的命令行工具初始化项目,下面会进行介绍。

              项目模板中的构建是基于 gulp + webpack 来执行的,支持开发、构建、测试等命令,详情可参阅项目模板的 README.md 文件。

              命令行工具

              官方提供了命令行工具,用于快速初始化一个项目。执行如下命令安装命令行工具:

              npm install -g @wechat-miniprogram/miniprogram-cli

              然后新建一个空目录作为项目根目录,在此根目录下执行:

              miniprogram init --type custom-component

              命令执行完毕后会发现项目根目录下生成了许多文件,这是根据官方的项目模板生成的完整项目,之后开发者可直接在此之上进行开发修改。

              命令行工具的更多用法可以查看 github 仓库上的 README.md 文件。

              PS:第一次使用 miniprogram init 初始化项目会去 github 上拉取模板,因此需要保证网络畅通。

              测试工具

              针对自定义组件的单元测试,可参阅文档单元测试

              自定义组件示例

              以下为官方提供的自定义组件,可以参考并使用:

              自定义组件扩展示例

              以下为官方提供的自定义组件扩展,可以参考并使用:


              单元测试

              在编写高质量的自定义组件过程中,单元测试是永远避不开的一个话题。完善的测试用例是提高自定义组件可用性的保证,同时测试代码覆盖率也是必不可少的一个环节。小程序从基础库版本 2.2.1 开始拥抱开源,支持使用 npm 安装自定义组件,那针对自定义组件的单元测试也是必须支持的。

              以下就来介绍如何对自定义组件进行单元测试。

              测试框架

              现在市面上流行的测试框架均可使用,只要它能兼顾 nodejs 端和 dom 环境。因为我们需要依赖到 nodejs 的一些库来完善测试环境,同时 dom 环境也是必须的,因为我们需要建成完整的 dom 树结构,才能更好的模拟自定义组件的运行。例如可以选用 mocha + jsdom 的组合,亦可选用 jest,下述例子选用 jest 作为测试框架来说明。

              自定义组件测试工具集

              小程序的运行环境比较特殊,不同于常见的浏览器环境,它采用的是双线程的架构。而在进行单元测试时,我们并不需要用到这样复杂的架构带来的利好,我们进行的是功能测试而无需苛求性能、安全等因素,因此我们提供了一个测试工具集以支持自定义组件在 nodejs 单线程中也能运行起来。

              我们先安装一下测试工具集——miniprogram-simulate

              npm i --save-dev miniprogram-simulate

              编写测试用例

              假设我们有如下自定义组件:

              <!-- /components/index.wmxl --><view class="index">{{prop}}</view>
              // /components/index.jsComponent({  properties: {    prop: {      type: String,      value: 'index.properties'    },  },})
              /* /components/index.wxss */.index {  color: green;}

              我们想要测试渲染的结果,可以按照如下方式编写测试用例:

              // /test/components/index.test.jsconst simulate = require('miniprogram-simulate')test('components/index', () => {    const id = simulate.load('/components/index') // 此处必须传入绝对路径    const comp = simulate.render(id) // 渲染成自定义组件树实例    const parent = document.createElement('parent-wrapper') // 创建父亲节点    comp.attach(parent) // attach 到父亲节点上,此时会触发自定义组件的 attached 钩子    const view = comp.querySelector('.index') // 获取子组件 view    expect(view.dom.innerHTML).toBe('index.properties') // 测试渲染结果    expect(window.getComputedStyle(view.dom).color).toBe('green') // 测试渲染结果})
              PS:测试工具集中的 wx 对象和内置组件都不会实现真正的功能,如果需要测试一些特殊场景的话,可以自行覆盖掉测试工具集中的 api 接口和内置组件。PS:目前因为有部分自定义组件功能仍未支持(如抽象节点等),故测试工具暂无法全部覆盖自定义组件的特性,后续会继续完善。

              测试工具集中提供了一些方便测试的接口,比如:

              • 模拟 touch 事件、自定义事件触发
              • 选取子节点
              • 更新自定义组件数据
              • 触发生命周期
              • ...

              更多详细的用法可以参阅 github 仓库上的文档。


              开发插件

              开发插件前,请阅读了解《小程序插件接入指南》了解开通流程及开放范围,并开通插件功能。如果未开通插件功能,将无法上传插件。

              创建插件项目

              插件类型的项目可以在开发者工具中直接创建。

              创建插件

              新建插件类型的项目后,如果创建示例项目,则项目中将包含三个目录:

              • plugin 目录:插件代码目录。
              • miniprogram 目录:放置一个小程序,用于调试插件。
              • doc 目录:用于放置插件开发文档。

              miniprogram 目录内容可以当成普通小程序来编写,用于插件调试、预览和审核。下面的内容主要介绍 plugin 中的插件代码及 doc 中的插件开发文档。

              我们提供了一个可以直接在微信开发者工具中查看的完整插件示例,开发者可以和本文互相对照以便理解。请注意:

              1. 由于插件需要 appid 才能工作,请填入一个 appid;
              2. 由于当前代码片段的限制,打开该示例后请 手动将 appid 填写到 miniprogram/app.json 中(如下图)使示例正常运行。

              手动填写 appid

              插件目录结构

              一个插件可以包含若干个自定义组件、页面,和一组 js 接口。插件的目录内容如下:

              plugin├── components│   ├── hello-component.js   // 插件提供的自定义组件(可以有多个)│   ├── hello-component.json│   ├── hello-component.wxml│   └── hello-component.wxss├── pages│   ├── hello-page.js        // 插件提供的页面(可以有多个,自小程序基础库版本 2.1.0 开始支持)│   ├── hello-page.json│   ├── hello-page.wxml│   └── hello-page.wxss├── index.js                 // 插件的 js 接口└── plugin.json              // 插件配置文件

              插件配置文件

              向使用者小程序开放的所有自定义组件、页面和 js 接口都必须在插件配置文件 plugin.json 列出,格式如下:

              代码示例:

              {  "publicComponents": {    "hello-component": "components/hello-component"  },  "pages": {    "hello-page": "pages/hello-page"  },  "main": "index.js"}

              这个配置文件将向使用者小程序开放一个自定义组件 hello-component,一个页面 hello-page 和 index.js 下导出的所有 js 接口。

              进行插件开发

              请注意:在插件开发中,只有部分接口可以直接调用;另外还有部分能力(如 获取用户信息 和 发起支付 等)可以通过插件功能页的方式使用。

              自定义组件

              插件可以定义若干个自定义组件,这些自定义组件都可以在插件内相互引用。但提供给使用者小程序使用的自定义组件必须在配置文件的 publicComponents 段中列出(参考上文)。

              除去接口限制以外,自定义组件的编写和组织方式与一般的自定义组件相同,每个自定义组件由 wxml, wxss, js 和 json 四个文件组成。具体可以参考自定义组件的文档

              页面

              插件从小程序基础库版本 2.1.0 开始支持页面。插件可以定义若干个插件页面,可以从本插件的自定义组件、其他页面中跳转,或从使用者小程序中跳转。所有页面必须在配置文件的 pages 段中列出(参考上文)。

              除去接口限制以外,插件的页面编写和组织方式与一般的页面相同,每个页面由 wxml, wxss, js 和 json 四个文件组成。具体可以参考其他关于页面的文档。

              插件执行页面跳转的时候,可以使用 navigator 组件。当插件跳转到自身页面时, url 应设置为这样的形式:plugin-private://PLUGIN_APPID/PATH/TO/PAGE 。需要跳转到其他插件时,也可以这样设置 url 。

              代码示例:

              <navigator url="plugin-private://wxidxxxxxxxxxxxxxx/pages/hello-page">  Go to pages/hello-page!</navigator>

              自基础库版本 2.2.2 开始,在插件自身的页面中,插件还可以调用 wx.navigateTo 来进行页面跳转, url 格式与使用 navigator 组件时相仿。

              接口

              插件可以在接口文件(在配置文件中指定,详情见上文)中 export 一些 js 接口,供插件的使用者调用,如:

              代码示例:

              module.exports = {  hello: function() {    console.log('Hello plugin!')  }}

              获取小程序导出

              从基础库 2.11.1 起,在插件中有全局函数 requireMiniProgram,可以获取由使用者小程序导出的内容。

              例如,使用者小程序做了如下导出:

              // 使用者小程序module.exports = {  greeting() {    return 'Greetings from Wechat MiniProgram!';  }}

              那么在插件中,可以这样获得内容:

              // 插件const miniProgramExports = requireMiniProgram();miniProgramExports.greeting(); // 'Greetings from Wechat MiniProgram!'

              预览、上传和发布

              插件可以像小程序一样预览和上传,但插件没有体验版。

              插件会同时有多个线上版本,由使用插件的小程序决定具体使用的版本号。

              手机预览和提审插件时,会使用一个特殊的小程序来套用项目中 miniprogram 文件夹下的小程序,从而预览插件。

              • (建议的方式)如果当前开发者有测试号,则会使用这个测试号;在测试号的设置页中可以看到测试号的 appid 、 appsecret 并设置域名列表。
              • 否则,将使用“插件开发助手”,它具有一个特定的 appid 。

              在开发版小程序中测试

              通常情况下,可以将 miniprogram 下的代码当做使用插件的小程序代码,来进行插件的调试和测试。

              但有时,需要将插件的代码放在实际运行的小程序中进行调试、测试。此时,可以使用开发版的小程序直接引用开发版插件。方法如下:

              1. 在开发者工具的插件项目中上传插件,此时,在上传成功的通知信息中将包含这次上传获得的插件开发版 ID (一个英文、数字组成的随机字符串);
              2. 点击开发者工具右下角的通知按钮,可以打开通知栏,看到新生成的 ID ;
              3. 在使用这个插件的任意小程序项目中,可以将插件 version 设置为 "version": "dev-[开发版ID]" 的形式,如 "version": "dev-abcdef0123456789abcdef0123456789" ;
              4. 这样就会引用到这次上传的开发版插件;
              5. 注意,再次上传插件时, ID 可能会改变。

              如果开发版小程序引用了开发版插件,此时这个小程序就不能上传发布了。必须要将插件版本设为正式版本之后,小程序才可以正常上传、发布。

              插件开发文档

              在使用者小程序使用插件时,插件代码并不可见。因此,除了插件代码,我们还支持插件开发者上传一份插件开发文档。这份开发文档将展示在插件详情页,供其他开发者在浏览插件和使用插件时进行阅读和参考。插件开发者应在插件开发文档中对插件提供的自定义组件、页面、接口等进行必要的描述和解释,方便使用者小程序正确使用插件。

              插件开发文档必须放置在插件项目根目录中的 doc 目录下,目录结构如下:

              doc├── README.md   // 插件文档,应为 markdown 格式└── picture.jpg // 其他资源文件,仅支持图片

              其中,README.md 的编写有一定的 限制条件,具体来说:

              1. 引用到的图片资源不能是网络图片,且必须放在这个目录下;
              2. 文档中的链接只能链接到:微信开发者社区(developers.weixin.qq.com)微信公众平台(mp.weixin.qq.com)GitHub(github.com)

              编辑 README.md 之后,可以在开发者工具左侧资源管理器的文件栏中右键单击 README.md,并选择上传文档。发布上传文档后,文档不会立刻发布。此时可以使用帐号和密码登录 管理后台 ,在 小程序插件 > 基本设置 中预览、发布插件文档。

              其他注意事项

              插件间互相调用

              插件不能直接引用其他插件。但如果小程序引用了多个插件,插件之间是可以互相调用的。

              一个插件调用另一个插件的方法,与插件调用自身的方法类似。可以使用 plugin-private://APPID 访问插件的自定义组件、页面(暂不能使用 plugin:// )。

              对于 js 接口,可使用 requirePlugin ,但目前尚不能在文件一开头就使用 requirePlugin ,因为被依赖的插件可能还没有初始化,请考虑在更晚的时机调用 requirePlugin ,如接口被实际调用时、组件 attached 时。(未来会修复这个问题。)

              插件请求签名

              插件在使用 wx.request 等 API 发送网络请求时,将会额外携带一个签名 HostSign ,用于验证请求来源于小程序插件。这个签名位于请求头中,形如:

              X-WECHAT-HOSTSIGN: {"noncestr":"NONCESTR", "timestamp":"TIMESTAMP", "signature":"SIGNATURE"}

              其中, NONCESTR 是一个随机字符串, TIMESTAMP 是生成这个随机字符串和 SIGNATURE 的 UNIX 时间戳。它们是用于计算签名 SIGNATRUE 的参数,签名算法为:

              SIGNATURE = sha1([APPID, NONCESTR, TIMESTAMP, TOKEN].sort().join(''))

              其中,APPID 是 所在小程序 的 AppId (可以从请求头的 referrer 中获得);TOKEN 是插件 Token,可以在小程序插件基本设置中找到。

              网络请求的 referer 格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 appid,{version} 为小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本。

              插件开发者可以在服务器上按以下步骤校验签名:

              1. sort 对 APPID NONCESTR TIMESTAMP TOKEN 四个值表示成字符串形式,按照字典序排序(同 JavaScript 数组的 sort 方法);
              2. join 将排好序的四个字符串直接连接在一起;
              3. 对连接结果使用 sha1 算法,其结果即 SIGNATURE 。

              自基础库版本 2.0.7 开始,在小程序运行期间,若网络状况正常, NONCESTR 和 TIMESTAMP 会每 10 分钟变更一次。如有必要,可以通过判断 TIMESTAMP 来确定当前签名是否依旧有效。


              使用插件

              添加插件

              在使用插件前,首先要在小程序管理后台的“设置-第三方服务-插件管理”中添加插件。开发者可登录小程序管理后台,通过 appid 查找插件并添加。如果插件无需申请,添加后可直接使用;否则需要申请并等待插件开发者通过后,方可在小程序中使用相应的插件。

              引入插件代码包

              使用插件前,使用者要在 app.json 中声明需要使用的插件,例如:

              代码示例:

              {  "plugins": {    "myPlugin": {      "version": "1.0.0",      "provider": "wxidxxxxxxxxxxxxxxxx"    }  }}

              如上例所示, plugins 定义段中可以包含多个插件声明,每个插件声明以一个使用者自定义的插件引用名作为标识,并指明插件的 appid 和需要使用的版本号。其中,引用名(如上例中的 myPlugin)由使用者自定义,无需和插件开发者保持一致或与开发者协调。在后续的插件使用中,该引用名将被用于表示该插件。

              在分包内引入插件代码包

              如果插件只在一个分包内用到,可以将插件仅放在这个分包内,例如:

              {  "subpackages": [    {      "root": "packageA",      "pages": [        "pages/cat",        "pages/dog"      ],      "plugins": {        "myPlugin": {          "version": "1.0.0",          "provider": "wxidxxxxxxxxxxxxxxxx"        }      }    }  ]}

              在分包内使用插件有如下限制:

              • 仅能在这个分包内使用该插件;
              • 同一个插件不能被多个分包同时引用;
              • 如果基础库版本低于 2.9.0 ,不能从分包外的页面直接跳入分包内的插件页面,需要先跳入分包内的非插件页面、再跳入同一分包内的插件页面。

              使用插件

              使用插件时,插件的代码对于使用者来说是不可见的。为了正确使用插件,使用者应查看插件详情页面中的“开发文档”一节,阅读由插件开发者提供的插件开发文档,通过文档来明确插件提供的自定义组件、页面名称及提供的 js 接口规范等。

              自定义组件

              使用插件提供的自定义组件,和使用普通自定义组件的方式相仿。在 json 文件定义需要引入的自定义组件时,使用 plugin:// 协议指明插件的引用名和自定义组件名,例如:

              代码示例:

              {  "usingComponents": {    "hello-component": "plugin://myPlugin/hello-component"  }}

              出于对插件的保护,插件提供的自定义组件在使用上有一定的限制:

              • 默认情况下,页面中的 this.selectComponent 接口无法获得插件的自定义组件实例对象;
              • wx.createSelectorQuery 等接口的 >>> 选择器无法选入插件内部。

              页面

              插件的页面从小程序基础库版本 2.1.0 开始支持。

              需要跳转到插件页面时,url 使用 plugin:// 前缀,形如 plugin://PLUGIN_NAME/PLUGIN_PAGE, 如:

              代码示例:

              <navigator url="plugin://myPlugin/hello-page">  Go to pages/hello-page!</navigator>

              js 接口

              使用插件的 js 接口时,可以使用 requirePlugin 方法。例如,插件提供一个名为 hello 的方法和一个名为 world 的变量,则可以像下面这样调用:

              var myPluginInterface = requirePlugin('myPlugin');myPluginInterface.hello();var myWorld = myPluginInterface.world;

              导出到插件

              从基础库 2.11.1 起,使用插件的小程序可以导出一些内容,供插件获取。具体来说,在声明使用插件时,可以通过 export 字段来指定一个文件,如:

              {  "myPlugin": {    "version": "1.0.0",    "provider": "wxidxxxxxxxxxxxxxxxx",    "export": "index.js"  }}

              则该文件(上面的例子里是 index.js)导出的内容可以被这个插件用全局函数获得。例如,在上面的文件中,使用插件的小程序做了如下导出:

              // index.jsmodule.exports = { whoami: 'Wechat MiniProgram' }

              那么插件就可以获得上面导出的内容:

              // pluginrequireMiniProgram().whoami // 'Wechat MiniProgram'

              具体导出什么内容,可以阅读插件开发文档,和插件的开发者做好约定。

              当插件在分包中时,这个特性也可以使用,但指定的文件的路径是相对于分包的。例如在 root: packageA 的分包中指定了 export: exports/plugin.js,那么被指定的文件在文件系统上应该是 /packageA/exports/plugin.js。

              使用的多个插件的导出互不影响,两个插件可以导出同一个文件,也可以是不同的文件。但导出同一个文件时,如果一个插件对导出内容做了修改,那么另一个插件也会被影响,请注意这一点。

              请谨慎导出 wx 对象或某个具体的 wx API,这将使插件可以以使用者小程序的身份调用 API。


              插件调用 API 的限制

              插件可以调用的 API 与小程序不同,主要有两个区别:

              • 插件的请求域名列表与小程序相互独立;
              • 一些 API 不允许插件调用(这些函数不存在于 wx 对象下)。

              有些接口虽然在插件中不能使用,但可以通过插件功能页来达到目的,请参考插件功能页。

              目前,允许插件调用的 API 及其对应版本要求如下:

              基础

              API最低版本备注
              wx.arrayBufferToBase64
              wx.base64ToArrayBuffer

              发起请求

              API最低版本备注
              wx.request1.9.6

              上传、下载

              API最低版本备注
              wx.downloadFile1.9.6
              wx.uploadFile1.9.6

              WebSocket

              API最低版本备注
              wx.connectSocket1.9.6

              图片

              API最低版本备注
              wx.previewImage1.9.6
              wx.chooseImage1.9.6
              wx.getImageInfo1.9.6
              wx.saveImageToPhotosAlbum1.9.6

              录音

              API最低版本备注
              wx.startRecord1.9.6
              wx.stopRecord1.9.6

              实时音视频

              API最低版本备注
              wx.createLivePlayerContext1.9.6
              wx.createLivePusherContext1.9.6

              录音管理

              API最低版本备注
              wx.getRecorderManager1.9.94

              音频播放控制

              API最低版本备注
              wx.pauseVoice1.9.6
              wx.playVoice1.9.6
              wx.stopVoice1.9.6

              音乐播放控制

              API最低版本备注
              wx.onBackgroundAudioPlay1.9.6
              wx.getBackgroundAudioPlayerState1.9.6
              wx.onBackgroundAudioStop1.9.6
              wx.stopBackgroundAudio1.9.6
              wx.onBackgroundAudioPause1.9.6
              wx.seekBackgroundAudio1.9.6
              wx.playBackgroundAudio1.9.6
              wx.pauseBackgroundAudio1.9.6

              背景音频播放管理

              API最低版本备注
              wx.getBackgroundAudioManager1.9.6

              音频组件控制

              API最低版本备注
              wx.createInnerAudioContext1.9.6
              wx.createAudioContext1.9.6

              视频

              API最低版本备注
              wx.chooseVideo1.9.6
              wx.saveVideoToPhotosAlbum1.9.6

              视频组件控制

              API最低版本备注
              wx.createVideoContext1.9.6

              相机组件控制

              API最低版本备注
              wx.createCameraContext1.9.6

              数据缓存

              API最低版本备注
              wx.setStorage1.9.6
              wx.getStorage1.9.6
              wx.removeStorage1.9.6
              wx.setStorageSync1.9.6
              wx.getStorageSync1.9.6
              wx.removeStorageSync1.9.6

              获取位置

              API最低版本备注
              wx.getLocation1.9.6
              wx.chooseLocation1.9.6
              wx.onLocationChange2.8.0
              wx.offLocationChange2.9.1
              wx.stopLocationUpdate2.8.0
              wx.startLocationUpdate2.8.0

              查看位置

              API最低版本备注
              wx.openLocation1.9.6

              地图组件控制

              API最低版本备注
              wx.createMapContext1.9.6

              系统信息

              API最低版本备注
              wx.getSystemInfoSync1.9.6
              wx.getSystemInfo1.9.6

              屏幕亮度

              API最低版本备注
              wx.setKeepScreenOn1.9.6
              wx.setScreenBrightness1.9.6
              wx.getScreenBrightness1.9.6

              用户截屏事件

              API最低版本备注
              wx.onUserCaptureScreen1.9.6仅限插件页面中调用
              wx.offUserCaptureScreen2.9.1仅限插件页面中调用

              振动

              API最低版本备注
              wx.vibrateLong1.9.6
              wx.vibrateShort1.9.6

              手机联系人

              API最低版本备注
              wx.addPhoneContact1.9.6

              NFC

              API最低版本备注
              wx.sendHCEMessage2.1.0
              wx.stopHCE2.1.0
              wx.onHCEMessage2.1.0
              wx.offHCEMessage2.9.1
              wx.startHCE2.1.0
              wx.getHCEState2.1.0

              网络状态

              API最低版本备注
              wx.onNetworkStatusChange1.9.6
              wx.offNetworkStatusChange2.9.1
              wx.getNetworkType1.9.6

              加速度计

              API最低版本备注
              wx.startAccelerometer1.9.6
              wx.stopAccelerometer1.9.6
              wx.onAccelerometerChange1.9.6
              wx.offAccelerometerChange2.9.1

              设备方向

              API最低版本备注
              wx.startDeviceMotionListening2.9.1
              wx.stopDeviceMotionListening2.9.1
              wx.offDeviceMotionChange2.9.1
              wx.onDeviceMotionChange2.9.1

              陀螺仪

              API最低版本备注
              wx.startGyroscope2.9.1
              wx.stopGyroscope2.9.1
              wx.offGyroscopeChange2.9.1
              wx.onGyroscopeChange2.9.1

              罗盘

              API最低版本备注
              wx.onCompassChange1.9.6
              wx.offCompassChange2.9.1
              wx.stopCompass1.9.6
              wx.startCompass1.9.6

              拨打电话

              API最低版本备注
              wx.makePhoneCall1.9.6

              扫码

              API最低版本备注
              wx.scanCode1.9.6

              剪贴板

              API最低版本备注
              wx.setClipboardData1.9.6
              wx.getClipboardData1.9.6

              蓝牙

              API最低版本备注
              wx.writeBLECharacteristicValue1.9.6
              wx.startBluetoothDevicesDiscovery1.9.6
              wx.getConnectedBluetoothDevices1.9.6
              wx.notifyBLECharacteristicValueChange1.9.6
              wx.onBluetoothDeviceFound1.9.6
              wx.offBluetoothDeviceFound2.9.1
              wx.readBLECharacteristicValue1.9.6
              wx.openBluetoothAdapter1.9.6
              wx.getBLEDeviceCharacteristics1.9.6
              wx.stopBluetoothDevicesDiscovery1.9.6
              wx.onBLEConnectionStateChange1.9.6
              wx.getBluetoothDevices1.9.6
              wx.getBluetoothAdapterState1.9.6
              wx.onBluetoothAdapterStateChange1.9.6
              wx.offBluetoothAdapterStateChange2.9.1
              wx.getBLEDeviceServices1.9.6
              wx.onBLECharacteristicValueChange1.9.6
              wx.offBLECharacteristicValueChange2.9.1
              wx.createBLEConnection1.9.6
              wx.closeBluetoothAdapter1.9.6
              wx.closeBLEConnection1.9.6
              wx.notifyBLECharacteristicValueChange1.9.6
              wx.onBLEConnectionStateChange1.9.6
              wx.offBLEConnectionStateChange2.9.1

              iBeacon

              API最低版本备注
              wx.getBeacons1.9.6
              wx.startBeaconDiscovery1.9.6
              wx.onBeaconServiceChange1.9.6
              wx.offBeaconServiceChange2.9.1
              wx.onBeaconUpdate1.9.6
              wx.offBeaconUpdate2.9.1
              wx.stopBeaconDiscovery1.9.6

              Wi-Fi

              API最低版本备注
              wx.connectWifi2.9.1
              wx.getConnectedWifi2.9.1
              wx.getWifiList2.9.1
              wx.offGetWifiList2.9.1
              wx.offWifiConnected2.9.1
              wx.onEvaluateWifi2.9.1
              wx.onGetWifiList2.9.1
              wx.onWifiConnected2.9.1
              wx.presetWifiList2.9.1
              wx.setWifiList2.9.1
              wx.startWifi2.9.1
              wx.stopWifi2.9.1

              交互反馈

              API最低版本备注
              wx.hideLoading1.9.6
              wx.showActionSheet1.9.6
              wx.showLoading1.9.6
              wx.hideToast1.9.6
              wx.showToast1.9.6
              wx.showModal1.9.6

              设置导航条

              API最低版本备注
              wx.showNavigationBarLoading2.1.0仅限插件页面中调用
              wx.hideNavigationBarLoading2.1.0仅限插件页面中调用
              wx.setNavigationBarColor2.1.0仅限插件页面中调用
              wx.setNavigationBarTitle2.1.0仅限插件页面中调用

              背景

              API最低版本备注
              wx.setBackgroundColor2.4.0仅限插件页面中调用
              wx.setBackgroundTextStyle2.4.0仅限插件页面中调用

              WXML节点信息

              API最低版本备注
              wx.createSelectorQuery1.9.6

              WXML节点布局相交状态

              API最低版本备注
              wx.createIntersectionObserver1.9.6

              导航

              API最低版本备注
              wx.navigateBack2.1.0仅限插件页面中调用
              wx.navigateTo2.2.2仅限插件页面中调用
              wx.redirectTo2.2.2仅限插件页面中调用
              wx.switchTab2.3.1仅限插件页面中调用
              wx.reLaunch2.3.1仅限插件页面中调用

              动画

              API最低版本备注
              wx.createAnimation1.9.6

              位置

              API最低版本备注
              wx.pageScrollTo2.1.0仅限插件页面中调用

              绘图

              API最低版本备注
              wx.createOffscreenCanvas2.7.1
              wx.canvasPutImageData1.9.6
              wx.canvasToTempFilePath1.9.6
              wx.createCanvasContext1.9.6
              wx.canvasGetImageData1.9.6

              下拉刷新

              API最低版本备注
              wx.stopPullDownRefresh2.1.0仅限插件页面中调用
              wx.startPullDownRefresh2.1.0仅限插件页面中调用

              当前帐号信息

              API最低版本备注
              wx.getAccountInfoSync2.2.2

              转发

              API最低版本备注
              wx.hideShareMenu2.1.0仅限插件页面中调用
              wx.getShareInfo2.1.0仅限插件页面中调用
              wx.showShareMenu2.1.0仅限插件页面中调用
              wx.updateShareMenu2.1.0仅限插件页面中调用

              其他

              API最低版本备注
              wx.getSetting2.6.3
              wx.openSetting2.10.3
              wx.reportAnalytics1.9.6见下方备注

              登录和获取用户信息

              这一组接口仅限在用户信息功能页中获得用户授权之后调用。否则将返回 fail 。详见 用户信息功能页 。

              API最低版本备注
              wx.login2.3.1
              wx.getUserInfo2.3.1

              提示:

              • wx.reportAnalytics 可以被正常调用,但目前不会进行统计展示。


              插件使用组件的限制

              在插件开发中,以下组件不能在插件页面中使用:

              • 开放能力(open-type)为以下之一的 button

                • contact(打开客服会话)
                • getPhoneNumber(获取用户手机号)
                • getUserInfo(获取用户信息)
              • open-data
              • web-view

              以下组件的使用对基础库版本有要求:


              插件功能页

              插件功能页从小程序基础库版本 2.1.0 开始支持。

              某些接口不能在插件中直接调用(如 wx.login),但插件开发者可以使用插件功能页的方式来实现功能。目前,插件功能页包括:

              • 获取用户信息,包括 openid 和昵称等(相当于 wx.login 和 wx.getUserInfo 的功能),详见用户信息功能页;
              • 支付(相当于 wx.requestPayment),详见支付功能页;
              • 获取收货地址(相当于 wx.chooseAddress),详见收货地址功能页。

              要使用插件功能页,需要先激活功能页特性,配置对应的功能页函数,再使用 functional-page-navigator 组件跳转到插件功能页,从而实现对应的功能。详情请参考下文。

              插件所有者小程序

              开始开发之前,我们需要知道,插件功能页是指 插件所有者小程序 中的一个特殊页面。

              插件所有者小程序,指的是与插件 AppID 相同的小程序。例如,“小程序示例”小程序开发了一个“小程序示例插件”,那么无论这个插件被哪个小程序使用,这个插件的 插件所有者小程序 都是“小程序示例”。下文中会继续使用 插件所有者小程序 这个说法。

              插件所有者小程序开发方法

              通常,在开始使用插件功能页的时候,需要开启两个开发者工具窗口,其中一个打开插件项目,另一个打开插件所有者小程序的小程序项目。例如,一个打开“小程序示例插件”项目,另一个打开“小程序示例”项目。

              这两个窗口,前者用于编辑插件,后者用于编辑插件所有者小程序。下文中所有需要编辑插件所有者小程序的内容,都是在后者中进行。

              激活功能页特性

              要在插件中调用插件功能页,需要先激活插件所有者小程序的功能页特性。具体来说,在插件所有者小程序的 app.json 文件中添加 functionalPages 定义段,并令其值为 true ,例如:

              代码示例:

              {  "functionalPages": {    "independent": true  }}

              目前,兼容旧式写法:

              {  "functionalPages": true}

              旧式写法将在未来将被移除支持,未来将不能编译上传。

              这两种写法的区别在于,新式的写法 "independent": true 会使得插件功能页的代码独立于其他代码,这意味着插件功能页可以被独立下载、加载,具有更好的性能表现。 但也同时使得插件功能页目录 functional-pages/ (支付功能页会使用其中的文件)不能 require 这个目录以外的文件(反之亦然:这个目录以外的文件也不能调用这个目录内的)。

              注意,新增或改变这个字段时,需要这个小程序发布新版本,才能在正式环境中使用插件功能页。

              跳转到功能页

              功能页不能使用 wx.navigateTo 来进行跳转,而是需要一个名为 functional-page-navigator 的组件。以获取用户信息为例,可以在插件中放置如下的 functional-page-navigator:

              代码示例:

              <functional-page-navigator name="loginAndGetUserInfo" args="" version="develop" bind:success="loginSuccess">  <button>登录到插件</button></functional-page-navigator>

              用户在点击这个 navigator 时,会自动跳转到插件所有者小程序的对应功能页。功能页会提示用户进行登录或其他相应的操作。操作结果会以组件事件的方式返回。

              functional-page-navigator 的参数和详细使用方法可以参考组件说明 。

              从小程序基础库版本 2.4.0 开始,支持插件所有者小程序跳转到自己的功能页。在基础库版本低于 2.4.0 时,点击跳转到自己的功能页的 functional-page-navigator 将没有任何反应。

              真机开发测试的常规步骤

              目前,功能页的跳转目前不支持在开发者工具中调试,请在真机上测试。初次进行真机开发测试时,通常步骤如下:

              1. 在开发者工具上打开插件所有者小程序项目,并点击“预览”;
              2. 用测试用的真机扫一下预览二维码,此时会进入插件所有者小程序,进入后就可以直接退出这个小程序;
              3. 在开发者工具上打开插件项目,将插件中 functional-page-navigator 中的 version 属性设置为 develop;
              4. 点击预览可以生成插件预览二维码,用测试用的真机扫码即可预览功能页;如果更改了插件代码,重新生成并扫描插件的预览二维码即可;
              5. 如果过了一段时间之后,跳转功能页时出现“开发版已过期”这样的提示,从第1步开始重试一次。

              注意:functional-page-navigator 的 version=develop 仅用于调试,因此在插件提审前,需要:

              1. 确保已发布设置了 "functionalPages": true 的插件所有者小程序;
              2. 确保所有的 functional-page-navigator 组件属性设置为 version="release" 。

              功能页常见问题 FAQ

              如何正确编辑插件所有者小程序?

              • 应该在开发者工具的“小程序”类型项目中编辑,而不是在“插件”类型的项目中编辑。比如,“小程序示例插件”的所有者小程序是“小程序示例”,它们的 AppID 都是 wxidxxxxxxxxxxxxxx ,如果是初次开发“小程序示例”小程序,可以在开发者工具中创建一个小程序项目,其 AppID 为 wxidxxxxxxxxxxxxxx ;如果之前开发过“小程序示例”小程序,直接打开之前的小程序项目即可。

              点击 functional-page-navigator 之后没有任何反应。

              • 请检查引用插件的小程序和插件本身是不是同一个 AppID ,如果是,跳转到自己的功能页需要基础库 2.4.0 支持,否则使用 functional-page-navigator 不会有任何反应。

              点击 functional-page-navigator 之后,展示了一个页面提示“页面不存在”。

              • 这种情况是因为插件所有者小程序没有正确设置 "functionalPages": true 。如果 functional-page-navigator 的 version="develop" ,这部手机需要扫码并进入插件所有者小程序一次;如果 version="release" ,请确保包含 "functionalPages": true 的插件所有者小程序已被发布。

              点击 <functional-page-navigator version="develop"> 之后,弹窗提示“小程序开发版已过期”。

              • 遇到这种情况,重新扫码并进入插件所有者小程序一次即可。

              点击 <functional-page-navigator name="requestPayment"> 之后,展示了一个页面提示“该功能无法使用”。

              • 在使用插件功能页时,小程序不能是个人小程序,同时,插件也需要额外的步骤申请开通插件支付权限(位于 管理后台 -> 小程序插件 -> 基本设置 -> 支付能力 )。

              点击 <functional-page-navigator name="requestPayment"> 之后,点击页面中的“支付”按钮,立刻退出了支付功能页。

              • 这通常是因为没有找到功能页函数 beforeRequestPayment ,请检查插件所有者小程序的 functional-pages/request-payment.js 文件和其中的 beforeRequestPayment 函数是否存在。

              点击 functional-page-navigator 之后,展示了一个仅有返回按钮的页面。

              • 请检查 functional-page-navigator 的 name 属性是否被正确设置。

              开发版可以正常跳转,但审核反馈不能跳转。

              • 请发布设置了 "functionalPages": true 的插件所有者小程序,且所有的 functional-page-navigator 组件属性设置为 version="release" 。

              Bugs & Tips

              • 功能页是插件所有者小程序中的一个特殊页面,开发者不能自定义这个页面的外观。
              • 插件所有者小程序本身也可以引用这个插件,此时,functional-page-navigator 组件的 version 属性将不会生效,而是取决于当前运行的插件所有者小程序的版本。
              • functional-page-navigator 可以在开发者工具中使用,但功能页的跳转目前不支持在开发者工具中调试,请在真机上测试。
              • Bug:在微信版本 6.6.7 中,功能页被拉起时会触发 App 的部分生命周期并使得功能页启动时间变得比较长。在后续的微信版本中这一行为会发生变更,使 App 生命周期不再被触发。

              用户信息功能页

              用户信息功能页用于帮助插件获取用户信息,包括 openid 和昵称等,相当于 wx.login 和 wx.getUserInfo 的功能。

              此外,自基础库版本 2.3.1 起,用户在这个功能页中授权之后,插件就可以直接调用 wx.login 和 wx.getUserInfo 。无需再次进入功能页获取用户信息。自基础库版本 2.6.3 起,可以使用 wx.getSetting 来查询用户是否授权过。

              调用参数

              用户信息功能页使用 functional-page-navigator 进行跳转时,对应的参数 name 应为固定值 loginAndGetUserInfo,其余参数与 wx.getUserInfo 相同,具体来说:

              args参数说明:

              参数名类型必填说明
              withCredentialsBoolean是否带上登录态信息
              langString指定返回用户信息的语言,zh_CN 简体中文,zh_TW 繁体中文,en 英文。默认为en。
              timeoutNumber超时时间,单位 ms

              注:当 withCredentials 为 true 时,返回的数据会包含 encryptedData, iv 等敏感信息。

              bindsuccess返回参数说明:

              参数类型说明
              codeString同 wx.login 获得的用户登录凭证(有效期五分钟)。开发者需要在开发者服务器后台调用 api,使用 code 换取 openid 和 session_key 等信息
              errMsgString调用结果
              userInfoOBJECT用户信息对象,不包含 openid 等敏感信息
              rawDataString不包括敏感信息的原始数据字符串,用于计算签名。
              signatureString使用 sha1( rawData + sessionkey ) 得到字符串,用于校验用户信息,参考文档 signature。
              encryptedDataString包括敏感数据在内的完整用户信息的加密数据,详细见加密数据解密算法
              ivString加密算法的初始向量,详细见加密数据解密算法

              userInfo参数说明:

              参数类型说明
              nickNameString用户昵称
              avatarUrlString用户头像,最后一个数值代表正方形头像大小(有0、46、64、96、132数值可选,0代表132*132正方形头像),用户没有头像时该项为空。若用户更换头像,原有头像URL将失效。
              genderString用户的性别,值为1时是男性,值为2时是女性,值为0时是未知
              cityString用户所在城市
              provinceString用户所在省份
              countryString用户所在国家
              languageString用户的语言,简体中文为zh_CN

              代码示例:

              <!--plugin/components/hello-component.wxml-->  <functional-page-navigator    name="loginAndGetUserInfo"    args="{{ args }}"    version="develop"    bind:success="loginSuccess"    bind:fail="loginFail"  >    <button class="login">登录到插件</button>  </functional-page-navigator>
              // plugin/components/hello-component.jsComponent({  properties: {},  data: {    args: {      withCredentials: true,      lang: 'zh_CN'    }  },  methods: {    loginSuccess: function (res) {      console.log(res.detail);    },    loginFail: function (res) {      console.log(res);    }  }});

              用户点击该 navigator 后,将跳转到如下的用户信息功能页:

              用户信息功能页

              在微信开发者工具中查看示例:

              1. 由于插件需要 appid 才能工作,请填入一个 appid;
              2. 由于当前代码片段的限制,打开该示例后请 手动将 appid 填写到 miniprogram/app.json 中(如下图)使示例正常运行。

              手动填写 appid


              支付功能页

              支付功能页用于帮助插件完成支付,相当于 wx.requestPayment 的功能。

              需要注意的是:插件使用支付功能,需要进行额外的权限申请,申请位置位于管理后台的“小程序插件 -> 基本设置 -> 支付能力”设置项中。另外,无论是否通过申请,主体为个人小程序在使用插件时,都无法正常使用插件里的支付功能。

              调用参数

              支付功能页使用 functional-page-navigator 进行跳转时,对应的参数 name 应为固定值 requestPayment,其他参数如下:

              args参数说明:

              参数名类型必填说明
              feeNumber需要显示在页面中的金额,单位为分
              paymentArgsObject任意数据,传递给功能页中的响应函数
              currencyTypeString需要显示在页面中的货币符号的代码,默认为 CNY

              currencyType 的合法值:

              说明最低版本
              CNY货币符号 ¥
              USD货币符号 US$
              JPY货币符号 J¥
              EUR货币符号 €
              HKD货币符号 HK$
              GBP货币符号 £
              AUD货币符号 A$
              MOP货币符号 MOP$
              KRW货币符号 ₩

              代码示例:

              <!-- plugin/components/pay.wxml --><!-- 上线时,version 应改为 "release",并确保插件所有者小程序已经发布 --><functional-page-navigator  version="develop"  name="requestPayment"  args="{{ args }}"  bind:success="paymentSuccess"  bind:fail="paymentFailed">  <button class="payment-button">支付 0.01 元</button></functional-page-navigator>
              // plugin/components/pay.jsComponent({  data: {    args: {      fee: 1,             // 支付金额,单位为分      paymentArgs: 'A', // 将传递到功能页函数的自定义参数      currencyType: 'USD' // 货币符号,页面显示货币简写 US$     }  },  methods: {    // 支付成功的回调接口    paymentSuccess: function (e) {      console.log(e);      e.detail.extraData.timeStamp // 用 extraData 传递数据,详见下面功能页函数代码    },    // 支付失败的回调接口    paymentFailed: function (e) {      console.log(e);    }  }})

              用户点击该 navigator 后,将跳转到如下的支付功能页:

              支付功能页

              配置功能页函数

              支付功能页需要插件开发者在插件所有者小程序中提供一个函数来响应插件中的支付调用。即,在插件中跳转到支付功能页时,这个函数就会在合适的时机被调用,来帮助完成支付。如果不提供功能页函数,功能页调用将通过 fail 事件返回失败。

              支付功能页函数应以导出函数的形式提供在插件所有者小程序的根目录下的 functional-pages/request-payment.js 文件中,名为 beforeRequestPayment。该函数应接收两个参数:

              参数名类型说明
              paymentArgsObject即通过 functional-page-navigator 的 arg 参数中的 paymentArgs 字段传递到功能页的自定义数据
              callbackFunction回调函数,调用该函数后,小程序将发起支付(类似于 wx.requestPayment)

              callback函数的参数:

              参数名类型说明
              errorObject失败信息,若无失败,应返回 null
              requestPaymentArgsObject支付参数,用于调用 wx.requestPayment,参数如下

              reqeustPaymentArgs 的参数:

              用于发起支付,和 wx.requestPayment 的参数相同,但没有回调函数(success, fail, complete):

              参数类型必填说明
              timeStampString时间戳从1970年1月1日00:00:00至今的秒数,即当前的时间
              nonceStrString随机字符串,长度为32个字符以下。
              packageString统一下单接口返回的 prepay_id 参数值,提交格式如:prepay_id=***
              signTypeString签名算法,暂支持 MD5
              paySignString签名,具体签名方案参见小程序支付接口文档;
              extraDataany由开发者决定的自定义数据段,该字段将被无修改地透传到支付成功的回调参数中,具体见代码示例中的使用方法。基础库 2.9.1 开始支持

              了解更多信息,请查看微信支付接口文档

              功能页函数代码示例:

              // functional-pages/request-payment.jsexports.beforeRequestPayment = function (paymentArgs, callback) {  // 注意:  // 功能页函数(这个函数)不应 require 其他非 functional-pages 目录中的文件,  // 其他非 functional-pages 目录中的文件也不应 require 这个目录中的文件,  // 这样的 require 调用在未来将不被支持。  //  // 同在 functional-pages 中的文件可以 require  var getOpenIdURL = require('./URL').getOpenIdURL;  var paymentURL = require('./URL').paymentURL;  // 自定义的参数,此处应为从插件传递过来的 'A'  var customArgument = paymentArgs.customArgument;  // 第一步:调用 wx.login 方法获取 code,然后在服务端调用微信接口使用 code 换取下单用户的 openId  // 具体文档参考 https://mp.weixin.qq.com/debug/wxadoc/dev/api/api-login.html?t=20161230#wxloginobject  wx.login({    success: function (data) {      wx.request({        url: getOpenIdURL,        data: { code: data.code },        success: function (res) {          // 拉取用户 openid 成功          // 第二步:在服务端调用支付统一下单,返回支付参数。这里的开发和普通的 wx.requestPayment 相同          // 文档可以参考 https://pay.weixin.qq.com/wiki/doc/api/wxa/wxa_api.php?chapter=7_4&index=3          wx.request({            url: paymentURL,            data: { openid: res.data.openid },            method: 'POST',            success: function (res) {              console.log('unified order success, response is:', res);              var payargs = res.data.payargs;              // 第三步:调用回调函数 callback 进行支付              // 在 callback 中需要返回两个参数: err 和 requestPaymentArgs:              // err 应为 null (或者一些失败信息);              // requestPaymentArgs 将被用于调用 wx.requestPayment,除了 success/fail/complete 不被支持外,              // 应与 wx.requestPayment 参数相同。              var error = null;              var requestPaymentArgs = {                timeStamp: payargs.timeStamp,                nonceStr: payargs.nonceStr,                package: payargs.package,                signType: payargs.signType,                paySign: payargs.paySign,                extraData: { // 用 extraData 传递自定义数据                  timeStamp: payargs.timeStamp                },              };              callback(error, requestPaymentArgs);            }          });        },        fail: function (res) {          console.log('拉取用户openid失败,将无法正常使用开放接口等服务', res);          // callback 第一个参数为错误信息,返回错误信息          callback(res);        }      });    },    fail: function (err) {      console.log('wx.login 接口调用失败,将无法正常使用开放接口等服务', err)      // callback 第一个参数为错误信息,返回错误信息      callback(err);    }  });}

              注意:功能页函数不应 require 其他非 functional-pages 目录中的文件,其他非 functional-pages 目录中的文件也不应 require 这个目录中的文件。这样的 require 调用在未来将不被支持。

              这个目录和文件应当被放置在插件所有者小程序代码中(而非插件代码中),它是插件所有者小程序的一部分(而非插件的一部分)。 如果需要新增或更改这段代码,需要发布插件所有者小程序,才能在正式版中生效;需要重新预览插件所有者小程序,才能在开发版中生效。


              收货地址功能页

              收货地址功能页用于展示用户的收货地址列表,用户可以选择其中的收货地址。自基础库版本 2.4.0 开始支持。

              调用参数

              用户信息功能页使用 functional-page-navigator 进行跳转时,对应的参数 name 应为固定值 chooseAddress ,返回参数与 wx.chooseAddress 相同。

              bindsuccess返回参数说明:

              属性类型说明最低版本
              userNamestring收货人姓名
              postalCodestring邮编
              provinceNamestring国标收货地址第一级地址
              cityNamestring国标收货地址第一级地址
              countyNamestring国标收货地址第一级地址
              detailInfostring详细收货地址信息
              nationalCodestring收货地址国家码
              telNumberstring收货人手机号码
              errMsgstring错误信息

              代码示例:

              <!--plugin/components/hello-component.wxml-->  <functional-page-navigator    name="chooseAddress"    version="develop"    bind:success="onSuccess"    bind:fail="onFail"  >    <button>选择收货地址</button>  </functional-page-navigator>
              // plugin/components/hello-component.jsComponent({  methods: {    onSuccess: function (res) {      console.log(res.detail);    },    onFail: function (res) {      console.log(res);    }  }});


              网络

              在小程序/小游戏中使用网络相关的 API 时,需要注意下列问题,请开发者提前了解。

              1. 服务器域名配置

              每个微信小程序需要事先设置通讯域名,小程序只可以跟指定的域名进行网络通信。包括普通 HTTPS 请求(wx.request)、上传文件(wx.uploadFile)、下载文件( wx.downloadFile) 和 WebSocket 通信(wx.connectSocket)。

              从基础库 2.4.0 开始,网络接口允许与局域网 IP 通信,但要注意 不允许与本机 IP 通信。

              从 2.7.0 开始,提供了 UDP 通信(wx.createUDPSocket)。

              配置流程

              服务器域名请在 「小程序后台-开发-开发设置-服务器域名」 中进行配置,配置时需要注意:

              • 域名只支持 https (wx.request、wx.uploadFile、wx.downloadFile) 和 wss (wx.connectSocket) 协议;
              • 域名不能使用 IP 地址(小程序的局域网 IP 除外)或 localhost;
              • 可以配置端口,如 https://myserver.com:8080,但是配置后只能向 https://myserver.com:8080 发起请求。如果向 https://myserver.com、https://myserver.com:9091 等 URL 请求则会失败。
              • 如果不配置端口。如 https://myserver.com,那么请求的 URL 中也不能包含端口,甚至是默认的 443 端口也不可以。如果向 https://myserver.com:443 请求则会失败。
              • 域名必须经过 ICP 备案;
              • 出于安全考虑,api.weixin.qq.com 不能被配置为服务器域名,相关API也不能在小程序内调用。 开发者应将 AppSecret 保存到后台服务器中,通过服务器使用 getAccessToken 接口获取 access_token,并调用相关 API;
              • 对于每个接口,分别可以配置最多 20 个域名。

              2. 网络请求

              超时时间

              • 默认超时时间和最大超时时间都是 60s;
              • 超时时间可以在 app.json 或 game.json 中通过 networktimeout 配置。

              使用限制

              • 网络请求的 referer header 不可设置。其格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 appid,{version} 为小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本;
              • wx.request、wx.uploadFile、wx.downloadFile 的最大并发限制是 10 个;
              • wx.connectSocket 的最大并发限制是 5 个。
              • 小程序进入后台运行后,如果 5s 内网络请求没有结束,会回调错误信息 fail interrupted;在回到前台之前,网络请求接口调用都会无法调用。

              返回值编码

              • 建议服务器返回值使用 UTF-8 编码。对于非 UTF-8 编码,小程序会尝试进行转换,但是会有转换失败的可能。
              • 小程序会自动对 BOM 头进行过滤(只过滤一个BOM头)。

              回调函数

              • 只要成功接收到服务器返回,无论 statusCode 是多少,都会进入 success 回调。请开发者根据业务逻辑对返回值进行判断。

              3. 常见问题

              HTTPS 证书

              小程序必须使用 HTTPS/WSS 发起网络请求。请求时系统会对服务器域名使用的 HTTPS 证书进行校验,如果校验失败,则请求不能成功发起。由于系统限制,不同平台对于证书要求的严格程度不同。为了保证小程序的兼容性,建议开发者按照最高标准进行证书配置,并使用相关工具检查现有证书是否符合要求。

              对证书要求如下:

              • HTTPS 证书必须有效;证书必须被系统信任,即根证书被已系统内置部署 SSL 证书的网站域名必须与证书颁发的域名一致证书必须在有效期内证书的信任链必需完整(需要服务器配置)
              • iOS 不支持自签名证书;
              • iOS 下证书必须满足苹果 App Transport Security (ATS) 的要求;
              • TLS 必须支持 1.2 及以上版本。部分旧 Android 机型还未支持 TLS 1.2,请确保 HTTPS 服务器的 TLS 版本支持 1.2 及以下版本;
              • 部分 CA 可能不被操作系统信任,请开发者在选择证书时注意小程序和各系统的相关通告。
              证书有效性可以使用 openssl s_client -connect example.com:443 命令验证,也可以使用其他在线工具。

              除了网络请求 API 外,小程序中其他 HTTPS 请求如果出现异常,也请按上述流程进行检查。如 https 的图片无法加载、音视频无法播放等。

              跳过域名校验

              在微信开发者工具中,可以临时开启 开发环境不校验请求域名、TLS版本及HTTPS证书 选项,跳过服务器域名的校验。此时,在微信开发者工具中及手机开启调试模式时,不会进行服务器域名的校验。

              在服务器域名配置成功后,建议开发者关闭此选项进行开发,并在各平台下进行测试,以确认服务器域名配置正确。

              如果手机上出现 “打开调试模式可以发出请求,关闭调试模式无法发出请求” 的现象,请确认是否跳过了域名校验,并确认服务器域名和证书配置是否正确。

              局域网通信

              基础库 2.4.0 提供了 wx.startLocalServiceDiscovery 等一系列 mDNS API,可以用来获取局域网内提供 mDNS 服务的设备的 IP。 wx.request/wx.connectSocket/wx.uploadFile/wx.downloadFile 的 url 参数允许为 ${IP}:${PORT}/${PATH} 的格式,当且仅当 IP 与手机 IP 处在同一网段且不与本机 IP 相同(一般来说,就是同一局域网,如连接在同一个 wifi 下)时,请求/连接才会成功。

              在这种情况下,不会进行安全域的校验,不要求必须使用 https/wss,也可以使用 http/ws。

              wx.request({  url: 'http://10.9.176.40:828'  // 省略其他参数})wx.connectSocket({  url: 'ws://10.9.176.42:828'  // 省略其他参数})

              基础库 2.7.0 开始,提供了 wx.createUDPSocket 接口用于进行 UDP 通信。通信规则同上,仅允许同一局域网下的非本机 IP。

              mDNS

              目前小程序只支持通过 mDNS 协议获取局域网内其他设备的 IP。iOS 上 mDNS API 的实现基于 Bonjour,Android 上则是基于 Android 系统接口。

              serviceType

              发起 mDNS 服务搜索 wx.startLocalServiceDiscovery 的接口有 serviceType 参数,指定要搜索的服务类型。

              serviceType 的格式和规范,iOS Bonjour Overview 在 Bonjour Names for Existing Service Types 有提及。

              Bonjour serviceType.png

              Android 文档 对此也有提及。

              Android serviceType.png


              存储

              每个微信小程序都可以有自己的本地缓存,可以通过 wx.setStorage/wx.setStorageSyncwx.getStorage/wx.getStorageSyncwx.clearStorage/wx.clearStorageSyncwx.removeStorage/wx.removeStorageSync 对本地缓存进行读写和清理。

              隔离策略

              同一个微信用户,同一个小程序 storage 上限为 10MB。storage 以用户维度隔离,同一台设备上,A 用户无法读取到 B 用户的数据;不同小程序之间也无法互相读写数据。

              清理策略

              本地缓存的清理时机跟代码包一样,只有在代码包被清理的时候本地缓存才会被清理。


              文件系统

              文件系统是小程序提供的一套以小程序和用户维度隔离的存储以及一套相应的管理接口。通过 wx.getFileSystemManager() 可以获取到全局唯一的文件系统管理器,所有文件系统的管理操作通过 FileSystemManager 来调用。

              var fs = wx.getFileSystemManager()

              文件主要分为两大类:

              • 代码包文件:代码包文件指的是在项目目录中添加的文件。
              • 本地文件:通过调用接口本地产生,或通过网络下载下来,存储到本地的文件。

              其中本地文件又分为三种:

              1. 本地临时文件:临时产生,随时会被回收的文件。不限制存储大小。
              2. 本地缓存文件:小程序通过接口把本地临时文件缓存后产生的文件,不能自定义目录和文件名。跟本地用户文件共计,普通小程序最多可存储 10MB,游戏类目的小程序最多可存储 50MB。
              3. 本地用户文件:小程序通过接口把本地临时文件缓存后产生的文件,允许自定义目录和文件名。跟本地缓存文件共计,普通小程序最多可存储 10MB,游戏类目的小程序最多可存储 50MB。

              代码包文件

              由于代码包文件大小限制,代码包文件适用于放置首次加载时需要的文件,对于内容较大或需要动态替换的文件,不推荐用添加到代码包中,推荐在小游戏启动之后再用下载接口下载到本地。

              访问代码包文件

              代码包文件的访问方式是从项目根目录开始写文件路径,不支持相对路径的写法。如:/a/b/c、a/b/c 都是合法的,./a/b/c ../a/b/c 则不合法。 image.png

              修改代码包文件

              代码包内的文件无法在运行后动态修改或删除,修改代码包文件需要重新发布版本。

              本地文件

              本地文件指的是小程序被用户添加到手机后,会有一块独立的文件存储区域,以用户维度隔离。即同一台手机,每个微信用户不能访问到其他登录用户的文件,同一个用户不同 appId 之间的文件也不能互相访问。 本地文件沙盒.png

              本地文件的文件路径均为以下格式:

              {{协议名}}://文件路径
              其中,协议名在 iOS/Android 客户端为 "wxfile",在开发者工具上为 "http",开发者无需关注这个差异,也不应在代码中去硬编码完整文件路径。

              本地临时文件

              本地临时文件只能通过调用特定接口产生,不能直接写入内容。本地临时文件产生后,仅在当前生命周期内有效,重启之后即不可用。因此,不可把本地临时文件路径存储起来下次使用。如果需要下次在使用,可通过 FileSystemManager.saveFile() 或 FileSystemManager.copyFile() 接口把本地临时文件转换成本地缓存文件或本地用户文件。

              示例
              wx.chooseImage({  success: function (res) {    var tempFilePaths = res.tempFilePaths // tempFilePaths 的每一项是一个本地临时文件路径  }})

              本地缓存文件

              本地缓存文件只能通过调用特定接口产生,不能直接写入内容。本地缓存文件产生后,重启之后仍可用。本地缓存文件只能通过 FileSystemManager.saveFile() 接口将本地临时文件保存获得。

              示例
              fs.saveFile({  tempFilePath: '', // 传入一个本地临时文件路径  success(res) {    console.log(res.savedFilePath) // res.savedFilePath 为一个本地缓存文件路径  }})

              注意:本地缓存文件是最初的设计,1.7.0 版本开始,提供了功能更完整的本地用户文件,可以完全覆盖本地缓存文件的功能,如果不需要兼容低于 1.7.0 版本,可以不使用本地缓存文件。

              本地用户文件

              本地用户文件是从 1.7.0 版本开始新增的概念。我们提供了一个用户文件目录给开发者,开发者对这个目录有完全自由的读写权限。通过 wx.env.USER_DATA_PATH 可以获取到这个目录的路径。

              示例
              // 在本地用户文件目录下创建一个文件 hello.txt,写入内容 "hello, world"const fs = wx.getFileSystemManager()fs.writeFileSync(`${wx.env.USER_DATA_PATH}/hello.txt`, 'hello, world', 'utf8')

              读写权限

              接口、组件
              代码包文件
              本地临时文件
              本地缓存文件
              本地用户文件

              清理策略

              • 本地临时文件只保证在小程序当前生命周期内,一旦小程序被关闭就可能被清理,即下次冷启动不保证可用。
              • 本地缓存文件和本地用户文件的清理时机跟代码包一样,只有在代码包被清理的时会被清理。


              Canvas 画布

              所有在 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)

              第三步:画图

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

              ctx.draw()

              结果:

              坐标系

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

              在上一节,我们用了这个方法 fillRect(0, 0, 150, 75)。

              它的含义为:从左上角(0, 0)开始,画一个150 x 75px 的矩形。

              代码示例

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

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

              当你把手指放到 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 gradientconst grd = ctx.createLinearGradient(0, 0, 200, 0)grd.addColorStop(0, 'red')grd.addColorStop(1, 'white')// Fill with gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()

              使用 createCircularGradient()

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


              分包加载

              微信客户端 6.6.0,基础库 1.7.3 及以上版本开始支持。开发者工具请使用 1.01.1712150 及以上版本,可点此下载

              某些情况下,开发者需要将小程序划分成不同的子包,在构建时打包成不同的分包,用户在使用时按需进行加载。

              在构建小程序分包项目时,构建会输出一个或多个分包。每个使用分包小程序必定含有一个主包。所谓的主包,即放置默认启动页面/TabBar 页面,以及一些所有分包都需用到公共资源/JS 脚本;而分包则是根据开发者的配置进行划分。

              在小程序启动时,默认会下载主包并启动主包内页面,当用户进入分包内某个页面时,客户端会把对应分包下载下来,下载完成后再进行展示。

              目前小程序分包大小有以下限制:

              • 整个小程序所有分包大小不超过 16M
              • 单个分包/主包大小不能超过 2M

              对小程序进行分包,可以优化小程序首次启动的下载时间,以及在多团队共同开发时可以更好的解耦协作。

              具体使用方法请参考:

              1、使用分包

              配置方法

              假设支持分包的小程序目录结构如下:

              ├── app.js├── app.json├── app.wxss├── packageA│   └── pages│       ├── cat│       └── dog├── packageB│   └── pages│       ├── apple│       └── banana├── pages│   ├── index│   └── logs└── utils

              开发者通过在 app.json subpackages 字段声明项目分包结构:

              写成 subPackages 也支持。
              {  "pages":[    "pages/index",    "pages/logs"  ],  "subpackages": [    {      "root": "packageA",      "pages": [        "pages/cat",        "pages/dog"      ]    }, {      "root": "packageB",      "name": "pack2",      "pages": [        "pages/apple",        "pages/banana"      ]    }  ]}

              subpackages 中,每个分包的配置有以下几项:

              字段类型说明
              rootString分包根目录
              nameString分包别名,分包预下载时可以使用
              pagesStringArray分包页面路径,相对与分包根目录
              independentBoolean分包是否是独立分包

              打包原则

              • 声明 subpackages 后,将按 subpackages 配置路径进行打包,subpackages 配置路径外的目录将被打包到 app(主包) 中
              • app(主包)也可以有自己的 pages(即最外层的 pages 字段)
              • subpackage 的根目录不能是另外一个 subpackage 内的子目录
              • tabBar 页面必须在 app(主包)内

              引用原则

              • packageA 无法 require packageB JS 文件,但可以 require app、自己 package 内的 JS 文件
              • packageA 无法 import packageB 的 template,但可以 require app、自己 package 内的 template
              • packageA 无法使用 packageB 的资源,但可以使用 app、自己 package 内的资源

              低版本兼容

              由微信后台编译来处理旧版本客户端的兼容,后台会编译两份代码包,一份是分包后代码,另外一份是整包的兼容代码。 新客户端用分包,老客户端还是用的整包,完整包会把各个 subpackage 里面的路径放到 pages 中。

              示例项目

              下载 小程序示例(分包加载版)源码



              2、独立分包

              微信客户端 6.7.2,基础库 2.3.0 及以上版本开始支持。开发者工具请使用 1.02.1808300 及以上版本,可点此下载

              独立分包是小程序中一种特殊类型的分包,可以独立于主包和其他分包运行。从独立分包中页面进入小程序时,不需要下载主包。当用户进入普通分包或主包内页面时,主包才会被下载。

              开发者可以按需将某些具有一定功能独立性的页面配置到独立分包中。当小程序从普通的分包页面启动时,需要首先下载主包;而独立分包不依赖主包即可运行,可以很大程度上提升分包页面的启动速度。

              一个小程序中可以有多个独立分包。

              小游戏不支持独立分包。

              配置方法

              假设小程序目录结构如下:

              ├── app.js├── app.json├── app.wxss├── moduleA│   └── pages│       ├── rabbit│       └── squirrel├── moduleB│   └── pages│       ├── pear│       └── pineapple├── pages│   ├── index│   └── logs└── utils

              开发者通过在app.json的subpackages字段中对应的分包配置项中定义independent字段声明对应分包为独立分包。

              {  "pages": [    "pages/index",    "pages/logs"  ],  "subpackages": [    {      "root": "moduleA",      "pages": [        "pages/rabbit",        "pages/squirrel"      ]    }, {      "root": "moduleB",      "pages": [        "pages/pear",        "pages/pineapple"      ],      "independent": true    }  ]}

              限制

              独立分包属于分包的一种。普通分包的所有限制都对独立分包有效。独立分包中插件、自定义组件的处理方式同普通分包。

              此外,使用独立分包时要注意:

              • 独立分包中不能依赖主包和其他分包中的内容,包括js文件、template、wxss、自定义组件、插件等。主包中的app.wxss对独立分包无效,应避免在独立分包页面中使用 app.wxss 中的样式;
              • App 只能在主包内定义,独立分包中不能定义 App,会造成无法预期的行为;
              • 独立分包中暂时不支持使用插件。

              注意事项

              (1)关于 getApp()

              与普通分包不同,独立分包运行时,App 并不一定被注册,因此 getApp() 也不一定可以获得 App 对象:

              • 当用户从独立分包页面启动小程序时,主包不存在,App也不存在,此时调用 getApp() 获取到的是 undefined。 当用户进入普通分包或主包内页面时,主包才会被下载,App 才会被注册。
              • 当用户是从普通分包或主包内页面跳转到独立分包页面时,主包已经存在,此时调用 getApp() 可以获取到真正的 App。

              由于这一限制,开发者无法通过 App 对象实现独立分包和小程序其他部分的全局变量共享。

              为了在独立分包中满足这一需求,基础库 2.2.4 版本开始 getApp支持 [allowDefault]参数,在 App 未定义时返回一个默认实现。当主包加载,App 被注册时,默认实现中定义的属性会被覆盖合并到真正的 App 中。

              示例代码:

              • 独立分包中
              const app = getApp({allowDefault: true}) // {}app.data = 456app.global = {}
              • app.js 中
              App({  data: 123,  other: 'hello'})console.log(getApp()) // {global: {}, data: 456, other: 'hello'}

              (2)关于 App 生命周期

              当从独立分包启动小程序时,主包中 App 的 onLaunch 和首次 onShow 会在从独立分包页面首次进入主包或其他普通分包页面时调用。

              由于独立分包中无法定义 App,小程序生命周期的监听可以使用 wx.onAppShow,wx.onAppHide 完成。App 上的其他事件可以使用 wx.onError,wx.onPageNotFound 监听。

              低版本兼容

              在低于6.7.2版本的微信中运行时,独立分包视为普通分包处理,不具备独立运行的特性。

              注意:在兼容模式下,主包中的 app.wxss 可能会对独立分包中的页面产生影响,因此应避免在独立分包页面中使用 app.wxss 中的样式。



              3、分包预下载

              基础库 2.3.0 开始支持,低版本需做兼容处理。 开发者工具请使用 1.02.1808300 及以上版本,可点此下载

              开发者可以通过配置,在进入小程序某个页面时,由框架自动预下载可能需要的分包,提升进入后续分包页面时的启动速度。对于独立分包,也可以预下载主包。

              分包预下载目前只支持通过配置方式使用,暂不支持通过调用API完成。

              vConsole 里有preloadSubpackages开头的日志信息,可以用来验证预下载的情况。

              配置方法

              预下载分包行为在进入某个页面时触发,通过在 app.json 增加 preloadRule 配置来控制。

              {  "pages": ["pages/index"],  "subpackages": [    {      "root": "important",      "pages": ["index"],    },    {      "root": "sub1",      "pages": ["index"],    },    {      "name": "hello",      "root": "path/to",      "pages": ["index"]    },    {      "root": "sub3",      "pages": ["index"]    },    {      "root": "indep",      "pages": ["index"],      "independent": true    }  ],  "preloadRule": {    "pages/index": {      "network": "all",      "packages": ["important"]    },    "sub1/index": {      "packages": ["hello", "sub3"]    },    "sub3/index": {      "packages": ["path/to"]    },    "indep/index": {      "packages": ["__APP__"]    }  }}

              preloadRule 中,key 是页面路径,value 是进入此页面的预下载配置,每个配置有以下几项:

              字段类型必填默认值说明
              packagesStringArray进入页面后预下载分包的 root 或 name__APP__ 表示主包。
              networkStringwifi在指定网络下预下载,可选值为:
              all: 不限网络
              wifi: 仅wifi下预下载

              限制

              同一个分包中的页面享有共同的预下载大小限额 2M,限额会在工具中打包时校验。

              如,页面 A 和 B 都在同一个分包中,A 中预下载总大小 0.5M 的分包,B中最多只能预下载总大小 1.5M 的分包。


              多线程 Worker

              一些异步处理的任务,可以放置于 Worker 中运行,待运行结束后,再把结果返回到小程序主线程。Worker 运行于一个单独的全局上下文与线程中,不能直接调用主线程的方法。

              Worker 与主线程之间的数据传输,双方使用 Worker.postMessage() 来发送数据,Worker.onMessage() 来接收数据,传输的数据并不是直接共享,而是被复制的。

              使用流程

              1. 配置 Worker 信息

              在 app.json 中可配置 Worker 代码放置的目录,目录下的代码将被打包成一个文件:

              配置示例:

              {  "workers": "workers"}

              2. 添加 Worker 代码文件

              根据步骤 1 中的配置,在代码目录下新建以下两个入口文件:

              workers/request/index.jsworkers/request/utils.jsworkers/response/index.js

              添加后,目录结构如下:

              ├── app.js├── app.json├── project.config.json└── workers    ├── request    │   ├── index.js    │   └── utils.js    └── response        └── index.js

              3. 编写 Worker 代码

              在 workers/request/index.js 编写 Worker 响应代码

              const utils = require('./utils')// 在 Worker 线程执行上下文会全局暴露一个 worker 对象,直接调用 worker.onMeesage/postMessage 即可worker.onMessage(function (res) {  console.log(res)})

              4. 在主线程中初始化 Worker

              在主线程的代码 app.js 中初始化 Worker

              const worker = wx.createWorker('workers/request/index.js') // 文件名指定 worker 的入口文件路径,绝对路径

              5. 主线程向 Worker 发送消息

              worker.postMessage({  msg: 'hello worker'})

              worker 对象的其它接口请看 worker接口说明

              注意事项

              1. Worker 最大并发数量限制为 1 个,创建下一个前请用 Worker.terminate() 结束当前 Worker
              2. Worker 内代码只能 require 指定 Worker 路径内的文件,无法引用其它路径
              3. Worker 的入口文件由 wx.createWorker() 时指定,开发者可动态指定 Worker 入口文件
              4. Worker 内不支持 wx 系列的 API
              5. Workers 之间不支持发送消息


              后端 API

              小程序还提供了一系列在后端服务器使用 HTTPS 请求调用的 API,帮助开发者在后台完成各类数据分析、管理和查询等操作。如 getAccessToken,code2Session 等。

              access_token

              access_token 是小程序全局唯一后台接口调用凭据,调用绝大多数后台接口时都需使用。开发者可以通过 getAccessToken 接口获取并进行妥善保存。

              为了 access_token 的安全性,后端 API 不能直接在小程序内通过 wx.request 调用,即 api.weixin.qq.com 不能被配置为服务器域名。开发者应在后端服务器使用getAccessToken获取 access_token,并调用相关 API;

              请求参数说明

              • 对于 GET 请求,请求参数应以 QueryString 的形式写在 URL 中。
              • 对于 POST 请求,部分参数需以 QueryString 的形式写在 URL 中(一般只有 access_token,如有额外参数会在文档里的 URL 中体现),其他参数如无特殊说明均以 JSON 字符串格式写在 POST 请求的 body 中。

              返回参数说明

              注意:当API调用成功时,部分接口不会返回 errcode 和 errmsg,只有调用失败时才会返回。


              消息推送

              接入微信小程序消息推送服务,可以两种方式选择其一:

              1. 开发者服务器接收消息推送
              2. 云函数接收消息推送

              开发者服务器接收消息推送

              开发者需要按照如下步骤完成:

              1. 填写服务器配置
              2. 验证服务器地址的有效性
              3. 据接口文档实现业务逻辑,接收消息和事件

              第一步:填写服务器配置

              登录小程序后台后,在「开发」-「开发设置」-「消息推送」中,管理员扫码启用消息服务,填写服务器地址(URL)、令牌(Token) 和 消息加密密钥(EncodingAESKey)等信息。

              • URL: 开发者用来接收微信消息和事件的接口 URL。开发者所填写的URL 必须以 http:// 或 https:// 开头,分别支持 80 端口和 443 端口。
              • Token: 可由开发者可以任意填写,用作生成签名(该 Token 会和接口 URL 中包含的 Token 进行比对,从而验证安全性)。
              • EncodingAESKey: 由开发者手动填写或随机生成,将用作消息体加解密密钥。

              同时,开发者可选择消息加解密方式:明文模式(默认)、兼容模式和安全模式。可以选择消息数据格式:XML 格式(默认)或 JSON 格式。

              填写服务器配置

              模式的选择与服务器配置在提交后都会立即生效,请开发者谨慎填写及选择。切换加密方式和数据格式需要提前配置好相关代码,详情请参考 消息加解密说明。

              第二步:验证消息的确来自微信服务器

              开发者提交信息后,微信服务器将发送GET请求到填写的服务器地址URL上,GET请求携带参数如下表所示:

              参数描述
              signature微信加密签名,signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。
              timestamp时间戳
              nonce随机数
              echostr随机字符串

              开发者通过检验 signature 对请求进行校验(下面有校验方式)。若确认此次 GET 请求来自微信服务器,请原样返回 echostr 参数内容,则接入生效,成为开发者成功,否则接入失败。加密/校验流程如下:

              1. 将token、timestamp、nonce三个参数进行字典序排序
              2. 将三个参数字符串拼接成一个字符串进行sha1加密
              3. 开发者获得加密后的字符串可与signature对比,标识该请求来源于微信

              验证URL有效性成功后即接入生效,成为开发者。

              检验signature的PHP示例代码:

              private function checkSignature(){    $signature = $_GET["signature"];    $timestamp = $_GET["timestamp"];    $nonce = $_GET["nonce"];    $token = TOKEN;    $tmpArr = array($token, $timestamp, $nonce);    sort($tmpArr, SORT_STRING);    $tmpStr = implode( $tmpArr );    $tmpStr = sha1( $tmpStr );    if ($tmpStr == $signature ) {        return true;    } else {        return false;    }}

              PHP示例代码下载:下载

              第三步:接收消息和事件

              当某些特定的用户操作引发事件推送时(如用户向小程序客服发送消息、或者进入会话等情况),微信服务器会将消息(或事件)的数据包以 POST 请求发送到开发者配置的 URL,开发者可以依据自身业务逻辑进行响应。

              微信服务器在将用户的消息发给开发者服务器地址后,微信服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次。如果在调试中,发现用户无法收到响应的消息,可以检查是否消息处理超时。关于重试的消息排重,有 msgid 的消息推荐使用 msgid 排重。事件类型消息推荐使用 FromUserName + CreateTime 排重。

              服务器收到请求必须做出下述回复,这样微信服务器才不会对此作任何处理,并且不会发起重试,否则,将出现严重的错误提示。详见下面说明:

              1. 直接回复success(推荐方式)
              2. 直接回复空串(指字节长度为0的空字符串,而不是结构体中content字段的内容为空)
              3. 若接口文档有指定返回内容,应按文档说明返回

              对于客服消息,一旦遇到以下情况,微信会在小程序会话中向用户下发系统提示“该小程序客服暂时无法提供服务,请稍后再试”:

              1. 开发者在5秒内未回复任何内容
              2. 开发者回复了异常数据

              如果开发者希望增强安全性,可以在开发者中心处开启消息加密,这样,用户发给小程序的消息以及小程序被动回复用户消息都会继续加密,详见消息加解密说明。

              云函数接收消息推送

              需开发者工具版本至少 1.02.1906252

              开通了云开发的小程序可以使用云函数接收消息推送,目前仅支持客服消息推送。

              接入步骤如下:

              1. 开发者工具中填写配置并上传
              2. 云函数中处理消息

              第一步:开发者工具云开发控制台中增加配置

              打开云开发控制台,到设置 tab 中选择全局设置 - 添加消息推送配置。消息类型对应收包的 MsgType,事件类型对应收包的 Event,同一个 <消息类型, 事件类型> 二元组只能推到一个环境的一个云函数。例如客服消息文本消息对应的就是消息类型为 text,事件类型为空。具体值请查看各个消息的消息格式。

              第二步:云函数中处理消息

              云函数被触发时,其 event 参数即是接口所定义的 JSON 结构的对象(统一 JSON 格式,不支持 XML 格式)。

              以客服消息为例,接收到客服消息推送时,event 结构如下:

              {  "FromUserName": "ohl4L0Rnhq7vmmbT_DaNQa4ePaz0",  "ToUserName": "wx3d289323f5900f8e",  "Content": "测试",  "CreateTime": 1555684067,  "MsgId": "49d72d67b16d115e7935ac386f2f0fa41535298877_1555684067",  "MsgType": "text"}

              此时可调用客服消息发送接口回复消息,一个简单的接收到消息后统一回复 “收到” 的示例如下:

              // 云函数入口文件const cloud = require('wx-server-sdk')cloud.init()// 云函数入口函数exports.main = async (event, context) => {  const wxContext = cloud.getWXContext()    await cloud.openapi.customerServiceMessage.send({    touser: wxContext.OPENID,    msgtype: 'text',    text: {      content: '收到',    },  })  return 'success'}


              自定义 tabBar

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

              自定义 tabBar 可以让开发者更加灵活地设置 tabBar 样式,以满足更多个性化的场景。

              在自定义 tabBar 模式下

              • 为了保证低版本兼容以及区分哪些页面是 tab 页,tabBar 的相关配置项需完整声明,但这些字段不会作用于自定义 tabBar 的渲染。
              • 此时需要开发者提供一个自定义组件来渲染 tabBar,所有 tabBar 的样式都由该自定义组件渲染。推荐用 fixed 在底部的 cover-view + cover-image 组件渲染样式,以保证 tabBar 层级相对较高。
              • 与 tabBar 样式相关的接口,如 wx.setTabBarItem 等将失效。
              • 每个 tab 页下的自定义 tabBar 组件实例是不同的,可通过自定义组件下的 getTabBar 接口,获取当前页面的自定义 tabBar 组件实例。

              注意:如需实现 tab 选中态,要在当前页面下,通过 getTabBar 接口获取组件实例,并调用 setData 更新选中态。可参考底部的代码示例。

              使用流程

              1. 配置信息

              • 在 app.json 中的 tabBar 项指定 custom 字段,同时其余 tabBar 相关配置也补充完整。
              • 所有 tab 页的 json 里需声明 usingComponents 项,也可以在 app.json 全局开启。

              示例:

              {  "tabBar": {    "custom": true,    "color": "#000000",    "selectedColor": "#000000",    "backgroundColor": "#000000",    "list": [{      "pagePath": "page/component/index",      "text": "组件"    }, {      "pagePath": "page/API/index",      "text": "接口"    }]  },  "usingComponents": {}}

              2. 添加 tabBar 代码文件

              在代码根目录下添加入口文件:

              custom-tab-bar/index.jscustom-tab-bar/index.jsoncustom-tab-bar/index.wxmlcustom-tab-bar/index.wxss

              3. 编写 tabBar 代码

              用自定义组件的方式编写即可,该自定义组件完全接管 tabBar 的渲染。另外,自定义组件新增 getTabBar 接口,可获取当前页面下的自定义 tabBar 组件实例。


              周期性更新

              基础库 2.8.0 开始支持,低版本需做兼容处理
              生效条件:用户七天内使用过的小程序

              周期性更新能够在用户未打开小程序的情况下,也能从服务器提前拉取数据,当用户打开小程序时可以更快地渲染页面,减少用户等待时间,增强在弱网条件下的可用性。

              使用流程

              1. 配置数据下载地址

              登录小程序 MP 管理后台,进入设置 -> 开发设置 -> 数据周期性更新,点击开启,填写数据下载地址。

              2. 设置 TOKEN

              第一次启动小程序时,调用 wx.setBackgroundFetchToken() 设置一个 TOKEN 字符串,可以跟用户态相关,会在后续微信客户端向开发者服务器请求时带上,便于给后者校验请求合法性。

              示例:

              App({  onLaunch() {    wx.setBackgroundFetchToken({      token: 'xxx'    })  }})

              3. 微信客户端定期拉取数据

              微信客户端会在一定的网络条件下,每隔 12 小时(以上一次成功更新的时间为准)向配置的数据下载地址发起一个 HTTP GET 请求,其中包含的 query 参数如下,数据获取到后会将整个 HTTP body 缓存到本地。

              参数类型说明
              appidString小程序标识
              tokenString前面设置的 TOKEN
              timestampNumber时间戳,微信客户端发起请求的时间
              query 参数会使用 urlencode 处理
              开发者服务器接口返回的数据类型应为字符串,且大小应不超过 256KB,否则将无法缓存数据

              4. 读取数据

              用户启动小程序时,调用 wx.getBackgroundFetchData() 获取已缓存到本地的数据。

              示例:

              App({  onLaunch() {    wx.getBackgroundFetchData({      fetchType: 'periodic',      success(res) {        console.log(res.fetchedData) // 缓存数据        console.log(res.timeStamp) // 客户端拿到缓存数据的时间戳      }    })  }})

              调试方法

              由于微信客户端每隔 12 个小时才会发起一次请求,调试周期性更新功能会显得不太方便。 因此为了方便调试周期性数据,工具提供了下面的调试能力给到开发者。


              数据预拉取

              预拉取能够在小程序冷启动的时候通过微信后台提前向第三方服务器拉取业务数据,当代码包加载完时可以更快地渲染页面,减少用户等待时间,从而提升小程序的打开速度 。

              使用流程

              1. 配置数据下载地址

              登录小程序 MP 管理后台,进入设置 -> 开发设置 -> 数据预加载,点击开启,填写数据下载地址,只支持 HTTPS 。

              2. 设置 TOKEN

              第一次启动小程序时,调用 wx.setBackgroundFetchToken() 设置一个 TOKEN 字符串,可以跟用户态相关,会在后续微信客户端向开发者服务器请求时带上,便于给后者校验请求合法性。

              示例:

              App({  onLaunch() {    wx.setBackgroundFetchToken({      token: 'xxx'    })  }})

              3. 微信客户端提前拉取数据

              当用户打开小程序时,微信服务器将向开发者服务器(上面配置的数据下载地址)发起一个 HTTP GET 请求,其中包含的 query 参数如下,数据获取到后会将整个 HTTP body 缓存到本地。

              参数类型必填说明
              appidString小程序标识。
              tokenString前面设置的 TOKEN。
              codeString用户登录凭证,未设置TOKEN时由微信侧预生成,可在开发者后台调用 auth.code2Session,换取 openid 等信息。
              timestampNumber时间戳,微信客户端发起请求的时间
              pathString打开小程序的路径。
              queryString打开小程序的query。
              sceneNumber打开小程序的场景值。
              query 参数会使用 urlencode 处理
              token和code只会存在一个,用于标识用户身份。
              开发者服务器接口返回的数据类型应为字符串,且大小应不超过 256KB,否则将无法缓存数据

              4. 读取数据

              用户启动小程序时,调用 wx.getBackgroundFetchData() 获取已缓存到本地的数据。

              示例:

              App({  onLaunch() {    wx.getBackgroundFetchData({      fetchType: 'pre',      success(res) {        console.log(res.fetchedData) // 缓存数据        console.log(res.timeStamp) // 客户端拿到缓存数据的时间戳        console.log(res.path) // 页面路径        console.log(res.query) // query 参数        console.log(res.scene) // 场景值      }    })  }})

              调试方法

              为了方便调试数据预拉取,工具提供了下面的调试能力给到开发者。


              DarkMode 适配指南

              微信从iOS客户端 7.0.12、Android客户端 7.0.13 开始正式支持 DarkMode,小程序也从基础库 v2.11.0、开发者工具 1.03.2004271 开始,为开发者提供小程序内的 DarkMode 适配能力。

              开启 DarkMode

              在app.json中配置darkmode为true,即表示当前小程序已适配 DarkMode,所有基础组件均会根据系统主题展示不同的默认样式,navigation bar 和 tab bar 也会根据下面的配置自动切换。

              相关配置

              当app.json中配置darkmode为true时,小程序部分配置项可通过变量的形式配置,在变量配置文件中定义不同主题下的颜色或图标,方法如下:

              1. 在app.json中配置themeLocation,指定变量配置文件theme.json路径,例如:在根目录下新增theme.json,需要配置"themeLocation":"theme.json"
              2. 在theme.json中定义相关变量;
              3. 在app.json中以@开头引用变量。

              支持通过变量配置的属性:

              • 全局配置的 window 属性与页面配置下的属性navigationBarBackgroundColornavigationBarTextStylebackgroundColorbackgroundTextStylebackgroundColorTopbackgroundColorBottom
              • 全局配置 window.tabBar 的属性colorselectedColorbackgroundColorborderStylelisticonPathselectedIconPath

              变量配置文件 theme.json

              theme.json用于颜色主题相关的变量定义,需要先在themeLocation中配置theme.json的路径,否则无法读取变量配置。

              配置文件须包含以下属性:

              属性类型必填描述
              lightobject浅色模式下的变量定义
              darkobject深色模式下的变量定义

              light和dark下均可以key: value的方式定义变量名和值,例如:

              {  "light": {    "navBgColor": "#f6f6f6",    "navTxtStyle": "black"  },  "dark": {    "navBgColor": "#191919",    "navTxtStyle": "white"  }}

              完成定义后,可在全局配置或页面配置的相关属性中以@开头引用,例如:

              // 全局配置{  "window": {    "navigationBarBackgroundColor": "@navBgColor",    "navigationBarTextStyle": "@navTxtStyle"  }}// 页面配置{  "navigationBarBackgroundColor": "@navBgColor",  "navigationBarTextStyle": "@navTxtStyle"}

              配置完成后,小程序框架会自动根据系统主题,为小程序展示对应主题下的颜色。

              配置示例

              app.json(示例省略了主题相关以外的配置项)

              {    "window": {        "navigationBarBackgroundColor": "@navBgColor",        "navigationBarTextStyle": "@navTxtStyle",        "backgroundColor": "@bgColor",        "backgroundTextStyle": "@bgTxtStyle",        "backgroundColorTop": "@bgColorTop",        "backgroundColorBottom": "@bgColorBottom"    },    "tabBar": {        "color": "@tabFontColor",        "selectedColor": "@tabSelectedColor",        "backgroundColor": "@tabBgColor",        "borderStyle": "@tabBorderStyle",        "list": [{            "iconPath": "@iconPath1",            "selectedIconPath": "@selectedIconPath1"        }, {            "iconPath": "@iconPath2",            "selectedIconPath": "@selectedIconPath2"        }]    }}

              theme.json

              {    "light": {        "navBgColor": "#f6f6f6",        "navTxtStyle": "black",        "bgColor": "#ffffff",        "bgTxtStyle": "light",        "bgColorTop": "#eeeeee",        "bgColorBottom": "#efefef",        "tabFontColor": "#000000",        "tabSelectedColor": "#3cc51f",        "tabBgColor": "#ffffff",        "tabBorderStyle": "black",        "iconPath1": "image/icon1_light.png",        "selectedIconPath1": "image/selected_icon1_light.png",        "iconPath2": "image/icon2_light.png",        "selectedIconPath2": "image/selected_icon2_light.png",    },    "dark": {        "navBgColor": "#191919",        "navTxtStyle": "white",        "bgColor": "#1f1f1f",        "bgTxtStyle": "dark",        "bgColorTop": "#191919",        "bgColorBottom": "#1f1f1f",        "tabFontColor": "#ffffff",        "tabSelectedColor": "#51a937",        "tabBgColor": "#191919",        "tabBorderStyle": "white",        "iconPath1": "image/icon1_dark.png",        "selectedIconPath1": "image/selected_icon1_dark.png",        "iconPath2": "image/icon2_dark.png",        "selectedIconPath2": "image/selected_icon2_dark.png",    }}

              获取当前系统主题

              如果app.json中声明了"darkmode": true,wx.getSystemInfo或wx.getSystemInfoSync的返回结果中会包含theme属性,值为light或dark。

              如果app.json未声明"darkmode": true,则无法获取到theme属性(即theme为undefined)。

              监听主题切换事件

              支持2种方式:

              1. 在App()中传入onThemeChange回调方法,主题切换时会触发此回调
              2. 通过wx.onThemeChange监听主题变化,wx.offThemeChange取消监听

              WXSS 适配

              WXSS中,支持通过媒体查询 prefers-color-scheme 适配不同主题,与 Web 中适配方式一致,例如:

              /* 一般情况下的样式 begin */.some-background {    background: white;}.some-text {    color: black;}/* 一般情况下的样式 end */@media (prefers-color-scheme: dark) {    /* DarkMode 下的样式 start */    .some-background {        background: #1b1b1b;    }    .some-text {        color: #ffffff;    }    /* DarkMode 下的样式 end */}

              开发者工具调试

              微信开发者工具 1.03.2004271 版本开始已支持 DarkMode 调试,在模拟器顶部可以切换 深色/浅色 模式进行,如图:

              darkmode_devtool

              Bug & Tip

              1. tip: 需要注意的是,WXSS 中的媒体查询不受app.json中的darkmode开关配置影响,只要微信客户端(iOS 7.0.12、Android 7.0.13)支持 DarkMode,无论是否配置"darkmode": true,在系统切换到 DarkMode 时,媒体查询都将生效。
              2. tip: 主题切换事件需要在配置"darkmode": true时,才会触发。
              3. bug: iOS 7.0.12 在 light 模式中配置 tabBar 的borderStyle为white时可能会出现黑色背景的 bug,后续版本将会修复。


              大屏适配指南

              目前市面上的用户设备大致可分为小屏的手机端、中屏的平板、大屏的 PC 端三类,而在这三类设备中又会有细小的尺寸差别,也称作屏幕碎片化。

              随着小程序能够在越来越多的设备终端上运行,开发者也应该针对不同的屏幕尺寸进行相应的适配。

              按照一般的适配原则,结合小程序特点,通常在以下三种情况中需要进行适配:

              1. 同一类设备下,尺寸有细微差别

              使用小程序提供的 rpx 单位,在尺寸差别不大的情况下对页面布局进行等比缩放。

              2. 在允许屏幕旋转的情况下,可分为横屏与竖屏

              手机端设置 "pageOrientation": "auto" 或 iPad 上设置 "resizable": true 时会允许屏幕旋转,此时使用 Page 的 onResize 事件或者 wx.onWindowResize 方法可对该操作进行监听,进而判断是使用横屏还是竖屏布局。

              3. 不同类设备或者能够自由拖拽窗口的 PC 小程序

              小程序目前是基于 Webview 实现,利用CSS 媒体查询可实时监听屏幕尺寸大小,在不同的屏幕下展现不同的 UI 布局,结合Flex 弹性布局、Grid 网格布局便能实现更加响应式的适配方案。

              matchMedia - 抽象式媒体查询

              小程序基础库基于 window.matchMedia API 新增了一组过程式与定义式接口 match-media 。开发者可以通过 <match-media></match-media> 和 wx.createMediaQueryObserver 来显式地使用媒体查询能力,对于多端适配来说,它有以下优势:

              1. 开发者能够更方便、显式地使用 Media Query 能力,而不是耦合在 CSS 文件中,难以复用。
              2. 能够在 WXML 中结合数据绑定动态地使用,不仅能做到组件的显示或隐藏,在过程式 API 中可塑性更高,例如能够根据尺寸变化动态地添加 class 类名,改变样式。
              3. 能够嵌套式地使用 Media Query 组件,即能够满足局部组件布局样式的改变。
              4. 组件化之后,封装性更强,能够隔离样式、模版以及绑定在模版上的交互事件,还能够提供更高的可复用性。
              5. 浏览器内置 API ,能够在所有基于 Webview 的小程序上使用,兼容性良好。 match-media 具体使用方法可参考相关 API 文档

              4. 自适应布局

              为了让开发者更好的自适应大屏,小程序提供了 row/col 组件 供开发者使用。

              自适应的主要特性是:

              • 整行最多只有 24 份,对于的排列会自动向下换行
              • 每个尺寸设置并不会影响到其它尺寸的布局

              设计指引与代码示例

              关于如何在设计、用户体验上实现更好的多端适配小程序。

              同时我们也提供了多端适配示例小程序 ,基于 row/col 组件 简单实现了常见的适配场景,例如:

              1. 屏幕越大,布局不变,模块左右伸缩

              1. 屏幕越大,内容越多,模块内容换行排列

              1. 屏幕越大,布局改变,模块内容可折叠 / 展现

              体验路径:“扩展能力” -> “多端适配(需在PC端体验)”


              蓝牙

              iOS 微信客户端 6.5.6 版本开始支持,Android 6.5.7 版本开始支持

              蓝牙适配器模块生效周期为调用 wx.openBluetoothAdapter 至调用 wx.closeBluetoothAdapter 或小程序被销毁为止。

              在小程序蓝牙适配器模块生效期间,开发者才能够正常调用蓝牙相关的小程序 API,并收到蓝牙模块相关的事件回调。

              注意

              • 由于系统限制,Android 上获取到的 deviceId 为设备 MAC 地址,iOS 上则为设备 uuid。因此 deviceId 不能硬编码到代码中。
              • 目前不支持在开发者工具上进行蓝牙功能的调试,需要使用真机才能正常调用小程序蓝牙接口。

              低功耗蓝牙(BLE)注意事项

              • iOS 上对特征值的 read、write、notify操作,由于系统需要获取特征值实例,传入的 serviceId 与 characteristicId 必须由 wx.getBLEDeviceServices 与 wx.getBLEDeviceCharacteristics 中获取到后才能使用。建议双平台统一在建立连接后先执行 wx.getBLEDeviceServices 与 wx.getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互。


              NFC

              支持 HCE(基于主机的卡模拟)模式,即将安卓手机模拟成实体智能卡。 支持 NFC 读写,即手机作为读卡器使用。

              • 适用机型:支持 NFC 功能,且系统版本为 Android 5.0 及以上的手机
              • 适用卡范围:符合ISO 14443-4 标准的 CPU 卡
              • 支持 Reader/Writer(读取器/写入器)模式,即支持 NFC 设备读取和/或写入被动 NFC 标签和贴纸。
              • 适用机型:支持 NFC 功能,且系统版本为 Android 5.0 及以上的手机
              • 适用范围:支持NFC-A (ISO 14443-3A)/NFC-B (ISO 14443-3B)/NFC-F (JIS 6319-4)/NFC-V (ISO 15693)/ISO-DEP (ISO 14443-4)标准的读写(部分Android手机)支持MIFARE Classic/MIFARE Ultralight标签的读写支持对NDEF格式的NFC标签上的NDEF数据的读写

              基本流程

              以往NFC-A卡片写入apdu指令为例

              • 调用wx.getNFCAdapter()获取NFC适配器实例
              • 调用NFCAdapter.onDiscovered(function callback)注册贴卡监听回调
              • 调用NFCAdapter.startDiscovery(Object object)开始监听贴卡
              • 贴卡,onDiscovered回调根据onDiscovered回调res对象的techs字段匹配到卡片支持NFC-A标准通过NFCAdapter.getNfcA()获取NfcA实例
              • 使用NfcA实例进行读写调用NfcA.connect()和NFC卡片建立连接调用NfcA.transceive(Object object)往NFC卡片写入apdu指令并接收卡片返回数据读写完毕,调用NfcA.close()断开连接
              • 调用NFCAdapter.stopDiscovery(Object object)结束监听贴卡


              Wi-Fi

              在小程序中支持搜索周边的 Wi-Fi,同时可以针对指定 Wi-Fi,传入密码发起连接。

              该系列接口为系统原生能力,如需查看「微信连Wi-Fi」能力及配置跳转小程序,请参考文档。

              连接指定 Wi-Fi 接口调用时序:

              • Android:startWifi —> connectWifi —> onWifiConnected
              • iOS(仅iOS 11及以上版本支持):startWifi —> connectWifi —> onWifiConnected

              连周边 Wi-Fi 接口调用时序:

              • Android:startWifi —> getWifiList —> onGetWifiList —> connectWifi —> onWifiConnected
              • iOS(iOS 11.0及11.1版本因系统原因暂不支持):startWifi —> getWifiList —> onGetWifiList —> setWifiList —> onWifiConnected

              注意:

              • Wi-Fi 相关接口暂不可用 wx.canIUse 接口判断。
              • Android 6.0 以上版本,在没有打开定位开关的时候会导致设备不能正常获取周边的 Wi-Fi 信息。


              小程序登录

              小程序可以通过微信官方提供的登录能力方便地获取微信提供的用户身份标识,快速建立小程序内的用户体系。

              登录流程时序

              说明:

              1. 调用 wx.login() 获取 临时登录凭证code ,并回传到开发者服务器。
              2. 调用 auth.code2Session 接口,换取 用户唯一标识 OpenID 和 会话密钥 session_key。

              之后开发者服务器可以根据用户标识来生成自定义登录态,用于后续业务逻辑中前后端交互时识别用户身份。

              注意:

              1. 会话密钥 session_key 是对用户数据进行 加密签名 的密钥。为了应用自身的数据安全,开发者服务器不应该把会话密钥下发到小程序,也不应该对外提供这个密钥。
              2. 临时登录凭证 code 只能使用一次


              UnionID 机制说明

              如果开发者拥有多个移动应用、网站应用、和公众帐号(包括小程序),可通过 UnionID 来区分用户的唯一性,因为只要是同一个微信开放平台帐号下的移动应用、网站应用和公众帐号(包括小程序),用户的 UnionID 是唯一的。换句话说,同一用户,对同一个微信开放平台下的不同应用,UnionID是相同的。

              UnionID获取途径

              绑定了开发者帐号的小程序,可以通过以下途径获取 UnionID。

              1. 调用接口 wx.getUserInfo,从解密数据中获取 UnionID。注意本接口需要用户授权,请开发者妥善处理用户拒绝授权后的情况。
              2. 如果开发者帐号下存在同主体的公众号,并且该用户已经关注了该公众号。开发者可以直接通过 wx.login + code2Session 获取到该用户 UnionID,无须用户再次授权。
              3. 如果开发者帐号下存在同主体的公众号或移动应用,并且该用户已经授权登录过该公众号或移动应用。开发者也可以直接通过 wx.login + code2Session 获取到该用户 UnionID ,无须用户再次授权。
              4. 用户在小程序(暂不支持小游戏)中支付完成后,开发者可以直接通过getPaidUnionId接口获取该用户的 UnionID,无需用户授权。注意:本接口仅在用户支付完成后的5分钟内有效,请开发者妥善处理。
              5. 小程序端调用云函数时,如果开发者帐号下存在同主体的公众号,并且该用户已经关注了该公众号,可在云函数中通过 cloud.getWXContext 获取 UnionID。
              6. 小程序端调用云函数时,如果开发者帐号下存在同主体的公众号或移动应用,并且该用户已经授权登录过该公众号或移动应用,也可在云函数中通过 cloud.getWXContext 获取 UnionID。

              微信开放平台绑定小程序流程

              登录微信开放平台 — 管理中心 — 小程序 — 绑定小程序

              img


              授权

              部分接口需要经过用户授权同意才能调用。我们把这些接口按使用范围分成多个 scope ,用户选择对 scope 来进行授权,当授权给一个 scope 之后,其对应的所有接口都可以直接使用。

              此类接口调用时:

              • 如果用户未接受或拒绝过此权限,会弹窗询问用户,用户点击同意后方可调用接口;
              • 如果用户已授权,可以直接调用接口;
              • 如果用户已拒绝授权,则不会出现弹窗,而是直接进入接口 fail 回调。请开发者兼容用户拒绝授权的场景。

              获取用户授权设置

              开发者可以使用 wx.getSetting 获取用户当前的授权状态。

              打开设置界面

              用户可以在小程序设置界面(「右上角」 - 「关于」 - 「右上角」 - 「设置」)中控制对该小程序的授权状态。

              开发者可以调用 wx.openSetting 打开设置界面,引导用户开启授权。

              提前发起授权请求

              开发者可以使用 wx.authorize 在调用需授权 API 之前,提前向用户发起授权请求。

              scope 列表

              scope对应接口描述
              scope.userInfowx.getUserInfo用户信息
              scope.userLocationwx.getLocation, wx.chooseLocation地理位置
              scope.userLocationBackgroundwx.startLocationUpdateBackground后台定位
              scope.addresswx.chooseAddress通讯地址
              scope.invoiceTitlewx.chooseInvoiceTitle发票抬头
              scope.invoicewx.chooseInvoice获取发票
              scope.werunwx.getWeRunData微信运动步数
              scope.recordwx.startRecord录音功能
              scope.writePhotosAlbumwx.saveImageToPhotosAlbum, wx.saveVideoToPhotosAlbum保存到相册
              scope.cameracamera 组件摄像头

              授权有效期

              一旦用户明确同意或拒绝过授权,其授权关系会记录在后台,直到用户主动删除小程序。

              最佳实践

              在真正需要使用授权接口时,才向用户发起授权申请,并在授权申请中说明清楚要使用该功能的理由。

              注意事项

              1. wx.authorize({scope: "scope.userInfo"}),不会弹出授权窗口,请使用 <button open-type="getUserInfo"/>
              2. 需要授权 scope.userLocation、scope.userLocationBackground 时必须配置地理位置用途说明。

              后台定位

              与其它类型授权不同的是,scope.userLocationBackground 不会弹窗提醒用户。需要用户在设置页中,主动将“位置信息”选项设置为“使用小程序期间和离开小程序后”。开发者可以通过调用wx.openSetting,打开设置页。

              background-location


              服务端获取开放数据

              小程序可以通过各种前端接口获取微信提供的开放数据。考虑到开发者服务端也需要获取这些开放数据,微信提供了两种获取方式:

              • 方式一:开发者后台校验与解密开放数据
              • 方式二:云调用直接获取开放数据(云开发

              方式一:开发者后台校验与解密开放数据

              微信会对这些开放数据做签名和加密处理。开发者后台拿到开放数据后可以对数据进行校验签名和解密,来保证数据不被篡改。

              签名校验以及数据加解密涉及用户的会话密钥 session_key。 开发者应该事先通过 wx.login 登录流程获取会话密钥 session_key 并保存在服务器。为了数据不被篡改,开发者不应该把 session_key 传到小程序客户端等服务器外的环境。

              数据签名校验

              为了确保开放接口返回用户数据的安全性,微信会对明文数据进行签名。开发者可以根据业务需要对数据包进行签名校验,确保数据的完整性。

              1. 通过调用接口(如 wx.getUserInfo)获取数据时,接口会同时返回 rawData、signature,其中 signature = sha1( rawData + session_key )
              2. 开发者将 signature、rawData 发送到开发者服务器进行校验。服务器利用用户对应的 session_key 使用相同的算法计算出签名 signature2 ,比对 signature 与 signature2 即可校验数据的完整性。

              如 wx.getUserInfo的数据校验:

              接口返回的rawData:

              {  "nickName": "Band",  "gender": 1,  "language": "zh_CN",  "city": "Guangzhou",  "province": "Guangdong",  "country": "CN",  "avatarUrl": "http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"}

              用户的 session-key:

              HyVFkGl5F5OQWJZZaNzBBg==

              用于签名的字符串为:

              {"nickName":"Band","gender":1,"language":"zh_CN","city":"Guangzhou","province":"Guangdong","country":"CN","avatarUrl":"http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"}HyVFkGl5F5OQWJZZaNzBBg==

              使用sha1得到的结果为

              75e81ceda165f4ffa64f4068af58c64b8f54b88c

              加密数据解密算法

              接口如果涉及敏感数据(如wx.getUserInfo当中的 openId 和 unionId),接口的明文内容将不包含这些敏感数据。开发者如需要获取敏感数据,需要对接口返回的加密数据(encryptedData) 进行对称解密。 解密算法如下:

              1. 对称解密使用的算法为 AES-128-CBC,数据采用PKCS#7填充。
              2. 对称解密的目标密文为 Base64_Decode(encryptedData)。
              3. 对称解密秘钥 aeskey = Base64_Decode(session_key), aeskey 是16字节。
              4. 对称解密算法初始向量 为Base64_Decode(iv),其中iv由数据接口返回。

              微信官方提供了多种编程语言的示例代码((点击下载)。每种语言类型的接口名字均一致。调用方式可以参照示例。

              另外,为了应用能校验数据的有效性,会在敏感数据加上数据水印( watermark )

              watermark参数说明:

              参数类型说明
              appidString敏感数据归属 appId,开发者可校验此参数与自身 appId 是否一致
              timestampInt敏感数据获取的时间戳, 开发者可以用于数据时效性校验

              如接口 wx.getUserInfo 敏感数据当中的 watermark:

              {    "openId": "OPENID",    "nickName": "NICKNAME",    "gender": GENDER,    "city": "CITY",    "province": "PROVINCE",    "country": "COUNTRY",    "avatarUrl": "AVATARURL",    "unionId": "UNIONID",    "watermark":    {        "appid":"APPID",        "timestamp":TIMESTAMP    }}

              注:

              1. 解密后得到的json数据根据需求可能会增加新的字段,旧字段不会改变和删减,开发者需要预留足够的空间

              会话密钥 session_key 有效性

              开发者如果遇到因为 session_key 不正确而校验签名失败或解密失败,请关注下面几个与 session_key 有关的注意事项。

              1. wx.login 调用时,用户的 session_key 可能会被更新而致使旧 session_key 失效(刷新机制存在最短周期,如果同一个用户短时间内多次调用 wx.login,并非每次调用都导致 session_key 刷新)。开发者应该在明确需要重新登录时才调用 wx.login,及时通过 auth.code2Session 接口更新服务器存储的 session_key。
              2. 微信不会把 session_key 的有效期告知开发者。我们会根据用户使用小程序的行为对 session_key 进行续期。用户越频繁使用小程序,session_key 有效期越长。
              3. 开发者在 session_key 失效时,可以通过重新执行登录流程获取有效的 session_key。使用接口 wx.checkSession可以校验 session_key 是否有效,从而避免小程序反复执行登录流程。
              4. 当开发者在实现自定义登录态时,可以考虑以 session_key 有效期作为自身登录态有效期,也可以实现自定义的时效性策略。

              方式二:云调用直接获取开放数据

              接口如果涉及敏感数据(如wx.getWeRunData),接口的明文内容将不包含这些敏感数据,而是在返回的接口中包含对应敏感数据的 cloudID 字段,数据可以通过云函数获取。完整流程如下:

              1. 获取 cloudID

              使用 2.7.0 或以上版本的基础库,如果小程序已开通云开发,在开放数据接口的返回值中可以通过 cloudID 字段获取(与 encryptedData 同级),cloudID 有效期五分钟。

              2. 调用云函数

              调用云函数时,对传入的 data 参数,如果有顶层字段的值为通过 wx.cloud.CloudID 构造的 CloudID,则调用云函数时,这些字段的值会被替换为 cloudID 对应的开放数据,一次调用最多可替换 5 个 CloudID。

              示例:

              在小程序获取到 cloudID 之后发起调用:

              wx.cloud.callFunction({  name: 'myFunction',  data: {    weRunData: wx.cloud.CloudID('xxx'), // 这个 CloudID 值到云函数端会被替换    obj: {      shareInfo: wx.cloud.CloudID('yyy'), // 非顶层字段的 CloudID 不会被替换,会原样字符串展示    }  }})

              在云函数收到的 event 示例:

              // event{  // weRunData 的值已被替换为开放数据  "weRunData": {    "cloudID": "xxx",    "data": {      "stepInfoList": [        {          "step": 5000,          "timestamp": 1554814312,        }      ],      "watermark": {        "appid": "wx1111111111",        "timestamp": 1554815786      }    }  },  "obj": {    // 非顶层字段维持原样    "shareInfo": "yyy",  }}

              如果 cloudID 非法或过期,则在 event 中获取得到的将是一个有包含错误码、错误信息和原始 cloudID 的对象。过期 cloudID 换取结果示例:

              // event{  "weRunData": {    "cloudID": "xxx",    "errCode": -601006,    "errMsg": "cloudID expired."  },  // ...}


              获取手机号

              获取微信用户绑定的手机号,需先调用wx.login接口。

              因为需要用户主动触发才能发起获取手机号接口,所以该功能不由 API 来调用,需用 button 组件的点击来触发。

              注意:目前该接口针对非个人开发者,且完成了认证的小程序开放(不包含海外主体)。需谨慎使用,若用户举报较多或被发现在不必要场景下使用,微信有权永久回收该小程序的该接口权限。

              使用方法

              需要将 button 组件 open-type 的值设置为 getPhoneNumber,当用户点击并同意之后,可以通过 bindgetphonenumber 事件回调获取到微信服务器返回的加密数据, 然后在第三方服务端结合 session_key 以及 app_id 进行解密获取手机号。

              注意

              在回调中调用 wx.login 登录,可能会刷新登录态。此时服务器使用 code 换取的 sessionKey 不是加密时使用的 sessionKey,导致解密失败。建议开发者提前进行 login;或者在回调中先使用 checkSession 进行登录态检查,避免 login 刷新登录态。

              代码示例

              <button open-type="getPhoneNumber" bindgetphonenumber="getPhoneNumber"></button>
              Page({  getPhoneNumber (e) {    console.log(e.detail.errMsg)    console.log(e.detail.iv)    console.log(e.detail.encryptedData)  }})

              返回参数说明

              参数类型说明最低版本
              encryptedDataString包括敏感数据在内的完整用户信息的加密数据,详细见加密数据解密算法
              ivString加密算法的初始向量,详细见加密数据解密算法
              cloudIDstring敏感数据对应的云 ID,开通云开发的小程序才会返回,可通过云调用直接获取开放数据,详细见云调用直接获取开放数据基础库 2.8.0

              获取得到的开放数据为以下 json 结构:

              {    "phoneNumber": "13580006666",    "purePhoneNumber": "13580006666",    "countryCode": "86",    "watermark":    {        "appid":"APPID",        "timestamp": TIMESTAMP    }}
              参数类型说明
              phoneNumberString用户绑定的手机号(国外手机号会有区号)
              purePhoneNumberString没有区号的手机号
              countryCodeString区号


              生物认证

              小程序通过 SOTER 提供以下生物认证方式。

              目前暂时只支持指纹识别认证。设备支持的生物认证方式可使用 wx.checkIsSupportSoterAuthentication 查询

              调用流程

              流程步骤说明

              1. 调用 wx.startSoterAuthentication,获取 resultJSON 和 resultJSONSignature
              2. (可选)签名校验。此处 resultJSONSignature 使用 SHA256withRSA/PSS 作为签名算法进行验签。此公式数学定义如下: bool 验签结果=verify(用于签名的原串,签名串,验证签名的公钥)
              3. 微信提供后台接口用于可信的密钥验签服务,微信将保证该接口返回的验签结果的正确性与可靠性,并且对于 Android root 情况下该接口具有上述特征(将返回是否保证root情况安全性)。

              接口地址:

              POST http://api.weixin.qq.com/cgi-bin/soter/verify_signature?access_token=%access_token

              post 数据内容(JSON 编码):

              {"openid":"$openid", "json_string" : "$resultJSON", "json_signature" : "$resultJSONSignature" }

              请求返回数据内容(JSON 编码):

              // 验证成功返回{"is_ok":true}// 验证失败返回{"is_ok":false}// 接口调用失败{"errcode":"xxx,"errmsg":"xxxxx"}


              分享到朋友圈(Beta)

              从基础库 2.11.3 开始支持
              此功能为beta版,暂仅在Android平台支持

              可将小程序页面分享到朋友圈。适用于内容型页面的分享,不适用于有较多交互的页面分享。

              设置分享状态

              小程序页面默认不可被分享到朋友圈,开发者需主动设置“分享到朋友圈”。页面允许被分享到朋友圈,需满足两个条件:

              1. 首先,页面需设置允许“发送给朋友”。具体参考 Page.onShareAppMessage 接口文档
              2. 满足条件 1 后,页面需设置允许“分享到朋友圈”,同时可自定义标题、分享图等。具体参考 Page.onShareTimeline 接口文档

              满足上述两个条件的页面,可被分享到朋友圈。

              单页模式

              用户在朋友圈打开分享的小程序页面,并不会真正打开小程序,而是进入一个“小程序单页模式”的页面,“单页模式”有以下特点:

              1. “单页模式”下,页面顶部固定有导航栏,标题显示为当前页面 JSON 配置的标题。底部固定有操作栏,点击操作栏的“前往小程序”可打开小程序的当前页面。顶部导航栏与底部操作栏均不支持自定义样式。
              2. “单页模式”默认运行的是小程序页面内容,但由于页面固定有顶部导航栏与底部操作栏,很可能会影响小程序页面的布局。因此,请开发者特别注意适配“单页模式”的页面交互,以实现流畅完整的交互体验。
              3. “单页模式”下,一些组件或接口存在一定限制,详情见下文单页模式下的限制章节

              avatar

              页面适配

              可通过判断场景值等于 1154 的方法来进行页面适配。另外,在单页模式下,可设置顶部导航栏与页面的相交状态,具体参考 navigationBarFit 配置。

              还需留意的是,在单页模式下,wx.getSystemInfo 接口返回的 safeArea 为整个屏幕空间。

              单页模式下的限制

              小程序“单页模式”适用于纯内容展示场景,可实现的交互与接口能力有限,因此存在如下限制:

              1. 页面无登录态,与登录相关的接口,如 wx.login 均不可用;云开发资源需开启未登录访问方可在单页模式下使用,详见未登录模式。
              2. 不允许跳转到其它页面,包括任何跳小程序页面、跳其它小程序、跳微信原生页面
              3. 不允许横屏使用
              4. 若页面包含 tabBar,tabBar 不会渲染,包括自定义 tabBar
              5. 本地存储与小程序普通模式不共用

              对于一些会产生交互的组件或接口,在点击后调用时,会弹 toast 提示“请前往小程序使用完整服务”。为达到良好的用户体验,请注意适配单页模式的接口能力,请勿大量使用被禁用的接口或组件。

              禁用能力列表:

              分类功能点
              组件button open-type 、 camera 、 editor 、 form 、 functional-page-navigator 、 live-pusher 、 navigator 、 navigation-bar 、 official-account 、 open-data 、 web-view
              路由wx.redirectTo 、 wx.reLaunch 、 wx.navigateTo 、 wx.switchTab 、 wx.navigateBack
              界面导航栏 、 Tab Bar
              网络mDNS 、 UDP 通信
              数据缓存周期性更新
              媒体VoIP 、 wx.chooseMedia 、 wx.chooseImage 、 wx.saveImageToPhotosAlbum 、 wx.chooseVideo 、 wx.saveVideoToPhotosAlbum 、 wx.getVideoInfo 、 wx.compressVideo
              位置wx.openLocation 、 wx.chooseLocation 、 wx.startLocationUpdateBackground 、 wx.startLocationUpdate
              转发wx.getShareInfo 、 wx.showShareMenu 、 wx.hideShareMenu 、 wx.updateShareMenu
              文件wx.openDocument
              开放接口登录 、 小程序跳转 、 用户信息 、 支付 、 授权 、 设置 、 收货地址 、 卡券 、 发票 、 生物认证 、 微信运动 、 微信红包
              设备蓝牙 、 iBeacon 、 Wi-Fi 、 NFC 、 联系人 、 剪贴板 、 电话 、 扫码
              广告ad 、 wx.createRewardedVideoAd 、 wx.createInterstitialAd

              运营须知

              分享朋友圈能力是为了满足纯内容场景的分享诉求,滥用于营销、诱导等行为将会被打击。

              1. 小程序提供的服务中,不得存在滥用分享违规行为。如强制用户分享行为;分享立即获得利益的诱导行为;以及通过明示或暗示的样式来达到诱导分享目的的行为等。详见《微信小程序平台运营规范》
              2. 在“单页模式”下,不得诱导或强制用户点击“打开小程序”,应在“单页模式”中尽可能呈现完整的内容

              提示:

              1. 低版本微信客户端打开时,会进入一个升级提示页面
              2. 不支持在小程序页面内直接发起分享
              3. 自定义分享内容时不支持自定义页面路径
              4. 存在 web-view 组件的页面不支持发起分享
              5. 支持打开开发版、体验版,无权限人员进入时页面会提示无权限


              转发

              获取更多转发信息

              通常开发者希望转发出去的小程序被二次打开的时候能够获取到一些信息,例如群的标识。现在通过调用 wx.showShareMenu 并且设置 withShareTicket 为 true ,当用户将小程序转发到任一群聊之后,此转发卡片在群聊中被其他用户打开时,可以在 App.onLaunch 或 App.onShow 获取到一个 shareTicket。通过调用 wx.getShareInfo 接口传入此 shareTicket 可以获取到转发信息。

              页面内发起转发

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

              通过给 button 组件设置属性 open-type="share",可以在用户点击按钮后触发 Page.onShareAppMessage 事件,相关组件:button。

              使用指引

              转发按钮,旨在帮助用户更流畅地与好友分享内容和服务。转发,应是用户自发的行为,且在需要时触手可及。开发者在使用时若遵从以下指引,会得到更佳的用户体验。

              1. 含义清晰:明确、一目了然的图形按钮,将为用户减少理解的时间。在我们的资源下载中心,你可以找到这样的按钮素材并直接使用。或者你可以根据自己业务的设计风格,灵活设计含义清晰的按钮的样式。当然,你也可以直接使用带文案的按钮,“转发给好友”,它也足够明确。
              2. 方便点击:按钮点击热区不宜过小,亦不宜过大。同时,转发按钮与其他按钮一样,热区也不宜过密,以免用户误操作。
              3. 按需出现:并非所有页面都适合放置转发按钮,涉及用户隐私的非公开内容,或可能打断用户完成当前操作体验的场景,该功能并不推荐使用。同时,由于转发过程中,我们将截取用户屏幕图像作为配图,因此,需要注意帮助用户屏蔽个人信息。
              4. 尊重意愿:理所当然,并非所有的用户,都喜欢与朋友分享你的小程序。因此,它不应该成为一个诱导或强制行为,如转发后才能解锁某项功能等。请注意,这类做法不仅不被推荐,还可能违反我们的《运营规范》,我们强烈建议你在使用前阅读这部分内容。

              以上,我们陈列了最重要的几点,如果你有时间,可以完整浏览《设计指南》,相信会有更多的收获。

              提示:

              1. 不自定义转发图片的情况下,默认会取当前页面,从顶部开始,高度为 80% 屏幕宽度的图像作为转发图片。
              2. 转发的调试支持请查看 普通转发的调试支持 和 带 shareTicket 的转发
              3. 只有转发到群聊中打开才可以获取到 shareTickets 返回值,单聊没有 shareTickets
              4. shareTicket 仅在当前小程序生命周期内有效
              5. 由于策略变动,小程序群相关能力进行调整,开发者可先使用 wx.getShareInfo 接口中的群 ID 进行功能开发。
              6. 微信7.0.12开始,支持群主转发小程序时同时把消息设为该群的群待办消息,群待办消息会以气泡形式出现在聊天窗口底部。默认每次转发一个群待办消息,都会生成一个待办消息气泡。通过 wx.updateShareMenu 接口修改toDoActivityId属性可以把多个待办消息聚合为同一个,即转发相同toDoActivityId的群待办消息,只会出现一个待办消息气泡。toDoActivityId需要在转发前通过 updatableMessage.createActivityId 接口创建。

              动态消息

              从基础库 2.4.0 开始,支持转发动态消息。动态消息对比普通消息,有以下特点:

              1. 消息发出去之后,开发者可以通过后台接口修改部分消息内容。
              2. 消息有对应的提醒按钮,用户点击提醒按钮可以订阅提醒,开发者可以通过后台修改消息状态并推送一次提醒消息给订阅了提醒的用户

              消息属性

              动态消息有状态、文字内容、文字颜色。

              状态

              消息有两个状态,分别有其对应的文字内容和颜色。其中状态 0 可以转移到状态 0 和 1,状态 1 无法再转移。

              状态文字内容颜色允许转移的状态
              0"成员正在加入,当前 {member_count}/{room_limit} 人"#FA9D390, 1
              1"已开始"#CCCCCC

              状态参数

              每个状态转移的时候可以携带参数,具体参数说明如下。

              参数类型说明
              member_countstring状态 0 时有效,文字内容模板中 member_count 的值
              room_limitstring状态 0 时有效,文字内容模板中 room_limit 的值
              pathstring状态 1 时有效,点击「进入」启动小程序时使用的路径。对于小游戏,没有页面的概念,可以用于传递查询字符串(query),如 "?foo=bar"
              version_typestring状态 1 时有效,点击「进入」启动小程序时使用的版本。有效参数值为:develop(开发版),trial(体验版),release(正式版)

              使用方法

              一、创建 activity_id

              每条动态消息可以理解为一个活动,活动发起前需要通过 updatableMessage.createActivityId 接口创建 activity_id。后续转发动态消息以及更新动态消息都需要传入这个 activity_id。

              活动的默认有效期是 24 小时。活动结束后,消息内容会变成统一的样式:

              • 文字内容:“已结束”
              • 文字颜色:#00ff00

              二、在转发之前声明消息类型为动态消息

              通过调用 wx.updateShareMenu 接口,传入 isUpdatableMessage: true,以及 templateInfo、activityId 参数。其中 activityId 从步骤一中获得。

              wx.updateShareMenu({  withShareTicket: true,  isUpdatableMessage: true,  activityId: '', // 活动 ID  templateInfo: {    parameterList: [{      name: 'member_count',      value: '1'    }, {      name: 'room_limit',      value: '3'    }]  }})

              三、修改动态消息内容

              动态消息发出去之后,可以通过 updatableMessage.setUpdatableMsg 修改消息内容。

              低版本兼容

              对于不支持动态消息的客户端版本,收到动态消息后会展示成普通消息


              收藏

              安卓 7.0.15 版本起支持,iOS 暂不支持

              小程序菜单增加收藏功能,可收藏某个页面至收藏夹。点开小程序右上角胶囊,点击收藏按钮会触发 Page.onAddToFavorites 事件。


              多人音视频对话

              用于实现小程序内多人音视频对话的功能。

              申请开通

              小程序管理后台,「开发」-「接口设置」中自助开通该组件权限。相关接口 wx.joinVoIPChat 和组件 voip-room。

              调用流程

              开发者仅需提供房间唯一标识,即可加入到指定的房间。传入相同唯一标识的用户,会进到相同的房间。为了保证前端传入的 groupId 可信,wx.joinVoIPChat 接口要求传入签名。详见下文 签名算法。当加入视频房间时,可结合 voip-room 组件显示成员画面。

              前端接口

              签名算法

              生成签名需要传入四个参数:

              参数名说明
              appId小游戏的 appId
              groupId游戏房间的唯一标识,由游戏自己保证唯一
              nonceStr随机字符串,长度应小于 128
              timeStamp生成这个随机字符串的 UNIX 时间戳(精确到秒)

              签名算法为:

              signature = hmac_sha256([appId, groupId, nonceStr, timeStamp].sort().join(''), sessionKey)

              具体来说,这个算法分为几个步骤:

              1. 对 appId groupId nonceStr timeStamp 四个值表示成字符串形式,按照字典序排序;
              2. 将排好序的四个字符串拼接在一起;
              3. 使用 session_key 作为 key,使用 hmac_sha256 算法对 2 中的结果字符串做计算,所得结果即为 signature

              示例:

              appId = 'wx20afc706a711eefc'groupId = '1559129713_672975982'nonceStr = '8AP6DT9ybtniUJfb'timeStamp = '1559129714'session_key = 'gDyVgzwa0mFz9uUP7M6GQQ=='str = [appId, groupId, nonceStr, timeStamp].sort().join('') = '1559129713_67297598215591297148AP6DT9ybtniUJfbwx20afc706a711eefc'signature = hmac_sha256('1559129713_67297598215591297148AP6DT9ybtniUJfbwx20afc706a711eefc', sessionKey) = 'b002b824688dd8593a6079e11d8c5e8734fbcb39a6d5906eb347bfbcad79c617'

              使用云开发完成签名

              在云开发中,无法获取 session_key,但提供了单独的函数 cloud.getVoIPSign 来计算签名。

              const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  const signature = cloud.getVoIPSign({    groupId: 'xxx',    timestamp: 123,    nonce: 'yyy'  })  return signature}

              人数限制

              每个房间最多同时加入 10 个人。

              频率限制

              对于每个小程序,每天最多允许创建 100000 个房间。当所有人退出房间时,房间即被销毁。此时如果传入之前用过的 groupId 重新加入房间,会被计算为新开一个房间。


              打开 App

              此功能需要用户主动触发才能打开 APP,所以不由 API 来调用,需要用 open-type 的值设置为 launchApp 的 button 组件的点击来触发。

              当小程序从 APP 分享消息卡片的场景打开(场景值 1036,APP 分享小程序文档 iOS / Android) 或从 APP 打开的场景打开时(场景值 1069),小程序会获得打开 APP 的能力,此时用户点击按钮可以打开分享该小程序卡片/拉起该小程序的 APP。即小程序不能打开任意 APP,只能 跳回 APP。

              在一个小程序的生命周期内,只有在特定条件下,才具有打开 APP 的能力。

              在基础库 < 2.5.1 的版本,这个能力的规则如下:

              当小程序从 1069 场景打开时,可以打开 APP。

              当小程序从非 1069 的打开时,会在小程序框架内部会管理的一个状态,为 true 则可以打开 APP,为 false 则不可以打开 APP。这个状态的维护遵循以下规则:

              • 当小程序从 App 分享消息卡片(场景值1036)打开时,该状态置为 true。
              • 当小程序从以下场景打开时,保持上一次打开小程序时打开 App 能力的状态:从其他小程序返回小程序(场景值1038)时(基础库 2.2.4 及以上版本支持)小程序从聊天顶部场景(场景值1089)中的「最近使用」内打开时长按小程序右上角菜单唤出最近使用历史(场景值1090)打开时
              • 当小程序从非以上场景打开时,不具有打开 APP 的能力,该状态置为 false。

              在基础库 >= 2.5.1 时,这个能力的规则如下:

              当小程序从任意场景打开时,会在小程序框架内部会管理的一个状态,为 true 则可以打开 APP,为 false 则不可以打开 APP。这个状态的维护遵循以下规则:

              • 当小程序从 App 分享消息卡片(场景值1036)或从 APP 打开的场景打开时(场景值 1069)打开时,该状态置为 true。
              • 当小程序从以下场景打开时,保持上一次打开小程序时打开 App 能力的状态:从其他小程序返回小程序(场景值1038)时(基础库 2.2.4 及以上版本支持)小程序从聊天顶部场景(场景值1089)中的「最近使用」内打开时长按小程序右上角菜单唤出最近使用历史(场景值1090)打开时
              • 当小程序从非以上场景打开时,不具有打开 APP 的能力,该状态置为 false。

              使用方法

              小程序端

              需要将 button 组件 open-type 的值设置为 launchApp。如果需要在打开 APP 时向 APP 传递参数,可以设置 app-parameter 为要传递的参数。通过 binderror 可以监听打开 APP 的错误事件。

              app 端

              APP 需要接入 OpenSDK。 文档请参考 iOS / Android

              Android 第三方 app 需要处理 ShowMessageFromWX.req 的微信回调,iOS 则需要将 appId 添加到第三方 app 工程所属的 plist 文件 URL types 字段。 app-parameter 的获取方法,参数解析请参考 Android SDKSample 中 WXEntryActivity 中的 onResp 方法以及 iOS SDKSample  中 WXApiDelegate 中的 onResp 方法。

              代码示例

              <button open-type="launchApp" app-parameter="wechat" binderror="launchAppError">打开APP</button>
              Page({  launchAppError (e) {    console.log(e.detail.errMsg)  }})

              error 事件参数说明

              说明
              invalid scene调用场景不正确,即此时的小程序不具备打开 APP 的能力。


              小程序订阅消息

              功能介绍

              消息能力是小程序能力中的重要组成,我们为开发者提供了订阅消息能力,以便实现服务的闭环和更优的体验。

              • 订阅消息推送位置:服务通知
              • 订阅消息下发条件:用户自主订阅
              • 订阅消息卡片跳转能力:点击查看详情可跳转至该小程序的页面

              intro

              使用说明

              步骤一:获取模板 ID

              在微信公众平台手动配置获取模板 ID:登录 https://mp.weixin.qq.com 获取模板,如果没有合适的模板,可以申请添加新模板,审核通过后可使用。

              intro

              步骤二:获取下发权限

              详见小程序端消息订阅接口 wx.requestSubscribeMessage

              步骤三:调用接口下发订阅消息

              详见服务端消息发送接口 subscribeMessage.send


              统一服务消息

              为便于开发者对用户进行服务消息触达,简化小程序和公众号模板消息下发流程,小程序提供统一的服务消息下发接口。

              相关接口


              客服消息

              在页面使用客服消息

              需要将 button 组件 open-type 的值设置为 contact,当用户点击后就会进入客服会话,如果用户在会话中点击了小程序消息,则会返回到小程序,开发者可以通过 bindcontact 事件回调获取到用户所点消息的页面路径 path 和对应的参数 query。

              代码示例

              <button open-type="contact" bindcontact="handleContact"></button>
              Page({    handleContact (e) {        console.log(e.detail.path)        console.log(e.detail.query)    }})

              返回参数说明

              参数类型说明
              pathString小程序消息指定的路径
              queryObject小程序消息指定的查询参数

              后台接入消息服务

              用户向小程序客服发送消息、或者进入会话等情况时,开发者填写的服务器配置 URL (如果使用的是云开发,则是配置的云函数)将得到微信服务器推送过来的消息和事件,开发者可以依据自身业务逻辑进行响应。接入和使用方式请参考消息推送


              接收消息和事件

              在页面中使用 <button open-type="contact" /> 可以显示进入客服会话按钮。

              当用户在客服会话发送消息、或由某些特定的用户操作引发事件推送时,微信服务器会将消息或事件的数据包发送到开发者填写的 URL,如果使用的是云开发,则可以推送到指定的云函数(详情请参考消息推送)。开发者收到请求后可以使用 发送客服消息 接口进行异步回复。

              各消息类型的推送JSON、XML数据包结构如下。

              文本消息

              用户在客服会话中发送文本消息时将产生如下数据包:

              XML 格式

              <xml>   <ToUserName><![CDATA[toUser]]></ToUserName>   <FromUserName><![CDATA[fromUser]]></FromUserName>   <CreateTime>1482048670</CreateTime>   <MsgType><![CDATA[text]]></MsgType>   <Content><![CDATA[this is a test]]></Content>   <MsgId>1234567890123456</MsgId></xml>

              JSON 格式

              {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "text",  "Content": "this is a test",  "MsgId": 1234567890123456}

              参数说明

              参数说明
              ToUserName小程序的原始ID
              FromUserName发送者的openid
              CreateTime消息创建时间(整型)
              MsgTypetext
              Content文本消息内容
              MsgId消息id,64位整型

              图片消息

              用户在客服会话中发送图片消息时将产生如下数据包:

              XML 格式

              <xml>      <ToUserName><![CDATA[toUser]]></ToUserName>      <FromUserName><![CDATA[fromUser]]></FromUserName>      <CreateTime>1482048670</CreateTime>      <MsgType><![CDATA[image]]></MsgType>      <PicUrl><![CDATA[this is a url]]></PicUrl>      <MediaId><![CDATA[media_id]]></MediaId>      <MsgId>1234567890123456</MsgId></xml>

              JSON 格式

              {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "image",  "PicUrl": "this is a url",  "MediaId": "media_id",  "MsgId": 1234567890123456}

              参数说明

              参数说明
              ToUserName小程序的原始ID
              FromUserName发送者的openid
              CreateTime消息创建时间(整型)
              MsgTypeimage
              PicUrl图片链接(由系统生成)
              MediaId图片消息媒体id,可以调用[获取临时素材]((getTempMedia)接口拉取数据。
              MsgId消息id,64位整型

              小程序卡片消息

              用户在客服会话中发送小程序卡片消息时将产生如下数据包:

              XML 格式

              <xml>  <ToUserName><![CDATA[toUser]]></ToUserName>  <FromUserName><![CDATA[fromUser]]></FromUserName>  <CreateTime>1482048670</CreateTime>  <MsgType><![CDATA[miniprogrampage]]></MsgType>  <MsgId>1234567890123456</MsgId>  <Title><![CDATA[Title]]></Title>  <AppId><![CDATA[AppId]]></AppId>  <PagePath><![CDATA[PagePath]]></PagePath>  <ThumbUrl><![CDATA[ThumbUrl]]></ThumbUrl>  <ThumbMediaId><![CDATA[ThumbMediaId]]></ThumbMediaId></xml>

              JSON 格式

              {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "miniprogrampage",  "MsgId": 1234567890123456,  "Title":"title",  "AppId":"appid",  "PagePath":"path",  "ThumbUrl":"",  "ThumbMediaId":""}

              参数说明

              参数说明
              ToUserName小程序的原始ID
              FromUserName发送者的openid
              CreateTime消息创建时间(整型)
              MsgTypeminiprogrampage
              MsgId消息id,64位整型
              Title标题
              AppId小程序appid
              PagePath小程序页面路径
              ThumbUrl封面图片的临时cdn链接
              ThumbMediaId封面图片的临时素材id

              进入会话事件

              用户在小程序“客服会话按钮”进入客服会话时将产生如下数据包:

              XML 格式

              <xml>    <ToUserName><![CDATA[toUser]]></ToUserName>    <FromUserName><![CDATA[fromUser]]></FromUserName>    <CreateTime>1482048670</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[user_enter_tempsession]]></Event>    <SessionFrom><![CDATA[sessionFrom]]></SessionFrom></xml>

              JSON 格式

              {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "event",  "Event": "user_enter_tempsession",  "SessionFrom": "sessionFrom"}

              参数说明

              参数说明
              ToUserName小程序的原始ID
              FromUserName发送者的openid
              CreateTime事件创建时间(整型)
              MsgTypeevent
              Event事件类型,user_enter_tempsession
              SessionFrom开发者在客服会话按钮设置的 session-from 属性

              发送客服消息

              当用户和小程序客服产生特定动作的交互时(具体动作列表请见下方说明),微信将会把消息数据推送给开发者,开发者可以在一段时间内(目前为 48 小时)调用客服接口,通过调用 发送客服消息接口 来发送消息给普通用户。此接口主要用于客服等有人工消息处理环节的功能,方便开发者为用户提供更加优质的服务。

              目前允许的动作列表如下,不同动作触发后,允许的客服接口下发消息条数和下发时限不同。

              用户动作允许下发条数限制下发时限
              用户发送消息5 条48 小时

              转发客服消息

              如果小程序设置了消息推送,普通微信用户向小程序客服发消息时,微信服务器会先将消息 POST 到开发者填写的 URL 上,如果希望将消息转发到网页版客服工具,则需要开发者在响应包中返回 MsgType 为 transfer_customer_service 的消息,微信服务器收到响应后会把当次发送的消息转发至客服系统。

              用户被客服接入以后,客服关闭会话以前,处于会话过程中时,用户发送的消息均会被直接转发至客服系统。当会话超过 30 分钟客服没有关闭时,微信服务器会自动停止转发至客服,而将消息恢复发送至开发者填写的 URL 上。

              用户在等待队列中时,用户发送的消息仍然会被推送至开发者填写的 URL 上。

              这里特别要注意,只针对微信用户发来的消息才进行转发,而对于其他事件(比如用户从小程序唤起客服会话)都不应该转发,否则客服在客服系统上就会看到一些无意义的消息了。

              消息转发到网页版客服工具

              开发者只要在响应包中返回 MsgType 为 transfer_customer_service 的消息,微信服务器收到响应后就会把当次发送的消息转发至客服系统。

              如果是使用自有服务器接收的消息推送,则需返回如下格式的 XML 数据:

              <xml>    <ToUserName><![CDATA[touser]]></ToUserName>    <FromUserName><![CDATA[fromuser]]></FromUserName>    <CreateTime>1399197672</CreateTime>    <MsgType><![CDATA[transfer_customer_service]]></MsgType></xml>

              参数说明

              参数是否必须描述
              ToUserName接收方帐号(收到的OpenID)
              FromUserName开发者微信号
              CreateTime消息创建时间 (整型)
              MsgTypetransfer_customer_service

              如果是使用云函数接收的消息推送,则需在云函数被客服消息触发后返回同样格式的 JSON 数据:

              // ...exports.main = async (event, context) => {  // 判断处理客服消息 ...  // 最后返回 JSON  return {    MsgType: 'transfer_customer_service',    ToUserName: 'touser',    FromUserName: 'fromuser',    CreateTime: parseInt(+new Date / 1000),  }}

              客服输入状态

              开发者可通过调用 客服输入状态接口,返回客服当前输入状态给用户。

              1. 此接口需要客服消息接口权限。
              2. 如果不满足发送客服消息的触发条件,则无法下发输入状态。
              3. 下发输入状态,需要客服之前 30 秒内跟用户有过消息交互。
              4. 在输入状态中(持续 15 秒),不可重复下发输入态。
              5. 在输入状态中,如果向用户下发消息,会同时取消输入状态。

              在客服消息中使用临时素材

              开发者可在接收和发送客服消息的过程中获取或上传临时素材。

              获取临时素材

              接收到用户消息之后,可通过 获取临时素材接口 获取消息中的临时素材

              上传临时素材

              通过 上传临时素材接口 可以上传临时素材,并在 发送消息接口 中使用。


              位置消息

              微信客户端 7.0.9 及以上版本支持,iOS 暂不支持

              为了让用户更便 捷地使用小程序的打车服务,我们在位置消息详情页的菜单中,新增了打车小程序入口。

              1. 打开聊天中的位置消息,点击详情页右下角绿色按钮,菜单中会展示符合条件的打车小程序,用户可以直接发起目的地为该位置的打车服务。
              2. 小程序的注册类目为“打车(网约车)”,且有用户最近使用的记录,才可以出现在该菜单中。
              3. 在此处点击打开小程序后,需要直接进入到发起打车页面。

              1. 位置消息入口声明

              开发者需要在全局配置app.json声明支持从位置消息入口进入小程序。

              配置示例:

              "entranceDeclare": {    "locationMessage": {        "path": "pages/index/index",        "query": "foo=bar"    }}

              配置项

              属性类型必填描述最低版本
              entranceDeclareObject入口声明信息7.0.9

              entranceDeclare参数列表

              属性类型必填描述最低版本
              locationMessageObject声明“位置消息”场景进入小程序的启动页面7.0.9

              locationMessage参数列表

              属性类型必填描述最低版本
              pathstring启动页路径,必须是在pages中已经定义7.0.9
              querystring启动页参数7.0.9

              2. 从启动参数获取位置信息

              示例代码:

              //app.jsApp({  onLaunch: function (options){    console.log(options)    var scene = options.scene     if (scene == 1146) { // 位置消息场景值      var location = options.locationInfo      var x = location.latitude      var y = location.longitude      var name = location.name    }  },})

              Object 启动参数

              属性类型描述
              scenenumber启动小程序的场景值,“位置消息”的启动场景值为1146
              locationInfoObject特殊场景的启动信息

              locationInfo 的结构

              属性类型描述
              latitudenumber纬度,范围为 -90~90,负数表示南纬
              longtitudenumber经度,范围为 -180~180,负数表示西经
              namestringPOI名称

              3. 工具调试

              Nightly v1.02.1912062 版本已支持条件编译增加位置消息入口。选择场景值 1146: 位置消息中用小程序打车,传入POI点名称和经纬度信息后可用真机预览调试。


              卡券

              说明

              小程序卡券接口支持在小程序中领取/查看/使用公众号 AppId 创建的会员卡、票、券(含通用卡)。更多使用方法可参考 小程序&卡券打通

              使用条件

              目前只有认证小程序才能使用卡券接口,可参考 指引 进行认证。

              接口

              小程序内可以通过 wx.addCard 接口给用户添加卡券。通过 wx.openCard 让用户选择已有卡券。


              会员卡组件

              开发者可以在小程序内调用该接口拉起会员开卡组件,方便用户快速填写会员注册信息并领卡。该接口拉起开卡组件无须提前将开卡组件和发起小程序绑定至同一个公众号,开发者直接调用即可。

              调用前开发者须完成以下步骤:

              1. 创建一张微信会员卡并设置为一键激活模式;
              2. 设置开卡字段;
              3. 获取开卡组件参数;

              详情查看会员开卡组件介绍:会员开卡组件

              参数说明

              参数名类型是否必填参数说明
              appIdString填写 wxeb490c6f9b154ef9,固定为此appid
              extraDataObject开卡组件参数,由第3步获取,包含以下三个参数
              encrypt_card_idString加密 card_id,传入前须 urldecode
              outer_strString会员卡领取渠道值,会在卡券领取事件回传给商户
              bizString商户公众号标识参数,传入前须 urldecode
              successFunction接口调用成功的回调函数
              failFunction接口调用失败的回调函数
              completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

              返回参数

              参数名类型参数说明
              errMsgString调用结果

              示例代码

              wx.navigateToMiniProgram({  appId: 'wxeb490c6f9b154ef9', //固定为此 appid,不可改动  extraData: data, // 包括 encrypt_card_id, outer_str, biz三个字段,须从 step3 中获得的链接中获取参数  success: function() {  },  fail: function() {  },  complete: function() {  }})

              navigateToMiniProgram接口即将废弃,新版本中请使用navigator组件来使用此功能

              <navigator target="miniProgram" app-id="wxeb490c6f9b154ef9" extra-data="{{data}}">会员卡开卡</navigator>

              返回说明

              在 App.onShow 里判断从会员开卡小程序返回的数据data

              1. 判断 data.referrerInfo.appId 是否为开卡小程序 appId wxeb490c6f9b154ef9,如果不是则中止判断
              2. 判断是否有 data.referrerInfo.extraData 是否有数据,如果没有,表示用户未激活直接左滑/点返回键返回,或者用户已经激活
              3. 若用户激活成功,可以从 data.referrerInfo.extraData 中获取 activate_ticket,card_id,code 参数用于下一步操作

              提示:

              1. 在开发者工具上调用此 API 并不会真实的跳转到另外的小程序,但是开发者工具会校验本次调用跳转是否成功详情
              2. 开发者工具上支持被跳转的小程序处理接收参数的调试详情
              3. 开卡组件是使用wx.navigateToMiniProgram开发的官方组件,跳转时无须绑定同一个公众号,直接调用即可


              获取小程序码

              通过后台接口可以获取小程序任意页面的小程序码,扫描该小程序码可以直接进入小程序对应的页面,所有生成的小程序码永久有效,可放心使用。 我们推荐生成并使用小程序码,它具有更好的辨识度,且拥有展示“公众号关注组件”等高级能力。 生成的小程序码如下所示:

              可以使用开发工具 1.02.1803130 及以后版本通过二维码编译功能调试所获得的二维码

              为满足不同需求和场景,这里提供了两个接口,开发者可挑选适合自己的接口。

              获取小程序二维码(不推荐使用)

              通过后台接口可以获取小程序任意页面的小程序二维码,生成的小程序二维码如下所示:

              • 接口 C:适用于需要的码数量较少的业务场景
                • 生成二维码,可接受 path 参数较长,生成个数受限,数量限制见 注意事项。

                  获取小程序码(一物一码)

                  微信一物一码 支持生成小程序码。微信通过“一物一码”接口发放的二维码相比较普通链接二维码更安全、支持更小的印刷面积,支持跳转到指定小程序页面,且无数量限制。

                  注意事项

                  1. 接口只能生成已发布的小程序的二维码
                  2. 接口 A 加上接口 C,总共生成的码数量限制为 100,000,请谨慎调用。
                  3. 接口 B 调用分钟频率受限(5000次/分钟),如需大量小程序码,建议预生成。



                数据分析接口

                开发者通过数据分析接口,可获取到小程序的各项数据指标,便于进行数据存储和整理。数据分析详细功能介绍及指标解释参见数据分析文档

                相关接口


                附近的小程序

                概述

                附近的小程序 API,提供给需快速批量创建附近地点的小程序开发者使用,使用前请先调高附近地点额度。 调高附近地点额度申请方式如下:

                下载 《调高地点额度申请表》,填写后发送至 placeofminiprogram@qq.com。

                邮件主题为:“帐号名称”申请调高附近地点额度。审核通过后可调高额度。

                管理接口


                快递接口(商家必看)

                1. 产品介绍

                快递接口是微信官方为小程序提供的免费物流接口。接入后,你可使用本接口在多家快递公司获取电子面单单号等信息,再通过热敏打印机完成电子面单打印,即可将快件交给快递公司上门揽收。

                2. 接入快递接口有什么好处

                可批量生成电子面单本接口已对接多家快递公司下单接口,使用本接口可在各快递公司批量生成电子面单;

                可回传物流轨迹给你经由快递接口下的单,微信会将物流轨迹返回给你,便于你实时掌握快件运输路径;

                用户可收到物流通知经由快递接口下的单,微信官方会通过服务通知推送快件状态给用户,提升用户体验;

                完全免费的官方接口快递接口为微信官方接口,统一对接多家物流公司,服务稳定,免费开放。

                增加用户回流小程序入口接入快递接口后,用户可通过两个方式回访你的小程序: 

                3.目前支持的快递公司


                4. 如何使用物流助手

                前往微信公众平台→【物流助手】→【去接入】查看接入流程指引 


                步骤1:绑定签约的快递网点账号

                在微信公众平台-小程序管理后台,点击【物流助手】→【去接入】→【去绑定】,选择和你签约过的物流公司,输入和网点签约时分配给你的账号密码,提交绑定; 


                绑定说明

                (1) 若当前无账号密码,请先线下联系物流公司网点完成签约获得账号和密码,再进行绑定;(2) 上述绑定账号即为调用快递接口Api下单时,选择物流公司后需填写的Bizid;(3) 若事先没有和物流公司签约,准备发散单,则无需在该页面绑定物流公司,调用物流接口下单时填写现付的Bizid即可,下单成功后系统会通知快递员上门取件,运费现结。目前两家物流公司支持下散单,对应Bizid如下:

                快递公司名称快递公司ID现付的BizID
                顺丰速运SFSF_CASH
                德邦快递DBDB_CASH

                步骤2:对接快递接口(商家必看)Api

                (1)查看接口文档

                (2)开发接口文档:你可自行开发或授权服务商开发,遇到问题可前往微信开放社区提问;

                (3)测试下单:自行填写测试的收发货人信息和商品信息,看是否可成功调用本接口下单、成功生成电子面单、获取面单数据、打印面单和接收服务通知,全流程走通则说明接口已调通。

                步骤3:打印电子面单

                用快递接口Api下单后,可选择以下任一方式打印电子面单

                • 使用微信物流助手对接的第三方打单软件打印面单,当前已支持的第三方打单软件为: 快递管家 点击获取对接指引更多第三方持续对接中,请期待
                • 使用物流公司接口或收件员上门打印电子面单;
                • 使用 getOrder 拉取电子面单 html,使用热敏打印机打印(可能存在格式兼容问题,需调试);
                • 使用 getOrder 拉取电子面单的waybill_data,自行构造面单并打印(可能存在格式兼容问题,需调试);
                • 安装使用微信打单PC软件:目前支持 Windows XP 及以上版本。点此下载

                步骤4:快递员上门揽件

                快递员上门揽件后,商家即可通过物流助手Api接收物流轨迹,微信会给用户推送已揽件、派件中、已签收/签收异常的服务通知,便于用户了解运单轨迹。


                附录:快递接口流程图


                微信物流助手(快递侧)

                物流助手,帮助有物流需求的开发者,快速高效对接多家物流公司。对接后用户可通过微信服务通知接收实时物流状态,提升用户体验。

                产品优势

                1. 承接微信生态订单:通过微信统一接口,一次性服务微信生态内有寄件需求的商户。
                2. 提升用户回访:关键物流状态会通过微信服务通知发送给用户,用户点击后可回访快递公司小程序查看该订单的物流状态或进行后续操作。

                接入说明

                目前物流助手采用定向邀请方式接入物流公司。

                接入准备

                1. 小程序

                用户收到轨迹更新消息后,可以间接跳转到快递小程序的轨迹详情页。至少需要提供两个页面:

                1. 快递轨迹详情页,路径可以参考pages/info/info?from=wx&no=12345678901234。微信做跳转时,会传入运单号。
                2. 快递投诉页面

                2. 小程序事件服务

                事件服务用于接收微信的推送,目前有审核商户、查询余额、下单、取消运单等事件。

                3. 面单模板和示例

                标注各个区域的尺寸、字号等。可参考模板示例

                相关接口

                相关事件


                物流助手-打单软件

                介绍

                商户可以通过打单软件,自助打印面单

                使用说明

                1. 通过 updatePrinter API 更新打印员。
                2. 打印员扫码登录、选择商户。
                3. 配置热敏打印机(PC端需安装打印机驱动,并选择203dpi分辨率)。
                4. 拉取面单,打印需要的面单;或启用自动打印,新订单下单成功即会自动打印。

                最新版本下载地址

                Windows

                支持 Windows XP 及以上版本。

                更新日志

                v1.0.0 (2019.01.16)

                1. 支持打印员扫码登录。
                2. 支持不同快递配置独立打印机。
                3. 支持手动拉取订单,保存或打印面单。
                4. 支持自动拉取订单、自动打印面单。

                其它打印方式

                你也可以使用微信物流助手对接的第三方打单软件打印面单,当前已支持的第三方打单软件为:


                常见问题

                问题1. 快递接口是什么?

                快递接口是微信官方提供的免费物流接口工具,帮助有物流需求的开发者快速高效对接多家物流公司。

                问题2. 使用快递接口有什么好处?

                商家通过本接口可调用各物流公司电子面单接口批量下单、打印电子面单和获取物流轨迹,减少逐一对接物流公司的成本,提高物流效率;用户通过你的小程序下单后,微信会通过服务通知告知用户关键物流动态,包括快递公司已揽件、快件派件中、快件已签收和运单异常四种状态,提升用户物流体验。

                问题3. 快递接口需要收费吗?

                快递接口是微信官方提供的基础能力,是完全免费的。

                问题4. 如何使用快递接口服务?

                前往微信公众平台→【物流助手】→【去接入】查看接入流程指引 


                步骤1:绑定签约的快递网点账号


                在微信公众平台-小程序管理后台,点击【物流助手】→【去接入】→【去绑定】,选择和你签约过的物流公司,输入和网点签约时分配给你的账号密码,提交绑定; 


                绑定说明


                (1) 若当前无账号密码,请先线下联系物流公司网点完成签约获得账号和密码,再进行绑定;(2) 上述绑定账号即为调用快递接口Api下单时,选择物流公司后需填写的Bizid;(3) 若事先没有和物流公司签约,准备发散单,则无需在该页面绑定物流公司,调用物流接口下单时填写现付的Bizid即可,下单成功后系统会通知快递员上门取件,运费现结。目前有三家物流公司支持下散单,对应Bizid如下:

                快递公司名称快递公司ID现付的BizID
                顺丰速运SFSF_CASH
                德邦快递DBDB_CASH

                步骤2:对接快递接口(商家必看)Api


                (1)查看接口文档

                (2)开发接口文档:你可自行开发或授权服务商开发,遇到问题可前往微信开放社区提问;

                (3)测试下单:自行填写测试的收发货人信息和商品信息,看是否可成功调用本接口下单、成功生成电子面单、获取面单数据、打印面单和接收服务通知,全流程走通则说明接口已调通。

                步骤3:打印电子面单用快递接口Api下单后,可选择以下任一方式打印电子面单

                安装微信打单PC软件:目前支持 Windows XP 及以上版本。点此下载
                • 使用物流公司接口或收件员上门打印电子面单;
                • 使用 getOrder 拉取电子面单 html,使用热敏打印机打印(可能存在格式兼容问题,需调试);
                • 使用 getOrder 拉取电子面单的waybill_data,自行构造面单并打印(可能存在格式兼容问题,需调试);

                步骤4:快递员上门揽件



                快递员上门揽件后,商家即可通过快递接口Api接收物流轨迹,微信会给用户推送已揽件、派件中、已签收/签收异常的服务通知,便于用户了解运单轨迹。



                问题5. 我此前没有和快递公司签约,怎么使用快递接口?

                如果你希望和快递公司签约,可先线下和发货仓附近的物流网点签约,拿到签约的账号和密码后再使用微信快递接口服务;

                若事先没有和物流公司签约,可以发现付单,调用物流接口下单时填写现付的Bizid即可(无需填写密码),下单成功后通知快递员上门取件,运费现结。目前三家物流公司支持下散单,对应Bizid如下:

                快递公司名称快递公司ID现付的BizID
                顺丰速运SFSF_CASH
                德邦快递DBDB_CASH

                问题6. 我已经在某家快递网点购买了大量的快递单号,如何使用快递接口?

                你可以在微信公众平台小程序后台-【物流助手】中,绑定该网点合作账号和密码,下单时即可扣减该物流公司账号内的预充值账号。

                问题7. 快递费怎么结算?

                快递接口帮助商户在信息流层面对接物流公司,具体的运单费用取决于你与快递公司签约的价格。

                问题8. 我在小程序后台绑定了快递公司,为什么没有办法下单?

                绑定快递公司后,你需要进行快递接口文档开发,才可完整使用快递接口服务,[接口文档] (https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/express/getallaccount.html "接口文档")

                问题9. 目前支持哪些快递公司?

                目前支持的公司如下,更多快递公司持续接入中,请期待。

                问题10. 目前所有微信内的订单都可以使用快递接口吗?

                当前可支持小程序内的订单(小游戏除外),后续将陆续开放公众号、H5的订单,请期待。

                问题11. 用快递接口下的单,快递员就会上门来揽件吗?

                快递接口可帮助你批量下单和打印面单。快递员上门的时间若与你此前有约定,则继续按照约定上门揽件,若此前没有约定,请和发件网点的快递员联系上门揽件。

                问题12. 打印电子面单必须使用快递接口提供的打单软件吗?

                优先推荐使用官方打单软件,可更好兼容各家物流公司格式要求,此外也可选择物流公司上门打单。 若需使用热敏打印机或自行构造面单并打印,可能会存在格式兼容问题,请调试后再使用。

                你也可以使用微信物流助手对接的第三方打单软件打印面单,当前已支持的第三方打单软件为:

                问题13. 开发过程中遇到问题怎么办?

                请前往微信开发者社区提问,我们会第一时间解答你的问题。


                网络快递沙盒环境指引

                为了方便商家接入自测,我们提供了测试的沙盒环境,商户可以通过下面的流程来模拟下单,修改订单状态,体验服务通知。

                接入须知

                1. 此环境只能用于测试下单,禁止用于其它用途。
                2. 为了防止骚扰用户,openid只能配置为小程序的管理员,运营者或者开发者
                3. 下单调用次数有限制,每天不能超时10次
                4. 只能使用以下测试信息进行测试!!!测试运力delivery_id="TEST"测试商户biz_id="test_biz_id"服务类型service.service_type=1服务类型service.service_name="test_service_name"

                测试流程

                1. 商户调用微信平台提供的api接口进行下单,查询订单,取消订单等操作
                2. 调用模拟更新订单接口来改变订单状态,收件人将收到相应的揽件单,派送,配送完成通知


                联系我们

                开发过程中遇到任何问题,请前往微信开放社区提问。提问时,建议标题以【物流助手】开头,我们会第一时间解答你的疑问。


                微信物流助手(快递侧)

                物流助手,帮助有物流需求的开发者,快速高效对接多家物流公司。对接后用户可通过微信服务通知接收实时物流状态,提升用户体验。

                产品优势

                1. 承接微信生态订单:通过微信统一接口,一次性服务微信生态内有寄件需求的商户。
                2. 提升用户回访:关键物流状态会通过微信服务通知发送给用户,用户点击后可回访快递公司小程序查看该订单的物流状态或进行后续操作。

                接入说明

                目前物流助手采用定向邀请方式接入物流公司。

                接入准备

                1. 小程序

                用户收到轨迹更新消息后,可以间接跳转到快递小程序的轨迹详情页。至少需要提供两个页面:

                1. 快递轨迹详情页,路径可以参考pages/info/info?from=wx&no=12345678901234。微信做跳转时,会传入运单号。
                2. 快递投诉页面

                2. 小程序事件服务

                事件服务用于接收微信的推送,目前有审核商户、查询余额、下单、取消运单等事件。

                3. 面单模板和示例

                标注各个区域的尺寸、字号等。可参考模板示例

                相关接口

                相关事件


                即时配送接口(商家查看)

                1. 概述

                即时配送接口,微信官方免费接口,旨在解决餐饮、生鲜、超市等小程序的外卖配送需求。接入后小程序商家可通过统一的接口获得多家配送公司的配送服务,提高经营效率。

                2. 接入有什么好处

                满足多品类配送需求可满足餐饮、生鲜、商超等多品类的配送需求

                接口完全免费即时配送接口是官方提供的基础能力,完全免费开放

                提升用户收货体验配送详情将通过微信服务通知下发给用户,提升收货体验。服务通知包括骑手已接单,骑手已取货、配送中,配送完成和配送异常四种状态

                统一对接节约成本本接口已统一对接多家配送公司下单接口,可直接生成配送单

                增加用户回访小程序入口配送详情的服务通知可跳转商家小程序,提升用户回访率  

                640

                3. 支持的配送公司

                hMoZQW4FiEmmm3uHSmtgVxDv7VNbS1FW-XoJ7X5Xvf4woN77msehMXVwQ6Xj-nJj51gXUzCV1bOx1dOvfBBWUQ

                4. 对接流程

                前提:商家需先和配送公司已达成合作关系,签约了账号才可使用本接口下单。例如:选择闪送下单,需事先和闪送沟通,在闪送创建一个合作账号以后,再来对接微信即时配送Api。

                步骤1:登录微信公众平台,授权绑定配送公司的签约账号,流程拆解为:

                (1)商家登录微信公众平台,点击右侧菜单【物流助手】——点击【即时配送】tab——去接入;(2)选择已经有合作账号的配送公司,如合作公司为闪送,跳转闪送的授权登录页面,输入在闪送的合作账号和密码后,授权登录;(3)合作的运力公司返回授权结果,商家后续即可使用该授权过的合作账号下单。

                步骤2:对接即时配送Api(商家查看),预计需要2-3天

                (1)查看接口文档(2)开发接口文档:你可自行开发或授权服务商开发,遇到问题可前往微信开放社区提问;

                步骤3:测试联调

                我们提供了稳定的沙盒环境供你开发过程进行调试,请先在沙盒环境调试完毕后再正式调用接口发单,测试指引需补充。

                步骤4:上线发单

                调试通过后即可上线,骑手接单后,你和用户均可接收配送详情的推送。


                版本说明

                • 2019.9.2 配送公司信息新增关于收取件码的规则 预下配送单接口新增各家配送公司返回字段的说明 预下配送单下配送单接口expected_delivery_time number 、expected_finish_time number、expected_pick_time number参数说明修订
                • 2019年8月11日 达达上线
                • 2019年7月23日 即时配送接口上线,支持已和配送公司签约的商户下单


                配送公司信息

                1. 配送公司基础信息

                配送公司配送公司ID配送服务代码获取Appkey和Appsecret的方式获取门店编号(shop_no)的方式
                顺丰同城急送SFTC不填第1步:登录顺丰同城开放平台
                第2步:点击顶部导航条的“开发者中心”
                第3步:Appkey即开发者ID,Appsecret 即密钥
                商家在入驻顺丰同城急送时时提供的门店编号
                闪送SS1 (闪送专送)第1步:打开闪送商家版官网
                第2步:登录账号
                第3步:点击左侧导航栏->基本设置->AppKey授权
                第4步:即可查看Appkey(开发者ID),Appsecret(密钥)
                商家在入驻闪送时提供的门店编号
                美团配送MTPS4002(飞速达:实时接单,45分钟内完成配送)

                4011(快速达:实时接单,60分钟内完成配送)

                4012(及时达:实时接单,120分钟内完成配送)

                4013(集中送:商家集中备货,固定时间推送订单,骑手上门取货后120分钟内完成配送)
                第1步:打开美团配送开放平台
                第2步:登录合作方账号
                第3步:点击左侧导航商户管理->开发管理
                第4步:获取线上环境Appkey(开发者ID)和AppSecret(密钥)
                商家在入驻美团配送时提供的门店编号
                达达DADA不填点击这里查看指引商家在入驻达达时提供的门店编号

                2. 配送公司业务规则说明

                配送公司多门店shop_no多门店发件人地址直拿直送保价规则收取件码规则加小费规则订单取消规则
                顺丰同城急送必传必传不支持,不填支持保价,需提前在顺丰同城急送系统中配置支持收取货码,支持微信接口传入,下单时返回。
                骑手接单后顺丰同城会短信下发取货码给商家,取货后短信下发收货码给收货人
                不支持加小费配送完成前任意节点可取消配送单
                闪送必传必传支持,全部为直拿直送不支持支持收取货码,以商家在闪送后台的开关设置状态为准。
                骑手接单后闪送会短信下发取货码给商家,取货后短信下发收货码给收货人。
                支持加小费
                小费规则:骑手接单前可加小费,需按固定档位加小费,档位为2、3、5、10、15、20、50、100;
                配送完成前任意节点可取消配送单
                美团配送必传不传不支持,不填支持保价,需线下和美团配送签订保价合同不支持收取货码不支持加小费配送完成前任意节点可取消配送单
                达达必传不传支持,选填支持仅支持收货码,支持微信接口传入,下单时返回。
                骑手取货后达达会短信下发给收货人
                支持加小费
                小费规则:可以对待接单状态的订单增加小费。订单的小费,以最新一次加小费动作的金额为准,故下一次增加小费额必须大于上一次小费额。(单位:元,精确小数点后一位)
                骑手取货前可以取消


                开发必读

                商家接入准备

                1. 小程序进行微信认证
                2. 开通事件推送,设置事件地址:登录小程序后台,开发->开发设置->消息推送->启用
                3. 消息加密方式使用安全模式,数据格式选JSON
                4. 如果授权给第三方,则不需要步骤2
                5. 在配送公司注册帐号,并在小程序后台进行授权绑定

                名称解释

                1. appkey: 一般为商家在登录配送公司开放平后分配的相应的appkey值
                2. AppSecret: 一般为商家在登录配送公司开放平后分配的相应的秘钥
                3. shopid:微信平台字段,对应配送公司的appkey
                4. shop_no:商家对不同门店进行的编号,需要在配送公司系统有过登记,比如商家自己门店系统中有100个门店,编号是1-100,在顺丰同城的系统中有登记过这100个门店,且在顺丰同城登记的编号也是1-100,那么下单的时候传shop_no=1,就是编号为1 的门店下的配送单
                5. shop:下单请求的一个字段,商家信息,会展示到物流通知消息中,如下图所示640 (1)
                6. 下单请求的取货码和收货码:取货码是指骑手在商家这里取货时,商家出示取货码,骑手才能完成取货;收货码指骑手送达给用户时,用户出示收货码,骑手才算配送完成。商家可在配送公司开放平台设置是否需要开启取货码和收货码

                调用api接口说明

                1. 编码方式:UTF-8
                2. 数据格式:JSON
                3. 提交方式:POST
                4. 下单需要使用绑定的shopid和AppSecret,其中shopid即配送公司帐号的appkey,AppSecret即配送公司帐号对应的秘钥
                5. resultcode错误码和resultmsg错误描述由运力方定义,微信侧负责透传,只统一定义code=0表示成功
                6. 除了平台本身的加解密和签名,和订单相关的请求还需要带上运力侧签名delivery_sign,签名规则为
                7. 如果接口请求里有字段shop_order_id ,则delivery_sign=SHA1(shopid + shop_order_id + AppSecret),其中shopid对应运力侧的appkey,shop_order_id对应订单id,AppSecret即配送公司帐号对应的秘钥
                8. 如果请求里没有字段shop_order_id ,则delivery_sign=SHA1(shopid + AppSecret),其中shopid对应运力侧的appkey,AppSecret即配送公司帐号对应的秘钥
                9. 示例:shopid=“test_shop_id”,shop_order_id =“test_shop_order_id”, AppSecret=“test_app_secrect”,则delivery_sign=“a93d8d6bae9a9483c1b1d4e8670e7f6226ec94cb”

                错误码说明

                错误码错误描述
                930555微信平台系统错误
                930556配送公司超时
                930557配送公司系统错误
                930558配送公司逻辑错误
                930559openid无效
                930560未绑定的商户号
                930561参数错误
                930562配送单已经存在
                930563配送单不存在
                930564调用无配额
                930565配送单已结束
                9300535shop字段商品缩略图 url、商品名称为空或者非法,或者商品数量为0
                其他错误码配送公司返回的错误码


                品类表

                一级类目二级类目
                美食夜宵零食小吃
                香锅/烤鱼
                西餐
                日韩料理
                海鲜/烧烤
                快餐/地方菜
                小龙虾
                披萨
                甜品饮料甜品
                奶茶果汁
                咖啡
                面包/糕点
                冰淇淋
                蛋糕蛋糕
                日用百货便利店
                水站/奶站
                零食/干果
                五金日用
                粮油调味
                文具店
                酒水行
                地方特产
                进口食品
                宠物用品
                超市
                书店
                宠物食品用品
                办公家居用品
                果蔬生鲜果蔬
                海鲜水产
                冷冻速食
                鲜花鲜花
                医药健康送药
                器材器具
                美妆护肤日化美妆
                母婴孕婴用品
                文件或票务保单
                票务文件
                政府文件
                证件
                服饰鞋帽服饰鞋帽综合
                洗涤脏衣服收
                干净衣服派
                珠宝奢侈品珠宝饰品
                奢侈品
                家居家装家具
                装修建材
                厨房卫浴
                数码产品数码产品
                配件器材配件器材
                电商电视购物
                线上商城
                现场勘查现场勘查
                快递业务快递配送
                其他其他


                order_status 枚举值

                说明
                101配送公司接单阶段——等待分配骑手,即初始状态
                102配送公司接单阶段——分配骑手成功
                103配送公司接单阶段——商家取消订单, 订单结束
                201骑手取货阶段——骑手到店开始取货
                202骑手取货阶段——取货成功
                203骑手取货阶段——取货失败,商家取消订单, 订单结束
                204骑手取货阶段——取货失败,骑手因自身原因取消订单, 订单结束
                205骑手取货阶段——取货失败,骑手因商家原因取消订单, 订单结束
                301骑手配送阶段——配送中
                302骑手配送阶段——配送成功, 订单结束
                303骑手配送阶段——商家取消订单,配送物品开始返还商家
                304骑手配送阶段——无法联系收货人,配送物品开始返还商家
                305骑手配送阶段——收货人拒收,配送物品开始返还商家
                401骑手返回配送货品阶段——货品返还商户成功, 订单结束
                501因运力系统原因取消, 订单结束
                502因不可抗拒因素(天气,道路管制等原因)取消,订单结束

                说明

                1. 最终状态包括成功状态302,失败状态: 103,203,204,205,401,501,502。
                2. 当状态更新时,我们会在关键节点给收件用户推送服务通知,告知配送状态,同一配送单常态下会收到三条通知,即【骑手已接单】、【骑手已取货,配送中】、【配送已完成】,配送异常时会下发【配送异常】服务通知。

                不同服务通知对应的 order_status 枚举值为

                服务通知对应的order_status值
                骑手已接单102
                骑手已取货,配送中202或301
                配送已完成302
                配送异常203、204、205、303、304、305、501、502


                即时配送沙盒环境指引

                为了方便商家接入自测,我们提供了测试的沙盒环境,商户可以通过下面的流程来模拟下单,修改订单状态,体验服务通知。

                接入须知

                1. 此环境只能用于测试下单,禁止用于其它用途。
                2. 为了防止骚扰用户,openid只能配置为小程序的管理员,运营者或者开发者
                3. 下单调用次数有限制,每天不能超时500次
                4. 只能使用以下测试信息进行测试测试运力delivery_id="TEST"测试商户shopid="test_shop_id"测试商户AppSecret="test_app_secrect"

                测试流程

                1. 商户调用微信平台提供的api接口进行预下单,下单,查询订单,取消订单等操作
                2. 调用模拟配送公司更新订单接口来改变订单状态,收件人将收到相应的接单,派送,配送完成通知


                常见问题

                问题1. 即时配送是什么?

                即时配送是微信官方免费接口,旨在解决餐饮、生鲜、超市等小程序的外卖配送需求。接入后小程序商家可通过统一的接口获得多家配送公司的配送服务,提高经营效率。

                问题2. 使用即时配送有什么好处?

                满足多品类配送需求可满足餐饮、生鲜、商超等多品类的配送需求

                接口完全免费即时配送接口是官方提供的基础能力,完全免费开放

                提升用户收货体验配送详情将通过微信服务通知下发给用户,提升收货体验。服务通知包括骑手已接单,骑手已取货、配送中,配送完成和配送异常四种状态

                统一对接节约成本本接口已统一对接多家配送公司下单接口,可直接生成配送单

                增加用户回访小程序入口配送详情的服务通知可跳转商家小程序,提升用户回访率  

                640 (2)

                问题3. 接口收费吗?

                即时配送是微信官方接口能力,完全免费的。

                问题4. 目前已经支持哪些配送公司了?

                640

                问题5. 配送费用怎么结算?

                目前商家使用即时配送的前提是商家已经是本接口支持的配送公司的客户。结算模式按原有商家和配送公司的结算模式来进行。

                问题6. 接入即时配送的流程是怎么样的?

                前提:商家需先和配送公司已达成合作关系,签约了账号才可使用本接口下单。 例如:选择闪送下单,需事先和闪送沟通,在闪送创建一个合作账号以后,再来对接微信即时配送Api。

                步骤1:登录微信公众平台,授权绑定配送公司的签约账号,流程拆解为:

                1. 商家登录微信公众平台,点击右侧菜单【物流助手】——点击【即时配送】tab——去接入;
                2. 选择已经有合作账号的配送公司,如合作公司为闪送,跳转闪送的授权登录页面,输入在闪送的合作账号和密码后,授权登录;
                3. 合作的运力公司返回授权结果,商家后续即可使用该授权过的合作账号下单。

                步骤2:对接即时配送Api(商家查看),预计需要2-3天

                1. 查看相关接口和事件
                2. 开发接口文档:你可自行开发或授权服务商开发,遇到问题可前往微信开放社区提问;

                步骤3:测试联调 我们提供了稳定的沙盒环境供你开发过程进行调试,请先在沙盒环境调试完毕后再正式调用接口发单,测试指引需补充。

                步骤4:上线发单 调试通过后即可上线,骑手接单后,你和用户均可接收配送详情的推送。

                问题7. 商家没有开发能力,可以让服务商代开发吗?

                可以的,服务商代开发的流程为:

                1. 商家登录微信公众平台,点击右侧菜单【物流助手】——点击【即时配送】tab——去接入;
                2. 选择已经有合作账号的配送公司,如合作公司为闪送,跳转闪送的授权登录页面,输入在闪送的合作账号和密码后,授权登录;
                3. 商家将整体即时配送权限集授权给服务商;
                4. 服务商对接Api,完成后续流程开发;
                5. 备注:服务商可以通过getBindAccount接口,查询到商家已授权绑定的配送公司合作账号。

                问题8. 怎么获取我在配送公司的appkey和appsecret?

                详见配送公司信息

                问题9. 用户会收到哪些配送通知?

                当状态更新时,我们会在关键节点给收件用户推送服务通知,告知配送状态,同一配送单常态下会收到三条通知,即【骑手已接单】、【骑手已取货,配送中】、【配送已完成】,配送异常时会下发【配送异常】服务通知。

                问题10. 达达开放平台授权绑定提示“已开通其他渠道”

                达达的商户号只能绑定一个渠道,请检查是否已经绑定达达开放平台的开发者帐号,需要先解绑。

                问题11. 开发过程中遇到问题怎么办?

                请前往微信开放社区提问,提问时请以【物流助手】开头,我们会第一时间解答你的问题。


                联系我们

                开发过程中遇到任何问题,请前往微信开放社区提问。 提问时,建议标题以【物流助手】开头,会第一时间解答你的疑问。


                Banner 广告

                小程序广告流量主操作指引:文档地址

                开发者可以使用 ad 组件创建 Banner 广告组件,Banner 广告组件在创建后会自动拉取广告数据并显示。

                广告尺寸设置

                Banner 广告不允许直接设置样式属性,默认宽度为100%(width: 100%),高度会自动等比例计算,因此开发者可以设置广告外层组件的宽度调整广告的尺寸。 广告外层组件的宽度不允许小于300px,当宽度小于300px时,Banner 广告的宽度会强制调整为300px。

                /* 外层组件的宽度可设置成100%或具体数值 */.adContainer {  width: 100%;}
                <view class="adContainer">  <ad unit-id="xxxx"></ad></view>

                广告事件监听

                Banner 广告在创建后会自动拉取广告。开发者可以通过 ad 组件的 onload 和 onerror 事件监听广告拉取成功或失败,可以通过 onclose 事件监听广告被关闭。

                <view class="adContainer">  <ad unit-id="xxxx" bindload="adLoad" binderror="adError" bindclose="adClose"></ad></view>
                Page({  adLoad() {    console.log('Banner 广告加载成功')  },  adError(err) {    console.log('Banner 广告加载失败', err)  },  adClose() {    console.log('Banner 广告关闭')  }})

                广告定时刷新

                开发者可以在创建 Banner 广告时传入 ad-intervals 参数实现广告的定时刷新,ad-intervals 参数为数字类型,单位为秒。注意:自动刷新的间隔不能低于30秒,因此 ad-intervals 的参数值必须大于或等于30。

                <view class="adContainer">  <ad unit-id="xxxx" ad-intervals="30"></ad></view>


                激励视频广告

                小程序广告流量主操作指引:文档地址

                激励视频广告组件是由客户端原生的图片、文本、视频控件组成的,层级最高,会覆盖在普通组件上。

                开发者可以调用 wx.createRewardedVideoAd 创建激励视频广告组件。该方法返回的是一个单例,该实例仅对当前页面有效,不允许跨页面使用。

                广告创建

                激励视频广告组件默认是隐藏的,因此可以提前创建,以提前初始化组件。开发者可以在小程序页面的 onLoad 事件回调中创建广告实例,并在该页面的生命周期内重复调用该广告实例。

                let rewardedVideoAd = nullPage({  onLoad() {    if(wx.createRewardedVideoAd){      rewardedVideoAd = wx.createRewardedVideoAd({ adUnitId: 'xxxx' })      rewardedVideoAd.onLoad(() => {        console.log('onLoad event emit')      })      rewardedVideoAd.onError((err) => {        console.log('onError event emit', err)      })      rewardedVideoAd.onClose((res) => {        console.log('onClose event emit', res)      })    }  }})

                为避免滥用广告资源,目前每个用户每天可观看激励式视频广告的次数有限,建议展示广告按钮前先判断广告是否拉取成功。

                显示/隐藏

                激励视频广告组件默认是隐藏的,在用户主动触发广告后,开发者需要调用 RewardedVideoAd.show() 进行显示。

                rewardedVideoAd.show() 

                只有在用户点击激励视频广告组件上的 关闭广告 按钮时,广告才会关闭。开发者不可控制激励视频广告组件的隐藏。

                广告拉取成功与失败

                激励视频广告组件是自动拉取广告并进行更新的。在组件创建后会拉取一次广告,用户点击 关闭广告 后会去拉取下一条广告。

                如果拉取成功,通过 RewardedVideoAd.onLoad() 注册的回调函数会执行,RewardedVideoAd.show() 返回的 Promise 也会是一个 resolved Promise。两者的回调函数中都没有参数传递。

                rewardedVideoAd.onLoad(() => {  console.log('激励视频 广告加载成功')})rewardedVideoAd.show().then(() => console.log('激励视频 广告显示'))

                如果拉取失败,通过 RewardedVideoAd.onError() 注册的回调函数会执行,回调函数的参数是一个包含错误信息的对象。

                rewardedVideoAd.onError(err => {  console.log(err)})

                RewardedVideoAd.show() 返回的 Promise 也会是一个 rejected Promise。

                rewardedVideoAd.show().catch(err => console.log(err))

                拉取失败,重新拉取

                如果组件的某次自动拉取失败,那么之后调用的 show() 将会被 reject。此时可以调用 RewardedVideoAd.load() 手动重新拉取广告。

                rewardedVideoAd.show().catch(() => {    rewardedVideoAd.load()    .then(() => rewardedVideoAd.show())    .catch(err => {      console.log('激励视频 广告显示失败')    })})

                如果组件的自动拉取是成功的,那么调用 load() 方法会直接返回一个 resolved Promise,而不会去拉取广告。

                rewardedVideoAd.load().then(() => rewardedVideoAd.show())

                监听用户关闭广告

                只有在用户点击激励视频广告组件上的 关闭广告 按钮时,广告才会关闭。这个事件可以通过 RewardedVideoAd.onClose() 监听。

                RewardedVideoAd.onClose() 的回调函数会传入一个参数 res,res.isEnded 描述广告被关闭时的状态。

                属性类型说明
                isEndedboolean视频是否是在用户完整观看的情况下被关闭的,true 表示用户是在视频播放完以后关闭的视频,false 表示用户在视频播放过程中关闭了视频

                开发者需要根据 res.isEnded 判断是否视频是否播放结束、可以向用户下发奖励。

                rewardedVideoAd.onClose(res => {    // 用户点击了【关闭广告】按钮    if (res && res.isEnded) {      // 正常播放结束,可以下发游戏奖励    } else {      // 播放中途退出,不下发游戏奖励    }})

                注意事项

                多次调用 RewardedVideoAd.onLoad()、RewardedVideoAd.onError()、RewardedVideoAd.onClose() 等方法监听广告事件会产生多次事件回调,建议在创建广告后监听一次即可,或者先取消原有的监听事件再重新监听。


                插屏广告

                插屏广告组件是由客户端原生的图片、文本、视频控件组成的,层级最高,会覆盖在普通组件上。

                开发者可以调用 wx.createInterstitialAd 创建插屏广告组件。每调用一次该方法,返回的都是一个全新实例,该实例仅对当前页面有效,不允许跨页面使用。

                广告创建

                插屏广告组件默认是隐藏的,因此可以提前创建,以提前初始化组件。开发者可以在小程序页面的 onLoad 事件回调中创建广告实例,并在该页面的生命周期内重复调用该广告实例。

                let interstitialAd = nullPage({  onLoad() {    if(wx.createInterstitialAd){      interstitialAd = wx.createInterstitialAd({ adUnitId: 'xxxx' })      interstitialAd.onLoad(() => {        console.log('onLoad event emit')      })      interstitialAd.onError((err) => {        console.log('onError event emit', err)      })      interstitialAd.onClose((res) => {        console.log('onClose event emit', res)      })    }  }})

                显示/隐藏

                插屏广告组件默认是隐藏的,开发者需要调用 InterstitialAd.show() 进行显示。如果广告拉取失败或触发频率限制,InterstitialAd.show() 方法会返回一个rejected Promise,开发者可自行监听错误信息。

                interstitialAd.show().catch((err) => {  console.error(err)})

                用户可以主动关闭插屏广告。开发者不可控制插屏广告组件的隐藏。

                广告拉取成功与失败

                插屏广告组件是自动拉取广告并进行更新的。在组件创建后会拉取一次广告,用户关闭广告后会去拉取下一条广告。

                如果拉取成功,通过 InterstitialAd.onLoad() 注册的回调函数会执行,回调函数没有参数传递。

                interstitialAd.onLoad(() => {  console.log('插屏 广告加载成功')})

                如果拉取失败,通过 InterstitialAd.onError() 注册的回调函数会执行,回调函数的参数是一个包含错误信息的对象。常见异常错误参考文档

                interstitialAd.onError(err => {  console.log(err)})

                监听用户关闭广告

                如果广告被关闭,通过 InterstitialAd.onClose() 注册的回调函数会执行,回调函数没有参数传递。

                interstitialAd.onClose(res => {    console.log('插屏 广告关闭')})

                注意事项

                多次调用 InterstitialAd.onLoad()InterstitialAd.onError()InterstitialAd.onClose() 等方法监听广告事件会产生多次事件回调,建议在创建广告后监听一次即可,或者先取消原有的监听事件再重新监听。

                在插屏广告展示过程中如果快速切换页面,可能会出现插屏广告展示在非调用页面的情况,如有需要请在页面切换完成后进行插屏广告展示。


                小程序视频广告

                小程序广告流量主操作指引:文档地址

                开发者可以使用 ad 组件创建小程序视频广告组件,视频广告组件在创建后会自动拉取广告数据并显示。暂时仅支持在同层渲染模式下使用,且不支持嵌套使用。

                广告尺寸设置

                小程序视频广告不允许直接设置样式属性,默认宽度为100%(width: 100%),高度会自动等比例计算,因此开发者可以设置广告外层组件的宽度调整广告的尺寸。 广告外层组件的宽度不允许小于屏幕宽度90%,当宽度小于屏幕宽度的90%时,视频广告组件的宽度会强制调整为屏幕宽度的90%。

                /* 外层组件的宽度可设置成100%或具体数值 */.adContainer {  width: 100%;}
                <view class="adContainer">  <ad unit-id="xxxx" ad-type="video" ad-theme="white"></ad></view>

                广告主题样式设置

                小程序视频广告组件提供黑、白两种主题样式,开发者可以在创建视频广告时传入ad-theme参数实现主题样式选择,ad-theme参数为字符串类型,参数值可选white, black

                <view class="adContainer">  <ad unit-id="xxxx" ad-type="video" ad-theme="white"></ad></view>
                <view class="adContainer">  <ad unit-id="xxxx" ad-type="video" ad-theme="black"></ad></view>

                广告事件监听

                视频广告在创建后会自动拉取广告。开发者可以通过 ad 组件的 onload 和 onerror 事件监听广告拉取成功或失败,可以通过 onclose 事件监听广告被关闭。

                <view class="adContainer">  <ad unit-id="xxxx" ad-type="video" ad-theme="white" bindload="adLoad" binderror="adError" bindclose="adClose"></ad></view>
                Page({  adLoad() {    console.log('小程序视频广告加载成功')  },  adError(err) {    console.log('小程序视频广告加载失败', err)  },  adClose() {    console.log('小程序视频广告关闭')  }})

                广告定时刷新

                小程序视频广告组件不适用于定时刷新参数ad-intervals


                视频前贴广告

                小程序广告流量主操作指引:文档地址

                开发者可以在 video 组件中添加属性配置,创建小程序视频前贴广告组件,视频广告组件在创建后会自动拉取广告数据,视频播放前展示广告。

                广告样式

                展示样式在开发者所设置的video组件中,以16:9的比例,垂直或者水平居中

                广告创建

                在 video 组件中添加了以下广告相关的属性配置,设置ad-unit-id后可以展示对应广告

                属性类型默认值必填说明
                ad-unit-idstring广告单元id,可在小程序管理后台的流量主模块新建
                bindadloadeventhandle广告加载成功的回调
                bindaderroreventhandle广告加载失败的回调,返回码同ad组件
                bindadcloseeventhandle广告关闭的回调
                bindadplayeventhandle广告开始,结束播放的回调 event.detail = {type: 'begin/end'}

                添加广告单元,绑定广告事件

                <video   class="xxx"  src="xxx"  bindadplay="onAdplay"  bindadload="onAdload"  bindadclose="onAdclose"  bindaderror="onAdError"  ad-unit-id="xxx"></video>

                监听广告事件

                Page({  onAdplay(e) {    console.log('onAdplay', e)  },  onAdload(e){    console.log('onAdload', e)  },  onAdclose(e) {    console.log('onAdclose', e)  },  onAdError(e) {    console.log('onAdError', e)  },})

                广告预加载

                开发者可以调用 wx.preloadVideoAd 的方式进行广告的预加载

                const adUnitId1 = 'xxx'const adUnitId2 = 'xxx'wx.preloadVideoAd([adUnitId1, adUnitId2])

                错误码

                错误码是通过bindaderror回调获取到的错误信息,前贴广告再普通广告组件ad错误码基础上新增了以下错误码。

                代码异常情况解决方案
                3001命中频控策略按照没有广告处理
                3002命中频控策略按照没有广告处理
                3003命中频控策略按照没有广告处理
                3004命中频控策略按照没有广告处理

                注意事项

                1、支持视频预加载能力:文档地址

                2、仅支持同层渲染模式下的video组件。

                3、开发者可监听bindadplay事件获取广告播放状态,做出相应处理。

                4、ad-unit-id不支持异步设置,只支持设置在wxml或者js文件的data属性里,通过setData设置的无效。

                5、全屏模式下不展示视频前贴广告。


                Grid 广告

                小程序广告流量主操作指引:文档地址

                开发者可以使用 ad 组件创建 Grid 广告组件,Grid 广告组件在创建后会自动拉取广告数据并显示。

                广告尺寸设置

                Grid 广告不允许直接设置样式属性,默认宽度为100%(width: 100%),高度会自动等比例计算,因此开发者可以设置广告外层组件的宽度调整广告的尺寸。格子广告有最小尺寸限制,5个的形态为331px,8个的形态为294px。

                /* 外层组件的宽度可设置成100%或具体数值 */.adContainer {  width: 100%;}
                <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" ad-theme="white" grid-count="5"></ad></view>

                广告事件监听

                Grid 广告在创建后会自动拉取广告。开发者可以通过 ad 组件的 onload 和 onerror 事件监听广告拉取成功或失败,可以通过 onclose 事件监听广告被关闭。

                <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" ad-theme="white" grid-count="5" bindload="adLoad" binderror="adError" bindclose="adClose"></ad></view>
                Page({  adLoad() {    console.log('Grid 广告加载成功')  },  adError(err) {    console.log('Grid 广告加载失败', err)  },  adClose() {    console.log('Grid 广告关闭')  }})

                广告主题样式设置

                小程序视频广告组件提供黑、白两种主题样式,开发者可以在创建视频广告时传入ad-theme参数实现主题样式选择,ad-theme参数为字符串类型,参数值可选white, black

                <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" ad-theme="white"></ad></view>
                <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" ad-theme="black"></ad></view>

                广告格子个数设置

                小程序视频广告组件提供黑、白两种主题样式,开发者可以在创建视频广告时传入grid-count参数实现主题样式选择,grid-count参数为数字类型,参数值可选5, 8

                <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" grid-count="5"></ad></view>
                <view class="adContainer">  <ad unit-id="xxxx" ad-type="grid" grid-count="8"></ad></view>


                原生模板 广告

                小程序广告流量主操作指引:文档地址

                开发者可以使用 ad-custom 组件创建 原生模板 广告组件,原生模板 广告组件在创建后会自动拉取广告数据并显示。

                广告尺寸设置

                原生模板 广告不允许直接设置样式属性,默认宽度为100%(width: 100%),高度会自动等比例计算,因此开发者可以设置广告外层组件的宽度调整广告的尺寸。 广告外层组件的宽度和具体模板相关,具体可以参考模板编辑器文档。

                /* 外层组件的宽度可设置成100%或具体数值 */.adContainer {  width: 100%;}
                <view class="adContainer">  <ad-custom unit-id="xxxx"></ad-custom></view>

                广告事件监听

                原生模板 广告在创建后会自动拉取广告。开发者可以通过 ad-custom 组件的 onload 和 onerror 事件监听广告拉取成功或失败。

                <view class="adContainer">  <ad-custom unit-id="xxxx" bindload="adLoad" binderror="adError"></ad-custom></view>
                Page({  adLoad() {    console.log('原生模板广告加载成功')  },  adError(err) {    console.log('原生模板广告加载失败', err)  }})

                广告定时刷新

                开发者可以在创建 原生模板 广告时传入 ad-intervals 参数实现广告的定时刷新,ad-intervals 参数为数字类型,单位为秒。注意:自动刷新的间隔不能低于30秒,因此 ad-intervals 的参数值必须大于或等于30。

                <view class="adContainer">  <ad-custom unit-id="xxxx" ad-intervals="30"></ad-custom></view>


                广告分析数据接口说明

                向所有成为流量主的公众号、小程序、小游戏开发者开放数据接口。通过数据接口,开发者可以获取与公众平台官网统计模块类似但更灵活的数据,还可根据需要进行高级处理。

                请注意:

                1. 接口侧数据库中仅存储了2016年1月1日之后的数据,将无法查询到此前的数据,即使查到,也是不可信的脏数据;
                2. 建议开发者在调用接口获取数据后,将数据保存在自身数据库中,以最大化访问的效率,也降低微信侧接口调用的不必要损耗;
                3. 由于数据量较大, 所有接口采取分页获取的方式, 每页最大获取量为90。(eg:total_num 为100,则当page = 1,page_size = 10,则返回前10条;page = 1,page_size = 20,则返回前20条;page = 2,page_size = 10,则返回第11条到第20条)
                4. 广告位枚举值变更说明由于多个接口都使用了广告位参数,为保证体验的一致性和参数的可读性,我们做了一些变更,所有接口均支持以 广告位类型名称(ad_slot) 传递参数,回包时新增这个名称来代表相关含义。此前的参数 slot_id 也可继续使用并回传。具体为:
                广告位类型名称(ad_slot)广告位类型
                SLOT_ID_BIZ_BOTTOM公众号底部广告
                SLOT_ID_BIZ_MID_CONTEXT公众号文中广告
                SLOT_ID_BIZ_VIDEO_END公众号视频后贴
                SLOT_ID_BIZ_SPONSOR公众号互选广告
                SLOT_ID_BIZ_CPS公众号返佣商品
                SLOT_ID_WEAPP_BANNER小程序banner
                SLOT_ID_WEAPP_REWARD_VIDEO小程序激励视频
                SLOT_ID_WEAPP_INTERSTITIAL小程序插屏广告
                SLOT_ID_WEAPP_VIDEO_FEEDS小程序视频广告
                SLOT_ID_WEAPP_VIDEO_BEGIN小程序视频前贴
                SLOT_ID_WEAPP_BOX小程序格子广告
                SLOT_ID_WEAPP_TEMPLATE小程序原生模板广告

                接口总览

                广告分析接口目前可用于获得“公众平台 → 流量主 → 数据统计”页面展示的部分广告数据和“公众平台 → 流量主 → 财务管理”页面展示的部分收入数据,与小程序相关的接口列表如下:

                接口名称用途最大时间跨度接口调用地址(必须使用https)
                publisher_adpos_general获取小程序广告汇总数据90天https://api.weixin.qq.com/publisher/stat?action=publisher_adpos_general&access_token=ACCESS_TOKEN
                publisher_adunit_general获取小程序广告细分数据90天https://api.weixin.qq.com/publisher/stat?action=publisher_adunit_general&access_token=ACCESS_TOKEN
                get_adunit_list获取小程序广告位清单https://api.weixin.qq.com/publisher/stat?action=get_adunit_list&access_token=ACCESS_TOKEN
                publisher_settlement获取小程序结算收入数据及结算主体信息https://api.weixin.qq.com/publisher/stat?action=publisher_settlement&access_token=ACCESS_TOKEN

                接口调用请求说明

                一、获取小程序广告汇总数据(publisher_adpos_general)

                需要向相应接口调用地址增加以下GET请求参数:

                参数是否必须说明
                page返回第几页数据
                page_size当页返回数据条数
                start_date获取数据的开始时间 yyyy-mm-dd
                end_date获取数据的结束时间 yyyy-mm-dd
                ad_slot广告位类型名称

                请注意: 如果不传递广告位类型名称,将默认返回全部类型广告位的数据。


                返回参数说明(publisher_adpos_general)

                参数说明
                err_msg返回错误信息
                ret错误码
                list: slot_id广告位类型id
                list: ad_slot广告位类型名称
                list: date日期
                list: req_succ_count拉取量
                list: exposure_count曝光量
                list: exposure_rate曝光率
                list: click_count点击量
                list: click_rate点击率
                list: income收入(分)
                list: ecpm广告千次曝光收益(分)
                summary: req_succ_count总拉取量
                summary: exposure_count总曝光量
                summary: exposure_rate总曝光率
                summary: click_count总点击量
                summary: click_rate总点击率
                summary: income总收入(分)
                summary: ecpm广告千次曝光收益(分)
                total_numlist返回总条数

                返回数据包示例(publisher_adpos_general)

                {    "base_resp":{        "err_msg":"ok",        "ret":0    },    "list":[        {            "slot_id":3030046789020061,            "ad_slot":"SLOT_ID_WEAPP_INTERSTITIAL",            "date":"2020-04-13",            "req_succ_count":443610,            "exposure_count":181814,            "exposure_rate":0.409850995,            "click_count":10095,            "click_rate":0.055523777,            "income":52175,            "ecpm":286.969100289        }    ],    "summary":{        "req_succ_count":4406394,        "exposure_count":1797225,        "exposure_rate":0.407867522,        "click_count":100167,        "click_rate":0.055734257,        "income":578003,        "ecpm":321.608591022    },    "total_num":1}

                二、获取小程序广告细分数据(publisher_adunit_general)

                需要向相应接口调用地址增加以下GET请求参数:

                参数是否必须说明
                page返回第几页数据
                page_size当页返回数据条数
                start_date获取数据的起始日期 yyyy-mm-dd
                end_date获取数据的结束时间 yyyy-mm-dd
                ad_slot广告位类型名称
                ad_unit_id广告位id

                请注意: 当需要获取全部广告位的细分数据时,无需传递广告位类型名称及广告位id;当需要获取某类型广告位的细分数据时,仅需传递广告位类型名称;当需要获取某广告位id的细分数据时,仅需传递广告位id。


                返回参数说明(publisher_adunit_general)

                参数说明
                err_msg返回错误信息
                ret错误码
                list: ad_unit_id广告位id
                list: ad_unit_name广告位名称
                list: stat_item: ad_slot广告位类型名称
                list: stat_item :date数据日期
                list: stat_item :req_succ_count拉取量
                list: stat_item :exposure_count曝光量
                list: stat_item: exposure_rate曝光率
                list: stat_item :click_count点击量
                list: stat_item :click_rate点击率
                list: stat_item :income收入
                list: stat_item :ecpm广告千次曝光收益(分)
                total_num请求返回总数

                返回数据包示例(publisher_adunit_general)

                {    "base_resp":{        "err_msg":"ok",        "ret":0    },    "list":[        {            "ad_unit_id":"adunit-9cedd8514XXXX",            "ad_unit_name":"激励视频长广告",            "stat_item":{                "ad_slot":"SLOT_ID_WEAPP_REWARD_VIDEO",                "date":"2020-04-10",                "req_succ_count":138250,                "exposure_count":74771,                "exposure_rate":0.54083906,                "click_count":2242,                "click_rate":0.029984887,                "income":93883,                "ecpm":6.790813743            }        }    ],    "total_num":1}

                三、获取小程序广告位清单(get_adunit_list)

                需要向相应接口调用地址增加以下GET请求参数:

                参数是否必须说明
                page返回第几页数据
                page_size当页返回数据条数
                ad_slot广告位类型名称
                ad_unit_id广告位id

                请注意: 当需要获取全部广告位的清单时,无需传递广告位类型名称及广告位id;当需要获取某类型广告位的清单时,仅需传递广告位类型名称;当需要获取某广告位id的数据时,仅需传递广告位id。


                返回参数说明(get_adunit_list)

                参数说明
                err_msg返回错误信息
                ret错误码
                ad_slot广告位类型名称
                ad_unit_id广告位ID
                ad_unit_name广告位名称
                ad_unit_size广告位尺寸
                ad_unit_status广告位状态

                返回数据包示例(get_adunit_list)

                {    "base_resp":{        "err_msg":"ok",        "ret":0    },    "ad_unit":[        {            "ad_slot":"SLOT_ID_WEAPP_REWARD_VIDEO",            "ad_unit_id":"adunit-e9418ee19XXXXX",            "ad_unit_name":"rewaXXXX",            "ad_unit_size":[                {                    "height":166,                    "width":582                }            ],            "ad_unit_status":"AD_UNIT_STATUS_ON",            "ad_unit_type":"AD_UNIT_TYPE_REWARED_VIDEO",            "appid":"wx0afc78670fXXXX",            "video_duration_max":30,            "video_duration_min":6        }    ],    "total_num":1}

                四、获取小程序结算收入数据及结算主体信息(publisher_settlement)

                需要向相应接口调用地址增加以下GET请求参数:

                参数是否必须说明
                page数据返回页数
                page_size每页返回数据条数
                start_date获取数据的开始时间 yyyy-mm-dd
                end_date获取数据的结束时间 yyyy-mm-dd

                请注意: 只要与获取数据的起止时间有重合,结算区间对应的数据都将返回。例如,请求2月11日至3月26日的数据,将会返回2月上半月、2月下半月、3月上半月、3月下半月四个结算区间的数据。


                返回参数说明(publisher_settlement)

                参数说明
                err_msg返回错误信息
                ret错误码
                body主体名称
                revenue_all累计收入
                penalty_all扣除金额
                settled_revenue_all已结算金额
                settlement_list: date数据更新时间
                settlement_list: zone日期区间
                settlement_list: month收入月份
                settlement_list: order1 = 上半月,2 = 下半月
                settlement_list: sett_status1 = 结算中;2、3 = 已结算;4 = 付款中;5 = 已付款
                settlement_list: settled_revenue区间内结算收入
                settlement_list: sett_no结算单编号
                settlement_list: mail_send_cnt申请补发结算单次数
                settlement_list: slot_revenue: slot_id产生收入的广告位
                settlement_list: slot_revenue: slot_settled_revenue该广告位结算金额
                total_num请求返回总条数

                返回数据包示例(publisher_settlement)

                {    "base_resp":{        "err_msg":"ok",        "ret":0    },    "body":"深圳市腾讯计算机系统有限公司",    "penalty_all":0,    "revenue_all":5178368698,    "settled_revenue_all":2613696765,    "settlement_list":[        {            "date":"2020-03-25",            "zone":"2020年3月1日至15日"            "month":"202003",            "order":1,            "sett_status":1,            "settled_revenue":718926045,            "sett_no":"XXX",            "mail_send_cnt":"0",            "slot_revenue":[                {                    "slot_id":"SLOT_ID_WEAPP_BANNER",                    "slot_settled_revenue":34139443                },                {                    "slot_id":"SLOT_ID_WEAPP_REWARD_VIDEO",                    "slot_settled_revenue":684786602                }            ]        }    ],    "total_num":1}

                错误码说明

                错误码返回值含义
                45009请求过于频繁, 请稍后尝试
                45010无效的接口名
                1701参数错误
                2009无效的流量主


                安全指引

                开发原则与注意事项

                本文档整理了部分小程序开发中常见的安全风险和漏洞,用于帮助开发者在开发环节中发现和修复相关漏洞,避免在上线后对业务和数据造成损失。开发者在开发环节中必须基于以下原则:

                1. 互不信任原则,不要信任用户提交的数据,包括第三方系统提供的数据,必要的数据校验必须放在后台校验。
                2. 最小权限原则,代码、模块等只拥有可以完成任务的最小权限,不赋予不必要的权限。
                3. 禁止明文保存用户敏感数据。
                4. 小程序代码(不包括云函数代码)跟传统 Web 应用的前端代码类似,可被外部获取及进行反混淆,重要业务逻辑应放在后台代码或云函数中进行。
                5. 后台接口调用以及云函数调用,必须进行有效的身份鉴权。


                  通用

                  接口鉴权

                  接口鉴权是指后台接口(包括自建后台接口与云函数)在被调用时需要对本次接口调用进行权限校验,否则容易发生越权行为。如商品删除接口,后台在收到请求时应当校验调用者的身份信息(如 openid、 ip 地址、开发者自定义的登录信息等),只有指定用户才可以通过校验进行删除。

                  越权通常分为平行越权和垂直越权:

                  • 平行越权 
                    平行越权是指相同角色之间的越权。 A1、 A2 都是普通用户, A1 通过请求后台接口 userinfo.php?id=A1 来获取用户 A1 自己的信息,如果 userinfo.php 没有进行权限校验,用户 A1 把请求改为 userinfo.php?id=A2 便可以获取到 A2 用户的信息,造成 A2 用户信息的泄露。
                  • 垂直越权 
                    垂直越权是指不同角色之间的越权。 B1 是管理员, B2 是普通用户,管理员 B1 通过请求后台接口 getalluserinfo.php 可以获取所有注册用户的信息,如果 getalluserinfo.php 没有进行权限校验, B2 用户也可以请求 getalluserinfo.php 来获取所有注册用户的信息,出现越权行为。

                  开发建议:

                  1. 敏感数据、能力相关接口需要在后台进行鉴权。通常可校验 openid、 IP 地址、自定义登陆态等信息。
                  2. 鉴权逻辑应放在后台进行,不应在小程序前端以隐藏页面、隐藏按钮等方式来代替。参照原则4。
                  3. 鉴权代码示例(仅供参考)
                    1. 自建后台鉴
                      function actionDelete(){    $item_id = $_POST["item_id"];     $openid = $_POST["openid"];    $ip = $_SERVER['REMOTE_ADDR'];    $user_role = $_SESSION["user_role"];    if ($openid === "xxx" &&        $ip === "192.168.0.101" &&        $user_role === "admin") {            // 进行删除操作            // ...            return 0;        } else {            // 记录非法请求            // ...            return -1;        }}
                    2. 云函数接口鉴权

                      exports.main = async (event, context) => {    const { OPENID, APPID, UNIONID } = cloud.getWXContext();    if (OPENID === "xxx") {        // 进行删除操作        // ...    } else {        // 记录非法请求        // ...    }}

                    代码管理与泄漏

                    1. 当使用 git、 svn 等版本管理工具时,会产生 .git 等目录。某些编辑器或软件也会在运行过程中生成临时文件。若这些目录或文件被带到生产环境,则可能发生源码泄漏。
                    2. 使用小程序代码管理平台或 github 等第三方平台时需要注意项目权限,不要公开敏感、内部项目。

                    开发建议:

                    1. 备份文件和版本管理工具产生的文件不要同步到 Web 目录下。
                    2. 禁止外部访问 .git 等目录与文件。
                    3. 小程序代码管理平台等管理平台内配置适当的访问权限。

                    小程序

                    信息泄露

                    敏感信息是指一旦泄露可能会对开发者的业务、合作伙伴和用户带来利益损害的数据,包括但不限于帐号 Appsecret、特权帐号信息、后台加密密钥、登录账户密码、用户身份证号、手机号、银行卡号等。

                    开发建议:

                    1. 敏感信息不应以明文、注释、可逆的编码方式(如 base64)、不安全散列函数(如 MD5、 SHA1)等形式出现在小程序文件内。
                    2. 部分敏感信息如用户的银行卡号、手机号等需要用于展示的,需要进行脱敏处理。常用脱敏规范如下: 
                      敏感信息类型展示样例
                      姓名名字只有两个字,对第一个字打码,如:*三。 多于两个字,只保留第一个和最后一个,其余都打码,如:王*四、欧**五
                      身份证只显示第一位和最后一位,如:3****************1
                      手机号除去手机国际码后,手机号位数不少于10位时,只显示前三位和最后两位,如:156******77。手机号位数少于10位时,只显示前两位和后两位,如:12*****89。国家码可以完全显示。
                      银行卡只显示最后4位,如:************1234
                    3. 如果小程序存在敏感信息泄露的问题,微信开放平台将有可能下架该小程序,并暂停该小程序的相关服务。


                    后台(包括云函数与自建后台)

                    注入漏洞

                    注入漏洞(SQL、 命令等)通常指用户绕过后台代码限制,直接在数据库、 shell 内执行自定义代码。

                    常见的注入漏洞有:

                    SQL 注入

                    SQL 注入是指 Web 程序代码中对于用户提交的参数未做有效过滤就直接拼接到 SQL 语句中执行,导致参数中的特殊字符打破了 SQL 语句原有逻辑,黑客可以利用该漏洞执行任意 SQL 语句。

                    开发建议:

                    1. 使用数据库提供的参数化查询来进行数据库操作,不允许直接通过拼接字符串的方式来合成 SQL 语句。
                    2. 如果存在部分情况需要通过拼接的方式来合成 SQL ,拼接的变量必须要经过处理:对于整数,需要判断变量是否为整数类型。对于字符串,需要对单引号、双引号等做转义处理。
                    3. 避免 Web 应用显示 SQL 的报错信息。
                    4. 保证 Web 应用里每一数据层的编码统一。

                    命令注入

                    命令注入漏洞是指 Web 应用未对用户可控参数进行有效过滤,攻击者可以构造恶意参数拼接到命令上来执行任意命令。

                    开发建议:

                    • 对用户输入的数据(如 ;、|、&等)进行过滤或转义。

                    弱口令

                    弱口令指管理后台的用户名密码设置得较为简单或者使用默认帐号。攻击者可以通过登录这些帐号修改后台数据或进行下一步的入侵操作。

                    开发建议:

                    1. 后台服务禁用默认帐号,修改后台弱口令。
                    2. 敏感服务增加二次验证机制,如短信验证码、邮箱验证码等。

                    文件上传漏洞

                    文件上传漏洞是指 Web 应用允许用户上传指定文件,但未对文件类型、格式等做合法性校验,导致可以上传非预期格式的文件。

                    开发建议:

                    • 正确解析上传文件的文件类型,通过白名单的方式限制可上传的文件类型。

                    文件下载

                    文件下载漏洞是指 Web 应用允许用户通过指定路径和文件名的方式来下载对应的文件,但未正确限制可下载文件所在的目录范围,导致预期范围外的文件被下载泄露。

                    开发建议:

                    1. 正确限制可下载文件所在的目录范围
                    2. 通过指定文件 id 的方式来查找下载对应的文件

                    目录遍历

                    目录遍历是指由后台服务对用户输入验证不足或配置不严谨导致的服务器目录内容泄漏。外部可能通过目录遍历获取系统文件、后台代码等敏感文件。

                    开发建议:

                    1. web 服务配置
                      1. 服务端禁止展示目录
                      2. 设置目录访问权限
                      3. 在每个目录下放置一个空的 index.html 页面
                    2. web 应用代码
                      1. 严格检查文件路径参数,限定文件的范围

                    条件竞争

                    条件竞争比较常见的例子是攻击者通过并发 https 请求而达到多次获奖、多次收获、多次获赠等非正常逻辑所能触发的效果。

                    • 漏洞代码示例 
                      // 从DB里查询该用户剩余获奖次数,初始值为1int remain_times = SelectRemainTimes();if(remain_times > 0){    EarnRewards();          // 用户获得奖励    ClearRemainTimes();     // 在DB里把该用户的剩余获奖次数清零}

                      开发者的设计本意是只允许用户获得一次奖励,但当出现并发请求时,有可能出现请求 A 和请求 B 都刚好执行完第2行代码的情况,此时两个请求的 remain_times 都为1,也就是可以通过第4行代码的判断,获得两次奖励。

                    开发建议:

                    • 对关键(完整)逻辑加锁操作或把关键逻辑以队列任务的形式去进行处理。


                    调试

                    vConsole

                    在真机上,如果想要查看 console API 输出的日志内容和额外的调试信息,需要在点击屏幕右上角的按钮打开的菜单里选择「打开调试」。此时小程序/小游戏会退出,重新打开后会右下角会出现一个 vConsole 按钮。点击 vConsole 按钮可以打开日志面板。

                    小程序和小游戏的 vConsole 展示内容会有一定差别,下图左边是小程序 vConsole,右边是小游戏 vConsole

                     

                    vConsole 使用说明

                    由于实现机制的限制,开发者调用 console API 打印的日志内容,是转换成 JSON 字符串后传输给 vConsole 的,导致 vConsole 中展示的内容会有一些限制:

                    • 除了 Number、String、Boolean、null 外,其他类型都会被作为 Object 处理展示,打印对象及原型链中的 Enumerable 属性。
                    • Infinity 和 NaN 会显示为 null。
                    • undefined、ArrayBuffer、Function 类型无法显示
                    • 无法打印存在循环引用的对象
                      let a = {}a.b = aconsole.log(a) // 2.3.2 以下版本,会打印 `An object width circular reference can't be logged`

                    针对上述问题,小程序/小游戏在使用 vConsole 时做了一些处理

                    • 2.3.2 及以上版本,支持打印循环引用对象。循环引用的对象属性会显示引用路径,@表示对象本身。
                      const circular = { x: {}, c: {} }circular.x = [{ promise: Promise.resolve() }]circular.a = circularcircular.c.x0 = circular.x[0]console.log(circular)// "{a: '<Circular: @>', c: {x0: '<Circular: @.x[0]>'}, x: [{promise: '<Promise>'}]}"
                    • 2.3.1 及以上版本,支持展示所有类型的数据。基础库会对日志内容进行一次转换,经过转换的内容会使用<>包裹。如:
                      • <Function: func>
                      • <Undefined>
                      • <Infinity>
                      • <Map: size=0>
                      • <ArrayBuffer: byteLength=10>
                      • ...
                    • 2.2.3 ~ 2.3.0 版本中,可以展示 ArrayBuffer 和 Function 类型,undefined 会被打印为字符串 'undefined'

                    注:尽量避免在非调试情景下打印结构过于复杂或内容过长的日志内容(如游戏引擎中的精灵或材质对象等),可能会带来额外耗时。为了防止异常发生,日志内容超过一定长度会被替换为<LOG_EXCEED_MAX_LENGTH>,此时需要开发者裁剪日志内容。

                    Source Map

                    目前只在 iOS 6.7.2 及以上版本支持

                    小程序/小游戏在打包时,会将所有 js 代码打包成一个文件,为了便于开发者在手机上调试时定位错误位置,小程序/小游戏提供了 Source Map 支持。

                    在开发者工具中开启 ES6 转 ES5、代码压缩时,会生成 Source Map 的 .map 文件。开发版小程序中,基础库会使用代码包中的 .map 文件,对 vConsole 中展示的错误信息堆栈进行重新映射(只对开发者代码文件进行)。

                    如果使用外部的编译脚本对源文件进行处理,只需将对应生成的 Source Map 文件放置在源文件的相同目录下

                    如:

                    pages/index.js
                    pages/index.js.map
                    app.js
                    app.js.map

                    开发者工具会读取、解析 Source Map 文件,并进行将其上传

                    后续可以在小程序后台的运营中心可以利用上传的 Source Map 文件进行错误分析

                    1. Source Map 文件不计入代码包大小计算。
                    2. 开发版代码包中由于包含了 .map 文件,实际代码包大小会比体验版和正式版大。

                    真机调试

                    真机远程调试功能可以实现直接利用开发者工具,通过网络连接,对手机上运行的小程序进行调试,帮助开发者更好的定位和查找在手机上出现的问题。


                    启动性能

                    小程序启动是小程序用户体验中极为重要的一环,启动耗时过长会造成小程序用户流失。

                    本章节的启动只包括小程序冷启动,不包括小程序后台切前台的热启动。

                    一、启动流程

                    在进行启动优化之前,先简单介绍以下小程序的启动过程。在小程序启动过程中,主要包括以下几个方面:

                    • 注 1:小程序启动的这些部分不是串行完成的,会尽可能的并行进行。
                    • 注 2:小程序启动各部分不是每次启动都完整进行的,会尽可能的利用缓存。

                    1. 资源准备

                    1.1 小程序相关信息准备

                    在用户访问小程序时,微信客户端需要从微信后台获取小程序的配置、版本、权限等相关信息,以对小程序进行必要的版本管理、权限控制和校验等。

                    对启动耗时的影响

                    信息的获取和更新会影响小程序的启动耗时,尤其体现在用户首次访问小程序时。

                    为了在尽量降低影响启动耗时的情况下保证信息的实时性,这些信息会在本地缓存,并通过一定的机制定期进行更新。

                    1.2 小程序运行环境准备

                    在执行小程序代码之前,微信客户端需要准备小程序运行的基础环境。

                    小程序的运行环境包括小程序进程、原生部分的 UI 元素(如 导航栏、tabBar等)、渲染页面使用的 WebView 容器、运行开发者 JS 代码的 JS 引擎、小程序基础库等等。

                    对启动耗时的影响

                    运行环境的准备耗时较长,对小程序的启动耗时有明显影响。

                    为了尽可能的降低运行环境准备对启动耗时的影响,微信客户端会根据用户的使用场景和设备资源的使用情况,提前对运行环境进行部分地预加载。但由于受到设备资源和操作系统调度的影响,目前很难保证每次小程序启动时都有预加载的环境。

                    1.3 小程序代码包准备

                    小程序启动时需要从服务器获取代码包地址、下载小程序代码包,并对代码包进行校验。根据小程序页面所在分包和使用的插件不同,一次启动可能需要下载多个代码包或插件包。

                    当小程序版本发生更新时,微信客户端还需要对代码包进行增量更新。

                    对启动耗时的影响

                    下载耗时是启动耗时中的重要瓶颈,与代码包或增量包的体积正相关。微信采用 ZSTD 算法对小程序代码包进行压缩,以尽可能降低下载过程中传输的数据量。

                    考虑到包大小对用户体验的影响,平台限制单个代码包的大小上限为 2M。代码包上限的增加对于开发者来说,能够实现更丰富的功能,但对于用户来说,也增加了下载流量和本地空间的占用。为了保证启动速度,开发者应该尽可能的控制代码包大小。

                    2. 开发者代码注入(逻辑层)

                    小程序启动时需要从代码包内读取小程序的配置和代码,并注入到 JS 引擎中。在主包代码注入过程中,会触发小程序的 App.onLaunch 和首次 App.onShow 生命周期。在开发者代码注入完成后,框架侧会根据用户访问的页面进行一些页面数据初始化工作,触发首页的 Page.onLoad, Page.onShow 事件。

                    对启动耗时的影响

                    开发者代码的注入耗时直接影响小程序的启动耗时。在主流的 JS 引擎中,代码注入耗时包括编译和执行等环节,代码量、同步接口调用和一些复杂的计算,都会影响注入耗时。

                    由于首页渲染需要使用逻辑层发送的数据,如果开发者代码注入耗时过长,也会延迟首页渲染开始的时间。

                    在部分平台上,微信客户端会使用 V8 引擎的 Code Caching 技术对代码编译结果进行缓存,降低二次注入时的编译耗时。

                    3. 开发者代码注入(渲染层)

                    开发者的 wxss 和 wxml 会经过编译注入到渲染层,包含页面渲染需要的页面结构和样式信息。渲染层的注入耗时主要和页面结构复杂度和使用的自定义组件数量有关。

                    渲染层和逻辑层的开发者代码注入是并行进行的。

                    对启动耗时的影响

                    由于首页渲染需要使用渲染层的页面结构和样式信息,如果开发者代码注入耗时过长,会延迟首页渲染开始的时间。

                    4. 首页(初次)渲染

                    在开发者代码注入完成后,结合逻辑层得到的数据和渲染层得到的页面结构和样式信息,小程序框架会进行小程序首页的渲染,展示小程序首屏,并触发首页的 Page.onReady 事件。Page.onReady 事件触发标志小程序启动过程完成。

                    对启动耗时的影响

                    首页渲染耗时主要受页面结构和参与渲染的数据量影响。

                    二、关键概念

                    在讨论小程序启动耗时时,需要明确几个概念:

                    1. 小程序首屏渲染完成

                    从开发者角度看,小程序首屏渲染完成的标志是首页 Page.onReady 事件触发。

                    从框架的角度来说,小程序的首屏的内容是基于小程序的初始数据,以及在渲染开始前到达的 setData 数据渲染的。

                    首屏渲染完成不表示小程序页面一定有完整内容,开发者触发的 setData(例如通过 wx.request 异步请求数据)不一定能参与到首屏渲染中。

                    由于框架和启动流程的差异,小程序定义的首屏渲染完成不等同于浏览器的 load 事件。

                    2. 小程序启动阶段

                    从用户点击访问小程序到小程序首屏渲染完成(首页 Page.onReady 事件触发)。

                    3. 打开率/到达率

                    小程序首屏渲染完成 PV 与 用户点击访问小程序 PV 的比值。流失率 = 1 - 打开率

                    三、启动性能优化

                    在启动流程中,小程序代码包准备、开发者代码注入和首页渲染是与开发者相关的,开发者可以进行一定的优化工作。其他部分目前开发者暂时无法干预,框架侧负责进行持续的优化。

                    1. 小程序代码包优化

                    代码包优化的核心手段是降低代码包大小,代码包大小直接影响了下载耗时,影响用户启动小程序时的体验。

                    开发者可以采取以下手段优化代码包大小:

                    1.1 分包加载

                    使用 分包加载 是优化小程序启动耗时效果最明显的手段。建议开发者按照功能划分,将小程序的功能按使用频率和场景拆分成分包,实现代码包的按需加载。

                    分包加载具有以下优势:

                    • 承载更多功能:小程序单个代码包的体积上限为 2M,使用分包可以提升小程序代码包总体积上限,承载更多的功能与服务。
                    • 降低代码包下载耗时:使用分包后可以显著启动时需要下载的代码包大小,在不影响功能正常使用的前提下明显提升启动耗时。
                    • 降低开发者代码注入耗时:小程序启动时会一次性注入全部的开发者代码,使用分包后可以降低注入的代码量,从而降低注入耗时。
                    • 降低页面渲染耗时

                    此外,结合分包加载的几个扩展功能,可以进一步优化启动耗时:

                    分包预下载

                    在使用「分包加载」后,虽然能够显著提升小程序的启动速度,但是当用户在使用小程序过程中跳转到分包内页面时,需要等待分包下载完成后才能进入页面,造成页面切换的延迟,影响小程序的使用体验。分包预下载便是为了解决首次进入分包页面时的延迟问题而设计的。

                    独立分包

                    但小程序中的某些场景(如广告页、活动页、支付页等),通常功能不是很复杂且相对独立,对启动性能有很高的要求。独立分包可以独立于主包和其他分包运行。从独立分包中页面进入小程序时,不需要下载主包。建议开发者将部分对启动性能要求很高的页面放到特殊的独立分包中。

                    独立分包和分包预下载可以配合使用,获得更好的效果,详情请参考独立分包与分包预下载教程

                    1.2 代码重构和优化

                    通过代码重构,降低代码冗余。在使用如 Webpack 等打包工具时,要尽量利用 tree-shaking 等特性去除冗余代码,也要注意防止打包时引入不需要的库和依赖。

                    1.3 控制代码包内图片等资源

                    避免在代码包中包含或在 WXSS 中使用 base64 内联过多、过大的图片,应尽量采用网络图片。代码包内的图片一般应只包含一些体积较小的图标。声音、视频等其他类型的资源应尽量避免放到代码包中。

                    小程序代码包在下载时会使用 ZSTD 算法进行压缩,降低下载时传输的数据量。这些资源文件会占用大量代码包体积,并且通常难以进一步被压缩,对于下载耗时的影响比代码文件大得多。

                    1.4 及时清理没有使用到的代码和资源

                    在日常开发的时候,我们可能引入了一些新的库文件,而过了一段时间后,由于各种原因又不再使用这个库了,我们常常会只是去掉了代码里的引用,而忘记删掉这类库文件了。

                    目前小程序打包是会将工程下所有文件都打入代码包内,也就是说,这些没有被实际使用到的库文件和资源也会被打入到代码包里,从而影响到整体代码包的大小。

                    2. 开发者代码注入优化

                    开发者代码注入的优化可以从优化执行耗时和优化代码量两部分着手。

                    2.1 减少启动过程的同步调用

                    在小程序启动流程中,会注入开发者代码并顺序同步执行 App.onLaunch, App.onShow, Page.onLoad, Page.onShow。在小程序初始化代码(Page,App 定义之外的内容)和启动相关的几个生命周期中,应避免执行复杂的计算逻辑或过度使用Sync结尾的同步API,如 wx.getStorageSync,wx.getSystemInfoSync 等。对于 getSystemInfo, getSystemInfoSync 的结果应进行缓存,避免重复调用。

                    2.2 使用懒注入

                    通常情况下,在小程序启动时,启动页面所在分包和主包(独立分包除外)的所有JS代码会全部合并注入,包括其他未访问的页面以及未用到自定义组件,造成很多没有使用的代码注入到小程序运行环境中,影响注入耗时和内存占用。

                    自基础库版本 2.11.1 起,小程序支持仅注入当前页面需要的自定义组件和当前页面代码,以降低小程序的启动时间和运行时内存。开发者可以在 app.json 中配置:

                    {  "lazyCodeLoading": "requiredComponents"}

                    注意:添加这项配置后,未使用到的代码文件将不被执行。

                    3. 页面渲染优化

                    3.1 提前首屏数据请求

                    大部分小程序在渲染首页时,需要依赖服务端的接口数据,小程序为开发者提供了提前发起数据请求的能力:

                    • 数据预拉取:能够在小程序冷启动的时候通过微信后台提前向第三方服务器拉取业务数据,当代码包加载完时可以更快地渲染页面,减少用户等待时间,从而提升小程序的打开速度。
                    • 周期性更新:在用户未打开小程序的情况下,也能从服务器提前拉取数据,当用户打开小程序时可以更快地渲染页面,减少用户等待时间。

                    3.2 骨架屏

                    在页面数据未准备好时(如需要通过网络获取),尽量避免展示空白页面,应先通过骨架屏展示页面的大致结构,请求数据返回后在进行页面更新。以提升用户的等待意愿。

                    3.3 缓存请求数据

                    小程序提供了wx.setStorage、wx.getStorage等读写本地缓存的能力,数据存储在本地,返回的会比网络请求快。如果开发者基于某些原因无法采用数据预拉取与周期性更新,我们推荐优先从缓存中获取数据来渲染视图,等待网络请求返回后进行更新。

                    3.4 精简首屏数据

                    我们推荐开发者延迟请求非关键渲染数据,与视图层渲染无关的数据尽量不要放在 data 中,加快页面渲染完成时间。

                    四、启动性能分析

                    1. 性能数据获取

                    1.1 小程序助手「性能分析」板块

                    小程序管理后台的性能数据还没有更新,正在规划改版中,建议在改版完成前开发者以小程序助手的性能数据为准。

                    建议开发者使用小程序助手中「性能分析」板块,持续关注小程序性能。性能分析从 启动性能、运行性能和网络性能 三个维度提供性能数据,供开发者根据平台、机型、网络环境和访问来源等条件做精细化分析。扫描下方小程序码即可立即体验。

                    目前,小程序助手中只包括微信客户端 >= 7.0.3 版本的正式版小程序数据。

                    1.2 通过 API 在小程序内获取

                    开发者可以在小程序中根据自身业务需有进行性能打点,也可以使用 wx.getPerformance ,获取当前小程序性能相关的信息。

                    在获取信息后,开发者可以自行上报或使用 wx.reportPerformance 进行测速。

                    1.3 体验评分

                    小程序工具中提供了体验评分工具,方便开发者能够及时发现小程序的体验问题。

                    2. 影响启动性能的因素

                    根据「启动流程」一节介绍的启动流程来看,影响小程序启动耗时的因素众多,分析小程序启动性能是一个比较复杂的过程。

                    对于同一个小程序,以下因素会直接影响平均启动耗时:

                    • 平台: 不同平台下(安卓、iOS、PC等)设备性能、操作系统、框架实现、优化方案存在较大差异,启动耗时也存在较大的差异。只有分平台比较启动耗时(包括各阶段的耗时)才有意义。
                    • 下载比例:代码包下载和更新都会显著影响小程序启动耗时,在其他流程耗时稳定的情况下,下载比例升高会影响大盘启动耗时。
                    • 入口页面:不同页面启动时,根据所在分包的不同,需要下载的代码包数量和大小和代码注入量都存在差异。不同页面渲染耗时也存在差异。
                    • 机型分布:启动耗时和设备性能有较强关联,不同小程序或使用场景用户群体的差异可能导致机型分布的差异,进而影响大盘启动耗时。
                    • 网络环境:网络环境主要影响网络请求的耗时,如小程序信息获取、代码包下载等。

                    此外,下列情况也会间接影响启动耗时:

                    • 场景/访问来源:不同场景用户访问的页面不同,访问的目的性和自身的等待意愿也有差异,对启动耗时和打开率都有一定影响。
                    • 首次访问用户比例:用户首次访问小程序时,需要完整的进行小程序信息准备、代码包下载的流程、代码缓存也需要重新生成,启动耗时会比非首次访问高。
                    • 小程序版本更新:小程序版本更新时,用户需要更新小程序信息和代码包,代码缓存也需要重新生成,启动耗时会出现上涨。

                    关于「性能分析」板块数据

                    小程序助手中提供了启动过程中和开发者相关的下载耗时、js注入耗时和初次渲染耗时供开发者优化参考。

                    这里需要注意的是,启动总耗时 ≠ 下载耗时 + js 注入耗时 + 初次渲染耗时。在启动过程中,下载不一定发生,也不一定只下载一个代码包。js 注入耗时和渲染耗时也会受缓存更新而发生波动。

                    各阶段耗时的下降不一定反应在总耗时的下降。例如小程序新版本发布后,即使各阶段耗时都下降,下载比例的升高反而可能导致总耗时的上升。

                    3. 影响打开率的因素

                    启动性能用户的等待意愿是影响打开率的两个关键因素。在部分场景下,如果用户等待意愿较低,即使启动耗时很低,也不一定能获得较高的打开率。


                    运行时性能

                    setData

                    setData 是小程序开发中使用最频繁的接口,也是最容易引发性能问题的接口。在介绍常见的错误用法前,先简单介绍一下 setData 背后的工作原理。

                    工作原理

                    小程序的视图层目前使用 WebView 作为渲染载体,而逻辑层是由独立的 JavascriptCore 作为运行环境。在架构上,WebView 和 JavascriptCore 都是独立的模块,并不具备数据直接共享的通道。当前,视图层和逻辑层的数据传输,实际上通过两边提供的 evaluateJavascript 所实现。即用户传输的数据,需要将其转换为字符串形式传递,同时把转换后的数据内容拼接成一份 JS 脚本,再通过执行 JS 脚本的形式传递到两边独立环境。

                    而 evaluateJavascript 的执行会受很多方面的影响,数据到达视图层并不是实时的。

                    常见的 setData 操作错误

                    1. 频繁的去 setData

                    在我们分析过的一些案例里,部分小程序会非常频繁(毫秒级)的去setData,其导致了两个后果:

                    • Android 下用户在滑动时会感觉到卡顿,操作反馈延迟严重,因为 JS 线程一直在编译执行渲染,未能及时将用户操作事件传递到逻辑层,逻辑层亦无法及时将操作处理结果及时传递到视图层;
                    • 渲染有出现延时,由于 WebView 的 JS 线程一直处于忙碌状态,逻辑层到页面层的通信耗时上升,视图层收到的数据消息时距离发出时间已经过去了几百毫秒,渲染的结果并不实时;

                    2. 每次 setData 都传递大量新数据

                    由setData的底层实现可知,我们的数据传输实际是一次 evaluateJavascript 脚本过程,当数据量过大时会增加脚本的编译执行时间,占用 WebView JS 线程,

                    3. 后台态页面进行 setData

                    当页面进入后台态(用户不可见),不应该继续去进行setData,后台态页面的渲染用户是无法感受的,另外后台态页面去setData也会抢占前台页面的执行。

                    图片资源

                    目前图片资源的主要性能问题在于大图片和长列表图片上,这两种情况都有可能导致 iOS 客户端内存占用上升,从而触发系统回收小程序页面。

                    图片对内存的影响

                    在 iOS 上,小程序的页面是由多个 WKWebView 组成的,在系统内存紧张时,会回收掉一部分 WKWebView。从过去我们分析的案例来看,大图片和长列表图片的使用会引起 WKWebView 的回收。

                    图片对页面切换的影响

                    除了内存问题外,大图片也会造成页面切换的卡顿。我们分析过的案例中,有一部分小程序会在页面中引用大图片,在页面后退切换中会出现掉帧卡顿的情况。

                    当前我们建议开发者尽量减少使用大图片资源。


                    性能 Trace 工具

                    微信 Andoid 6.5.10 开始,我们提供了 Trace 导出工具,开发者可以在开发者工具 Trace Panel 中使用该功能。

                    使用方法

                    1. PC 上需要先安装 adb 工具,可以参考一些主流教程进行安装,Mac 上可使用 brew 直接安装。
                    2. 确定 adb 工具已成功安装后,在开发者工具上打开 Trace Panel,将 Android 手机通过 USB 连接上 PC,点击「Choose Devices」,此时手机上可能弹出连接授权框,请点击「允许」。
                    3. 选择设备后,在手机上打开你需要调试的开发版小程序,通过右上角菜单,打开性能监控面板,重启小程序;
                    4. 重启后,在小程序上进行操作,完成操作后,通过右上角菜单,导出 Trace 数据;
                    5. 此时开发者工具 Trace Panel 上会自动拉取 Trace 文件,选择你要分析的 Trace 文件即可;
                    可以通过 adb devices 命令确定设备是否已和 PC 建立起连接

                    image

                    性能面板

                    从微信 6.5.8 开始,我们提供了性能面板让开发者了解小程序的性能。开发者可以在开发版小程序下打开性能面板,打开方法:进入开发版小程序,进入右上角更多按钮,点击「显示性能窗口」。

                    image

                    性能面板指标说明

                    指标说明
                    CPU小程序进程的 CPU 占用率,仅 Android 下提供
                    内存小程序进程的内存占用(Total Pss),仅 Android 下提供
                    启动耗时小程序启动总耗时
                    下载耗时小程序包下载耗时,首次打开或资源包需更新时会进行下载
                    页面切换耗时小程序页面切换的耗时
                    帧率/FPS
                    首次渲染耗时页面首次渲染的耗时
                    再次渲染耗时页面再次渲染的耗时(通常由开发者的 setData 操作触发)
                    数据缓存小程序通过 Storage 接口储存的缓存大小


                    体验评分是一项给小程序的体验好坏打分的功能,它会在小程序运行过程中实时检查,分析出一些可能导致体验不好的地方,并且定位出哪里有问题,以及给出一些优化建议。

                    运行环境要求

                    • 下载并安装 1.02.1808300 或以上版本的开发者工具,下载地址
                    • 基础库需要切到 2.2.0 或以上版本。

                    使用流程

                    1. 打开开发者工具,在详情里切换基础库到 2.2.0 或以上版本。
                    2. 在调试器区域切换到 Audits 面板。
                    3. 点击”开始“按钮,然后自行操作小程序界面,运行过的页面就会被“体验评分”检测到。

                    start

                    1. 点击 “停止" 则结束检测,在当前面板显示相应的检测报告,开发者可根据报告中的建议对相应功能进行优化。
                    2. 如需再次运行体验评分,可点击报告上方的“清空体验评分”恢复初始状态。请注意,目前系统不提供报告存储服务,一旦清空体验评分,将无法再查看本次评分结果。

                    start

                    自动运行

                    为了方便开发者能够及时发现小程序的体验问题,从开发者工具 1.02.1811150 版本起支持体验评分的 “自动运行” 功能。

                    该功能会在开发调试小程序时,实时检查,一旦发现体验分数低于 70 分时,系统会在 console 面板打印一个 warning 信息提示开发者,此时开发者可以切到 Audits 面板查看详情。

                    开发者在工具的右上角 “详情” 面板的 本地设置 中勾选 “自动运行体验评分” 选项即可开启。

                    autorun

                    评分规则

                    具体的评分细则和详情的规则说明可参考下列文档:

                    1、评分方法


                    目前体验评分共有27条规则,共分为三类:性能、体验、最佳实践,满足规则要求得分(100分),否则不得分(0分),最后根据各规则权重和公式计算出总得分。

                    权重为0的规则,表示该规则不参与评分,仅作为提示项。开发者可在开发者工具中可以点击“忽略”。各规则的得分条件也可能会随小程序的版本更新有一定的调整。

                    权重如下表

                    分类规则权重
                    性能脚本执行时间7
                    首屏时间6
                    渲染时间6
                    setData调用频率6
                    setData数据大小6
                    WXML节点数6
                    请求耗时5
                    网络请求数5
                    图片请求数5
                    图片缓存4
                    图片大小4
                    网络请求缓存2
                    体验开启惯性滚动8
                    避免使用:active伪类来实现点击态8
                    保持图片大小比例4
                    可点击元素的响应区域3
                    iPhone X兼容3
                    合理的颜色搭配0
                    最佳实践避免JS异常3
                    避免网络请求异常3
                    废弃接口2
                    使用HTTPS1
                    避免setData数据冗余1
                    最低基础库版本0
                    移除不可访问到的页面0
                    WXSS使用率0
                    及时回收定时器0


                    2、性能


                    1. 首屏时间

                    首屏时间是指用户从打开小程序看到第一屏主要内容的时间,首屏时间太长会导致用户长时间看到的都是白屏,影响使用体验。

                    优化首屏时间,可以分为以下几种情况:

                    1. 首屏渲染的内容较多,需要集合多份数据进行渲染。这种情况需要开发者把内容分优先级,把优先级高的内容做优先展示,缩短白屏时间;
                    2. 首屏内容依赖的数据从服务端请求的时间太长。开发者需要从服务端侧具体分析服务端数据返回的时间长的原因;
                    3. 一次性渲染数据太大或依赖的计算过于复杂。减少渲染的数据量、优化渲染相关数据的算法可以解决这类问题。

                    得分条件:首屏时间不超过 5 秒

                    2. 渲染时间

                    渲染时间指的是首次渲染或因数据变化带来的页面结构变化的渲染花费的时间。

                    渲染界面的耗时过长会让用户觉得卡顿,体验较差,出现这一情况时,需要校验下是否同时渲染的区域太大(例如列表过长),或渲染依赖的计算是否过于复杂。

                    得分条件:渲染时间不超过 500ms

                    3. 脚本执行时间

                    脚本执行时间是指JS脚本在一次同步执行中消耗的时间,比如生命周期回调、事件处理函数的同步执行时间。

                    执行脚本的耗时过长会让用户觉得卡顿,体验较差,出现这一情况时,需要确认并优化脚本的逻辑

                    得分条件:一个执行周期内脚本运行时间不超过 1 秒

                    4. setData调用频率

                    setData接口的调用涉及逻辑层与渲染层间的线程通信,通信过于频繁可能导致处理队列阻塞,界面渲染不及时而导致卡顿,应避免无用的频繁调用。

                    得分条件:每秒调用setData的次数不超过 20 次

                    5. setData数据大小

                    由于小程序运行逻辑线程与渲染线程之上,setData的调用会把数据从逻辑层传到渲染层,数据太大会增加通信时间。

                    得分条件:setData的数据在JSON.stringify后不超过 256KB

                    6. WXML节点数

                    建议一个页面使用少于 1000 个 WXML 节点,节点树深度少于 30 层,子节点数不大于 60 个。一个太大的 WXML 节点树会增加内存的使用,样式重排时间也会更长,影响体验。

                    得分条件:页面WXML节点少于 1000 个,节点树深度少于 30 层,子节点数不大于 60 个

                    7. 图片缓存

                    开启 HTTP 缓存控制后,下一次加载同样的图片,会直接从缓存读取,大大提升加载速度。

                    得分条件:所有图片均开启 HTTP 缓存

                    8. 图片大小

                    图片太大会增加下载时间和内存的消耗,应根据显示区域大小合理控制图片大小。

                    得分条件:图片宽高乘积 <= 实际显示宽高乘积 * (设备像素比 ^ 2)

                    9. 请求耗时

                    请求的耗时太长会让用户一直等待甚至离开,应当优化好服务器处理时间、减小回包大小,让请求快速响应。

                    得分条件:所有网络请求都在 1 秒内返回结果

                    10. 网络请求数

                    短时间内发起太多请求会触发小程序并行请求数量的限制,同时太多请求也可能导致加载慢等问题,应合理控制请求数量,甚至做请求的合并等。

                    得分条件:通过wx.request发起的耗时超过 300ms 的请求并发数不超过 10 个

                    11. 图片请求数

                    短时间内发起太多图片请求会触发浏览器并行加载的限制,可能导致图片加载慢,用户一直处理等待。应该合理控制数量,可考虑使用雪碧图技术或在屏幕外的图片使用懒加载。

                    得分条件:同域名耗时超过 100ms 的图片请求并发数不超过 20 个

                    12. 网络请求缓存

                    发起网络请求总会让用户等待,可能造成不好的体验,应尽量避免多余的请求,比如对同样的请求进行缓存

                    得分条件:3 分钟以内同一个url请求不出现两次回包大于 128KB 且一模一样的内容


                    3、体验


                    1. 开启惯性滚动

                    惯性滚动会使滚动比较顺畅,在安卓下默认有惯性滚动,而在 iOS 下需要额外设置-webkit-overflow-scrolling: touch的样式;

                    得分条件:wxss中带有overflow: scroll的元素,在 iOS 下需要设置-webkit-overflow-scrolling: touch样式

                    2. 避免使用:active伪类来实现点击态

                    使用 css :active伪类来实现点击态,很容易触发,并且滚动或滑动时点击态不会消失,体验较差。建议使用小程序内置组件的 'hover-class' 属性来实现

                    得分条件:不使用:active伪类,并使用hover-class替换:active

                    3. 保持图片大小比例

                    图片若没有按原图宽高比例显示,可能导致图片歪曲,不美观,甚至导致用户识别困难。可根据情况设置 image 组件的 mode 属性,以保持原图宽高比。

                    得分条件:显示的高/宽与原图的高/宽不超过 15%

                    4. 可点击元素的响应区域

                    我们应该合理地设置好可点击元素的响应区域大小,如果过小会导致用户很难点中,体验很差。

                    得分条件:可点击元素的宽高都不小于 20px

                    5. iPhone X 兼容

                    对于position: fixed的可交互组件,如果渲染在iPhone X的安全区域外,容易误触 Home Indicator,应当把可交互的部分都渲染到安全区域内。

                    建议使用以下wxss进行兼容

                    padding-bottom: constant(safe-area-inset-bottom);padding-bottom: env(safe-area-inset-bottom);

                    得分条件:position: fixed且高度小于 68px 的可交互组件渲染在安全区域内

                    6. 合理的颜色搭配

                    文字颜色与背景色需要搭配得当,适宜的颜色对比度可以让用户更好地阅读,提升小程序的用户体验。

                    由于颜色搭配的计算方法较为复杂,目前算法还在不断优化中。因此该指标仅作为评分的提醒项,不计入总分中。

                    判断标准:

                    1. 对于较大字体(font-size >= 24px,或同时满足font-size >= 19px与font-weight >= 700),文字颜色和背景颜色的对比度不小于3

                    2. 其他字体,文字颜色和背景颜色的对比度不小于4.5

                    对比度计算方法参考W3C标准


                    4、最佳实践


                    1. 避免JS异常

                    出现 JavaScript 异常可能导致程序的交互无法进行下去,我们应当追求零异常,保证程序的高鲁棒性和高可用性。

                    得分条件:不出现任何JS异常

                    2. 避免网络请求异常

                    请求失败可能导致程序的交互无法进行下去,应当保证所有请求都能成功。

                    得分条件:所有已授权网络请求都正常返回,未授权网络请求需要给出 401 或 403 这两种状态码

                    3. 不使用废弃接口

                    使用即将废弃或已废弃接口,可能导致小程序运行不正常。一般而言,接口不会立即去掉,但保险起见,建议不要使用,避免后续小程序突然运行异常。

                    得分条件:不使用任何文档中提示废弃的接口

                    4. 使用HTTPS

                    使用HTTPS,可以让你的小程序更加安全,而HTTP是明文传输的,存在可能被篡改内容的风险

                    得分条件:所有网络请求都使用HTTPS

                    5. 避免setData数据冗余

                    setData操作会引起框架处理一些渲染界面相关的工作,一个未绑定的变量意味着与界面渲染无关,传入setData会造成不必要的性能消耗。

                    得分条件:setData传入的所有数据都在模板渲染中有相关依赖

                    6. 最低基础库版本

                    当使用的组件/API 的支持版本大于配置的线上最低基础库版本时,可能导致相应功能不可用。开发者可通过调整最低基础库版本或在代码上兼容的方式解决该问题。

                    由于用户可以通过代码兼容的方式解决该问题,因此该指标仅作为评分的提醒项,不计入总分中。

                    判断标准:不存在使用的组件/API 的支持版本大于配置的线上最低基础库版本

                    7. 移除不可访问到的页面

                    小程序的包大小会影响加载时间,应该尽量控制包体积大小,避免将不会被使用的文件打包进去。

                    由于该项指标依赖开发者的操作路径,因此仅作为评分的提醒项,不计入总分中。

                    判断标准:不存在访问不到的页面被打包到小程序中

                    8. WXSS使用率

                    我们应该按需引入 wxss 资源,如果小程序中存在大量未使用的样式,会增加小程序包体积大小,从而在一定程度上影响加载速度。

                    由于该项指标依赖开发者的操作路径,因此仅作为评分的提醒项,不计入总分中。

                    判断标准:每个 wxss 资源的未使用部分不超过 2KB

                    9. 及时回收定时器

                    定时器是全局的,并不是跟页面绑定的,当小程序从一个页面路由到另一个页面之后,前一个页面定时器应注意手动回收。

                    由于该项指标依赖开发者的操作路径,因此仅作为评分的提醒项,不计入总分中。

                    判断标准:所有定时器的回调执行时所在的页面都与设置定时器的页面一致


                    基础库版本分布

                    更新时间:2020 年 7 月 29 日

                    占比低于 0.01% 的版本已隐藏,占比低于 1% 的版本以灰色显示。灰度发布中的版本也会显示。

                    基础库版本安卓版本安卓用户占比iOS版本iOS用户占比总体占比
                    2.12.07.0.1587.76%7.0.1382.81%86.60%
                    2.11.3-0.06%-0.02%0.05%
                    2.11.27.0.133.54%7.0.126.51%4.24%
                    2.11.0-0.16%--0.12%
                    2.10.47.0.95.69%7.0.95.21%5.58%
                    2.10.3-0.01%--0.01%
                    2.9.57.0.70.62%7.0.71.98%0.94%
                    2.9.3-0.02%--0.01%
                    2.8.37.0.50.84%7.0.50.87%0.84%
                    2.7.77.0.40.42%7.0.40.69%0.49%
                    2.6.67.0.30.48%7.0.30.78%0.55%
                    2.5.27.0.00.14%7.0.00.29%0.17%
                    2.4.46.7.30.13%6.7.30.45%0.20%
                    2.3.26.7.20.02%6.7.20.10%0.04%
                    2.2.56.6.70.05%6.7.00.10%0.06%
                    2.1.3--6.6.70.04%0.01%
                    2.0.96.6.60.02%6.6.60.06%0.03%
                    1.9.976.6.20.02%6.6.20.04%0.03%
                    1.9.96.6.10.01%6.6.10.02%0.01


                    兼容

                    小程序的功能不断的增加,但是旧版本的微信客户端并不支持新功能,所以在使用这些新能力的时候需要做兼容。

                    开发者可以通过以下方式进行低版本的兼容:

                    1. 版本号比较

                    微信客户端和小程序基础库的版本号风格为 Major.Minor.Patch(主版本号.次版本号.修订版本号)。

                    文档中会在组件,API等页面描述中带上各个功能所要求的最低基础库版本号。

                    开发者可以在小程序中通过调用 wx.getSystemInfo 或者 wx.getSystemInfoSync 获取到当前小程序运行的基础库的版本号。通过版本号比较的方式进行运行低版本兼容逻辑。

                    版本号比较适用于所有情况。部分场景下也可以使用后面提到的方法完成。

                    注意:不要直接使用字符串比较的方法进行版本号比较。

                    版本号比较可以参考以下代码:

                    function compareVersion(v1, v2) {  v1 = v1.split('.')  v2 = v2.split('.')  const len = Math.max(v1.length, v2.length)  while (v1.length < len) {    v1.push('0')  }  while (v2.length < len) {    v2.push('0')  }  for (let i = 0; i < len; i++) {    const num1 = parseInt(v1[i])    const num2 = parseInt(v2[i])    if (num1 > num2) {      return 1    } else if (num1 < num2) {      return -1    }  }  return 0}compareVersion('1.11.0', '1.9.9') // 1
                    const version = wx.getSystemInfoSync().SDKVersionif (compareVersion(version, '1.1.0') >= 0) {  wx.openBluetoothAdapter()} else {  // 如果希望用户在最新版本的客户端上体验您的小程序,可以这样子提示  wx.showModal({    title: '提示',    content: '当前微信版本过低,无法使用该功能,请升级到最新微信版本后重试。'  })}

                    2. API 存在判断

                    对于新增的 API,可以通过判断该API是否存在来判断是否支持用户使用的基础库版本。例如:

                    if (wx.openBluetoothAdapter) {  wx.openBluetoothAdapter()} else {  // 如果希望用户在最新版本的客户端上体验您的小程序,可以这样子提示  wx.showModal({    title: '提示',    content: '当前微信版本过低,无法使用该功能,请升级到最新微信版本后重试。'  })}

                    3. wx.canIUse

                    除了直接通过版本号判断,也可以通过 wx.canIUse 来判断是否可以在该基础库版本下直接使用。例如:

                    API 参数或返回值

                    对于 API 的参数或者返回值有新增的参数,可以判断用以下代码判断。

                    wx.showModal({  success: function(res) {    if (wx.canIUse('showModal.success.cancel')) {      console.log(res.cancel)    }  }})

                    组件

                    对于组件,新增的组件或属性在旧版本上不会被处理,不过也不会报错。如果特殊场景需要对旧版本做一些降级处理,可以这样子做。

                    Page({  data: {    canIUse: wx.canIUse('cover-view')  }})
                    <video controls="{{!canIUse}}">  <cover-view wx:if="{{canIUse}}">play</cover-view></video>
                    canIUse 的数据文件随基础库进行更新,新版本中的新功能可能出现遗漏的情况,建议开发者在使用时提前测试。

                    设置最低基础库版本

                    需要 iOS 6.5.8 / 安卓 6.5.7 及以上版本微信客户端支持

                    为便于开发者解决低版本基础库无法兼容小程序的新功能的问题,开发者可设置小程序最低基础库版本要求。

                    开发者可以登录小程序管理后台,进入「设置 - 基本设置 - 基础库最低版本设置」进行配置。在配置前,开发者可查看近 30 天内访问当前小程序的用户所使用的基础库版本占比,以帮助开发者了解当前用户使用的情况。

                    设置后,若用户基础库版本低于设置值,则无法正常打开小程序,并提示用户更新客户端版本。


                    实时日志

                    背景

                    为帮助小程序开发者快捷地排查小程序漏洞、定位问题,我们推出了实时日志功能。从基础库2.7.1开始,开发者可通过提供的接口打印日志,日志汇聚并实时上报到小程序后台。开发者可从小程序管理后台“开发->运维中心->实时日志”进入日志查询页面,查看开发者打印的日志信息。

                    如何使用

                    1、调用相关接口。打日志的接口是wx.getRealtimeLogManager,为了兼容旧的版本,建议使用如下代码封装一下,例如封装在log.js文件里面:

                    var log = wx.getRealtimeLogManager ? wx.getRealtimeLogManager() : nullmodule.exports = {  info() {    if (!log) return    log.info.apply(log, arguments)  },  warn() {    if (!log) return    log.warn.apply(log, arguments)  },  error() {    if (!log) return    log.error.apply(log, arguments)  },  setFilterMsg(msg) { // 从基础库2.7.3开始支持    if (!log || !log.setFilterMsg) return    if (typeof msg !== 'string') return    log.setFilterMsg(msg)  },  addFilterMsg(msg) { // 从基础库2.8.1开始支持    if (!log || !log.addFilterMsg) return    if (typeof msg !== 'string') return    log.addFilterMsg(msg)  }}

                    2、在页面的具体位置打印日志:

                    var log = require('./log.js') // 引用上面的log.js文件log.info('hello test hahaha') // 日志会和当前打开的页面关联,建议在页面的onHide、onShow等生命周期里面打log.warn('warn')log.error('error')log.setFilterMsg('filterkeyword')log.setFilterMsg('addfilterkeyword')

                    完整的例子可以参考代码片段:https://developers.weixin.qq.com/s/i42NbKmp76bJ

                    如何查看日志

                    登录小程序管理后台,从“开发->运维中心->实时日志”进入日志查询页面。开发者可通过设置时间、微信号/OpenID、页面链接、FilterMsg内容(基础库2.7.3及以上支持setFilterMsg)等筛选条件查询指定用户的日志信息。

                    ./log.png

                    注意事项

                    由于后台资源限制,“实时日志”使用规则如下:

                    1. 为了定位问题方便,日志是按页面划分的,某一个页面,在onShow到onHide(切换到其它页面、右上角圆点退到后台)之间打的日志,会聚合成一条日志上报,并且在小程序管理后台上可以根据页面路径搜索出该条日志
                    2. 每个小程序账号每天限制500万条日志,日志会保留7天,建议遇到问题及时定位。
                    3. 一条日志的上限是5KB,最多包含200次打印日志函数调用(info、warn、error调用都算),所以要谨慎打日志,避免在循环里面调用打日志接口,避免直接重写console.log的方式打日志。
                    4. 意见反馈里面的日志,可根据OpenID搜索日志。
                    5. setFilterMsg可以设置过滤的Msg。这个接口的目的是提供某个场景的过滤能力,例如 setFilterMsg('scene1'),则在MP上可输入scene1查询得到该条日志。比如上线过程中,某个监控有问题,可以根据FilterMsg过滤这个场景下的具体的用户日志。FilterMsg仅支持大小写字母。如果需要添加多个关键字,建议使用addFilterMsg替代setFilterMsg。

                    filtermsg  

                    小程序测速

                    为帮助开发者优化小程序性能,我们推出了"小程序测速"功能。"小程序测速"可以简单方便地统计小程序内某一事件的实时耗时情况,并可根据地域、运营商、操作系统、网络类型、机型等关键维度进行实时交叉分析。从基础库2.9.2开始,开发者通过“测速上报”接口上报某一指标的耗时情况后,可在小程序管理后台"开发 -运维中心 -小程序测速" 查看各指标耗时趋势,并支持分钟级数据实时查看。

                    新建监控 ID

                    为了实现对某一指标的耗时监控,开发者需要先定义监控指标。在小程序管理后台 :"开发 -运维中心 -小程序测速"中新建监控 ID,并填写监控指标的名称和解释。

                    img

                    点击"新建"可以新建 ID ,你需要选择指标类型,并填写指标名称和指标对应的解释。 监控指标分为两类:

                    网络请求类: 此类耗时主要受网络环境影响,包含操作系统、运营商、网络环境、地区等统计维度。如:网络 api 耗时、云调用耗时、网络数据读写耗时等。注意此类指标最多可创建20个。

                    加载/渲染类:此类耗时主要受设备性能影响,包含操作系统、机型类别等统计维度。可以用来测量页面切换耗时、组件渲染耗时等。 注意此类指标最多可创建20个。

                    img

                    新建后,可以看到上报需要使用的监控 ID 。

                    img

                    测速上报

                    开发者定义监控ID后,需要在小程序代码中调用 wx.reportPerformance 接口上报耗时数值,才可实现耗时监控:

                    上报方法1: 使用 canIUse 进行判断

                    // * 需要使用 canIUse 判断接口是否可用if (wx.canIUse('reportPerformance')) {  wx.reportPerformance(id, val)}

                    上报方法2:使用 compareVersion 进行判断

                    // * 需要先使用 compareVersion 判断接口是否可用const sdkVersion = wx.getSystemInfoSync().SDKVersionif (compareVersion(sdkVersion, '2.9.2') >= 0) {  wx.reportPerformance(id, val)}

                    ​id 和 val 均为 uint32 类型,其中 id 为小程序管理后台定义的监控 ID,val 为本次要上报的耗时数值(由开发者自行计算)。接口调用需要基础库的版本号高于 2.9.2,否则在一些低版本基础库可能报错。

                    (compareVersion 定义)

                    数据观察

                    完成代码上报后,可在小程序管理后台"开发 -运维中心 -小程序测速" 查看各指标耗时趋势。目前线上数据约有15分钟数据时延,上报数据保留 7 天,可按照 1 分钟 - 1 小时等不同的时间粒度进行聚合。

                    每个指标可以观察到两条曲线,分别为平均值曲线和上报次数曲线。

                    ​ img

                    ​同时对于不同维度的数据,我们提供了交叉对比功能,以帮助大家快速便捷的完成分析,注意交叉对比的曲线数最多不能超过10条。 img

                    ​对于网络请求类指标,我们提供了区域地图,以帮助大家快速的定位区域资源问题。 img

                    自定义维度(可选功能)

                    对于更复杂的用户场景,用户可能需要将测速数据根据url、页面等维度进行细分,所以我们提供了自定义维度,用户可以将一些业务层面的维度字符串填入至自定义维度中,以方便业务分析。 目前每个指标的自定义纬度值的数量需要限制在50以内(超限制的数据会被丢弃),自定义维度值的长度需要限制在256字节内(超限制的值会被截断)。自定义维度的使用效果如下: img想要使用自定义维度,只需要给wx.reportPerformance加上第三个参数dimensions,即可上报自定义维度:

                    wx.reportPerformance(id, value, dimensions)

                    (wx.reportPerformance 文档)

                    Q&A

                    Q : 测速系统可以在哪些场景发挥作用?

                    A : 可以测量网络类指标(如网络调用/云调用耗时、网络数据读写速度等)和非网络类指标(页面切换加载速度、组件渲染速度等)。可以查看这些指标在不同维度下的数量分布和性能差异。在一些计算视频首屏时延、帧率等场景也可以发挥作用。

                    Q :上报API需要的基础库版本是多少?

                    A : 需要基础库版本 2.9.2 以上。在一些低版本基础库上可能报错,后续会支持用 canIUse 接口来进行判断。

                    Q: 系统是否可以再测试版使用?上报的时延大概是多少?数据保存的时间是多久?

                    A : 可以在测试版使用,目前上报的时延为 15 分钟左右。数据会保存 7 天。

                    Q: 我可以定义多少指标 ID?

                    A : 单个小程序每个类别可以定义 20 个 ID。


                    小程序搜索优化指南

                    爬虫访问小程序内页面时,会携带特定的 user-agent "mpcrawler" 及场景值:1129

                    判断请求是否来源于官方搜索爬虫的方法:

                    签名算法与小程序消息推送接口的签名算法一致。

                    参数在请求的header里设置,分别是: X-WXApp-Crawler-Timestamp X-WXApp-Crawler-Nonce X-WXApp-Crawler-Signature

                    签名流程如下: 1.将token、X-WXApp-Crawler-Timestamp、X-WXApp-Crawler-Nonce三个参数进行字典序排序 2.将三个参数字符串拼接成一个字符串进行sha1加密 3.开发者获得加密后的字符串可与X-WXApp-Crawler-Signature对比,标识该请求来源于微信

                    1. 小程序里跳转的页面 (url) 可被直接打开。

                    小程序页面内的跳转url是我们爬虫发现页面的重要来源,且搜索引擎召回的结果页面 (url) 是必须能直接打开,不依赖上下文状态的。 特别的:建议页面所需的参数都包含在url

                    2. 页面跳转优先采用navigator组件。

                    小程序提供了两种页面路由方式:a. navigator 组件b. 路由 API,包括 navigateTo / redirectTo / switchTab / navigateBack / reLaunch 建议使用 navigator 组件,若不得不使用API,可在爬虫访问时屏蔽针对点击设置的时间锁或变量锁。

                    3. 清晰简洁的页面参数。

                    结构清晰、简洁、参数有含义的 querystring 对抓取以及后续的分析都有很大帮助,但是将 JSON 数据作为参数的方式是比较糟糕的实现。

                    4. 必要的时候才请求用户进行授权、登录、绑定手机号等。

                    建议在必须的时候才要求用户授权(比如阅读文章可以匿名,而发表评论需要留名)。

                    5. 我们不收录 web-view 中的任何内容。

                    我们暂时做不到这一点,长期来看,我们可能也做不到。

                    6. 利用 sitemap 配置引导爬虫抓取,同时屏蔽无搜索价值的路径。

                    https://www.51coolma.cn/weixinapp/weixinapp-cspq38rh.html

                    7. 设置一个清晰的标题和页面缩略图。

                    页面标题和缩略图对于我们理解页面和提高曝光转化有重要的作用。 通过 wx.setNavigationBarTitle 或 自定义转发内容 onShareAppMessage 对页面的标题和缩略图设置,另外也为 video、audio 组件补齐 poster / poster-for-crawler 属性。

                    8. 使用页面路径推送能力

                    可极大丰富微信可以收录的内容,进而提高小程序内容的曝光机会。请参考:

                    https://www.51coolma.cn/weixinapp/weixinapp-it7838x9.html


                    商品数据接入(内测)

                    商品数据应用场景

                    商品数据目前应用于 微信扫一扫识物功能、小程序商品搜索功能 和 扫条码 三个功能。 这些功能可以很好的满足微信用户对商品的信息获取诉求,同时也能为商家小程序带来曝光流量和建立用户品牌认知的机会。

                    扫一扫识物- 效果图

                     

                    小程序商品搜索- 效果图

                     

                    扫一扫商品条码- 效果图

                    商品数据接入

                    目前微信已经爬得部分商品详情页,并对页面的商品信息进行了一定的分析理解。商家小程序可以配合接入商品数据,帮助微信更好地发现更多更丰富的商品信息,提高商品的曝光机会。

                    成功接入需要完成以下三步:

                    第一步:开启「爬虫开关」

                    确保爬虫开关处于开启状态,保证小程序页面内容获得被微信收录的机会。爬虫开关在微信公众平台上设置,可参考如下示意图。

                    第二步:推送「页面路径」

                    通过接口主动推送商品详情页的页面路径至微信后台,保证推送页面被微信爬虫及时发现,获得曝光机会。具体参考:小程序search.submitPages接口文档

                    第三步:接入「数据更新协议」

                    接入数据更新协议,可支持微信实时的获取到商品的价格、上下架状态等最新信息,避免由于信息不准确而影响商品的曝光效果。

                    具体参考文档: 小程序商品数据实时更新文档

                    完成以上三步后,商家小程序的商品详情页将被收录,获得在“扫一扫识物功能”、“小程序商品搜索功能”和“扫条码”的曝光机会。

                    此外,我们建议商家小程序还可继续标记页面结构化内容和优化页面结构:

                    一、标记「页面结构化内容」

                    通过对页面结构化内容的标记,帮助微信爬虫更好的理解页面信息,提高页面的召回排序精准度和曝光转化率。具体参考:页面标记商品结构化数据文档

                    二、优化页面结构设计

                    基于小程序搜索优化指南,优化页面结构设计,提高页面对爬虫的友好度。具体参考:小程序SEO建议

                    如本文档版本过旧,请访问Git查看最新版本:点我


                    小程序直播

                    小程序直播是微信官方提供的商家经营工具。通过调用该组件,商家可以在小程序中实现直播互动与商品销售闭环。

                    按照下面的使用说明接入,在你的小程序中引入直播组件即可实现直播功能。使用过程中如遇到问题,可在小程序直播社区发帖交流。

                    使用方法说明

                    1. 【直播组件】如何引入

                    版本限制:微信客户端版本 7.0.7 及以上(基础库版本2.9.x及以上支持同层渲染)可以观看直播及使用直播间的功能,低版本刚进入直播间时会提示用户升级微信客户端版本(低版本只能观看直播,无法使用直播间的功能)。

                    支持在主包或分包内引入【直播组件】 live-player-plugin 代码包(注:直播组件不计入代码包体积),项目根目录的 app.json 引用,示例代码如下:

                    (1) 主包引入

                    "plugins": {    "live-player-plugin": {        "version": "1.1.4", // 注意填写该直播组件最新版本号,微信开发者工具调试时可获取最新版本号(复制时请去掉注释)        "provider": "wx2b03c6e691cd7370" // 必须填该直播组件appid,该示例值即为直播组件appid(复制时请去掉注释)    }}

                    (2) 分包引入

                    "subpackages": [    {        "plugins": {            "live-player-plugin": {                "version": "1.1.4", // 注意该直播组件最新版本号,微信开发者工具调试时可获取最新版本号(复制时请去掉注释)                "provider": "wx2b03c6e691cd7370" // 必须填该直播组件appid,该示例值即为直播组件appid(复制时请去掉注释)            }        }    }]

                    2. 【直播组件】如何使用

                    按第1步的方法把组件代码包配置引入后,即可直接通过链接地址跳转到直播组件页面(即为进直播间页面)链接地址需要带上直播房间 id;房间 id 可通过下面 获取直播房间列表 API 获取。

                    示例代码如下:

                    (1) 使用 navigator 组件跳转进入直播间

                    index.js
                    let roomId = [直播房间id] // 填写具体的房间号,可通过下面【获取直播房间列表】 API 获取let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数(如示例中的path和pid参数),后续可以在分享卡片链接和跳转至商详页时获取,详见【获取自定义参数】、【直播间到商详页面携带参数】章节(上限600个字符,超过部分会被截断)this.setData({    roomId,    customParams})
                    index.wxml
                    <navigator url="plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id={{roomId}}&custom_params={{customParams}}"></navigator>// 其中wx2b03c6e691cd7370是直播组件appid不能修改

                    (2) 使用 navigateTo 方法跳转进入直播间

                    index.js
                    let roomId = [直播房间id] // 填写具体的房间号,可通过下面【获取直播房间列表】 API 获取let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数(如示例中的path和pid参数),后续可以在分享卡片链接和跳转至商详页时获取,详见【获取自定义参数】、【直播间到商详页面携带参数】章节(上限600个字符,超过部分会被截断)wx.navigateTo({    url: `plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=${roomId}&custom_params=${customParams}`})// 其中wx2b03c6e691cd7370是直播组件appid不能修改

                    通过该链接可跳转到直播组件页面(当前页面入口仅开放‘live-player-plugin’)。

                    示例效果图如下:

                    直播组件页面

                    直播组件和接口

                    【组件接口】

                    通过在主包/分包中引入直播组件,开发者可以很方便的实现订阅、获取直播状态、获取用户openid以及获取分享卡片链接参数等功能。

                    【服务端接口】

                    服务端接口包含直播间接口和商品管理接口。

                    • 直播间管理接口是小程序直播提供给开发者对直播间进行批量操作的接口能力。开发者可以批量创建直播间,获取回放源视频,获取直播间列表等。
                    • 商品管理接口是小程序直播提供给开发者对直播商品进行批量操作的接口能力。开发者可以对商品批量进行添加、提审、删除以及更新等操作。
                    类别名称功能说明
                    组件接口订阅组件 subscribe用户进入直播间内,可对一场未开播的直播进行单次订阅,开播时直播组件会自动下发开播提醒给用户
                    获取直播状态  getLiveStatus首次获取立马返回直播状态,往后间隔1分钟或更慢的频率去轮询获取直播状态
                    获取用户openid参数getOpenid在直播组件版本 1.1.4 及以上版本通过该接口获取用户openid参数
                    获取分享卡片链接参数getShareParams在直播组件版本 1.1.4 及以上版本通过该接口获取以下参数,开发者可以根据这些参数建立用户、直播间、商品之间的映射关系
                    直播小窗控制参数 close_picture_in_picture_mode通过参数设置是否关闭小窗
                    携带参数( 直播间到商详页面, 从群分享卡片返回直播间直播组件版本 1.1.4 及以上支持携带以下参数,可用这些参数建立用户、直播间、商品之间的映射关系。
                    服务端接口创建直播间该接口可直接创建直播间,创建成功后直播间将在直播间列表展示
                    后台获取直播房间列表该接口可获取直播房间列表
                    后台获取回放源视频该接口可在直播结束后拿到回放源视频
                    往指定直播间导入已入库商品调用此接口往指定直播间导入已入库的商品
                    商品添加并提审调用此接口上传并提审需要直播的商品信息,审核通过后商品录入【小程序直播】商品库
                    撤回商品审核调用此接口,可撤回直播商品的提审申请,消耗的提审次数不返还
                    重新提交商品审核调用此接口可以对已撤回提审的商品再次发起提审申请
                    删除商品调用此接口,可删除【小程序直播】商品库中的商品,删除后直播间上架的该商品也将被同步删除,不可恢复
                    更新商品调用此接口可以更新商品信息,审核通过的商品仅允许更新价格类型与价格,审核中的商品不允许更新,未审核的商品允许更新所有字段, 只传入需要更新的字段
                    获取商品状态调用此接口可获取商品的信息与审核状态
                    获取商品列表调用此接口可获取商品列表


                    【小程序直播】直播间管理接口

                    名称功能说明
                    创建直播间该接口可直接创建直播间,创建成功后直播间将在直播间列表展示
                    获取直播房间列表该接口可获取直播房间列表
                    获取直播间回放该接口可在直播结束后拿到回放源视频
                    直播间导入商品调用此接口往指定直播间导入已入库的商品

                    一、简介

                    直播间管理接口,是小程序直播提供给开发者对直播房间进行批量操作的接口能力。 开发者可以创建直播间、获取直播间信息、获取直播间回放以及往直播间导入商品。

                    二、接口文档

                    1.创建直播间

                    接口说明:

                    调用此接口创建直播间,创建成功后将在直播间列表展示

                    调用频率

                    调用额度:10000次/一天

                    请求方式

                    POST

                    请求URL

                    https://api.weixin.qq.com/wxaapi/broadcast/room/create?access_token=

                    请求参数示例: json

                    {      name: "测试直播房间1",  // 房间名字      coverImg: "",   // 通过 uploadfile 上传,填写 mediaID      startTime: 1588237130,   // 开始时间      endTime: 1588237130 , // 结束时间      anchorName: "zefzhang1",  // 主播昵称      anchorWechat: "WxgQiao_04",  // 主播微信号      shareImg: "" ,  //通过 uploadfile 上传,填写 mediaID      type: 1 , // 直播类型,1 推流 0 手机直播      screenType: 0,  // 1:横屏 0:竖屏      closeLike: 0 , // 是否 关闭点赞 1 关闭      closeGoods: 0, // 是否 关闭商品货架,1:关闭      closeComment: 0 // 是否开启评论,1:关闭}

                    请求参数含义

                    参数类型必填说明
                    nameString直播间名字,最短3个汉字,最长17个汉字,1个汉字相当于2个字符
                    coverImgString背景图,填入mediaID(mediaID获取后,三天内有效);图片mediaID的获取,请参考以下文档: https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html;直播间背景图,图片规则:建议像素1080*1920,大小不超过2M
                    startTimeNumber直播计划开始时间(开播时间需要在当前时间的10分钟后 并且 开始时间不能在 6 个月后)
                    endTimeNumber直播计划结束时间(开播时间和结束时间间隔不得短于30分钟,不得超过24小时)
                    anchorNameString主播昵称,最短2个汉字,最长15个汉字,1个汉字相当于2个字符
                    anchorWechatString主播微信号,如果未实名认证,需要先前往“小程序直播”小程序进行实名验证, 小程序二维码链接:https://res.wx.qq.com/op_res/BbVNeczA1XudfjVqCVoKgfuWe7e3aUhokktRVOqf_F0IqS6kYR--atCpVNUUC3zr
                    subAnchorWechatString主播副号微信号,如果未实名认证,需要先前往“小程序直播”小程序进行实名验证, 小程序二维码链接:https://res.wx.qq.com/op_res/BbVNeczA1XudfjVqCVoKgfuWe7e3aUhokktRVOqf_F0IqS6kYR--atCpVNUUC3zr
                    createrWechatString创建者微信号
                    shareImgString分享图,填入mediaID(mediaID获取后,三天内有效);图片mediaID的获取,请参考以下文档: https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html;直播间分享图,图片规则:建议像素800*640,大小不超过1M;
                    feedsImgString购物直播频道封面图,填入mediaID(mediaID获取后,三天内有效);图片mediaID的获取,请参考以下文档: https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html; 购物直播频道封面图,图片规则:建议像素800*800,大小不超过100KB;
                    isFeedsPublicNumber是否开启官方收录 【1: 开启,0:关闭】,默认开启收录
                    typeNumber直播间类型 【1: 推流,0:手机直播】
                    screenTypeNumber横屏、竖屏 【1:横屏,0:竖屏】(横屏:视频宽高比为16:9、4:3、1.85:1 ;竖屏:视频宽高比为9:16、2:3)
                    closeLikeNumber是否关闭点赞 【0:开启,1:关闭】(若关闭,直播开始后不允许开启)
                    closeGoodsNumber是否关闭货架 【0:开启,1:关闭】(若关闭,直播开始后不允许开启)
                    closeCommentNumber是否关闭评论 【0:开启,1:关闭】(若关闭,直播开始后不允许开启)
                    closeReplayNumber是否关闭回放 【0:开启,1:关闭】默认关闭回放
                    closeShareNumber是否关闭分享 【0:开启,1:关闭】默认开启分享(直播开始后不允许修改)
                    closeKfNumber是否关闭客服 【0:开启,1:关闭】 默认关闭客服

                    正确返回示例

                    {    "roomId": 33, //房间ID    "errcode": 0} 

                    返回参数含义

                    参数说明
                    roomId房间ID
                    qrcode_url"小程序直播" 小程序码

                    2.获取直播间列表

                    接口说明

                    调用此接口获取直播间列表及直播间信息

                    调用频率

                    调用额度:100000次/一天(与获取回放接口共用次数)

                    请求方式

                    POST

                    请求URL

                    https://api.weixin.qq.com/wxa/business/getliveinfo?access_token=

                    请求参数示例: json

                    {    "start": 0, // 起始拉取房间,start = 0 表示从第 1 个房间开始拉取    "limit": 10 // 每次拉取的个数上限,不要设置过大,建议 100 以内}

                    请求参数含义

                    参数类型必填说明
                    startNumber起始房间,0表示从第1个房间开始拉取
                    limitNumber每次拉取的房间数量,建议100以内

                    正确返回示例

                    {    "errcode": 0,    // 错误码,0代表成功,1代表未创建直播间    "errmsg": "ok"   // 错误信息    "room_info":[{        "name":"直播房间名"        "roomid": 1,        "cover_img":"http://http://mmbiz.qpic.cn/mmbiz_jpgRl1RuuhdstSfZa8EEljedAYcbtX3Ejpdl2et1tPAQ37bdicnxoVialDLCKKDcPBy8Iic0kCiaiaalXg3EbpNKoicrweQ/0?wx_fmt=jpeg",        "share_img":"http://http://mmbiz.qpic.cn/mmbiz_jpgRl1RuuhdstSfZa8EEljedAYcbtX3Ejpdl2et1tPAQ37bdicnxoVialDLCKKDcPBy8Iic0kCiaiaalXg3EbpNKoicrweQ/0?wx_fmt=jpeg",        "live_status": 101,        "start_time": 1568128900,        "end_time": 1568131200,        "anchor_name":"里斯",        "goods":[{             "cover_img":"http://http://mmbiz.qpic.cn/mmbiz_jpg/Rl1RuuhdstSfZa8EEljedAYcbtX3Ejpdl2et1tPAQ37bdicnxoVialDLCKKDcPBy8Iic0kCiaiaalXg3EbpNKoicrweQ/0?wx_fmt=jpeg",             "url":"pages/index/index.html",             "price":1100,             "name":"茶杯"}],        "total":1    }]}

                    返回参数含义

                    房间参数

                    参数说明
                    name直播间名称
                    roomid直播间ID
                    cover_img直播间背景图链接
                    share_img直播间分享图链接
                    live_status直播间状态。101:直播中,102:未开始,103已结束,104禁播,105:暂停,106:异常,107:已过期
                    start_time直播间开始时间,列表按照start_time降序排列
                    end_time直播计划结束时间
                    anchor_name主播名
                    total拉取房间总数

                    商品参数

                    参数说明
                    cover_img商品封面图链接
                    url商品小程序路径
                    price商品价格
                    name商品名称

                    3.获取直播间回放

                    接口说明

                    调用接口获取已结束直播间的回放源视频(一般在直播结束后10分钟内生成,源视频无评论等内容)

                    调用频率

                    调用额度:100000次/一天

                    请求方法

                    POST

                    请求URL

                    https://api.weixin.qq.com/wxa/business/getliveinfo?access_token=

                    请求参数示例: json

                    {     "action": "get_replay",       "room_id": 354,        "start": 0,        "limit": 10        }

                    请求参数含义

                    参数类型必填说明
                    actionString获取回放
                    room_idNumber直播间ID
                    startNumber起始拉取视频,0表示从第一个视频片段开始拉取
                    limitNumber每次拉取的数量,建议100以内

                    正确返回示例

                    {     "live_replay":[{         "expire_time":"",         "create_time":"",         "media_url":""      }],      "errcode": 0,      "total": 1,      "errmsg":"ok"}

                    返回参数含义

                    参数说明
                    expire_time回放视频url过期时间
                    create_time回放视频创建时间
                    media_url回放视频链接
                    total回放视频片段个数

                    4.直播间导入商品

                    接口说明

                    调用接口往指定直播间导入已入库的商品

                    调用频率

                    调用额度:10000次/一天

                    请求方法

                    POST

                    请求URL

                    https://api.weixin.qq.com/wxaapi/broadcast/room/addgoods?access_token=

                    请求参数示例: json

                    {    "ids": [1150, 1111],  // 数组列表,可传入多个,里面填写 商品 ID    "roomId": 2554}

                    请求参数含义

                    参数类型必填说明
                    idsArray<Number>数组列表,可传入多个,里面填写 商品 ID
                    roomIdNumber房间ID

                    正确返回示例

                    {   "errcode": 0 // 0:成功}

                    附录:错误码

                    -1:系统错误

                    1:未创建直播间

                    1003:商品id不存在

                    47001:入参格式不符合规范

                    200002:入参错误

                    300001:禁止创建/更新商品 或 禁止编辑&更新房间

                    300002:名称长度不符合规则

                    300006:图片上传失败(如:mediaID过期)

                    300022:此房间号不存在

                    300023:房间状态 拦截(当前房间状态不允许此操作)

                    300024:商品不存在

                    300025:商品审核未通过

                    300026:房间商品数量已经满额

                    300027:导入商品失败

                    300028:房间名称违规

                    300029:主播昵称违规

                    300030:主播微信号不合法

                    300031:直播间封面图不合规

                    300032:直播间分享图违规

                    300033:添加商品超过直播间上限

                    300034:主播微信昵称长度不符合要求

                    300035:主播微信号不存在

                    300036: 主播微信号未实名认证

                    300037:购物直播频道封面图不合规

                    300038:未在小程序管理后台配置客服

                    300039:主播副号微信号不合法

                    300040:名称含有非限定字符(含有特殊字符)

                    300041:创建者微信号不合法

                    9410000: 直播间列表为空

                    9410001: 获取房间失败

                    9410002: 获取商品失败

                    9410003: 获取回放失败


                    【小程序直播】直播商品管理接口

                    名称功能说明
                    商品添加并提审调用此接口上传并提审需要直播的商品信息,审核通过后商品录入【小程序直播】商品库
                    撤回商品审核调用此接口,可撤回直播商品的提审申请,消耗的提审次数不返还
                    重新提交商品审核调用此接口可以对已撤回提审的商品再次发起提审申请
                    删除商品调用此接口,可删除【小程序直播】商品库中的商品,删除后直播间上架的该商品也将被同步删除,不可恢复
                    更新商品调用此接口可以更新商品信息,审核通过的商品仅允许更新价格类型与价格,审核中的商品不允许更新,未审核的商品允许更新所有字段, 只传入需要更新的字段
                    获取商品状态调用此接口可获取商品的信息与审核状态
                    获取商品列表调用此接口可获取商品列表

                    一、简介

                    直播商品管理接口,是小程序直播提供给开发者对直播商品进行批量操作的接口能力。

                    开发者可以对商品批量进行添加、提审、删除以及更新等操作。

                    接口仅支持对通过接口添加的商品进行操作,开发者在小程序管理后台添加的商品,不支持通过接口操作。

                    开发者必须保存【商品ID】与【审核单ID】,如果丢失,则无法调用其他相关接口。

                    二、接口文档

                    1.商品添加并提审

                    接口说明

                    调用此接口上传并提审需要直播的商品信息,审核通过后商品录入【小程序直播】商品库

                    注意:开发者必须保存【商品ID】与【审核单ID】,如果丢失,则无法调用其他相关接口

                    调用频率

                    调用额度:500次/一天

                    请求方法

                    POST

                    请求URL

                    https://api.weixin.qq.com/wxaapi/broadcast/goods/add?access_token=

                    请求参数示例: json

                    {        "goodsInfo": {                       "coverImgUrl": "ZuYVNKk9sMP1X4m7FXdcDCKra251KDZTjS502UTV7gwalgLZXcrOhG6oNYX6c7AR",                 "name":"TIT茶杯",               "priceType":1,            "price":99.5,         // "price2": 150.5, priceType为2或3时必填         "url":"pages/index/index"      }}

                    请求参数含义

                    参数类型必填说明
                    coverImgUrlString填入mediaID(mediaID获取后,三天内有效);图片mediaID的获取,请参考以下文档: https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html;图片规则:图片尺寸最大300像素*300像素;
                    nameString商品名称,最长14个汉字,1个汉字相当于2个字符
                    priceTypeNumber价格类型,1:一口价(只需要传入price,price2不传) 2:价格区间(price字段为左边界,price2字段为右边界,price和price2必传) 3:显示折扣价(price字段为原价,price2字段为现价, price和price2必传)
                    priceNumber数字,最多保留两位小数,单位元
                    price2Number数字,最多保留两位小数,单位元
                    urlString商品详情页的小程序路径,路径参数存在 url 的,该参数的值需要进行 encode 处理再填入

                    正确返回示例

                    {      "goodsId": 51,    "auditId": 525022786,    "errcode": 0 }

                    返回参数含义

                    参数说明
                    goodsId商品ID
                    auditId审核单ID

                    2.撤回审核

                    接口说明

                    调用此接口,可撤回直播商品的提审申请,消耗的提审次数不返还

                    调用频率

                    调用额度:500次/一天

                    请求方法

                    POST

                    请求URL

                    https://api.weixin.qq.com/wxaapi/broadcast/goods/resetaudit?access_token=

                    请求参数示例: json

                    {        "auditId": 525022184,    "goodsId": 9}

                    请求参数含义

                    参数类型必填说明
                    goodsIdNumber商品ID
                    auditIdNumber审核单ID

                    正确返回示例

                    {      "errcode": 0 }

                    3.重新提交审核

                    接口说明

                    调用此接口可以对已撤回提审的商品再次发起提审申请

                    调用频率

                    调用额度:500次/一天(与接口1共用500次限制)

                    请求方法

                    POST

                    请求URL

                    https://api.weixin.qq.com/wxaapi/broadcast/goods/audit?access_token=

                    请求参数示例: json

                    {        "goodsId": 9}

                    请求参数含义

                    参数类型必填说明
                    goodsIdNumber商品ID

                    正确返回示例

                    {      "errcode": 0,    "auditId": 525022184}

                    返回参数含义

                    参数说明
                    auditId审核单ID

                    4.删除商品

                    接口说明

                    调用此接口,可删除【小程序直播】商品库中的商品,删除后直播间上架的该商品也将被同步删除,不可恢复;

                    调用频率

                    调用额度:1000次/一天

                    请求方法

                    POST

                    请求URL

                    https://api.weixin.qq.com/wxaapi/broadcast/goods/delete?access_token=

                    请求参数示例: json

                    {        "goodsId": 9}

                    请求参数含义

                    参数类型必填说明
                    goodsIdNumber商品ID

                    返回参数

                    {       "errcode": 0,   }

                    5.更新商品

                    接口说明

                    调用此接口可以更新商品信息,审核通过的商品仅允许更新价格类型与价格,审核中的商品不允许更新,未审核的商品允许更新所有字段, 只传入需要更新的字段。

                    调用频率

                    调用额度:1000次/一天

                    请求方法

                    POST

                    请求URL

                    https://api.weixin.qq.com/wxaapi/broadcast/goods/update?access_token=

                    请求参数示例: json

                    {        "goodsInfo": {                // 需要更新哪个字段就传入哪个字段,goodsId 必传                "coverImgUrl": "ZuYVNKk9sMP1X4m7FXdcDCKra251KDZTjS502UTV7gwalgLZXcrOhG6oNYX6c7AR",                "name":"TIT茶杯",                "priceType":1,        "price":99.5,        // "price2": 150.5, priceType为2或3时必填        "url": "pages/index/index",               "goodsId": 9         }}

                    请求参数含义

                    参数类型必填说明
                    coverImgUrlString填入mediaID(mediaID获取后,三天内有效);图片mediaID的获取,请参考以下文档: https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html;图片规则:图片尺寸最大300像素*300像素;
                    nameString商品名称,最长14个汉字,1个汉字相当于2个字符
                    priceTypeNumber价格类型,1:一口价(只需要传入price,price2不传) 2:价格区间(price字段为左边界,price2字段为右边界,price和price2必传) 3:显示折扣价(price字段为原价,price2字段为现价, price和price2必传)
                    priceNumber数字,最多保留两位小数,单位元
                    price2Number数字,最多保留两位小数,单位元
                    urlString商品详情页的小程序路径,路径参数存在 url 的,该参数的值需要进行 encode 处理再填入
                    goodsIdNumber商品ID

                    返回参数

                    {       "errcode": 0,   }

                    6.获取商品状态

                    接口说明

                    调用此接口可获取商品的信息与审核状态

                    调用频率

                    调用额度:1000次/一天

                    请求方法

                    POST

                    请求URL

                    https://api.weixin.qq.com/wxa/business/getgoodswarehouse?access_token=

                    请求参数示例: json

                    {​    "goods_ids": [1]}

                    请求参数含义

                    参数类型必填说明
                    goods_idsArray<Number>商品ID

                    返回参数

                    {​    "errcode":0,​    "errmsg":"ok",​    "goods":​        [​            {​                "goods_id":9,​                "cover_img_url":"xxxx",​                "name":"xxxxx"​                "price":12300,​                "url":"xxxxxxx",​                "price_type":1,​                "price2":0,​                "audit_status":1,​                "third_party_tag":0​            }​        ],​    "total":0}

                    返回参数含义

                    参数说明
                    goods_id商品ID
                    name商品名称
                    cover_img_url商品图片url
                    url商品详情页的小程序路径
                    priceType1:一口价,此时读price字段; 2:价格区间,此时price字段为左边界,price2字段为右边界; 3:折扣价,此时price字段为原价,price2字段为现价;
                    price价格左区间,单位“元”
                    price2价格右区间,单位“元”
                    audit_status0:未审核,1:审核中,2:审核通过,3审核失败
                    third_party_tag1、2:表示是为 API 添加商品,否则是直播控制台添加的商品
                    total商品个数

                    7.获取商品列表

                    接口说明

                    调用此接口可获取商品列表

                    调用频率

                    调用额度:10000次/一天

                    请求方法

                    GET

                    请求URL

                    https://api.weixin.qq.com/wxaapi/broadcast/goods/getapproved?access_token=[access_token]

                    URL query 参数

                    参数类型必填说明
                    offsetNumber分页条数起点
                    limitNumber分页大小,默认30,不超过100
                    statusNumber商品状态,0:未审核。1:审核中,2:审核通过,3:审核驳回

                    返回参数

                    {​    "errcode":0,​    "total":68,​    "goods":​        [​            {​                "goodsId":9,​                "coverImgUrl":"xxxx",​                "name":"xxxxx"​                "price":12300,​                "url":"xxxxxxx",​                "priceType":1,​                "price2":0,​                "thirdPartyTag":0​            }​        ]}

                    返回参数含义

                    参数说明
                    total商品数量
                    goodsId商品ID
                    coverImgUrl商品图片链接
                    name商品名称
                    price价格左区间,单位“元”
                    price2价格右区间,单位“元”
                    url商品小程序路径
                    priceType1:一口价,此时读price字段; 2:价格区间,此时price字段为左边界,price2字段为右边界; 3:折扣价,此时price字段为原价,price2字段为现价;
                    thirdPartyTag1、2:表示是为 API 添加商品,否则是直播控制台添加的商品

                    附录:错误码

                    -1:系统错误

                    1003:商品id不存在

                    47001:入参格式不符合规范

                    200002:入参错误

                    300001:禁止创建/更新商品(如:商品创建功能被封禁)

                    300002:名称长度不符合规则

                    300003:价格输入不合规(如:现价比原价大、传入价格非数字等)

                    300004:商品名称存在违规违法内容

                    300005:商品图片存在违规违法内容

                    300006:图片上传失败(如:mediaID过期)

                    300007:线上小程序版本不存在该链接

                    300008:添加商品失败

                    300009:商品审核撤回失败

                    300010:商品审核状态不对(如:商品审核中)

                    300011:操作非法(API不允许操作非API创建的商品)

                    300012:没有提审额度(每天500次提审额度)

                    300013:提审失败

                    300014:审核中,无法删除(非零代表失败)

                    300017:商品未提审

                    300021:商品添加成功,审核失败


                    其他能力

                    1、 直播间小程序码

                    说明:

                    • 小程序引入直播组件后必须进行一次小程序发布上线,否则直播间的小程序码不生效,具体表现是用户扫码进入直播间会显示“页面不存在”。
                    • 在 MP 小程序直播后台创建好直播间后,可以直接拿到直播间分享小程序码,无需额外开发

                    如果商家在后台自己生成的直播间小程序码,需要做以下配置: 在跳转进入直播间的路径加上 type = 9 标识场景入口为小程序码: "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=9"。 若需要带上自定义参数则还需要加上 custom_params: "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=9&custom_params=encodeURIComponent(JSON.stringify(custom_params))"。

                    2、 商家公众号文章添加小程序卡片

                    说明:

                    商家在公众号文章中添加跳转进入直播间的小程序卡片时,需要做以下配置: 在跳转进入直播间的路径加上 type = 10 标识场景入口为小程序卡片: "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=10"。 若需要带上自定义参数则还需要加上 custom_params: "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=[直播房间id]&type=10&custom_params=encodeURIComponent(JSON.stringify(custom_params))"。

                    3、 商品详情页注意事项

                    (1)添加返回按钮: 点击直播组件页面里的货架商品跳转到商家小程序的商品详情页面后,为了避免用户无法再返回直播间,商家需在小程序商品详情页面左上角加上返回按钮,通过wx.navigateBack返回到直播组件页面。

                    (2)不建议使用wx.switchTab:若在商品详情页点击按钮(如购物车按钮等)通过wx.switchTab跳转到tabbar页,然后再点小窗回到直播间时会出现页面卡死问题(微信客户端7.0.15版本才修复)。此时可把页面改为非tabbar页并通过wx.navigateTo跳转,也可通过关闭小窗来解决该问题。

                    (3)不建议使用wx.reLaunch:若在商品详情页及之后的页面元素上使用wx.reLaunch跳转,不仅会关闭小窗,而且无法返回到上一页,体验不好。

                    4、 快速更新直播组件版本的方法

                    商家小程序对应的管理员微信号收到【公众平台安全助手】下发的直播组件版本更新的服务通知后,可点击通知进行快速发布,移动端即可快速更新小程序内直播组件的新版本,无需修改代码或重新提交审核。

                    服务通知如下图所示:

                    直播组件页面

                    5、 直播小窗

                    版本限制:直播组件版本 1.1.4 及以上支持通过以下参数设置是否关闭小窗。

                    close_picture_in_picture_mode:默认支持直播小窗,可通过close_picture_in_picture_mode=1关闭小窗功能,如 "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=直播房间号&close_picture_in_picture_mode=1"。

                    6、 携带参数

                    版本限制:直播组件版本 1.1.4 及以上支持携带以下参数,开发者可以根据这些参数建立用户、直播间、商品之间的映射关系。

                    (1) shareTicket:分享直播间卡片到微信群,点击此卡片后可以在 App onShow 里获取该参数(默认不可获取该参数,可在跳转直播间页面路径上配置 open_share_ticket=1 打开 shareTicket,如 "plugin-private://wx2b03c6e691cd7370/pages/live-player-plugin?room_id=直播房间号&open_share_ticket=1",但长按分享卡片时不能转发。)

                    (2) room_id + openid + share_openid + custom_params :点击直播间里的货架商品跳转到商家小程序的商品详情页或点击直播间左上角首页icon跳转到商家小程序的首页时,可以在Page onLoad options里获取房间号、用户openid、分享者share_openid(如果是从分享卡片进入直播间再跳转到商详页才有该参数)、开发者携带的自定义参数custom_params


                    版本更新日志

                    1.3.2

                    1. 修复WebGLCanvasContext2d报错导致动画不播放问题

                    1.3.1

                    1. 修复 getShareParams 接口无法获取直播间分享海报的参数问题

                    1.3.0

                    1. 新增助力榜功能

                    1.2.10

                    1. 优化getShareParams接口(新增扫码/广告等场景获取参数)

                    1.2.9

                    1. 新增智能回复功能
                    2. 新增评论支持微信表情功能
                    3. 新增分享直播间海报到会话功能

                    1.2.8

                    1. 新增手机号兑奖方式
                    2. 新增自定义兑奖说明
                    3. 直播间小程序昵称展示长度自适应

                    1.2.7

                    1. 修复部分用户微信版本过低导致的白屏问题

                    1.2.6

                    1. 新增直播预告功能
                    2. 新增直播挂件组件
                    3. 直播间组队抽奖优化
                    4. 直播间启动性能优化
                    5. 直播间色调设计优化
                    6. 直播间点赞素材更新

                    1.2.5

                    1. 新增组队抽奖功能

                    1.2.4

                    1. 直播间详情页优化
                    2. 连麦小窗画面支持移动
                    3. 直播间新增下载海报功能

                    1.2.3

                    1. 新增直播间公告功能
                    2. 新增购物袋动画效果
                    3. 优化点赞动画同步效果
                    4. 优化清屏热区体验

                    1.2.2

                    1. 新增连麦功能
                    2. 新增点赞动画同步功能
                    3. 新增直播间拍一拍彩蛋
                    4. PC端支持全屏
                    5. 安卓直播间分享面板新增分享到朋友圈功能
                    6. 优化朋友圈中间页交互体验

                    1.2.0

                    1. 直播间客服聊天窗支持发送直播间卡片
                    2. 优化直播间清屏/回放快进等体验
                    3. 优化直播间点赞动画性能

                    1.1.10

                    1. 优化长期订阅直播能力
                    2. 修复回放偶现丢评论问题

                    1.1.9

                    1. 新增长期订阅直播功能
                    2. 直播间UI改版
                    3. 推流直播支持自定义背景墙
                    4. 优化群分享样式

                    1.1.8

                    1. 新增商品讲解功能
                    2. 新增商品点赞功能

                    1.1.4

                    1. 直播间可配置小程序客服
                    2. 直播间分享能力可配置
                    3. 修复分包引入小程序直播组件导致样式错乱问题
                    4. 修复直播结束页滚动时商品展示不全问题

                    1.1.3

                    1. 支持分享朋友圈功能(灰度安卓用户)
                    2. 订阅组件支持自定义颜色和大小
                    3. 开播提醒和订阅组件支持携带自定义参数
                    4. 优化回放进度条拖动精度
                    5. 优化评论体验

                    1.1.0

                    1. 修复推流回放样式相关问题

                    1.0.18

                    1. 优化直播间打开速度

                    1.0.16

                    1. 优惠券功能全面上线
                    2. 优化竖屏推流直播画面显示

                    1.0.15

                    1. 优化手机发烫问题
                    2. 修复部分用户点赞无动画效果问题

                    1.0.13

                    1. 适配iPad及PC
                    2. 修复清屏相关问题
                    3. 订阅组件新增stopPropagation属性控制事件冒泡

                    1.0.11

                    1. 修复弹起评论框后点直播画面区域无法收起问题
                    2. 修复清屏回来打开货架无法收起问题

                    1.0.10

                    1. 修复横屏下点击清屏再返回竖屏后互动按钮失效问题
                    2. 修复从左往右滑时出现清屏动画问题

                    1.0.9

                    1. 修复进直播间闪现货架问题

                    1.0.8

                    1. 新增竖屏清屏功能
                    2. 新增回放视频小窗功能
                    3. 优化评论区域卡顿问题
                    4. 修复商品链接type参数被覆盖问题
                    5. 修复商品链接参数里的html被去掉问题

                    1.0.6

                    1. 新增小助手功能

                    1.0.5

                    1. 优化部分机型回放拉伸等问题
                    2. 修复直播小窗重音问题
                    3. 修复客户端导致点赞动画显示问题
                    4. 修复跳转其他页面提示“当前处于非WiFi环境,请注意流量消耗”问题

                    1.0.4

                    1. 新增回放功能
                    2. 通过close_share_ticket参数设置shareTicket
                    3. 商品链接支持跳转到tab页面

                    1.0.3

                    1. 新增推流功能
                    2. 获取分享链接参数getShareParams接口优化

                    1.0.2

                    1. 携带 openid / room_id / 自定义参数给开发者
                    2. 优化跳转至商详页再跳回直播间先load封面问题
                    3. 修复 windows 平台无法观看直播问题
                    4. 修复企业微信提示升级问题

                    1.0.1

                    1. 缩减代码包体积至 445 KB
                    2. 跳转至商品详情页时带上 room_id 参数
                    3. 分享时带上 shareTicket 参数给商家
                    4. 获取直播状态接口优化

                    1.0.0

                    1. 新增直播小窗效果
                    2. 分享入口外显直播间
                    3. 直播结束页商品展示优化
                    4. 抽奖地址优化


                    仿原生乘车码

                    业务方可通过接入仿原生乘车码行业模板,在业务方小程序中快速实现公共交通的线上扫码乘车功能,以及开通线路、乘车记录、帮助中心等相关页面。仿原生乘车码行业模板包括以下接口(在调用前需先完成小程序账号注册、微信支付商户号申请流程,并向 city_api@tencent.com 发送接入仿原生乘车码行业模板能力的申请邮件):

                    API名称API描述
                    仿原生跳转根据需求不同跳转不同的微信仿原生页面实现不同的功能需求。
                    生码微信后台向业务方请求二维码源数据,微信前端可以根据源数据生成乘车码。
                    支付回调微信后台向业务方请求二维码源数据,微信前端可以根据源数据生成乘车码。
                    微信扣费用于接收业务方依据扫码接口获取到的信息对用户进行免密扣费。
                    用户注册/签约微信后台向业主方发起用户注册。
                    用户解约微信后台向业主方通知用户注销/解约。
                    用户签约状态查询业主方查询用户签约状态接口。
                    欠费支付微信后台向业主方通知用户支付成功(支付失败时无通知)。
                    查询线路查询设置的公交/地铁线路
                    设置线路设置公交/地铁线路
                    查询欠费用户列表微信后台会定时(每天6点开始)获取所有欠费用户列表,并提供接口查询列表接口,此后如果有用户完成欠费缴纳会在收到成功支付通知时删除记录。

                    仿原生跳转

                    根据需求不同跳转不同的微信仿原生页面实现不同的功能需求。

                    1、 请求参数

                    参数名称类型必选备注
                    path_typeintY需要跳转的页面 0 - 新用户首页/欢迎页(开通乘车码,包含“成功开通乘车码”
                    1 - 乘车码页 2 - 已开通路线 3 - 个人中心 4 - 我的乘车记录 5 - 帮助 6 - 欠费记录

                    注意:请求参数为json格式。

                    2、 返回参数

                    参数名称类型必选备注
                    errcodeintY返回码
                    errmsgstringY返回信息
                    business_typestringY业务类型
                    query_stringstringY调用仿原生小程序时使用的参数
                    expire_atintY返回query_string的到期时间(uinx时间戳)

                    3、 示例代码

                    请求:

                    https://api.weixin.qq.com/intp/transportcode/getbusinessview?access_token=ACCESSTOKEN

                    请求参数:

                    {"path_type":1}

                    返回:

                    {    "errcode":0,    "errmsg":"ok",    "business_type":"wxCity",    "query_string":"addr=pages%2Froute%2Fmain&amp;business_view_token=a52f6d30814a8d7d5717d004a0c38894",    "expire_at":1576838728}


                    生码

                    微信后台向业务方请求二维码源数据,前端可以根据源数据生成乘车码。

                    1、 请求参数

                    参数名称类型必选备注
                    appidstringY小程序
                    appidmch_idstringY支付商户号
                    nonce_strstringY随机字符串
                    encrypted_datastringY使用AESCBCPKCS7PADDING
                    ivstringY用于解密的IV(base64后)
                    signstringY1~5字段的签名

                    encrypted_data解密后的数据

                    参数名称类型必选备注
                    openidstringY用户
                    idcard_idstringY第三方用户id(有注册环节则有)
                    user_public_keystringY用户公钥,16进制格式,共130字节

                    2、 返回参数

                    参数名称类型必选备注
                    errcodeintY0为成功
                    errmsgstringN错误信息
                    nonce_strstringY原样带回
                    encrypted_datastringY使用AESCBCPKCS7PADDING

                    encrypted_data解密后的数据

                    参数名称类型必选备注
                    base64_svr_datastringY交通部乘车码标准1~15字段拼接的二进制流,base64后便于网络传输

                    3、 示例代码

                    请求:

                    {"appid":"test","mch_id":"123456","nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

                    encrypted_data解密后:

                    {"openid":"1234","user_public_key":"123123","card_id":"2342343"}

                    返回:

                    {"errcode":0,"nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

                    encrypted_data解密后的数据:

                    {"base64_svr_data":"xxafdafd"}


                    扫码支付

                    (1)支付回调接口

                    业务方调用微信扣费接口之后,接收扣费结果通知。

                    1、 请求参数

                    参数名称类型必选备注
                    appidstringY小程序
                    appidmch_idstringY支付商户号
                    nonce_strstringY随机字符串
                    encrypted_datastringY使用AESCBCPKCS7PADDING
                    ivstringY用于解密的IV
                    signstringY1~5字段的签名

                    解密后的参数如下:

                    参数名称类型必选备注
                    openidstringY用户在小程序appid下的openid
                    bank_typestringY支付类型
                    total_feeintY支付总额,单位为分
                    trade_statestringY支付状态:SUCCESS/FAIL
                    trade_msgstringN支付失败时返回
                    transaction_idstringY微信支付单号
                    out_trade_nostringY乘车码业务方单号
                    attachstringN扣费API的入参,原样带回
                    time_endstringY支付完成时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010
                    qrcodestringY二维码

                    2、 返回参数

                    参数名称类型必选备注
                    errcodeintY0为成功
                    errmsgstringN错误信息
                    nonce_strstringY原样带回

                    3、 示例代码

                    {"appid":"test","mch_id":"123456","nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

                    解密后数据:

                    {"openid":"fafwefawef","bank_type":"CFT","total_fee":100,"trade_state":"SUCCESS",...}

                    (2)微信扣费接口(微信API接口)

                    用于接收业务方依据扫码接口获取到的信息对用户进行免密扣费。

                    1、请求参数

                    参数名称类型必选备注
                    qrcodestringY乘车码数据,需要base64
                    total_feeintY支付总额,分为单位(优惠后)
                    original_feeintY支付总额,分为单位(优惠前)
                    machine_ipstringN扫码机接入IP
                    machine_latitudefloatN扫码机GPS纬度
                    machine_longitudefloatN扫码机GPS经度
                    bodystringY公交代扣/地铁代扣
                    start_timestringY上车/乘车时间,如20091225091010
                    end_timestringN下车时间,格式同上,适用于二次刷码的场景
                    line_namestringY乘车线路
                    trade_scenestringYMETRO/BUS
                    start_qrcodestringN二次刷码时,传入首次刷码使用的二维码
                    out_order_nostringN业务方自定义订单号,需要保证唯一
                    attachstringN业务方自定义数据,对账单和查询接口会原样返回

                    2、 返回参数

                    参数名称类型必选备注
                    errcodeint32Y返回码
                    errmsgstringN返回信息

                    3、 示例代码

                    入参:

                    {"qrcode":"afefawefwef",....}

                    返回

                    {"errcode":0,....}


                    用户注册/签约(可选)

                    微信后台向业主方发起用户注册。

                    1、请求参数

                    参数名称类型必选备注
                    appidstringY小程序
                    appidmch_idstringY支付商户号
                    nonce_strstringY随机字符串
                    encrypted_datastringY使用AESCBCPKCS7PADDING
                    ivstringY用于解密的IV
                    signstringY1~5字段的签名

                    encrypted_data解密后的数据

                    参数名称类型必选备注
                    openidstringY用户id

                    2、返回参数

                    参数名称类型必选备注
                    errcodeintY0为成功
                    errmsgstringN错误信息
                    nonce_strstringY原样带回
                    encrypted_datastringY使用AESCBCPKCS7PADDING
                    ivstringY用于解密的IV

                    encrypted_data解密后的数据

                    参数名称类型必选备注
                    cardidstringY用户卡ID

                    3、示例代码

                    请求:

                    {"appid":"test","mch_id":"123456","nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

                    encrypted_data解密后为:

                    {“openid”:”1234”}

                    返回:

                    {"errcode":0,"nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

                    encrypted_data解密后的数据:

                    {“card_id”:”xxafdafd”}


                    用户解约(可选)

                    微信后台向业主方通知用户注销/解约。

                    1、请求参数

                    参数名称类型必选备注
                    appidstringY小程序
                    mch_idstringY支付商户号
                    nonce_strstringY随机字符串
                    encrypted_datastringY使用AESCBCPKCS7PADDING
                    ivstringY用于解密的IV(base64)
                    signstringY1~5字段的签名

                    encrypted_data解密后的数据

                    参数名称类型必选备注
                    openidstringY用户openid
                    cardidstringN业主方的用户标识

                    2、返回参数

                    参数名称类型必选备注
                    errcodeintY0为成功
                    errmsgstringN错误信息
                    nonce_strstringY原样带回

                    3、 示例代码

                    请求:

                    {"appid":"test","mch_id":"123456","nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

                    encrypted_data解密后为:

                    {"openid":"1234","cardid":"1234"}

                    返回:

                    {"errcode":0,"nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}


                    用户签约状态查询

                    业主方查询用户签约状态接口。

                    1、请求参数

                    参数名称类型必选备注
                    openidstringN用户openid(优先使用)
                    cardidstringN业主方的用户标识,注册接口返回

                    2、返回参数

                    参数名称类型必选备注
                    errcodeint32Y返回码
                    errmsgstringN返回信息
                    statusintY用户签约状态 0-已签约 1-未签约

                    3、示例代码

                    请求:

                    {"openid":"afefawefwef","cardid":"123"}

                    返回:

                    {"errcode":0,"errmsg":"ok","status":0}


                    欠费支付

                    微信后台向业主方通知用户支付成功(支付失败时无通知)。

                    1、请求参数

                    参数名称类型必选备注
                    appidstringY小程序appid
                    mch_idstringY支付商户号
                    nonce_strstringY随机字符串
                    encrypted_datastringY使用AESCBCPKCS7PADDING
                    ivstringY用于解密的IV(base64)
                    signstringY1~5字段的签名

                    encrypted_data解密后的数据

                    参数名称类型必选备注
                    out_user_idstringY业主后台对用户的标识,设置过注册回调接口时存在
                    openidstringY用户openid
                    bank_typestringY支付类型,采用字符串类型的银行标识
                    total_feeintY支付费用
                    transaction_idstringY微信支付单号
                    time_endstringY格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010
                    repay_nostringY欠费单号
                    order_noarrayY与本欠费单号相关联的乘车码单号(存在一次支付多笔乘车欠费的情况),每一项的内容为string
                    orderarrayY与本欠费单号相关联的乘车码单号的详细信息

                    其中order的每一项内容如下:

                    参数名称类型必选备注
                    order_nostringY乘车码单号
                    attachstringY免密代扣上传的附加信息
                    base64_qrcodestringYbase64后的乘车码信息
                    out_order_nostringY外部传的单号

                    2、返回参数

                    参数名称类型必选备注
                    errcodeintY0为成功
                    errmsgstringN错误信息
                    nonce_strstringY原样带回

                    3、示例

                    请求:

                    {"appid":"test","mch_id":"123456","nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}

                    encrypted_data解密后为:

                    {    "out_user_id":"xxx",    "openid":"1234",    "bank_type":"LQT",    "total_fee":123,    "transaction_id":"12312312",    "time_end":"2020030319551111",    "repay_no":"2020202202020",    "order_no":[        "123",        "456"]}

                    返回:

                    {"errcode":0,"nonce_str":"abcdefg","encrypted_data":"jfiwajeofjiefef","iv":"afweifwefe"}


                    查询线路接口

                    查询设置的公交/地铁线路。

                    1、请求参数

                    参数名称类型必选备注
                    typeintY类型 0-地铁 1-公交

                    2、返回参数

                    参数名称类型必选备注
                    errcodeintY错误码
                    errmsgstringY错误信息
                    resultsobjectN线路信息

                    其中results的内容如下:

                    参数名称类型必选备注
                    line_listawayY线路信息

                    其中results.line_list的每一项内容如下:

                    参数名称类型必选备注
                    idintY线路的唯一id
                    start_stationstringY起点站
                    end_stationstringY终点站
                    line_namestringY线路名称


                    设置线路接口

                    设置公交/地铁线路。

                    1、请求参数

                    参数名称类型必选备注
                    typeintY类型 0-地铁 1-公交
                    confobjectY设置的线路配置

                    其中conf的内容如下:

                    参数名称类型必选备注
                    line_listawayY线路信息

                    其中conf.line_list的每一项内容如下:

                    参数名称类型必选备注
                    idintY线路的唯一id
                    start_stationstringY起点站
                    end_stationstringY终点站
                    line_namestringY线路名称

                    2、返回参数

                    参数名称类型必选备注
                    errcodeintY错误码
                    errmsgstringY错误信息


                    查询欠费用户列表

                    微信后台会定时(每天6点开始)获取所有欠费用户列表,并提供接口查询列表接口,此后如果有用户完成欠费缴纳会在收到成功支付通知时删除记录。

                    1、请求参数

                    参数名称类型必选备注
                    start_openidstringN开始的openid,从头开始填空,start_openid不会包含在返回结果中
                    limitintY最大返回数量(0,10000]

                    2、返回参数

                    参数名称类型必选备注
                    errcodeintY错误码
                    errmsgstringY错误信息
                    listarrayN返回欠费用户列表

                    其中list的每一项的内容如下:

                    参数名称类型必选备注
                    openidstringY用户openid
                    feeintY欠费金额
                    create_timeintY更新的时间
                    out_user_idstringN用户在业主方的id,当设置了注册回调后才有


                    safety-specifications

                    接入微信城市服务,业务方需确保功能安全性。

                    常见安全检查表

                    XSS

                    1. 输入校验:长度限制、值类型是否正确、是否包含特殊字符(如<>’”等)
                    2. 输出编码:根据输出的位置进行相应的编码,如HTML编码、JavaScript编码、URL编码。
                    3. 输出到HTML标签之间时,对这些数据进行HTML Entity编码
                    4. 输出到HTML属性里时,特殊字符编码为&#xHH
                    5. 输出到SCRIPT里时,对这些数据进行SCRIPT编码,除了阿拉伯数字和字母,对其他所有的字符进行编码,只要该字符的ASCII码小于256。编码后输出的格式为xHH
                    6. 输出到Style属性里时,对这些数据进行CSS编码,除了阿拉伯数字和字母,对其他所有的字符进行编码,只要该字符的ASCII码小于256。编码后输出的格式为HH
                    7. 输出到HTML URL里时,对这些数据进行URL编码,当需要往HTML页面中的URL里插入不可信数据的时候,需要对其进行URL编码

                    SQL注入

                    1. 最佳方式就是使用预编译语句,绑定变量
                    2. 检查数据类型
                    3. 使用安全函数,例如php的mysql_real_escape_string
                    4. 从数据库自身来说,应使用最小权限原则,切记不要使用dba权限

                    上传漏洞

                    1. 在客户端和服务器端对用户上传的文件名和文件路径等项目分别进行严格的检查,尤其是服务端检测不能少
                    2. 服务器端的检查最好使用白名单过滤的方法,比如只允许jpg文件上传等
                    3. 上传目标路径尽量不在web目录下,如果在web目录下去掉该目录的可执行权限
                    4. 慎用Fckeditor、ewebeditor等第三方上传组件,历史上曾出现多个漏洞

                    Struts2

                    历史上Struts2框架出过多个高危漏洞,这些漏洞足以黑掉一个网站,要尽量使用最新版本

                    信息泄漏

                    1. 线上机器删掉测试页面,例如test.html,phpinfo.php等
                    2. 禁掉详细的错误提示
                    3. 禁止显示调试信息
                    4. 禁止将svn相关的文件更新到线上机器,例如.svn/entries

                    登录安全

                    1. 登录页面最好加入验证码
                    2. 尽量使用https协议

                    会话安全

                    公众号开发中通常将openid作为用户身份标识,使用openid时要将openid设置到cookie中不要拼接到URL中例如http://www.qq.com/getuser?code=aaaaaa

                    管理页面

                    Tomcat、jboss、weblogic等管理页面可以做以下加个方面的安全策略

                    使用白名单的方式限制可以登录的IP

                    如果不使用这些管理界面直接删掉

                    平行权限问题

                    像订单等场景需要格外注意平行权限问题,例如order?Id=111,是否order?Id=112就可以看到其他的订单。对于这种情况的防御,可以加入校验参数,order?Id=111&sign=hash(字符串常量+id)

                    支付金额问题

                    1. 涉及到微支付的web应用一定要严格按照微信支付官方网站的文档设计
                    2. 确定用户的支付金额与应付金额是否相等


                    results-page

                    接入微信城市服务,业务方需确保功能的闭环服务体验,需接入消息通路。点击此处查看城市服务消息通路说明

                    调用方法

                    1、接口调用请求

                    请求方式:POST 请求地址:https://api.weixin.qq.com/cityservice/sendmsgdata?access_token=ACCESS_TOKEN

                    (1)获取access_token方式请点击此处查看;获取openid方式请点击此处查看

                    (2)通过小程序提供服务时,需使用小程序用户 openid ,并使用与小程序关联的、且申请了“消息通路”的公众号的 access_token

                    2、以POST方式传入json格式的参数

                    (1)模板申请成功后,将会分配biz_template_id,并根据模板推送渠道不同分别提供样式ID:result_page_style_id、deal_msg_style_id、card_style_id。

                    (2)调用接口时,通过POST方式传入json格式的以下参数,所有参数的数据类型均为“字符串”,且字符集默认使用UTF-8。

                    字段说明

                    参数说明是否必填
                    openid用户唯一标识必填
                    biz_template_id城市服务分配给公众号的模板id必填
                    result_page_style_id结果页样式id含结果页必填
                    deal_msg_style_id办事记录样式id含办事记录必填
                    card_style_id页卡样式id含页卡必填
                    order_no订单号,同一订单号的办事记录会合并必填
                    url跳转链接,用于服务通知、结果页、待办提醒含结果页必填
                    data模板json数据,其中color字段只对服务通知有效必填

                    参数示例

                    {           "openid":"OPENID",           "biz_template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",           "result_page_style_id":"cUjfPSEtwasWQFsJ5PXo218PexBaHy5jg_peVDe4WkY",           "deal_msg_style_id":"cUjfPSEtwasWQFsJ5PXo24LeNjWbwMObXSHPNjVZ0uQ",           "card_style_id":"cUjfPSEtwasWQFsJ5PXo2z8LSM0Q6FH05DCerWEVkDs",           "order_no":"ORDER_NO",           "url":"http://weixin.qq.com/download",           "data":{                   "first": {                       "value":"恭喜你购买成功!",                       "color":"#173177"                   },                   "keynote1":{                       "value":"巧克力",                       "color":"#173177"                   },                   "keynote2": {                       "value":"39.8元",                       "color":"#173177"                   },                   "keynote3": {                       "value":"2014年9月22日",                       "color":"#173177"                   },                   "remark":{                       "value":"欢迎再次购买!",                       "color":"#173177"                   }           }}

                    注:data为数组时用[ ]括起“data”字段内数据。

                    3、返码说明

                    在调用消息通路接口后,返回JSON数据包:

                    返回结果返回码说明
                    result_page_url结果页url需跳转至该url,替代原有的服务结果页面。如未传入result_page_style_id,则调用后result_page_url返回为空。
                    errcode48001api未授权
                    errcode400971.参数错误。2.或openid不来自有“消息通路”api权限的公众号
                    errcode82020未关注公众号的用户,从未在城市服务访问过服务
                    errcode82021未关注公众号的用户,未在近30天内通过城市服务访问服务
                    errcode82022未关注公众号的用户,通过城市服务访问服务后,30天内被下发数超过10次(医疗行业超过20次)
                    errcode82023未关注公众号的用户,1个小时内被下发次数超过5次
                    errcode82024order_no异常,例如所有用户的业务订单号都用同一个
                    errcode82025URL无效
                    errcode820261.服务已下线。2.或服务在审核中且审核期超过了30天

                    正常时的返回JSON数据包示例:

                    {"errcode":0,"errmsg":"ok","result_page_url":"https://city.weixin.qq.com/static/resultpagenew.html?openid=ont-9vjAcIdSU-LgB7ubALAVJO9U&biz_template_id=ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY #wechat_redirect"}

                    注:如未传入结果页样式ID(result_page_style_id),则result_page_url结果为空

                    4、页面报错提示

                    提示信息说明
                    中文显示错误字符集未用utf8
                    参数错误json参数错误
                    非本人,页面打开失败非本人openid;或登录态获取失败
                    请在微信内打开需在微信内打开页面
                    系统错误其他错误


                    auto-fill

                    接入微信城市服务,业务方可以使用小程序auto-fill组件功能,获取用户首次填写过的表单的信息。需接入auto-fill组件,点击此处查看详细说明

                    组件调用说明

                    1、字段描述

                    auto­-fill字段由两部分组成,(group.key)表示分组和具体字段,相同group的字段可以关联在一起,用户的一次选择可以完成全部的填写。另外,开发时,需要给input、textarea、picker指定auto­fill字段。

                    字段定义及具体的group和key字段,详见详见下表。(申请权限时,可选择本表中的group_key,或key)

                    group_keykey字段定义
                    公共字段
                    (可以和任意group_key组合)
                    name姓名
                    id_card_num身份证号
                    phone手机号
                    email邮箱
                    基础信息
                    base_info
                    sex性别
                    birthday生日
                    nationality国籍
                    驾驶证信息
                    driver_licence_info
                    licence_num驾驶证号
                    licence_file_num驾驶证档案编号
                    行驶证信息
                    driver_licence_info
                    licence_plate_num行驶证车牌号
                    engine_num行驶证发动机号
                    licence_hassis_num行驶证车架号
                    地址
                    address_info
                    nationality国家
                    address
                    address_detail详细地址
                    postcode邮编
                    护照
                    passport
                    passport_num护照号
                    validity护照有效期
                    issue_at签发地
                    first_name_zh名字(中文)
                    last_name_zh姓氏(中文)
                    first_name_en名字(英文)
                    last_name_en姓氏(英文)
                    birth_place户口出生地
                    residence_place户口所在地
                    港澳通行证
                    hk_macau_passport
                    passport_num港澳通行证号
                    validity护照有效期
                    issue_at签发地
                    first_name_zh名字(中文)
                    last_name_zh姓氏(中文)
                    first_name_en名字(英文)
                    last_name_en姓氏(英文)
                    birth_place户口出生地
                    residence_place户口所在地
                    社保卡
                    social_security
                    card_num社保卡号

                    调用字段填写表单时,公共字段使用,需调用对应group,如:base_info.name,base_info.phone;passport.name, passport.phone。其它group字段直接调用,如:base_info.email。

                    2、form表单示例

                    <form bindsubmit="submit">  <input class="weui-input" placeholder="姓名" auto-fill="address_info.name"  />  <input class="weui-input" placeholder="手机" auto-fill="address_info.phone" />  <input class="weui-input" placeholder="身份证" auto-fill="address_info.id_card_num" />  <button form-type="submit">submit</button></form>

                    3、测试案例

                    除以上文档,还可下载以下测试案例,测试试用。

                    点击下载测试案例


                    checkrealnameinfo

                    接入微信城市服务,开发者小程序可以使用实名信息校验接口。主要实现的功能是,在用户同意情况下,通过微信城市服务去校验用户(或业务方)输入的实名信息,是否正确且与用户在“开通微信支付”时,预留的实名信息一致。此接口与接入城市服务的开放范围一致,需申请权限可点击此处查看详细说明

                    接口文档说明

                    1、业务流程说明

                    1. 第一步:业务方小程序的界面,需要实现实名信息校验时,需根据接口文档提供的path跳转至微信城市服务提供的小程序授权页。
                    2. 第二步:用户在微信授权页点击同意确认后,微信会回跳至业务方小程序,并带上code参数(code参数包含在返回的extraData)。
                    3. 第三步:业务方页面获得code之后,需要通过后台调用微信提供的后台API,进行实名信息的校验。校验完成后,业务方再根据具体情况,完成自有的业务流程。

                    2、获取code参数

                    根据4.1描述的步骤,调用后台API校验实名信息时,需要先获取code参数。获取方式如下:

                    1、请求方式:

                    跳转至微信城市服务提供的appid和path appid:wx308bd2aeb83d3345 path:subPages/city/wxpay-auth/main

                    2、应答方式:

                    用户完成确认同意后,会跳回至业务方小程序,并在extraData字段中带上调用后台接口所需的code,即extraData中的code字段。 如需了解如何处理extraData字段,可以点击此处查看更多

                    3、后台校验实名信息的API

                    注:此后台API,与小程序API使用方式一致。如需了解小程序API使用方式,请点击此处查看详细说明

                    1、请求方式:POST

                    2、请求地址:

                    https://api.weixin.qq.com/intp/realname/checkrealnameinfo?access_token=ACCESSTOKEN

                    说明:此处的access_token获取方式,可点击此处参考详细说明

                    3、请求格式:JSON

                    4、请求参数:

                    字段类型说明备注
                    openidstring用户在业务方下的openid与申请权限时提供的业务方的小程序appid保持一致
                    real_namestring姓名需要校验的姓名
                    cred_idstring证件号需要校验的证件号
                    cred_typestring默认为1,即身份证目前暂只支持身份证
                    codestring回调获取的code通过小程序回跳获取的code参数

                    5、返回字段:

                    字段类型说明备注
                    errcodeint0为接口调用成功错误码
                    errmsgstring失败时的错误提示错误原因
                    verify_openidstringV_OP_NA:用户暂未实名认证;V_OP_NM_MA:用户与姓名匹配;V_OP_NM_UM:用户与姓名不匹配。有多个结果时用分号”;”连接;
                    verify_real_namestringverify_openid 为V_OP_NM_MA 时返回:V_NM_ID_MA:姓名与证件号匹配;V_NM_ID_UM:姓名与证件号不匹配。校验结果


                    框架

                    小程序开发框架的目标是通过尽可能简单、高效的方式让开发者可以在微信中开发具有原生APP体验的服务。

                    框架提供了自己的视图层描述语言WXMLWXSS,以及基于JavaScript的逻辑层框架,并在视图层与逻辑层间提供了数据传输和事件系统,可以让开发者可以方便的聚焦于数据与逻辑上。


                    响应的数据绑定

                    框架的核心是一个响应的数据绑定系统。

                    整个系统分为两块视图层(View)逻辑层(App Service)

                    框架可以让数据与视图非常简单地保持同步。当做数据修改的时候,只需要在逻辑层修改数据,视图层就会做相应的更新。

                    通过这个简单的例子来看:

                    <!-- Thie 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,可以方便的调起微信提供的能力,如获取用户信息本地存储支付功能等。


                    文件结构

                    MINA程序包含一个描述整体程序的app和多个描述各自页面的page。

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

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

                    一个MINA页面由四个文件组成,分别是:

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

                    注意:为了方便开发者减少配置项,我们规定描述页面的这四个文件必须具有相同的路径与文件名。

                    全局配置

                    小程序根目录下的 app.json 文件用来对微信小程序进行全局配置。文件内容为一个 JSON 对象,有以下属性:

                    配置项

                    属性类型必填描述最低版本
                    entryPagePathstring小程序默认启动首页
                    pagesstring[]页面路径列表
                    windowObject全局的默认窗口表现
                    tabBarObject底部 tab 栏的表现
                    networkTimeoutObject网络超时时间
                    debugboolean是否开启 debug 模式,默认关闭
                    functionalPagesboolean是否启用插件功能页,默认关闭2.1.0
                    subpackagesObject[]分包结构配置1.7.3
                    workersstringWorker 代码放置的目录1.9.90
                    requiredBackgroundModesstring[]需要在后台使用的能力,如「音乐播放」
                    pluginsObject使用到的插件1.9.6
                    preloadRuleObject分包预下载规则2.3.0
                    resizablebooleanPC 小程序是否支持用户任意改变窗口大小(包括最大化窗口);iPad 小程序是否支持屏幕旋转。默认关闭2.3.0
                    usingComponentsObject全局自定义组件配置开发者工具 1.02.1810190
                    permissionObject小程序接口权限相关设置微信客户端 7.0.0
                    sitemapLocationstring指明 sitemap.json 的位置
                    stylestring指定使用升级后的weui样式2.8.0
                    useExtendedLibObject指定需要引用的扩展库2.2.1
                    entranceDeclareObject微信消息用小程序打开微信客户端7.0.9
                    darkmodeboolean小程序支持 DarkMode2.11.0
                    themeLocationstring指明 theme.json 的位置,darkmode为true为必填开发者工具 1.03.2004271
                    lazyCodeLoadingstring配置自定义组件代码按需注入2.11.1
                    singlePageObject单页模式相关配置2.12.0

                    entryPagePath

                    指定小程序的默认启动路径(首页),常见情景是从微信聊天列表页下拉启动、小程序列表启动等。如果不填,将默认为 pages 列表的第一项。不支持带页面路径参数。

                    {  "entryPagePath": "pages/index/index"}

                    pages

                    用于指定小程序由哪些页面组成,每一项都对应一个页面的 路径(含文件名) 信息。文件名不需要写文件后缀,框架会自动去寻找对应位置的 .json, .js, .wxml, .wxss 四个文件进行处理。

                    未指定 entryPagePath 时,数组的第一项代表小程序的初始页面(首页)。

                    小程序中新增/减少页面,都需要对 pages 数组进行修改。

                    如开发目录为:

                    ├── app.js├── app.json├── app.wxss├── pages│   │── index│   │   ├── index.wxml│   │   ├── index.js│   │   ├── index.json│   │   └── index.wxss│   └── logs│       ├── logs.wxml│       └── logs.js└── utils

                    则需要在 app.json 中写

                    {  "pages": ["pages/index/index", "pages/logs/logs"]}

                    window

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

                    属性类型默认值描述最低版本
                    navigationBarBackgroundColorHexColor#000000导航栏背景颜色,如 #000000
                    navigationBarTextStylestringwhite导航栏标题颜色,仅支持 black / white
                    navigationBarTitleTextstring导航栏标题文字内容
                    navigationStylestringdefault导航栏样式,仅支持以下值:
                    default 默认样式
                    custom 自定义导航栏,只保留右上角胶囊按钮。参见注 2。
                    微信客户端 6.6.0
                    backgroundColorHexColor#ffffff窗口的背景色
                    backgroundTextStylestringdark下拉 loading 的样式,仅支持 dark / light
                    backgroundColorTopstring#ffffff顶部窗口的背景色,仅 iOS 支持微信客户端 6.5.16
                    backgroundColorBottomstring#ffffff底部窗口的背景色,仅 iOS 支持微信客户端 6.5.16
                    enablePullDownRefreshbooleanfalse是否开启全局的下拉刷新。
                    详见 Page.onPullDownRefresh
                    onReachBottomDistancenumber50页面上拉触底事件触发时距页面底部距离,单位为 px。
                    详见 Page.onReachBottom
                    pageOrientationstringportrait屏幕旋转设置,支持 auto / portrait / landscape
                    详见 响应显示区域变化
                    2.4.0 (auto) / 2.5.0 (landscape)
                    • 注 1:HexColor(十六进制颜色值),如"#ff00ff"
                    • 注 2:关于navigationStyle客户端 7.0.0 以下版本,navigationStyle 只在 app.json 中生效。客户端 6.7.2 版本开始,navigationStyle: custom 对 web-view 组件无效开启 custom 后,低版本客户端需要做好兼容。开发者工具基础库版本切到 1.7.0(不代表最低版本,只供调试用)可方便切到旧视觉

                    如:

                    {  "window": {    "navigationBarBackgroundColor": "#ffffff",    "navigationBarTextStyle": "black",    "navigationBarTitleText": "微信接口功能演示",    "backgroundColor": "#eeeeee",    "backgroundTextStyle": "light"  }}

                    tabBar

                    如果小程序是一个多 tab 应用(客户端窗口的底部或顶部有 tab 栏可以切换页面),可以通过 tabBar 配置项指定 tab 栏的表现,以及 tab 切换时显示的对应页面。

                    属性类型必填默认值描述最低版本
                    colorHexColortab 上的文字默认颜色,仅支持十六进制颜色
                    selectedColorHexColortab 上的文字选中时的颜色,仅支持十六进制颜色
                    backgroundColorHexColortab 的背景色,仅支持十六进制颜色
                    borderStylestringblacktabbar 上边框的颜色, 仅支持 black / white
                    listArraytab 的列表,详见 list 属性说明,最少 2 个、最多 5 个 tab
                    positionstringbottomtabBar 的位置,仅支持 bottom / top
                    custombooleanfalse自定义 tabBar,见详情2.5.0

                    其中 list 接受一个数组,只能配置最少 2 个、最多 5 个 tab。tab 按数组的顺序排序,每个项都是一个对象,其属性值如下:

                    属性类型必填说明
                    pagePathstring页面路径,必须在 pages 中先定义
                    textstringtab 上按钮文字
                    iconPathstring图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px,不支持网络图片。
                    当 position 为 top 时,不显示 icon。
                    selectedIconPathstring选中时的图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px,不支持网络图片。
                    当 position 为 top 时,不显示 icon。

                    networkTimeout

                    各类网络请求的超时时间,单位均为毫秒。

                    属性类型必填默认值说明
                    requestnumber60000wx.request 的超时时间,单位:毫秒。
                    connectSocketnumber60000wx.connectSocket 的超时时间,单位:毫秒。
                    uploadFilenumber60000wx.uploadFile 的超时时间,单位:毫秒。
                    downloadFilenumber60000wx.downloadFile 的超时时间,单位:毫秒。

                    debug

                    可以在开发者工具中开启 debug 模式,在开发者工具的控制台面板,调试信息以 info 的形式给出,其信息有 Page 的注册,页面路由,数据更新,事件触发等。可以帮助开发者快速定位一些常见的问题。

                    functionalPages

                    基础库 2.1.0 开始支持,低版本需做兼容处理。

                    插件所有者小程序需要设置这一项来启用插件功能页。

                    subpackages

                    微信客户端 6.6.0 ,基础库 1.7.3 及以上版本支持

                    启用分包加载时,声明项目分包结构。

                    写成 subPackages 也支持。

                    workers

                    基础库 1.9.90 开始支持,低版本需做兼容处理。

                    使用 Worker 处理多线程任务时,设置 Worker 代码放置的目录

                    requiredBackgroundModes

                    微信客户端 6.7.2 及以上版本支持

                    申明需要后台运行的能力,类型为数组。目前支持以下项目:

                    • audio: 后台音乐播放
                    • location: 后台定位

                    如:

                    {  "pages": ["pages/index/index"],  "requiredBackgroundModes": ["audio", "location"]}

                    注:在此处申明了后台运行的接口,开发版和体验版上可以直接生效,正式版还需通过审核。

                    plugins

                    基础库 1.9.6 开始支持,低版本需做兼容处理。

                    声明小程序需要使用的插件。

                    preloadRule

                    基础库 2.3.0 开始支持,低版本需做兼容处理。

                    声明分包预下载的规则。

                    resizable

                    基础库 2.3.0 开始支持,低版本需做兼容处理。

                    在 iPad 上运行的小程序可以设置支持屏幕旋转。

                    在 PC 上运行的小程序,用户可以按照任意比例拖动窗口大小,也可以在小程序菜单中最大化窗口

                    usingComponents

                    开发者工具 1.02.1810190 及以上版本支持

                    在此处声明的自定义组件视为全局自定义组件,在小程序内的页面或自定义组件中可以直接使用而无需再声明。

                    permission

                    微信客户端 7.0.0 及以上版本支持

                    小程序接口权限相关设置。字段类型为 Object,结构为:

                    属性类型必填默认值描述
                    scope.userLocationPermissionObject位置相关权限声明

                    PermissionObject 结构

                    属性类型必填默认值说明
                    descstring小程序获取权限时展示的接口用途说明。最长 30 个字符

                    如:

                    {  "pages": ["pages/index/index"],  "permission": {    "scope.userLocation": {      "desc": "你的位置信息将用于小程序位置接口的效果展示" // 高速公路行驶持续后台定位    }  }}

                    sitemapLocation

                    指明 sitemap.json 的位置;默认为 'sitemap.json' 即在 app.json 同级目录下名字的 sitemap.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,}

                    style

                    基础库 2.8.0 开始支持,低版本需做兼容处理。

                    微信客户端 7.0 开始,UI 界面进行了大改版。小程序也进行了基础组件的样式升级。app.json 中配置 "style": "v2"可表明启用新版的组件样式。

                    本次改动涉及的组件有 button icon radio checkbox switch slider。可前往小程序示例进行体验。

                    useExtendedLib

                    基础库 2.2.1 开始支持,低版本需做兼容处理。
                    最新的 nightly 版开发者工具开始支持,同时基础库从支持 npm 的版本(2.2.1)起支持

                    指定需要引用的扩展库。目前支持以下项目:

                    • kbone: 多端开发框架
                    • weui: WeUI 组件库

                    指定后,相当于引入了对应扩展库相关的最新版本的 npm 包,同时也不占用小程序的包体积。目前暂不支持在分包中引用。用法如下:

                    {  "useExtendedLib": {    "kbone": true,    "weui": true  }}

                    entranceDeclare

                    微信客户端 7.0.9 及以上版本支持,iOS 暂不支持

                    聊天位置消息用打车类小程序打开,详情参考。

                    "entranceDeclare": {    "locationMessage": {        "path": "pages/index/index",        "query": "foo=bar"    }}

                    darkmode

                    开发者工具 1.03.2004271 及以上版本支持,基础库 2.11.0 及以上版本支持

                    微信iOS客户端 7.0.12 版本、Android客户端 7.0.13 版本正式支持 DarkMode,可通过配置"darkmode": true表示当前小程序可适配 DarkMode,所有基础组件均会根据系统主题展示不同的默认样式,navigation bar 和 tab bar 也会根据开发者的配置自动切换。

                    配置后,请根据DarkMode 适配指南自行完成基础样式以外的适配工作。

                    {  "darkmode": true}

                    themeLocation

                    自定义 theme.json 的路径,当配置"darkmode":true时,当前配置文件为必填项。

                    {  "themeLocation": "/path/to/theme.json"}

                    lazyCodeLoading

                    基础库 2.11.1 及以上版本支持,2.11.1 以下兼容但无优化效果

                    通常情况下,在小程序启动期间,所有页面及自定义组件的代码都会进行注入,当前页面没有使用到的自定义组件和页面在注入后其实并没有被使用。

                    自基础库版本 2.11.1 起,小程序支持有选择地注入必要的代码,以降低小程序的启动时间和运行时内存。

                    {  "lazyCodeLoading": "requiredComponents"}

                    当配置了这一项时,小程序仅注入当前页面需要的自定义组件和页面代码,在页面中必然不会用到的自定义组件不会被加载和初始化。

                    注意:添加这项配置后,未使用到的代码文件将不被执行。

                    singlePage

                    基础库 2.11.3 及以上版本支持,目前分享到朋友圈 (Beta) 后打开会进入单页模式

                    单页模式相关配置

                    属性类型必填默认值描述
                    navigationBarFitString默认自动调整,若原页面是自定义导航栏,则为 float,否则为 squeezed导航栏与页面的相交状态,值为 float 时表示导航栏浮在页面上,与页面相交;值为 squeezed 时表示页面被导航栏挤压,与页面不相交


                    页面配置

                    每一个小程序页面也可以使用 .json 文件来对本页面的窗口表现进行配置。页面中配置项在当前页面会覆盖 app.json 的 window 中相同的配置项。文件内容为一个 JSON 对象,有以下属性:

                    配置项

                    属性类型默认值描述最低版本
                    navigationBarBackgroundColorHexColor#000000导航栏背景颜色,如 #000000
                    navigationBarTextStylestringwhite导航栏标题颜色,仅支持 black / white
                    navigationBarTitleTextstring导航栏标题文字内容
                    navigationStylestringdefault导航栏样式,仅支持以下值:
                    default 默认样式
                    custom 自定义导航栏,只保留右上角胶囊按钮
                    微信客户端 7.0.0
                    backgroundColorHexColor#ffffff窗口的背景色
                    backgroundTextStylestringdark下拉 loading 的样式,仅支持 dark / light
                    backgroundColorTopstring#ffffff顶部窗口的背景色,仅 iOS 支持微信客户端 6.5.16
                    backgroundColorBottomstring#ffffff底部窗口的背景色,仅 iOS 支持微信客户端 6.5.16
                    enablePullDownRefreshbooleanfalse是否开启当前页面下拉刷新。
                    详见 Page.onPullDownRefresh
                    onReachBottomDistancenumber50页面上拉触底事件触发时距页面底部距离,单位为px。
                    详见 Page.onReachBottom
                    pageOrientationstringportrait屏幕旋转设置,支持 auto / portrait / landscape
                    详见 响应显示区域变化
                    2.4.0 (auto) / 2.5.0 (landscape)
                    disableScrollbooleanfalse设置为 true 则页面整体不能上下滚动。
                    只在页面配置中有效,无法在 app.json 中设置
                    usingComponentsObject页面自定义组件配置1.6.3
                    stylestringdefault启用新版的组件样式2.10.2
                    singlePageObject单页模式相关配置2.12.0
                    页面配置中只能设置 app.json 中 window 对应的配置项,以决定本页面的窗口表现,所以无需写 window 这个属性。

                    singlePage

                    基础库 2.11.3 及以上版本支持,目前分享到朋友圈 (Beta) 后打开会进入单页模式

                    单页模式相关配置

                    属性类型必填默认值描述
                    navigationBarFitString默认自动调整,若原页面是自定义导航栏,则为 float,否则为 squeezed导航栏与页面的相交状态,值为 float 时表示导航栏浮在页面上,与页面相交;值为 squeezed 时表示页面被导航栏挤压,与页面不相交

                    配置示例

                    {  "navigationBarBackgroundColor": "#ffffff",  "navigationBarTextStyle": "black",  "navigationBarTitleText": "微信接口功能演示",  "backgroundColor": "#eeeeee",  "backgroundTextStyle": "light"}


                    微信现已开放小程序内搜索,开发者可以通过 sitemap.json 配置,或者管理后台页面收录开关来配置其小程序页面是否允许微信索引。当开发者允许微信索引时,微信会通过爬虫的形式,为小程序的页面内容建立索引。当用户的搜索词条触发该索引时,小程序的页面将可能展示在搜索结果中。 爬虫访问小程序内页面时,会携带特定的 user-agent:mpcrawler 及场景值:1129。需要注意的是,若小程序爬虫发现的页面数据和真实用户的呈现不一致,那么该页面将不会进入索引中。

                    sitemap 配置

                    小程序根目录下的 sitemap.json 文件用于配置小程序及其页面是否允许被微信索引,文件内容为一个 JSON 对象,如果没有 sitemap.json ,则默认为所有页面都允许被索引;sitemap.json 有以下属性:

                    配置项

                    属性类型必填描述
                    rulesObject[]索引规则列表

                    rules

                    rules 配置项指定了索引规则,每项规则为一个JSON对象,属性如下所示:

                    属性类型必填默认值取值取值说明
                    actionstring"allow""allow"、"disallow"命中该规则的页面是否能被索引
                    pagestring"*"、页面的路径* 表示所有页面,不能作为通配符使用
                    paramsstring[][]当 page 字段指定的页面在被本规则匹配时可能使用的页面参数名称的列表(不含参数值)
                    matchingstring"inclusive"参考 matching 取值说明当 page 字段指定的页面在被本规则匹配时,此参数说明 params 匹配方式
                    priorityNumber优先级,值越大则规则越早被匹配,否则默认从上到下匹配

                    matching 取值说明

                    说明
                    exact当小程序页面的参数列表等于 params 时,规则命中
                    inclusive当小程序页面的参数列表包含 params 时,规则命中
                    exclusive当小程序页面的参数列表与 params 交集为空时,规则命中
                    partial当小程序页面的参数列表与 params 交集不为空时,规则命中

                    配置示例

                    示例1

                    {  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "exact"  }, {    "action": "disallow",    "page": "path/to/page"  }]}
                    • path/to/page?a=1&b=2 => 优先索引
                    • path/to/page => 不被索引
                    • path/to/page?a=1 => 不被索引
                    • path/to/page?a=1&b=2&c=3 => 不被索引
                    • 其他页面都会被索引

                    示例2

                    {  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "inclusive"  }, {    "action": "disallow",    "page": "path/to/page"  }]}
                    • path/to/page?a=1&b=2 => 优先索引
                    • path/to/page?a=1&b=2&c=3 => 优先索引
                    • path/to/page => 不被索引
                    • path/to/page?a=1 => 不被索引
                    • 其他页面都会被索引

                    示例3

                    {  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "exclusive"  }, {    "action": "disallow",    "page": "path/to/page"  }]}
                    • path/to/page => 优先索引
                    • path/to/page?c=3 => 优先索引
                    • path/to/page?a=1 => 不被索引
                    • path/to/page?a=1&b=2 => 不被索引
                    • 其他页面都会被索引

                    示例4

                    {  "rules":[{    "action": "allow",    "page": "path/to/page",    "params": ["a", "b"],    "matching": "partial"  }, {    "action": "disallow",    "page": "path/to/page"  }]}
                    • path/to/page?a=1 => 优先索引
                    • path/to/page?a=1&b=2 => 优先索引
                    • path/to/page => 不被索引
                    • path/to/page?c=3 => 不被索引
                    • 其他页面都会被索引

                    注:没有 sitemap.json 则默认所有页面都能被索引

                    注:{"action": "allow", "page": "*"} 是优先级最低的默认规则,未显式指明 "disallow" 的都默认被索引


                    App(Object object)

                    注册小程序。接受一个 Object 参数,其指定小程序的生命周期回调等。

                    App() 必须在 app.js 中调用,必须调用且只能调用一次。不然会出现无法预期的后果。

                    参数

                    Object object
                    属性类型默认值必填说明最低版本
                    onLaunchfunction生命周期回调——监听小程序初始化。
                    onShowfunction生命周期回调——监听小程序启动或切前台。
                    onHidefunction生命周期回调——监听小程序切后台。
                    onErrorfunction错误监听函数。
                    onPageNotFoundfunction页面不存在监听函数。1.9.90
                    onUnhandledRejectionfunction未处理的 Promise 拒绝事件监听函数。2.10.0
                    onThemeChangefunction监听系统主题变化2.11.0
                    其他any开发者可以添加任意的函数或数据变量到 Object 参数中,用 this 可以访问
                    关于小程序前后台的定义和小程序的运行机制,请参考运行机制章节。

                    示例代码

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

                    onLaunch(Object object)

                    小程序初始化完成时触发,全局只触发一次。参数也可以使用 wx.getLaunchOptionsSync 获取。

                    参数:与 wx.getLaunchOptionsSync 一致

                    onShow(Object object)

                    小程序启动,或从后台进入前台显示时触发。也可以使用 wx.onAppShow 绑定监听。

                    参数:与 wx.onAppShow 一致

                    onHide()

                    小程序从前台进入后台时触发。也可以使用 wx.onAppHide 绑定监听。

                    onError(String error)

                    小程序发生脚本错误或 API 调用报错时触发。也可以使用 wx.onError 绑定监听。

                    参数:与 wx.onError 一致

                    onPageNotFound(Object object)

                    基础库 1.9.90 开始支持,低版本需做兼容处理。

                    小程序要打开的页面不存在时触发。也可以使用 wx.onPageNotFound 绑定监听。注意事项请参考 wx.onPageNotFound。

                    参数:与 wx.onPageNotFound 一致

                    示例代码:

                    App({  onPageNotFound(res) {    wx.redirectTo({      url: 'pages/...'    }) // 如果是 tabbar 页面,请使用 wx.switchTab  }})

                    onUnhandledRejection(Object object)

                    基础库 2.10.0 开始支持,低版本需做兼容处理。

                    小程序有未处理的 Promise 拒绝时触发。也可以使用 wx.onUnhandledRejection 绑定监听。注意事项请参考 wx.onUnhandledRejection。

                    参数:与 wx.onUnhandledRejection 一致

                    onThemeChange(Object object)

                    基础库 2.11.0 开始支持,低版本需做兼容处理。

                    系统切换主题时触发。也可以使用 wx.onThemeChange 绑定监听。

                    参数:与 wx.onThemeChange 一致


                    AppObject getApp(Object object)

                    获取到小程序全局唯一的 App 实例。

                    参数

                    Object object
                    属性类型默认值必填说明最低版本
                    allowDefaultbooleanfalse在 App 未定义时返回默认实现。当App被调用时,默认实现中定义的属性会被覆盖合并到App中。一般用于独立分包2.2.4

                    示例代码

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

                    注意

                    • 不要在定义于 App() 内的函数中,或调用 App 前调用 getApp() ,使用 this 就可以拿到 app 实例。
                    • 通过 getApp() 获取实例之后,不要私自调用生命周期函数。


                    Page(Object object)

                    注册小程序中的一个页面。接受一个 Object 类型参数,其指定页面的初始数据、生命周期回调、事件处理函数等。

                    参数

                    Object object
                    属性类型默认值必填说明
                    dataObject页面的初始数据
                    onLoadfunction生命周期回调—监听页面加载
                    onShowfunction生命周期回调—监听页面显示
                    onReadyfunction生命周期回调—监听页面初次渲染完成
                    onHidefunction生命周期回调—监听页面隐藏
                    onUnloadfunction生命周期回调—监听页面卸载
                    onPullDownRefreshfunction监听用户下拉动作
                    onReachBottomfunction页面上拉触底事件的处理函数
                    onShareAppMessagefunction用户点击右上角转发
                    onShareTimelinefunction用户点击右上角转发到朋友圈
                    onAddToFavoritesfunction用户点击右上角收藏
                    onPageScrollfunction页面滚动触发事件的处理函数
                    onResizefunction页面尺寸改变时触发,详见 响应显示区域变化
                    onTabItemTapfunction当前是 tab 页时,点击 tab 时触发
                    其他any开发者可以添加任意的函数或数据到 Object 参数中,在页面的函数中用 this 可以访问

                    示例代码

                    //index.jsPage({  data: {    text: "This is page data."  },  onLoad: function(options) {    // Do some initialize when page load.  },  onShow: function() {    // Do something when page show.  },  onReady: function() {    // Do something when page ready.  },  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  },  onResize: function() {    // Do something when page resize  },  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

                    data 是页面第一次渲染使用的初始数据。

                    页面加载时,data 将会以JSON字符串的形式由逻辑层传至渲染层,因此data中的数据必须是可以转成JSON的类型:字符串,数字,布尔值,对象,数组。

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

                    示例代码:

                    在开发者工具中预览效果

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

                    生命周期回调函数

                    生命周期的触发以及页面的路由方式详见

                    onLoad(Object query)

                    页面加载时触发。一个页面只会调用一次,可以在 onLoad 的参数中获取打开当前页面路径中的参数。

                    参数:

                    名称类型说明
                    queryObject打开当前页面路径中的参数

                    onShow()

                    页面显示/切入前台时触发。

                    onReady()

                    页面初次渲染完成时触发。一个页面只会调用一次,代表页面已经准备妥当,可以和视图层进行交互。

                    注意:对界面内容进行设置的 API 如wx.setNavigationBarTitle,请在onReady之后进行。详见生命周期

                    onHide()

                    页面隐藏/切入后台时触发。 如 wx.navigateTo 或底部 tab 切换到其他页面,小程序切入后台等。

                    onUnload()

                    页面卸载时触发。如wx.redirectTo或wx.navigateBack到其他页面时。

                    页面事件处理函数

                    onPullDownRefresh()

                    监听用户下拉刷新事件。

                    • 需要在app.json的window选项中或页面配置中开启enablePullDownRefresh。
                    • 可以通过wx.startPullDownRefresh触发下拉刷新,调用后触发下拉刷新动画,效果与用户手动下拉刷新一致。
                    • 当处理完数据刷新后,wx.stopPullDownRefresh可以停止当前页面的下拉刷新。

                    onReachBottom()

                    监听用户上拉触底事件。

                    • 可以在app.json的window选项中或页面配置中设置触发距离onReachBottomDistance。
                    • 在触发距离内滑动期间,本事件只会被触发一次。

                    onPageScroll(Object object)

                    监听用户滑动页面事件。

                    参数 Object object:

                    属性类型说明
                    scrollTopNumber页面在垂直方向已滚动的距离(单位px)

                    注意:请只在需要的时候才在 page 中定义此方法,不要定义空方法。以减少不必要的事件派发对渲染层-逻辑层通信的影响。 注意:请避免在 onPageScroll 中过于频繁的执行 setData 等引起逻辑层-渲染层通信的操作。尤其是每次传输大量数据,会影响通信耗时。

                    onAddToFavorites(Object object)

                    本接口为 Beta 版本,安卓 7.0.15 版本起支持,暂只在安卓平台支持

                    监听用户点击右上角菜单“收藏”按钮的行为,并自定义收藏内容。

                    参数 Object object:

                    参数类型说明
                    webviewUrlString页面中包含web-view组件时,返回当前web-view的url

                    此事件处理函数需要 return 一个 Object,用于自定义收藏内容:

                    字段说明默认值
                    title自定义标题页面标题或账号名称
                    imageUrl自定义图片,显示图片长宽比为 1:1页面截图
                    query自定义query字段当前页面的query

                    示例代码

                    Page({  onAddToFavorites(res) {    // webview 页面返回 webviewUrl    console.log('WebviewUrl: ', res.webviewUrl)    return {      title: '自定义标题',      imageUrl: 'http://demo.png',      query: 'name=xxx&age=xxx',    }  }})

                    onShareAppMessage(Object object)

                    监听用户点击页面内转发按钮(button 组件 open-type="share")或右上角菜单“转发”按钮的行为,并自定义转发内容。

                    注意:只有定义了此事件处理函数,右上角菜单才会显示“转发”按钮

                    参数 Object object:

                    参数类型说明最低版本
                    fromString转发事件来源。
                    button:页面内转发按钮;
                    menu:右上角转发菜单
                    1.2.4
                    targetObject如果 from 值是 button,则 target 是触发这次转发事件的 button,否则为 undefined1.2.4
                    webViewUrlString页面中包含web-view组件时,返回当前web-view的url1.6.4

                    此事件处理函数需要 return 一个 Object,用于自定义转发内容,返回内容如下:

                    自定义转发内容 基础库 2.8.1 起,分享图支持云图片。

                    字段说明默认值最低版本
                    title转发标题当前小程序名称
                    path转发路径当前页面 path ,必须是以 / 开头的完整路径
                    imageUrl自定义图片路径,可以是本地文件路径、代码包文件路径或者网络图片路径。支持PNG及JPG。显示图片长宽比是 5:4。使用默认截图1.5.0

                    示例代码

                    在开发者工具中预览效果

                    Page({  onShareAppMessage: function (res) {    if (res.from === 'button') {      // 来自页面内转发按钮      console.log(res.target)    }    return {      title: '自定义转发标题',      path: '/page/user?id=123'    }  }})

                    onShareTimeline()

                    基础库 2.11.3 开始支持,低版本需做兼容处理。
                    本接口为 Beta 版本,暂只在 Android 平台支持,详见分享到朋友圈 (Beta)

                    监听右上角菜单“分享到朋友圈”按钮的行为,并自定义发享内容。

                    注意:只有定义了此事件处理函数,右上角菜单才会显示“分享到朋友圈”按钮

                    自定义转发内容

                    事件处理函数返回一个 Object,用于自定义分享内容,不支持自定义页面路径,返回内容如下:

                    字段说明默认值最低版本
                    title自定义标题,即朋友圈列表页上显示的标题当前小程序名称
                    query自定义页面路径中携带的参数,如 path?a=1&b=2 的 “?” 后面部分当前页面路径携带的参数
                    imageUrl自定义图片路径,可以是本地文件或者网络图片。支持 PNG 及 JPG,显示图片长宽比是 1:1。默认使用小程序 Logo

                    onResize(Object object)

                    基础库 2.4.0 开始支持,低版本需做兼容处理。

                    小程序屏幕旋转时触发。详见 响应显示区域变化

                    onTabItemTap(Object object)

                    基础库 1.9.0 开始支持,低版本需做兼容处理。

                    点击 tab 时触发

                    Object 参数说明:

                    参数类型说明最低版本
                    indexString被点击tabItem的序号,从0开始1.9.0
                    pagePathString被点击tabItem的页面路径1.9.0
                    textString被点击tabItem的按钮文字1.9.0

                    示例代码:

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

                    组件事件处理函数

                    Page 中还可以定义组件事件处理函数。在渲染层的组件中加入事件绑定,当事件被触发时,就会执行 Page 中定义的事件处理函数。

                    示例代码:

                    在开发者工具中预览效果

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

                    Page.route

                    基础库 1.2.0 开始支持,低版本需做兼容处理。

                    到当前页面的路径,类型为String。

                    Page({  onShow: function() {    console.log(this.route)  }})

                    Page.prototype.setData(Object data, Function callback)

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

                    参数说明

                    字段类型必填描述最低版本
                    dataObject这次要改变的数据
                    callbackFunctionsetData引起的界面更新渲染完毕后的回调函数1.5.0

                    Object 以 key: value 的形式表示,将 this.data 中的 key 对应的值改变成 value。

                    其中 key 可以以数据路径的形式给出,支持改变数组中的某一项或对象的某个属性,如 array[2].message,a.b.c.d,并且不需要在 this.data 中预先定义。

                    注意:

                    1. 直接修改 this.data 而不调用 this.setData 是无法改变页面的状态的,还会造成数据不一致。
                    2. 仅支持设置可 JSON 化的数据。
                    3. 单次设置的数据不能超过1024kB,请尽量避免一次设置过多的数据。
                    4. 请不要把 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.jsPage({  data: {    text: 'init data',    num: 0,    array: [{text: 'init data'}],    object: {      text: 'init data'    }  },  changeText: function() {    // this.data.text = 'changed data' // 不要直接修改 this.data    // 应该使用 setData    this.setData({      text: 'changed data'    })  },  changeNum: function() {    // 或者,可以修改 this.data 之后马上用 setData 设置一下修改了的字段    this.data.num = 1    this.setData({      num: this.data.num    })  },  changeItemInArray: function() {    // 对于对象或数组字段,可以直接修改一个其下的子字段,这样做通常比修改整个对象或数组更好    this.setData({      'array[0].text':'changed data'    })  },  changeItemInObject: function(){    this.setData({      'object.text': 'changed data'    });  },  addNewField: function() {    this.setData({      'newField.text': 'new data'    })  }})

                    页面间通信

                    基础库 2.7.3 开始支持,低版本需做兼容处理。

                    如果一个页面由另一个页面通过 wx.navigateTo 打开,这两个页面间将建立一条数据通道:

                    • 被打开的页面可以通过 this.getOpenerEventChannel() 方法来获得一个 EventChannel 对象;
                    • wx.navigateTo 的 success 回调中也包含一个 EventChannel 对象。

                    这两个 EventChannel 对象间可以使用 emit 和 on 方法相互发送、监听事件。


                    PageObject[] getCurrentPages()

                    获取当前页面栈。数组中第一个元素为首页,最后一个元素为当前页面。

                    注意:

                    • 不要尝试修改页面栈,会导致路由以及页面状态错误。
                    • 不要在 App.onLaunch 的时候调用 getCurrentPages(),此时 page 还没有生成。


                    Component(Object object)

                    创建自定义组件,接受一个 Object 类型的参数。

                    参数

                    Object object

                    定义段类型是否必填描述最低版本
                    propertiesObject Map组件的对外属性,是属性名到属性设置的映射表
                    dataObject组件的内部数据,和 properties 一同用于组件的模板渲染
                    observersObject组件数据字段监听器,用于监听 properties 和 data 的变化,参见 数据监听器2.6.1
                    methodsObject组件的方法,包括事件响应函数和任意的自定义方法,关于事件响应函数的使用,参见 组件间通信与事件
                    behaviorsString Array类似于mixins和traits的组件间代码复用机制,参见 behaviors
                    createdFunction组件生命周期函数-在组件实例刚刚被创建时执行,注意此时不能调用 setData )
                    attachedFunction组件生命周期函数-在组件实例进入页面节点树时执行)
                    readyFunction组件生命周期函数-在组件布局完成后执行)
                    movedFunction组件生命周期函数-在组件实例被移动到节点树另一个位置时执行)
                    detachedFunction组件生命周期函数-在组件实例被从页面节点树移除时执行)
                    relationsObject组件间关系定义,参见 组件间关系
                    externalClassesString Array组件接受的外部样式类,参见 外部样式类
                    optionsObject Map一些选项(文档中介绍相关特性时会涉及具体的选项设置,这里暂不列举)
                    lifetimesObject组件生命周期声明对象,参见 组件生命周期2.2.3
                    pageLifetimesObject组件所在页面的生命周期声明对象,参见 组件生命周期2.2.3
                    definitionFilterFunction定义段过滤器,用于自定义组件扩展,参见 自定义组件扩展2.2.3

                    生成的组件实例可以在组件的方法、生命周期函数和属性 observer 中通过 this 访问。组件包含一些通用属性和方法。

                    属性名类型描述
                    isString组件的文件路径
                    idString节点id
                    datasetString节点dataset
                    dataObject组件数据,包括内部数据和属性值
                    propertiesObject组件数据,包括内部数据和属性值(与 data 一致)
                    方法名参数描述最低版本
                    setDataObject newData设置data并执行视图层渲染
                    hasBehaviorObject behavior检查组件是否具有 behavior (检查时会递归检查被直接或间接引入的所有behavior)
                    triggerEventString name, Object detail, Object options触发事件,参见 组件间通信与事件
                    createSelectorQuery创建一个 SelectorQuery 对象,选择器选取范围为这个组件实例内
                    createIntersectionObserver创建一个 IntersectionObserver 对象,选择器选取范围为这个组件实例内
                    createMediaQueryObserver创建一个 MediaQueryObserver 对象2.11.1
                    selectComponentString selector使用选择器选择组件实例节点,返回匹配到的第一个组件实例对象(会被 wx://component-export 影响)
                    selectAllComponentsString selector使用选择器选择组件实例节点,返回匹配到的全部组件实例对象组成的数组(会被 wx://component-export 影响)
                    selectOwnerComponent选取当前组件节点所在的组件实例(即组件的引用者),返回它的组件实例对象(会被 wx://component-export 影响)2.8.2
                    getRelationNodesString relationKey获取这个关系所对应的所有关联节点,参见 组件间关系
                    groupSetDataFunction callback立刻执行 callback ,其中的多个 setData 之间不会触发界面绘制(只有某些特殊场景中需要,如用于在不同组件同时 setData 时进行界面绘制同步)2.4.0
                    getTabBar返回当前页面的 custom-tab-bar 的组件实例,详见自定义 tabBar2.6.2
                    getPageId返回页面标识符(一个字符串),可以用来判断几个自定义组件实例是不是在同一个页面内2.7.1
                    animateString selector, Array keyframes, Number duration, Function callback执行关键帧动画,详见动画2.9.0
                    clearAnimationString selector, Object options, Function callback清除关键帧动画,详见动画2.9.0

                    代码示例:

                    在开发者工具中预览效果

                    Component({  behaviors: [],  // 属性定义(详情参见下文)  properties: {    myProperty: { // 属性名      type: String,      value: ''    },    myProperty2: String // 简化的定义方式  },  data: {}, // 私有数据,可用于模板渲染  lifetimes: {    // 生命周期函数,可以为函数,或一个在methods段中定义的方法名    attached: function () { },    moved: function () { },    detached: function () { },  },  // 生命周期函数,可以为函数,或一个在methods段中定义的方法名  attached: function () { }, // 此处attached的声明会被lifetimes字段中的声明覆盖  ready: function() { },  pageLifetimes: {    // 组件所在页面的生命周期函数    show: function () { },    hide: function () { },    resize: function () { },  },  methods: {    onMyButtonTap: function(){      this.setData({        // 更新属性和数据的方法与更新页面数据的方法类似      })    },    // 内部方法建议以下划线开头    _myPrivateMethod: function(){      // 这里将 data.A[0].B 设为 'myPrivateData'      this.setData({        'A[0].B': 'myPrivateData'      })    },    _propertyChange: function(newVal, oldVal) {    }  }})

                    注意:在 properties 定义段中,属性名采用驼峰写法(propertyName);在 wxml 中,指定属性值时则对应使用连字符写法(component-tag-name property-name="attr value"),应用于数据绑定时采用驼峰写法(attr="")。

                    properties 定义

                    定义段类型是否必填描述最低版本
                    type属性的类型
                    optionalTypesArray属性的类型(可以指定多个)2.6.5
                    value属性的初始值
                    observerFunction属性值变化时的回调函数

                    属性值的改变情况可以使用 observer 来监听。目前,在新版本基础库中不推荐使用这个字段,而是使用 Component 构造器的 observers 字段代替,它更加强大且性能更好。

                    代码示例:

                    Component({  properties: {    min: {      type: Number,      value: 0    },    min: {      type: Number,      value: 0,      observer: function(newVal, oldVal) {        // 属性值变化时执行      }    },    lastLeaf: {      // 这个属性可以是 Number 、 String 、 Boolean 三种类型中的一种      type: Number,      optionalTypes: [String, Object],      value: 0    }  }})

                    属性的类型可以为 String Number Boolean Object Array 其一,也可以为 null 表示不限制类型。

                    多数情况下,属性最好指定一个确切的类型。这样,在 WXML 中以字面量指定属性值时,值可以获得一个确切的类型,如:

                    <custom-comp min="1" max="5" />

                    此时,由于自定义组件的对应属性被规定为 Number 类型, min 和 max 会被赋值为 1 和 5 ,而非 "1" 和 "5" ,即:

                    this.data.min === 1 // truethis.data.max === 5 // true

                    提示:

                    • 使用 this.data 可以获取内部数据和属性值;但直接修改它不会将变更应用到界面上,应使用 setData 修改。
                    • 生命周期函数无法在组件方法中通过 this 访问到。
                    • 属性名应避免以 data 开头,即不要命名成 dataXyz 这样的形式,因为在 WXML 中, data-xyz="" 会被作为节点 dataset 来处理,而不是组件属性。
                    • 在一个组件的定义和使用时,组件的属性名和 data 字段相互间都不能冲突(尽管它们位于不同的定义段中)。
                    • 从基础库 2.0.9 开始,对象类型的属性和 data 字段中可以包含函数类型的子字段,即可以通过对象类型的属性字段来传递函数。低于这一版本的基础库不支持这一特性。
                    • bug : 位于 slot 中的自定义组件没有触发 pageLifetimes 中声明的页面生命周期,此问题在 2.5.2 中修复。
                    • bug : 对于 type 为 Object 或 Array 的属性,如果通过该组件自身的 this.setData 来改变属性值的一个子字段,则依旧会触发属性 observer ,且 observer 接收到的 newVal 是变化的那个子字段的值, oldVal 为空, changedPath 包含子字段的字段名相关信息;目前推荐使用 observers 定义段代替。

                    Behavior(Object object)

                    注册一个 behavior,接受一个 Object 类型的参数。

                    参数

                    Object object

                    定义段类型是否必填描述最低版本
                    propertiesObject Map同组件的属性
                    dataObject同组件的数据
                    methodsObject同自定义组件的方法
                    behaviorsString Array引入其它的 behavior
                    createdFunction生命周期函数
                    attachedFunction生命周期函数
                    readyFunction生命周期函数
                    movedFunction生命周期函数
                    detachedFunction生命周期函数

                    代码示例:

                    // my-behavior.jsmodule.exports = Behavior({  behaviors: [],  properties: {    myBehaviorProperty: {      type: String    }  },  data: {    myBehaviorData: {}  },  attached: function(){},  methods: {    myBehaviorMethod: function(){}  }})


                    any require(string path)

                    引入模块。返回模块通过 module.exports 或 exports 暴露的接口。

                    参数

                    名称类型说明
                    pathstring需要引入模块文件相对于当前文件的相对路径,或npm模块名,或npm模块路径。不支持绝对路径

                    示例代码

                    // common.jsfunction sayHello(name) {  console.log(`Hello ${name} !`)}function sayGoodbye(name) {  console.log(`Goodbye ${name} !`)}module.exports.sayHello = sayHelloexports.sayGoodbye = sayGoodbye
                    var common = require('common.js')Page({  helloMINA: function() {    common.sayHello('MINA')  },  goodbyeMINA: function() {    common.sayGoodbye('MINA')  }})

                    Object module

                    当前模块对象

                    属性

                    属性类型说明
                    exportsObject模块向外暴露的对象,使用require引用该模块时可以获取

                    示例代码

                    // common.jsfunction sayHello(name) {  console.log(`Hello ${name} !`)}function sayGoodbye(name) {  console.log(`Goodbye ${name} !`)}module.exports.sayHello = sayHelloexports.sayGoodbye = sayGoodbye

                    Object exports

                    module.exports 的引用

                    示例代码

                    // common.jsfunction sayHello(name) {  console.log(`Hello ${name} !`)}function sayGoodbye(name) {  console.log(`Goodbye ${name} !`)}module.exports.sayHello = sayHelloexports.sayGoodbye = sayGoodbye


                    Object wx

                    小程序 API 全局对象,用于承载小程序能力相关 API。

                    Object wx.env

                    小程序环境变量对象

                    String wx.env.USER_DATA_PATH

                    文件系统中的用户目录路径


                    console

                    向调试面板中打印日志。console 是一个全局对象,可以直接访问。在微信客户端中,向 vConsole 中输出日志。

                    方法:

                    console.debug()

                    向调试面板中打印 debug 日志

                    参数

                    any ...args

                    日志内容,可以有任意多个。


                    console.error()

                    向调试面板中打印 error 日志

                    参数

                    any ...args

                    日志内容,可以有任意多个。


                    console.group(string label)

                    在调试面板中创建一个新的分组。随后输出的内容都会被添加一个缩进,表示该内容属于当前分组。调用 console.groupEnd之后分组结束。

                    参数

                    string label

                    分组标记,可选。

                    注意

                    仅在工具中有效,在 vConsole 中为空函数实现。


                    console.groupEnd()

                    结束由 console.group 创建的分组

                    注意

                    仅在工具中有效,在 vConsole 中为空函数实现。


                    console.info()

                    向调试面板中打印 info 日志

                    参数

                    any ...args

                    日志内容,可以有任意多个。


                    console.log()

                    向调试面板中打印 log 日志

                    参数

                    any ...args

                    日志内容,可以有任意多个


                    console.warn()

                    向调试面板中打印 warn 日志

                    参数

                    any ...args

                    日志内容,可以有任意多个。


                    number setTimeout(function callback, number delay, any rest)

                    设定一个定时器。在定时到期以后执行注册的回调函数

                    参数

                    function callback

                    回调函数

                    number delay

                    延迟的时间,函数的调用会在该延迟之后发生,单位 ms。

                    any rest

                    param1, param2, ..., paramN 等附加参数,它们会作为参数传递给回调函数。

                    返回值

                    number

                    定时器的编号。这个值可以传递给 clearTimeout 来取消该定时。


                    clearTimeout(number timeoutID)

                    取消由 setTimeout 设置的定时器。

                    参数

                    number timeoutID

                    要取消的定时器的 ID


                    number setInterval(function callback, number delay, any rest)

                    设定一个定时器。按照指定的周期(以毫秒计)来执行注册的回调函数

                    参数

                    function callback

                    回调函数

                    number delay

                    执行回调函数之间的时间间隔,单位 ms。

                    any rest

                    param1, param2, ..., paramN 等附加参数,它们会作为参数传递给回调函数。

                    返回值

                    number

                    定时器的编号。这个值可以传递给 clearInterval 来取消该定时。


                    clearInterval(number intervalID)

                    取消由 setInterval 设置的定时器。

                    参数

                    number intervalID

                    要取消的定时器的 ID


                    逻辑层(App Service)


                    小程序开发框架的逻辑层是由JavaScript编写。

                    逻辑层将数据进行处理后发送给视图层,同时接受视图层的事件反馈。在 JavaScript 的基础上,我们做了一些修改,以方便地开发小程序。

                    • 增加 AppPage 方法,进行程序和页面的注册。
                    • 提供丰富的 API,如扫一扫,支付等微信特有能力。
                    • 每个页面有独立的作用域,并提供模块化能力。
                    • 由于框架并非运行在浏览器中,所以 JavaScript 在 web 中一些能力都无法使用,如 document,window 等。
                    • 开发者写的所有代码最终将会打包成一份 JavaScript,并在小程序启动的时候运行,直到小程序销毁。类似 ServiceWorker,所以逻辑层也称之为 App Service。

                    App

                    App()


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

                    object参数说明:

                    属性类型描述触发时机
                    onLaunchFunction生命周期函数--监听小程序初始化当小程序初始化完成时,会触发 onLaunch(全局只触发一次)
                    onShowFunction生命周期函数--监听小程序显示当小程序启动,或从后台进入前台显示,会触发 onShow
                    onHideFunction生命周期函数--监听小程序隐藏当小程序从前台进入后台,会触发 onHide
                    onErrorFunction错误监听函数当小程序发生脚本错误,或者 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 参数

                    字段类型说明
                    pathString打开小程序的路径
                    queryObject打开小程序的query
                    sceneNumber打开小程序的场景值
                    shareTicketStringshareTicket,详见 获取更多转发信息
                    referrerInfoObject当场景为由另一个小程序打开时,返回此字段
                    referrerInfo.appIdString来源小程序的 appId
                    referrerInfo.extraDataObject来源小程序传过来的数据

                    场景值 详见

                    以下场景支持返回 referrerInfo.appId:

                    场景值场景appId 信息含义
                    1020公众号 profile 页相关小程序列表返回来源公众号 appId
                    1035公众号自定义菜单返回来源公众号 appId
                    1036App 分享消息卡片返回来源应用 appId
                    1037小程序打开小程序返回来源小程序 appId
                    1038从另一个小程序返回返回来源小程序 appId
                    1043公众号模板消息返回来源公众号 appId

                    onPageNotFound

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

                    当要打开的页面并不存在时,会回调这个监听器,并带上以下信息:

                    字段类型说明
                    pathString不存在页面的路径
                    queryObject打开不存在页面的 query
                    isEntryPageBoolean是否本次启动的首个页面(例如从分享等入口进来,首个页面是开发者配置的分享页面)

                    开发者可以在 onPageNotFound 回调中进行重定向处理,但必须在回调中同步处理,异步处理(例如 setTimeout 异步执行)无效。

                    示例代码:

                    App({  onPageNotFound(res) {    wx.redirectTo({      url: 'pages/...'    })  }})

                    注意:

                    1. 微信开发者工具暂不支持 onPageNotFound 调试,请使用真机调试
                    2. 如果开发者没有添加 onPageNotFound 监听,当跳转页面不存在时,将推入微信客户端原生的页面不存在提示页面
                    3. 如果 onPageNotFound 回调中又重定向到另一个不存在的页面,将推入微信客户端原生的页面不存在提示页面,并且不在回调 onPageNotFound

                    getApp()


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

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

                    注意:

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

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

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

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

                    场景值列表

                    关于场景值的详细说明和获取方式请参考 指南-场景值

                    场景值ID说明图例
                    1000其他/
                    1001发现栏小程序主入口,「最近使用」列表(基础库2.2.4版本起包含「我的小程序」列表)/
                    1005微信首页顶部搜索框的搜索结果页查看
                    1006发现栏小程序主入口搜索框的搜索结果页查看
                    1007单人聊天会话中的小程序消息卡片查看
                    1008群聊会话中的小程序消息卡片查看
                    1010收藏夹查看
                    1011扫描二维码查看
                    1012长按图片识别二维码查看
                    1013扫描手机相册中选取的二维码查看
                    1014小程序模板消息查看
                    1017前往小程序体验版的入口页查看
                    1019微信钱包(微信客户端7.0.0版本改为支付入口)查看
                    1020公众号 profile 页相关小程序列表(已废弃)查看
                    1022聊天顶部置顶小程序入口(微信客户端6.6.1版本起废弃)/
                    1023安卓系统桌面图标查看
                    1024小程序 profile 页查看
                    1025扫描一维码查看
                    1026发现栏小程序主入口,「附近的小程序」列表查看
                    1027微信首页顶部搜索框搜索结果页「使用过的小程序」列表查看
                    1028我的卡包查看
                    1029小程序中的卡券详情页查看
                    1030自动化测试下打开小程序/
                    1031长按图片识别一维码查看
                    1032扫描手机相册中选取的一维码查看
                    1034微信支付完成页查看
                    1035公众号自定义菜单查看
                    1036App 分享消息卡片查看
                    1037小程序打开小程序查看
                    1038从另一个小程序返回查看
                    1039摇电视查看
                    1042添加好友搜索框的搜索结果页查看
                    1043公众号模板消息查看
                    1044带 shareTicket 的小程序消息卡片 详情查看
                    1045朋友圈广告查看
                    1046朋友圈广告详情页查看
                    1047扫描小程序码查看
                    1048长按图片识别小程序码查看
                    1049扫描手机相册中选取的小程序码查看
                    1052卡券的适用门店列表查看
                    1053搜一搜的结果页查看
                    1054顶部搜索框小程序快捷入口(微信客户端版本6.7.4起废弃)/
                    1056聊天顶部音乐播放器右上角菜单查看
                    1057钱包中的银行卡详情页查看
                    1058公众号文章查看
                    1059体验版小程序绑定邀请页/
                    1064微信首页连Wi-Fi状态栏查看
                    1067公众号文章广告查看
                    1068附近小程序列表广告(已废弃)/
                    1069移动应用查看
                    1071钱包中的银行卡列表页查看
                    1072二维码收款页面查看
                    1073客服消息列表下发的小程序消息卡片查看
                    1074公众号会话下发的小程序消息卡片查看
                    1077摇周边查看
                    1078微信连Wi-Fi成功提示页查看
                    1079微信游戏中心查看
                    1081客服消息下发的文字链查看
                    1082公众号会话下发的文字链查看
                    1084朋友圈广告原生页查看
                    1088会话中查看系统消息,打开小程序/
                    1089微信聊天主界面下拉,「最近使用」栏(基础库2.2.4版本起包含「我的小程序」栏)查看
                    1090长按小程序右上角菜单唤出最近使用历史查看
                    1091公众号文章商品卡片查看
                    1092城市服务入口查看
                    1095小程序广告组件查看
                    1096聊天记录,打开小程序查看
                    1097微信支付签约原生页,打开小程序查看
                    1099页面内嵌插件/
                    1102公众号 profile 页服务预览查看
                    1103发现栏小程序主入口,「我的小程序」列表(基础库2.2.4版本起废弃)/
                    1104微信聊天主界面下拉,「我的小程序」栏(基础库2.2.4版本起废弃)/
                    1106聊天主界面下拉,从顶部搜索结果页,打开小程序/
                    1107订阅消息,打开小程序/
                    1113安卓手机负一屏,打开小程序(三星)/
                    1114安卓手机侧边栏,打开小程序(三星)/
                    1124扫“一物一码”打开小程序/
                    1125长按图片识别“一物一码”/
                    1126扫描手机相册中选取的“一物一码”/
                    1129微信爬虫访问 详情/
                    1131浮窗打开小程序/
                    1133硬件设备打开小程序 详情/
                    1135小程序profile页其他小程序列表,打开小程序查看
                    1146地理位置信息打开出行类小程序查看
                    1148卡包-交通卡,打开小程序/
                    1150扫一扫商品条码结果页打开小程序查看
                    1153“识物”结果页打开小程序查看
                    1154朋友圈内打开“单页模式”查看
                    1155“单页模式”打开小程序查看
                    1169发现栏小程序主入口,各个生活服务入口(例如快递服务、出行服务等)查看


                    Page


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

                    object 参数说明:

                    属性类型描述
                    dataObject页面的初始数据
                    onLoadFunction生命周期函数--监听页面加载
                    onReadyFunction生命周期函数--监听页面初次渲染完成
                    onShowFunction生命周期函数--监听页面显示
                    onHideFunction生命周期函数--监听页面隐藏
                    onUnloadFunction生命周期函数--监听页面卸载
                    onPullDownRefreshFunction页面相关事件处理函数--监听用户下拉动作
                    onReachBottomFunction页面上拉触底事件的处理函数
                    onShareAppMessageFunction用户点击右上角转发
                    onPageScrollFunction页面滚动触发事件的处理函数
                    其他Any开发者可以添加任意的函数或数据到 object 参数中,在页面的函数中用 this 可以访问

                    示例代码:

                    //index.jsPage({  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  },  // 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[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: 页面卸载

                      • redirectTonavigateBack的时候调用。

                    生命周期的调用以及页面的路由方式详见

                    onLoad参数

                    类型说明
                    Object其他页面打开当前页面所调用的 query 参数

                    页面相关事件处理函数


                    • onPullDownRefresh: 下拉刷新

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

                      • 监听用户下拉触底事件。
                    • onPageScroll: 页面滚动

                      • 监听用户滑动页面事件。
                      • 参数为 Object,包含以下字段:
                    字段类型说明
                    scrollTopNumber页面在垂直方向已滚动的距离(单位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


                    route 字段可以获取到当前页面的路径。

                    Page.prototype.setData()


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

                    setData() 参数格式


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

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

                    注意:

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

                    示例代码:

                    <!--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.jsPage({  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 实例的生命周期。

                    1488607970192659


                    页面路由

                    在小程序中所有页面的路由全部由框架进行管理。

                    页面栈

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

                    路由方式页面栈表现
                    初始化新页面入栈
                    打开新页面新页面入栈
                    页面重定向当前页面出栈,新页面入栈
                    页面返回页面不断出栈,直到目标返回页,新页面入栈
                    Tab 切换页面全部出栈,只留下新的 Tab 页面
                    重加载页面全部出栈,只留下新的页面

                    getCurrentPages()

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

                    Tip:不要尝试修改页面栈,会导致路由以及页面状态错误。

                    路由方式

                    对于路由的触发方式以及页面生命周期函数如下:

                    路由方式触发时机路由前页面路由后页面
                    初始化小程序打开的第一个页面 onLoad, onSHow
                    打开新页面调用 API wx.navigateTo 或使用组件 <navigator open-type="navigateTo"/>onHideonLoad, onShow
                    页面重定向调用 API wx.redirectTo 或使用组件 <navigator open-type="redirectTo"/>onUnloadonLoad, onShow
                    页面返回调用 API wx.navigateBack 或使用组件<navigator open-type="navigateBack">或用户按左上角返回按钮onUnloadonShow
                    Tab 切换调用 API wx.switchTab 或使用组件 <navigator open-type="switchTab"/> 或用户切换 Tab 各种情况请参考下表
                    重启动调用 API wx.reLaunch 或使用组件 <navigator open-type="reLaunch"/>onUnloadonLoad, onShow

                    Tab 切换对应的生命周期(以 A、B 页面为 Tabbar 页面,C 是从 A 页面打开的页面,D 页面是从 C 页面打开的页面为例):

                    当前页面路由后页面触发的生命周期(按顺序)
                    AANothing happend
                    ABA.onHide(), B.onLoad(), B.onShow()
                    AB(再次打开)A.onHide(), B.onShow()
                    CAC.onUnload(), A.onShow()
                    CBC.onUnload(), B.onLoad(), B.onShow()
                    DBD.onUnload(), C.onUnload(), B.onLoad(), B.onShow()
                    D(从转发进入)AD.onUnload(), A.onLoad(), A.onShow()
                    D(从转发进入)BD.onUnload(), B.onLoad(), B.onShow()

                    Tips:

                    • navigateTo,redirectTo只能打开非 tabBar 页面。
                    • switchTab 只能打开 tabBar 页面。
                    • reLaunch 可以打开任意页面。
                    • 页面底部的 tabBar 由页面决定,即只要是定义为 tabBar 的页面,底部都有 tabBar。
                    • 调用页面路由带的参数可以在目标页面的onLoad中获取。

                    文件作用域

                    在JavaScript文件中声明的变量和函数只在该文件中有效;不同的文件中可以声明相同名字的变量和函数,不会互相影响。

                    通过全局函数getApp()可以获取全局的应用实例,如果需要全局的数据可以在App()中设置,如:

                    // app.jsApp({  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才能对外暴露接口。

                    需要注意的是:

                    • exportsmodule.exports的一个引用,因此在模块里边随意更改exports的指向会造成未知的错误。所以我们更推荐开发者采用module.exports来暴露模块接口,除非你已经清晰知道这两者的关系。
                    • 小程序目前不支持直接引入node_modules,开发者需要使用到node_modules时候建议拷贝出相关的代码到小程序的目录中。

                    // common.jsfunction sayHello(name) {  console.log('Hello ${name} !')}function sayGoodbye(name) {  console.log('Goodbye ${name} !')}module.exports.sayHello = sayHelloexports.sayGoodbye = sayGoodbye

                    ​在需要使用这些模块的文件中,使用require(path)将公共代码引入。

                    var common = require('common.js')Page({  helloMINA: function() {    common.sayHello('MINA')  }  goodbyeMINA: function() {    common.sayGoodbye('MINA')  }})

                    Tips

                    1. tip:require暂时不支持绝对路径


                    小程序API

                    小程序开发框架MINA提供丰富的微信原生API,可以方便的调起微信提供的能力,如获取用户信息本地存储支付功能等。

                    详细介绍请参考微信小程序API文档

                    视图层


                    • MINA的视图层由WXML与WXSS编写。
                    • 将逻辑层的数据反应成视图,同时将视图层的事件发送给逻辑层。
                    • WXML(WeiXin Markup language)用于描述页面的结构。
                    • WXSS(WeiXin Style Sheet)用于描述页面的样式。
                    • 组件(Component)是视图的基本组成单元。

                    WXML


                    WXML(WeiXin Markup Language)是框架设计的一套标签语言,结合基础组件事件系统,可以构建出页面的结构。

                    用以下一些简单的例子来看看WXML具有什么能力:

                    数据绑定


                    <!--wxml--><view> {{message}} </view>
                    // page.jsPage({  data: {    message: 'Hello MINA!'  }})

                    列表渲染


                    <!--wxml--><view wx:for-items="{{array}}"> {{item}} </view>
                    // page.jsPage({  data: {    array: [1, 2, 3, 4, 5]  }})

                    条件渲染


                    <!--wxml--><view wx:if="{{view == 'WEBVIEW'}}"> WEBVIEW </view><view wx:elif="{{view == 'APP'}}"> APP </view><view wx:else="{{view == 'MINA'}}"> MINA </view>
                    // page.jsPage({  data: {    view: 'MINA'  }})

                    模板


                    <!--wxml--><template name="staffName">  <view>    FirstName: {{firstName}}, LastName: {{lastName}}  </view></template><template is="staffName" data="{{...staffA}}"></template><template is="staffName" data="{{...staffB}}"></template><template is="staffName" data="{{...staffC}}"></template>
                    // page.jsPage({  data: {    staffA: {firstName: 'Hulk', lastName: 'Hu'},    staffB: {firstName: 'Shang', lastName: 'You'},    staffC: {firstName: 'Gideon', lastName: 'Lin'}  }})

                    事件


                    <view bindtap="add"> {{count}} </view>
                    Page({  data: {    count: 1  },  add: function(e) {    this.setData({      count: this.data.count + 1    })  }})

                    具体的能力以及使用方式在以下章节查看:

                    数据绑定列表渲染条件渲染模板事件引用

                    数据绑定

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

                    简单绑定

                    数据绑定使用"Mustache"语法(双大括号)将变量包起来,可以作用于:

                    内容

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

                    组件属性(需要在双引号之内)

                    <view id="item-{{id}}"> </view>
                    Page({  data: {    id: 0  }})

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

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

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

                    true:boolean 类型的 true,代表真值。

                    false: boolean 类型的 false,代表假值。

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

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


                    运算

                    可以在{{}}内进行简单的运算,支持的有如下几种方式:

                    三元运算

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

                    算数运算

                    <view> {{a + b}} + {{c}} + d </view>
                    Page({  data: {    a: 1,    b: 2,    c: 3  }})

                    view中的内容为3 + 3 + d

                    逻辑判断

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

                    字符串运算

                    <view>{{"hello" + name}}</view>
                    Page({  data:{    name:"MINA"  }})

                    数据路径运算

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

                    组合

                    也可以在Mustache内直接进行组合,构成新的对象或者数组。

                    数组

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

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

                    对象

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

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

                    也可以用扩展运算符...来将一个对象展开

                    <template is="objectCombine" data="{{...obj1, ...obj2, e: 5}}"></template>
                    Page({  data: {    obj1: {      a: 1,      b: 2    },    obj2: {      c: 3,      d: 4    }  }})

                    最终组合成的对象是{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'}

                    注意:上述方式可以随意组合,但是如有存在变量名相同的情况,后边的会覆盖前面,如:

                    <template is="objectCombine" data="{{...obj1, ...obj2, a, c: 6}}"></template>
                    Page({  data: {    obj1: {      a: 1,      b: 2    },    obj2: {      b: 3,      c: 4    },    a: 5  }})

                    最终组合成的对象是 {a: 5, b: 3, c: 6}

                    注意: 花括号和引号之间如果有空格,将最终被解析成为字符串

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

                    等同于

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

                    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方法:

                    20200629113357203

                    20200629113319412

                     这个注意了。wx:key还是要加上的,不然一直报这个提示错误

                    20200629145733130



                    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>

                    wx:key


                    如果列表中项目的位置会动态改变或者有新的项目添加到列表中,并且希望列表中的项目保持自己的特征和状态(如 <input/> 中的输入内容,<switch/> 的选中状态),需要使用 wx:key 来指定列表中项目的唯一的标识符。

                    wx:key 的值以两种形式提供

                    1. 字符串,代表在 for 循环的 array 中 item 的某个 property,该 property 的值需要是列表中唯一的字符串或数字,且不能动态改变。
                    2. 保留关键字 *this 代表在 for 循环中的 item 本身,这种表示需要 item 本身是一个唯一的字符串或者数字,如:

                    当数据改变触发渲染层重新渲染的时候,会校正带有 key 的组件,框架会确保他们被重新排序,而不是重新创建,以确保使组件保持自身的状态,并且提高列表渲染时的效率。

                    如不提供 wx:key,会报一个 warning, 如果明确知道该列表是静态,或者不必关注其顺序,可以选择忽略。

                    示例代码:

                    <switch wx:for="{{objectArray}}" wx:key="unique" style="display: block;"> {{item.id}} </switch><button bindtap="switch"> Switch </button><button bindtap="addToFront"> Add to the front </button><switch wx:for="{{numberArray}}" wx:key="*this" style="display: block;"> {{item}} </switch><button bindtap="addNumberToFront"> Add to the front </button>
                    Page({  data: {    objectArray: [      {id: 5, unique: 'unique_5'},      {id: 4, unique: 'unique_4'},      {id: 3, unique: 'unique_3'},      {id: 2, unique: 'unique_2'},      {id: 1, unique: 'unique_1'},      {id: 0, unique: 'unique_0'},    ],    numberArray: [1, 2, 3, 4]  },  switch: function(e) {    const length = this.data.objectArray.length    for (let i = 0; i < length; ++i) {      const x = Math.floor(Math.random() * length)      const y = Math.floor(Math.random() * length)      const temp = this.data.objectArray[x]      this.data.objectArray[x] = this.data.objectArray[y]      this.data.objectArray[y] = temp    }    this.setData({      objectArray: this.data.objectArray    })  },  addToFront: function(e) {    const length = this.data.objectArray.length    this.data.objectArray = [{id: length, unique: 'unique_' + length}].concat(this.data.objectArray)    this.setData({      objectArray: this.data.objectArray    })  },  addNumberToFront: function(e){    this.data.numberArray = [ this.data.numberArray.length + 1 ].concat(this.data.numberArray)    this.setData({      numberArray: this.data.numberArray    })  }})

                    注意:

                    wx:for 的值为字符串时,会将字符串解析成字符串数组

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

                    等同于

                    <view wx:for="{{['a','r','r','a','y']}}">  {{item}}</view>

                    注意: 花括号和引号之间如果有空格,将最终被解析成为字符串

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

                    等同于

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


                    wx:if

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

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

                    也可以用wx:elifwx:else来添加一个else块:

                    <view wx:if="{{length > 5}}"> 1 </view><view wx:elif="{{length > 2}}"> 2 </view><view wx:else> 3 </view>

                    block wx:if

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

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

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

                    实例:

                    wxml:使用view

                    <!--index.wxml--><button bindtap="EventHandle">按钮</button><!-- wx:if --><view wx:if="{{boolean==true}}">    <view class="bg_black"></view></view> <view wx:elif="{{boolean==false}}">    <view class="bg_red"></view></view>

                    wxss:

                    /**index.wxss**/.bg_black {  height: 200rpx;  background: lightskyblue;}.bg_red {  height: 200rpx;  background: lightpink;}

                    js:

                    // index.js Page({  data: {    boolean:false  },   EventHandle: function(){    var bol = this.data.boolean;    this.setData({      boolean: !bol     })  } })

                    运行:

                    p


                    wx:ifvshidden

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

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

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

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


                    模板


                    WXML提供模板(template),可以在模板中定义代码片段,然后在不同的地方调用。

                    定义模板


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

                    <!--  index: int  msg: string  time: string--><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'    }  }})

                    is属性可以使用Mustache语法,来动态决定具体需要渲染哪个模板:

                    <template name="odd">  <view> odd </view></template><template name="even">  <view> even </view></template><block wx:for="{{[1, 2, 3, 4, 5]}}">    <template is="{{item % 2 == 0 ? 'even' : 'odd'}}"/></block>

                    模板的作用域

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

                    什么是事件


                    • 事件是视图层到逻辑层的通讯方式。
                    • 事件可以将用户的行为反馈到逻辑层进行处理。
                    • 事件可以绑定在组件上,当达到触发事件,就会执行逻辑层中对应的事件处理函数。
                    • 事件对象可以携带额外信息,如id, dataset, touches。

                    事件的使用方式


                    • 在组件中绑定一个事件处理函数。

                    bindtap,当用户点击该组件的时候会在该页面对应的Page中找到相应的事件处理函数。

                    <view id="tapTest" data-hi="WeChat" bindtap="tapName"> Click me! </view>
                    • 在相应的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,}],}

                    事件详解

                    事件分类

                    事件分为冒泡事件和非冒泡事件

                    1. 冒泡事件:当一个组件上的事件被触发后,该事件会向父节点传递。
                    2. 非冒泡事件:当一个组件上的事件被触发后,该事件不会向父节点传递。

                    WXML的冒泡事件列表:

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

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

                    事件绑定


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

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

                    bind事件绑定不会阻止冒泡事件向上冒泡,catch事件绑定可以阻止冒泡事件向上冒泡。

                    如在下边这个例子中,点击inner view会先后触发handleTap3handleTap2(因为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>

                    事件对象


                    如无特殊说明,当组件触发事件时,逻辑层绑定该事件的处理函数会收到一个事件对象。

                    BaseEvent基础事件对象属性列表:

                    属性 类型 说明
                    type String 事件类型
                    timeStamp Integer 事件生成时的时间戳
                    target Object 触发事件的组件的一些属性值集合
                    currentTarget Object 当前组件的一些属性值集合

                    CustomEvent 自定义事件对象属性列表(继承 BaseEvent):

                    属性类型说明
                    detailObject额外的信息

                    TouchEvent 触摸事件对象属性列表(继承 BaseEvent):

                    属性类型说明
                    touchesArray触摸事件,当前停留在屏幕中的触摸点信息的数组
                    changedTouchesArray触摸事件,当前变化的触摸点信息的数组

                    特殊事件:<canvas/>中的触摸事件不可冒泡,所以没有 currentTarget。


                    type

                    通用事件类型

                    timeStamp

                    该页面打开到触发事件所经过的毫秒数。

                    target

                    触发事件的源组件。

                    属性类型说明
                    idString事件源组件的id
                    tagNameString当前组件的类型
                    datasetObject事件源组件上由data-开头的自定义属性组成的集合

                    currentTarget

                    事件绑定的当前组件。

                    属性类型说明
                    idString当前组件的id
                    tagNameString当前组件的类型
                    datasetObject当前组件上由data-开头的自定义属性组成的集合

                    说明: target 和 currentTarget 可以参考上例中,点击 inner view 时,handleTap3 收到的事件对象 target 和 currentTarget 都是 inner,而 handleTap2 收到的事件对象 target 就是 inner,currentTarget 就是 middle。

                    dataset

                    在组件中可以定义数据,这些数据将会通过事件传递给 SERVICE。书写方式:以data-开头,多个单词由连字符-链接,不能有大写(大写会自动转成小写)如data-element-type,最终在 event.target.dataset 中会将连字符转成驼峰elementType

                    示例:

                    <view data-alpha-beta="1" data-alphaBeta="2" bindtap="bindViewTap"> DataSet Test </view>
                    Page({  bindViewTap:function(event){    event.target.dataset.alphaBeta === 1 // - 会转为驼峰写法    event.target.dataset.alphabeta === 2 // 大写会转为小写  }})

                    touches

                    touches 是一个数组,每个元素为一个 Touch 对象(canvas 触摸事件中携带的 touches 是 CanvasTouch 数组)。 表示当前停留在屏幕上的触摸点。

                    Touch 对象

                    属性类型说明
                    identifierNumber触摸点的标识符
                    pageX, pageYNumber距离文档左上角的距离,文档的左上角为原点 ,横向为X轴,纵向为Y轴
                    clientX, clientYNumber距离页面可显示区域(屏幕除去导航条)左上角距离,横向为X轴,纵向为Y轴

                    CanvasTouch 对象

                    属性类型说明特殊说明
                    identifierNumber触摸点的标识符 
                    x, yNumber距离 Canvas 左上角的距离,Canvas 的左上角为原点 ,横向为X轴,纵向为Y轴 

                    changedTouches

                    changedTouches 数据格式同 touches。表示有变化的触摸点,如从无变有(touchstart),位置变化(touchmove),从有变无(touchend、touchcancel)。

                    detail

                    自定义事件所携带的数据,如表单组件的提交事件会携带用户的输入,媒体的错误事件会携带错误信息,详见组件定义中各个事件的定义。

                    点击事件的detail 带有的 x, y 同 pageX, pageY 代表距离文档左上角的距离。

                    引用

                    WXML提供两种文件引用方式importinclude

                    import

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

                    在item.wxml中定义了一个叫itemtemplate

                    <!-- item.wxml --><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

                    <!-- A.wxml --><template name="A">  <text> A template </text></template>
                    <!-- B.wxml --><import src="a.wxml"/><template name="B">  <text> B template </text></template>
                    <!-- C.wxml --><import src="b.wxml"/><template is="A"/>  <!-- Error! Can not use tempalte when not import A. --><template is="B"/>

                    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>

                    WXS

                    WXS(WeiXin Script)是小程序的一套脚本语言,结合 WXML,可以构建出页面的结构。

                    注意:

                    1. wxs 不依赖于运行时的基础库版本,可以在所有版本的小程序中运行。
                    2. wxs 与 javascript 是不同的语言,有自己的语法,并不和 javascript 一致。
                    3. wxs 的运行环境和其他 javascript 代码是隔离的,wxs 中不能调用其他 javascript 文件中定义的函数,也不能调用小程序提供的API。
                    4. wxs 函数不能作为组件的事件回调。
                    5. 由于运行环境的差异,在 iOS 设备上小程序内的 wxs 会比 javascript 代码快 2 ~ 20 倍。在 android 设备上二者运行效率无差异。

                    以下是一些使用 WXS 的简单示例:

                    页面渲染

                    <!--wxml--><wxs module="m1">var msg = "hello world";module.exports.message = msg;</wxs><view> {{m1.message}} </view>

                    页面输出:

                    hello world

                    数据处理

                    // page.jsPage({  data: {    array: [1, 2, 3, 4, 5, 1, 2, 3, 4]  }})
                    <!--wxml--><!-- 下面的 getMax 函数,接受一个数组,且返回数组中最大的元素的值 --><wxs module="m1">var getMax = function(array) {  var max = undefined;  for (var i = 0; i < array.length; ++i) {    max = max === undefined ?       array[i] :       (max >= array[i] ? max : array[i]);  }  return max;}module.exports.getMax = getMax;</wxs><!-- 调用 wxs 里面的 getMax 函数,参数为 page.js 里面的 array --><view> {{m1.getMax(array)}} </view>

                    页面输出:

                    5

                    WXS 模块

                    WXS 代码可以编写在 wxml 文件中的<wxs> 标签内,或以 .wxs 为后缀名的文件内。

                    模块

                    每一个 .wxs 文件和 <wxs> 标签都是一个单独的模块。

                    每个模块都有自己独立的作用域。即在一个模块里面定义的变量与函数,默认为私有的,对其他模块不可见。

                    一个模块要想对外暴露其内部的私有变量与函数,只能通过 module.exports 实现。

                    .wxs 文件

                    在微信开发者工具里面,右键可以直接创建 .wxs 文件,在其中直接编写 WXS 脚本。

                    示例代码:

                    // /pages/comm.wxs

                    var foo = "'hello world' from comm.wxs";var bar = function(d) { return d;}module.exports = { foo: foo, bar: bar};

                    上述例子在 /pages/comm.wxs 的文件里面编写了 WXS 代码。该 .wxs 文件可以被其他的 .wxs 文件 或 WXML 中的 <wxs> 标签引用。

                    module 对象

                    每个 wxs 模块均有一个内置的 module 对象。

                    属性

                    • exports: 通过该属性,可以对外共享本模块的私有变量与函数。

                    示例代码:

                    // /pages/tools.wxs

                    var foo = "'hello world' from tools.wxs";var bar = function (d) { return d;}module.exports = { FOO: foo, bar: bar,};module.exports.msg = "some msg";

                    {{tools.msg}}

                    {{tools.bar(tools.FOO)}}

                    页面输出:

                    some msg'hello world' from tools.wxs

                    require 函数

                    在.wxs模块中引用其他 wxs 文件模块,可以使用 require 函数。

                    引用的时候,要注意如下几点:

                    • 只能引用 .wxs 文件模块,且必须使用相对路径。
                    • wxs 模块均为单例,wxs 模块在第一次被引用时,会自动初始化为单例对象。多个页面,多个地方,多次引用,使用的都是同一个 wxs 模块对象。
                    • 如果一个 wxs 模块在定义之后,一直没有被引用,则该模块不会被解析与运行。

                    示例代码:

                    // /pages/tools.wxs

                    var foo = "'hello world' from tools.wxs";var bar = function (d) { return d;}module.exports = { FOO: foo, bar: bar,};module.exports.msg = "some msg";

                    // /pages/logic.wxs

                    var tools = require("./tools.wxs");

                    console.log(tools.FOO);console.log(tools.bar("logic.wxs"));console.log(tools.msg);

                    控制台输出:

                    'hello world' from tools.wxslogic.wxssome msg

                    标签

                    属性名类型默认值说明
                    moduleString 当前<wxs>标签的模块名。必填字段。
                    srcString 引用 .wxs 文件的相对路径。仅当本标签为单闭合标签标签的内容为空时有效。

                    module 属性

                    module 属性是当前<wxs>标签的模块名。在单个 wxml 文件内,建议其值唯一。有重复模块名则按照先后顺序覆盖(后者覆盖前者)。不同文件之间的 wxs 模块名不会相互覆盖。

                    module 属性值的命名必须符合下面两个规则:

                    • 首字符必须是:字母(a-zA-Z),下划线(_
                    • 剩余字符可以是:字母(a-zA-Z),下划线(_), 数字(0-9)

                    示例代码:

                    <!--wxml--> 

                    <wxs module="foo">

                    var some_msg = "hello world";module.exports = { msg : some_msg,}

                    </wxs>

                    <view> {{foo.msg}} </view>

                    页面输出:

                    hello world

                    上面例子声明了一个名字为 foo 的模块,将 some_msg 变量暴露出来,供当前页面使用。

                    src 属性

                    src 属性可以用来引用其他的 wxs 文件模块。

                    引用的时候,要注意如下几点:

                    • 只能引用 .wxs 文件模块,且必须使用相对路径。
                    • wxs 模块均为单例,wxs 模块在第一次被引用时,会自动初始化为单例对象。多个页面,多个地方,多次引用,使用的都是同一个 wxs 模块对象。
                    • 如果一个 wxs 模块在定义之后,一直没有被引用,则该模块不会被解析与运行。

                    示例代码:

                    // /pages/index/index.js

                    Page({ data: { msg: "'hello world' from js", }})

                    <!-- 也可以直接使用单标签闭合的写法

                    -->

                    {{some_comms.bar(some_comms.foo)}}

                    {{some_comms.bar(msg)}}

                    页面输出:

                    'hello world' from comm.wxs'hello wrold' from js

                    上述例子在文件 /page/index/index.wxml 中通过 标签引用了 /page/comm.wxs 模块。

                    注意

                    • <wxs>模块只能在定义模块的 WXML 文件中被访问到。使用<include> 或<import> 时, <wxs>模块不会被引入到对应的 WXML 文件中。
                    • 标签中,只能使用定义该 的 WXML 文件中定义的 模块。


                    概念

                    • WXS 中的变量均为值的引用。
                    • 没有声明的变量直接赋值使用,会被定义为全局变量。
                    • 如果只声明变量而不赋值,则默认值为 undefined。
                    • var表现与javascript一致,会有变量提升。
                    var foo = 1;var bar = "hello world";var i; // i === undefined

                    上面代码,分别声明了 foo、 bar、 i 三个变量。然后,foo 赋值为数值 1 ,bar 赋值为字符串 "hello wolrd"。

                    变量名

                    变量命名必须符合下面两个规则:

                    • 首字符必须是:字母(a-zA-Z),下划线(_)
                    • 剩余字符可以是:字母(a-zA-Z),下划线(_), 数字(0-9)

                    保留标识符

                    以下标识符不能作为变量名:

                    delete void typeofnull undefined NaN Infinity varif else true falserequirethis function argumentsreturnforwhiledobreakcontinueswitchcasedefault

                    WXS 主要有 3 种注释的方法。

                    示例代码:

                    <!-- wxml -->
                    <wxs module="sample">
                    // 方法一:单行注释
                    /*
                    方法二:多行注释
                    */
                    /*
                    方法三:结尾注释。即从 /* 开始往后的所有 WXS 代码均被注释
                    var a = 1;
                    var b = 2;
                    var c = "fake";
                    </wxs>

                    上述例子中,所有 WXS 代码均被注释掉了。

                    方法三 和 方法二 的唯一区别是,没有 */ 结束符。


                    示例:

                    1.在文件中选中一行代码

                    无标题

                    2.然后再代码前面使用//,表示注释。

                    5a5a00def4dca0396459dc5f58d96975f3c40d99

                    3.另外我们还可以在代码的头部和尾部分别加上/*和*/,也是表示注释! a1780d1fceecd3d91333e0776799594305010899

                    4.将模拟器打开。

                    f385f2995943040137b80cf1d66b04d148290599

                    5.在下面我们就发现内容是空白的,是因为我们的代码被注释掉了,就不起作用了

                    edd84743040148fe9e044fd88fd149299b880299

                    基本运算符

                    示例代码:

                    var a = 10, b = 20;// 加法运算console.log(30 === a + b);// 减法运算console.log(-10 === a - b);// 乘法运算console.log(200 === a * b);// 除法运算console.log(0.5 === a / b);// 取余运算console.log(10 === a % b);
                    • 加法运算(+)也可以用作字符串的拼接。
                    var a = '.w' , b = 'xs';// 字符串拼接console.log('.wxs' === a + b);

                    一元运算符

                    示例代码:

                    var a = 10, b = 20;// 自增运算console.log(10 === a++);console.log(12 === ++a);// 自减运算console.log(12 === a--);console.log(10 === --a);// 正值运算console.log(10 === +a);// 负值运算console.log(0-10 === -a);// 否运算console.log(-11 === ~a);// 取反运算console.log(false === !a);// delete 运算console.log(true === delete a.fake);// void 运算console.log(undefined === void a);// typeof 运算console.log("number" === typeof a);

                    位运算符

                    示例代码:

                    var a = 10, b = 20;// 左移运算console.log(80 === (a << 3));// 无符号右移运算console.log(2 === (a >> 2));// 带符号右移运算console.log(2 === (a >>> 2));// 与运算console.log(2 === (a & 3));// 异或运算console.log(9 === (a ^ 3));// 或运算console.log(11 === (a | 3));

                    比较运算符

                    示例代码:

                    var a = 10, b = 20;// 小于console.log(true === (a < b));// 大于console.log(false === (a > b));// 小于等于console.log(true === (a <= b));// 大于等于console.log(false === (a >= b));

                    等值运算符

                    示例代码:

                    var a = 10, b = 20;// 等号console.log(false === (a == b));// 非等号console.log(true === (a != b));// 全等号console.log(false === (a === b));// 非全等号console.log(true === (a !== b));

                    赋值运算符

                    示例代码:

                    var a = 10;a = 10; a *= 10;console.log(100 === a);a = 10; a /= 5;console.log(2 === a);a = 10; a %= 7;console.log(3 === a);a = 10; a += 5;console.log(15 === a);a = 10; a -= 11;console.log(-1 === a);a = 10; a <<= 10;console.log(10240 === a);a = 10; a >>= 2;console.log(2 === a);a = 10; a >>>= 2;console.log(2 === a);a = 10; a &= 3;console.log(2 === a);a = 10; a ^= 3;console.log(9 === a);a = 10; a |= 3;console.log(11 === a);

                    二元逻辑运算符

                    示例代码:

                    var a = 10, b = 20;// 逻辑与console.log(20 === (a && b));// 逻辑或console.log(10 === (a || b));

                    其他运算符

                    示例代码:

                    var a = 10, b = 20;//条件运算符console.log(20 === (a >= 10 ? a + 10 : b + 10));//逗号运算符console.log(20 === (a, b));

                    运算符优先级

                    优先级运算符说明结合性
                    20( ... )括号n/a
                    19... . ...成员访问从左到右
                    ... [ ... ]成员访问从左到右
                    ... ( ... )函数调用从左到右
                    17... ++后置递增n/a
                    ... --后置递减n/a
                    16! ...逻辑非从右到左
                    ~ ...按位非从右到左
                    + ...一元加法从右到左
                    - ...一元减法从右到左
                    ++ ...前置递增从右到左
                    -- ...前置递减从右到左
                    typeof ...typeof从右到左
                    void ...void从右到左
                    delete ...delete从右到左
                    14... * ...乘法从左到右
                    ... / ...除法从左到右
                    ... % ...取模从左到右
                    13... + ...加法从左到右
                    ... - ...减法从左到右
                    12... << ...按位左移从左到右
                    ... >> ...按位右移从左到右
                    ... >>> ...无符号右移从左到右
                    11... < ...小于从左到右
                    ... <= ...小于等于从左到右
                    ... > ...大于从左到右
                    ... >= ...大于等于从左到右
                    10... == ...等号从左到右
                    ... != ...非等号从左到右
                    ... === ...全等号从左到右
                    ... !== ...非全等号从左到右
                    9... & ...按位与从左到右
                    8... ^ ...按位异或从左到右
                    7...  ...按位或从左到右
                    6... && ...逻辑与从左到右
                    5... || ...逻辑或从左到右
                    4... ? ... : ...条件运算符从右到左
                    3... = ...赋值从右到左
                    ... += ...赋值从右到左
                    ... -= ...赋值从右到左
                    ... *= ...赋值从右到左
                    ... /= ...赋值从右到左
                    ... %= ...赋值从右到左
                    ... <<= ...赋值从右到左
                    ... >>= ...赋值从右到左
                    ... >>>= ...赋值从右到左
                    ... &= ...赋值从右到左
                    ... ^= ...赋值从右到左
                    ... |= ...赋值从右到左
                    0... , ...逗号从左到右

                    if 语句

                    在 WXS 中,可以使用以下格式的 if 语句 :

                    • if (expression) statement : 当 expression 为 truthy 时,执行 statement。
                    • if (expression) statement1 else statement2 : 当 expression 为 truthy 时,执行 statement1。 否则,执行 statement2
                    • if ... else if ... else statementN 通过该句型,可以在 statement1 ~ statementN 之间选其中一个执行。

                    示例语法:

                    // if ...if (表达式) 语句;if (表达式)   语句;if (表达式) {  代码块;}// if ... else if (表达式) 语句;else 语句;if (表达式)   语句;else   语句;if (表达式) {  代码块;} else {  代码块;}// if ... else if ... else ...if (表达式) {  代码块;} else if (表达式) {  代码块;} else if (表达式) {  代码块;} else {  代码块;}

                    switch 语句

                    示例语法:

                    switch (表达式) {  case 变量:    语句;  case 数字:    语句;    break;  case 字符串:    语句;  default:    语句;}
                    • default 分支可以省略不写。
                    • case 关键词后面只能使用:变量,数字,字符串。

                    示例代码:

                    var exp = 10;switch ( exp ) {case "10":  console.log("string 10");  break;case 10:  console.log("number 10");  break;case exp:  console.log("var exp");  break;default:  console.log("default");}

                    输出:

                    number 10

                    for 语句

                    示例语法:

                    for (语句; 语句; 语句)  语句;for (语句; 语句; 语句) {  代码块;}
                    • 支持使用 break,continue 关键词。

                    示例代码:

                    for (var i = 0; i < 3; ++i) {  console.log(i);  if( i >= 1) break;}

                    输出:

                    01

                    while 语句

                    示例语法:

                    while (表达式)  语句;while (表达式){  代码块;}do {  代码块;} while (表达式)
                    • 当表达式为 true 时,循环执行语句或代码块。
                    • 支持使用 break,continue 关键词。

                    数据类型

                    WXS 语言目前共有以下几种数据类型:

                    • number : 数值
                    • string :字符串
                    • boolean:布尔值
                    • object:对象
                    • function:函数
                    • array : 数组
                    • date:日期
                    • regexp:正则

                    number

                    语法

                    number 包括两种数值:整数,小数。

                    var a = 10;var PI = 3.141592653589793;

                    属性

                    • constructor:返回字符串 "Number"。

                    方法

                    • toString
                    • toLocaleString
                    • valueOf
                    • toFixed
                    • toExponential
                    • toPrecision
                    以上方法的具体使用请参考 ES5 标准。

                    string

                    语法

                    string 有两种写法:

                    'hello world';"hello world";

                    属性

                    • constructor:返回字符串 "String"。
                    • length
                    除constructor外属性的具体含义请参考 ES5 标准。

                    方法

                    • toString
                    • valueOf
                    • charAt
                    • charCodeAt
                    • concat
                    • indexOf
                    • lastIndexOf
                    • localeCompare
                    • match
                    • replace
                    • search
                    • slice
                    • split
                    • substring
                    • toLowerCase
                    • toLocaleLowerCase
                    • toUpperCase
                    • toLocaleUpperCase
                    • trim
                    以上方法的具体使用请参考 ES5 标准。

                    boolean

                    语法

                    布尔值只有两个特定的值:true 和 false。

                    属性

                    • constructor:返回字符串 "Boolean"。

                    方法

                    • toString
                    • valueOf
                    以上方法的具体使用请参考 ES5 标准。

                    object

                    语法

                    object 是一种无序的键值对。使用方法如下所示:

                    var o = {} //生成一个新的空对象//生成一个新的非空对象o = {  'string'  : 1,  //object 的 key 可以是字符串  const_var : 2,  //object 的 key 也可以是符合变量定义规则的标识符  func      : {}, //object 的 value 可以是任何类型};//对象属性的读操作console.log(1 === o['string']);console.log(2 === o.const_var);//对象属性的写操作o['string']++;o['string'] += 10;o.const_var++;o.const_var += 10;//对象属性的读操作console.log(12 === o['string']);console.log(13 === o.const_var);

                    属性

                    • constructor:返回字符串 "Object"。
                    console.log("Object" === {k:"1",v:"2"}.constructor)

                    方法

                    • toString:返回字符串 "[object Object]"。

                    function

                    语法

                    function 支持以下的定义方式:

                    //方法 1function a (x) {  return x;}//方法 2var b = function (x) {   return x;}

                    function 同时也支持以下的语法(匿名函数,闭包等):

                    var a = function (x) {  return function () { return x;}}var b = a(100);console.log( 100 === b() );

                    arguments

                    function 里面可以使用 arguments 关键词。该关键词目前只支持以下的属性:

                    • length: 传递给函数的参数个数。
                    • [index]: 通过 index 下标可以遍历传递给函数的每个参数。

                    示例代码:

                    var a = function(){    console.log(3 === arguments.length);    console.log(100 === arguments[0]);    console.log(200 === arguments[1]);    console.log(300 === arguments[2]);};a(100,200,300);

                    属性

                    • constructor:返回字符串 "Function"。
                    • length:返回函数的形参个数。

                    方法

                    • toString:返回字符串 "[function Function]"。

                    示例代码:

                    var func = function (a,b,c) { }console.log("Function" === func.constructor);console.log(3 === func.length);console.log("[function Function]" === func.toString());

                    array

                    语法

                    array 支持以下的定义方式:

                    var a = [];      //生成一个新的空数组a = [1,"2",{},function(){}];  //生成一个新的非空数组,数组元素可以是任何类型

                    属性

                    • constructor:返回字符串 "Array"。
                    • length
                    除constructor外属性的具体含义请参考 ES5 标准。

                    方法

                    • toString
                    • concat
                    • join
                    • pop
                    • push
                    • reverse
                    • shift
                    • slice
                    • sort
                    • splice
                    • unshift
                    • indexOf
                    • lastIndexOf
                    • every
                    • some
                    • forEach
                    • map
                    • filter
                    • reduce
                    • reduceRight
                    以上方法的具体使用请参考 ES5 标准。

                    date

                    语法

                    生成 date 对象需要使用 getDate函数, 返回一个当前时间的对象。

                    getDate()getDate(milliseconds)getDate(datestring)getDate(year, month[, date[, hours[, minutes[, seconds[, milliseconds]]]]])
                    • 参数milliseconds: 从1970年1月1日00:00:00 UTC开始计算的毫秒数datestring: 日期字符串,其格式为:"month day, year hours:minutes:seconds"

                    示例代码:

                    var date = getDate(); //返回当前时间对象date = getDate(1500000000000);// Fri Jul 14 2017 10:40:00 GMT+0800 (中国标准时间)date = getDate('2017-7-14');// Fri Jul 14 2017 00:00:00 GMT+0800 (中国标准时间)date = getDate(2017, 6, 14, 10, 40, 0, 0);// Fri Jul 14 2017 10:40:00 GMT+0800 (中国标准时间)

                    属性

                    • constructor:返回字符串 “Date”。

                    方法

                    • parse
                    • UTC
                    • now
                    • toString
                    • toDateString
                    • toTimeString
                    • toLocaleString
                    • toLocaleDateString
                    • toLocaleTimeString
                    • valueOf
                    • getTime
                    • getFullYear
                    • getUTCFullYear
                    • getMonth
                    • getUTCMonth
                    • getDate
                    • getUTCDate
                    • getDay
                    • getUTCDay
                    • getHours
                    • getUTCHours
                    • getMinutes
                    • getUTCMinutes
                    • getSeconds
                    • getUTCSeconds
                    • getMilliseconds
                    • getUTCMilliseconds
                    • getTimezoneOffset
                    • setTime
                    • setMilliseconds
                    • setUTCMilliseconds
                    • setSeconds
                    • setUTCSeconds
                    • setMinutes
                    • setUTCMinutes
                    • setHours
                    • setUTCHours
                    • setDate
                    • setUTCDate
                    • setMonth
                    • setUTCMonth
                    • setFullYear
                    • setUTCFullYear
                    • toUTCString
                    • toISOString
                    • toJSON
                    以上方法的具体使用请参考 ES5 标准。

                    regexp

                    语法

                    生成 regexp 对象需要使用 getRegExp函数。

                    getRegExp(pattern[, flags])
                    • 参数:pattern: 正则表达式的内容。flags:修饰符。该字段只能包含以下字符:g: globali: ignoreCasem: multiline。

                    示例代码:

                    var a = getRegExp("x", "img");console.log("x" === a.source);console.log(true === a.global);console.log(true === a.ignoreCase);console.log(true === a.multiline);

                    属性

                    • constructor:返回字符串 "RegExp"。
                    • source
                    • global
                    • ignoreCase
                    • multiline
                    • lastIndex
                    除constructor外属性的具体含义请参考 ES5 标准。

                    方法

                    • exec
                    • test
                    • toString
                    以上方法的具体使用请参考 ES5 标准。

                    数据类型判断

                    constructor 属性

                    数据类型的判断可以使用 constructor 属性。

                    示例代码:

                    var number = 10;console.log( "Number" === number.constructor );var string = "str";console.log( "String" === string.constructor );var boolean = true;console.log( "Boolean" === boolean.constructor );var object = {};console.log( "Object" === object.constructor );var func = function(){};console.log( "Function" === func.constructor );var array = [];console.log( "Array" === array.constructor );var date = getDate();console.log( "Date" === date.constructor );var regexp = getRegExp();console.log( "RegExp" === regexp.constructor );

                    typeof

                    使用 typeof 也可以区分部分数据类型。

                    示例代码:

                    var number = 10;var boolean = true;var object = {};var func = function(){};var array = [];var date = getDate();var regexp = getRegExp();console.log( 'number' === typeof number );console.log( 'boolean' === typeof boolean );console.log( 'object' === typeof object );console.log( 'function' === typeof func );console.log( 'object' === typeof array );console.log( 'object' === typeof date );console.log( 'object' === typeof regexp );console.log( 'undefined' === typeof undefined );console.log( 'object' === typeof null );


                    console

                    console.log 方法用于在 console 窗口输出信息。它可以接受多个参数,将它们的结果连接起来输出。

                    Math

                    属性

                    • E
                    • LN10
                    • LN2
                    • LOG2E
                    • LOG10E
                    • PI
                    • SQRT1_2
                    • SQRT2
                    以上属性的具体使用请参考 ES5 标准。

                    方法

                    • abs
                    • acos
                    • asin
                    • atan
                    • atan2
                    • ceil
                    • cos
                    • exp
                    • floor
                    • log
                    • max
                    • min
                    • pow
                    • random
                    • round
                    • sin
                    • sqrt
                    • tan
                    以上方法的具体使用请参考 ES5 标准。

                    JSON

                    方法

                    • stringify(object): 将 object 对象转换为 JSON 字符串,并返回该字符串。
                    • parse(string): 将 JSON 字符串转化成对象,并返回该对象。

                    示例代码:

                    console.log(undefined === JSON.stringify());console.log(undefined === JSON.stringify(undefined));console.log("null"===JSON.stringify(null));console.log("111"===JSON.stringify(111));console.log('"111"'===JSON.stringify("111"));console.log("true"===JSON.stringify(true));console.log(undefined===JSON.stringify(function(){}));console.log(undefined===JSON.parse(JSON.stringify()));console.log(undefined===JSON.parse(JSON.stringify(undefined)));console.log(null===JSON.parse(JSON.stringify(null)));console.log(111===JSON.parse(JSON.stringify(111)));console.log("111"===JSON.parse(JSON.stringify("111")));console.log(true===JSON.parse(JSON.stringify(true)));console.log(undefined===JSON.parse(JSON.stringify(function(){})));

                    Number

                    属性

                    • MAX_VALUE
                    • MIN_VALUE
                    • NEGATIVE_INFINITY
                    • POSITIVE_INFINITY
                    以上属性的具体使用请参考 ES5 标准。

                    Date

                    属性

                    • parse
                    • UTC
                    • now
                    以上属性的具体使用请参考 ES5 标准。

                    Global

                    属性

                    • NaN
                    • Infinity
                    • undefined
                    以上属性的具体使用请参考 ES5 标准。

                    方法

                    • parseInt
                    • parseFloat
                    • isNaN
                    • isFinite
                    • decodeURI
                    • decodeURIComponent
                    • encodeURI
                    • encodeURIComponent
                    以上方法的具体使用请参考 ES5 标准。


                    WXSS

                    WXSS(WeiXin Style Sheets)是一套样式语言,用于描述WXML的组件样式。

                    WXSS用来决定WXML的组件应该怎么显示。

                    为了适应广大的前端开发者,我们的WXSS具有CSS大部分特性。同时为了更适合开发微信小程序,我们对CSS进行了扩充以及修改。

                    与css相比我们扩展的特性有:

                    尺寸单位

                    • 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"的组件
                    element view 选择所有view组件
                    element, element view checkbox 选择所有文档的view组件和所有的checkbox组件
                    ::after view::after 在view组件后边插入内容
                    ::before view::before 在view组件前边插入内容

                    全局样式与局部样式

                    定义在app.wxss中的样式为全局样式,作用于每一个页面。在page的wxss文件中定义的样式为局部样式,只作用在对应的页面,并会覆盖app.wxss中相同的选择器。


                    基础组件


                    框架为开发者提供了一系列基础组件,开发者可以通过组合这些基础组件进行快速开发。

                    详细介绍请参考组件文档

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

                    双向绑定语法

                    在 WXML 中,普通的属性的绑定是单向的。例如:

                    <input value="{{value}}" />

                    如果使用 ​this.setData({ value: 'leaf' })​ 来更新 ​value​ ,​this.data.value​ 和输入框的中显示的值都会被更新为 leaf ;但如果用户修改了输入框里的值,却不会同时改变 ​this.data.value​ 。

                    如果需要在用户输入的同时改变 ​this.data.value​ ,需要借助简易双向绑定机制。此时,可以在对应项目之前加入 ​model​: 前缀:

                    <input model:value="{{value}}" />

                    这样,如果输入框的值被改变了, ​this.data.value​ 也会同时改变。同时, WXML 中所有绑定了 ​value​ 的位置也会被一同更新, 数据监听器 也会被正常触发。

                    用于双向绑定的表达式有如下限制:

                    1. 只能是一个单一字段的绑定,如
                    2. <input model:value="值为 {{value}}" /><input model:value="{{ a + b }}" />

                      都是非法的;

                    3. 目前,尚不能 data 路径,如

                      <input model:value="{{ a.b }}" />

                      这样的表达式目前暂不支持。

                    在自定义组件中传递双向绑定

                    双向绑定同样可以使用在自定义组件上。如下的自定义组件:

                    // custom-component.jsComponent({  properties: {    myValue: String  }})
                    <!-- custom-component.wxml --><input model:value="{{myValue}}" />

                    这个自定义组件将自身的 ​myValue​ 属性双向绑定到了组件内输入框的 ​value​ 属性上。这样,如果页面这样使用这个组件:

                    <custom-component model:my-value="{{pageValue}}" />

                    当输入框的值变更时,自定义组件的 ​myValue​ 属性会同时变更,这样,页面的 ​this.data.pageValue​ 也会同时变更,页面 WXML 中所有绑定了 ​pageValue​ 的位置也会被一同更新。

                    在自定义组件中触发双向绑定更新

                    自定义组件还可以自己触发双向绑定更新,做法就是:使用 setData 设置自身的属性。例如:

                    // custom-component.jsComponent({  properties: {    myValue: String  },  methods: {    update: function() {      // 更新 myValue      this.setData({        myValue: 'leaf'      })    }  }})

                    如果页面这样使用这个组件:

                    <custom-component model:my-value="{{pageValue}}" />

                    当组件使用 ​setData​ 更新 ​myValue​ 时,页面的 ​this.data.pageValue​ 也会同时变更,页面 WXML 中所有绑定了 ​pageValue​ 的位置也会被一同更新。


                    目前,我们提供了两种性能分析工具,和几个性能优化上的建议,开发者可以参考使用。

                    1. 分析工具

                    2. 优化建议

                    微信 Andoid 6.5.10 开始,我们提供了 Trace 导出工具,开发者可以在开发者工具 Trace Panel 中使用该功能。

                    使用方法

                    1. PC 上需要先安装adb工具,可以参考一些主流教程进行安装,Mac 上可使用 brew 直接安装。
                    2. 确定adb工具已成功安装后,在开发者工具上打开 Trace Panel,将 Android 手机通过 USB 连接上 PC,点击「Choose Devices」,此时手机上可能弹出连接授权框,请点击「允许」。
                    3. 选择设备后,在手机上打开你需要调试的开发版小程序,通过右上角菜单,打开性能监控面板,重启小程序;
                    4. 重启后,在小程序上进行操作,完成操作后,通过右上角菜单,导出 Trace 数据;
                    5. 此时开发者工具 Trace Panel 上会自动拉取 Trace 文件,选择你要分析的 Trace 文件即可;

                    可以通过adb devices命令确定设备是否已和 PC 建立起连接

                    image

                    性能面板

                    从微信 6.5.8 开始,我们提供了性能面板让开发者了解小程序的性能。开发者可以在开发版小程序下打开性能面板,打开方法:进入开发版小程序,进入右上角更多按钮,点击「显示性能窗口」。

                    image

                    性能面板指标说明

                    指标说明
                    CPU小程序进程的 CPU 占用率,仅 Android 下提供
                    内存小程序进程的内存占用(Total Pss),仅 Android 下提供
                    启动耗时小程序启动总耗时
                    下载耗时小程序包下载耗时,首次打开或资源包需更新时会进行下载
                    页面切换耗时小程序页面切换的耗时
                    帧率/FPS 
                    首次渲染耗时页面次首次渲染的耗时
                    再次渲染耗时页面再次渲染的耗时(通常由开发者的 setData 操作触发)
                    数据缓存小程序通过 Storage 接口储存的缓存大小

                    setData

                    setData是小程序开发中使用最频繁的接口,也是最容易引发性能问题的接口。在介绍常见的错误用法前,先简单介绍一下setData背后的工作原理。

                    工作原理

                    小程序的视图层目前使用 WebView 作为渲染载体,而逻辑层是由独立的 JavascriptCore 作为运行环境。在架构上,WebView 和 JavascriptCore 都是独立的模块,并不具备数据直接共享的通道。当前,视图层和逻辑层的数据传输,实际上通过两边提供的evaluateJavascript所实现。即用户传输的数据,需要将其转换为字符串形式传递,同时把转换后的数据内容拼接成一份 JS 脚本,再通过执行 JS 脚本的形式传递到两边独立环境。

                    evaluateJavascript的执行会受很多方面的影响,数据到达视图层并不是实时的。同一进程内的 WebView 实际上会共享一个 JS VM,如果 WebView 内 JS 线程正在执行渲染或其他逻辑,会影响 evaluateJavascript 脚本的实际执行时间,另外多个 WebView 也会抢占 JS VM 的执行权限;另外还有 JS 本身的编译执行耗时,都是影响数据传输速度的因素。

                    常见的 setData 操作错误

                    1. 频繁的去 setData

                    在我们分析过的一些案例里,部分小程序会非常频繁(毫秒级)的去setData,其导致了两个后果:

                    • Android 下用户在滑动时会感觉到卡顿,操作反馈延迟严重,因为 JS 线程一直在编译执行渲染,未能及时将用户操作事件传递到逻辑层,逻辑层亦无法及时将操作处理结果及时传递到视图层;
                    • 渲染有出现延时,由于 WebView 的 JS 线程一直处于忙碌状态,逻辑层到页面层的通信耗时上升,视图层收到的数据消息时距离发出时间已经过去了几百毫秒,渲染的结果并不实时;

                    2. 每次 setData 都传递大量新数据

                    setData的底层实现可知,我们的数据传输实际是一次evaluateJavascript脚本过程,当数据量过大时会增加脚本的编译执行时间,占用 WebView JS 线程。

                    3. 后台态页面进行 setData

                    当页面进入后台态(用户不可见),不应该继续去进行setData,后台态页面的渲染用户是无法感受的,另外后台态页面去setData也会抢占前台页面的执行。

                    图片资源

                    目前图片资源的主要性能问题在于大图片和长列表图片上,这两种情况都有可能导致 iOS 客户端内存占用上升,从而触发系统回收小程序页面。

                    图片对内存的影响

                    在 iOS 上,小程序的页面是由多个 WKWebView 组成的,在系统内存紧张时,会回收掉一部分 WKWebView。从过去我们分析的案例来看,大图片和长列表图片的使用会引起 WKWebView 的回收。

                    图片对页面切换的影响

                    除了内存问题外,大图片也会造成页面切换的卡顿。我们分析过的案例中,有一部分小程序会在页面中引用大图片,在页面后退切换中会出现掉帧卡顿的情况。

                    当前我们建议开发者尽量减少使用大图片资源。

                    代码包大小的优化

                    小程序一开始时代码包限制为 1MB,但我们收到了很多反馈说代码包大小不够用,经过评估后我们放开了这个限制,增加到 2MB 。代码包上限的增加对于开发者来说,能够实现更丰富的功能,但对于用户来说,也增加了下载流量和本地空间的占用。

                    开发者在实现业务逻辑同时也有必要尽量减少代码包的大小,因为代码包大小直接影响到下载速度,从而影响用户的首次打开体验。除了代码自身的重构优化外,还可以从这两方面着手优化代码大小:

                    控制代码包内图片资源

                    小程序代码包经过编译后,会放在微信的 CDN 上供用户下载,CDN 开启了 GZIP 压缩,所以用户下载的是压缩后的 GZIP 包,其大小比代码包原体积会更小。 但我们分析数据发现,不同小程序之间的代码包压缩比差异也挺大的,部分可以达到 30%,而部分只有 80%,而造成这部分差异的一个原因,就是图片资源的使用。GZIP 对基于文本资源的压缩效果最好,在压缩较大文件时往往可高达 70%-80% 的压缩率,而如果对已经压缩的资源(例如大多数的图片格式)则效果甚微。

                    及时清理没有使用到的代码和资源

                    在日常开发的时候,我们可能引入了一些新的库文件,而过了一段时间后,由于各种原因又不再使用这个库了,我们常常会只是去掉了代码里的引用,而忘记删掉这类库文件了。目前小程序打包是会将工程下所有文件都打入代码包内,也就是说,这些没有被实际使用到的库文件和资源也会被打入到代码包里,从而影响到整体代码包的大小。

                    基础库与客户端之间的关系

                    小程序的能力需要微信客户端来支撑,每一个基础库都只能在对应的客户端版本上运行,高版本的基础库无法兼容低版本的微信客户端。

                    关于基础库的兼容方法,可以查看「兼容处理」章节。

                    基础库更新时机

                    为了避免新版本的基础库给线上小程序带来未知的影响,微信客户端都是携带 上一个稳定版 的基础库发布的。

                    在新版本客户端发布后,我们再通过后台灰度新版本基础库,灰度时长一般为 12 小时,在灰度结束后,用户设备上才会有新版本的基础库。

                    以微信 6.5.8 为例,客户端在发布时携带的是 1.1.1 基础库(6.5.7 上已全量的稳定版)发布,在 6.5.8 发布后,我们再通过后台灰度 1.2.0 基础库。

                    基础库版本分布

                    iOS

                    基础库版本用户占比
                    1.4.01.88%
                    1.3.080.74%
                    1.2.60.00%
                    1.2.57.29%
                    1.2.40.00%
                    1.2.30.00%
                    1.2.20.00%
                    1.2.10.00%
                    1.2.00.00%
                    1.1.16.75%
                    1.1.00.00%
                    1.0.13.34%
                    1.0.00.00%

                    (数据截止 2017-07-10)

                    Android

                    基础库版本用户占比
                    1.4.03.20%
                    1.3.051.24%
                    1.2.60.00%
                    1.2.537.03%
                    1.2.40.58%
                    1.2.30.00%
                    1.2.20.02%
                    1.2.10.00%
                    1.2.00.00%
                    1.1.14.33%
                    1.1.00.00%
                    1.0.12.05%
                    1.0.01.55%

                    (数据截止 2017-07-10)


                    小程序的功能不断的增加,但是旧版本的微信客户端并不支持新功能,所以在使用这些新能力的时候需要做兼容。

                    文档会在组件,API等页面描述中带上各个功能所支持的版本号。

                    可以通过wx.getSystemInfo或者wx.getSystemInfoSync获取到小程序的基础库版本号。

                    也可以通过wx.canIUse 详情 来判断是否可以在该基础库版本下直接使用对应的API或者组件

                    兼容方式 - 接口

                    对于新增的 API,可以用以下代码来判断是否支持用户的手机。

                    if (wx.openBluetoothAdapter) {  wx.openBluetoothAdapter()} else {  // 如果希望用户在最新版本的客户端上体验您的小程序,可以这样子提示  wx.showModal({    title: '提示',    content: '当前微信版本过低,无法使用该功能,请升级到最新微信版本后重试。'  })}

                    兼容方式 - 参数

                    对于 API 的参数或者返回值有新增的参数,可以判断用以下代码判断。

                    wx.showModal({  success: function(res) {    if (wx.canIUse('showModal.cancel')) {      console.log(res.cancel)    }  }})

                    兼容方式 - 组件

                    对于组件,新增的属性在旧版本上不会被处理,不过也不会报错。如果特殊场景需要对旧版本做一些降级处理,可以这样子做。

                    Page({  data: {    canIUse: wx.canIUse('button.open-type.contact')  }})
                    <button wx:if="{{canIUse}}" open-type="contact"> 客服消息 </button><contact-button wx:else></contact-button>

                    运行机制

                    • 小程序没有重启的概念
                    • 当小程序进入后台,客户端会维持一段时间的运行状态,超过一定时间后(目前是5分钟)会被微信主动销毁
                    • 置顶的小程序不会被微信主动销毁
                    • 当收到系统内存告警也会进行小程序的销毁

                    再次打开逻辑

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

                    用户打开小程序的预期有以下两类场景:

                    A. 打开首页: 场景值有 1001, 1019, 1022, 1023, 1038, 1056

                    B. 打开小程序指定的某个页面: 场景值为除 A 以外的其他

                    当再次打开一个小程序逻辑如下:

                    上一次的场景当前打开的场景效果
                    AA保留原来的状态
                    BA清空原来的页面栈,打开首页(相当于执行 wx.reLaunch 到首页)
                    A 或 BB清空原来的页面栈,打开指定页面(相当于执行 wx.reLaunch 到指定页)

                    view


                    视图容器。

                    属性类型默认值必填说明最低版本
                    hover-classstringnone指定按下去的样式类。当 hover-class="none" 时,没有点击态效果1.0.0
                    hover-stop-propagationbooleanfalse指定是否阻止本节点的祖先节点出现点击态1.5.0
                    hover-start-timenumber50按住后多久出现点击态,单位毫秒1.0.0
                    hover-stay-timenumber400手指松开后点击态保留时间,单位毫秒1.0.0

                    示例:

                    <view class="section">  <view class="section__title">flex-direction: row</view>  <view class="flex-wrp" style="flex-direction:row;">    <view class="flex-item bc_green">1</view>    <view class="flex-item bc_red">2</view>    <view class="flex-item bc_blue">3</view>  </view></view><view class="section">  <view class="section__title">flex-direction: column</view>  <view class="flex-wrp" style="height: 300px;flex-direction:column;">    <view class="flex-item bc_green">1</view>    <view class="flex-item bc_red">2</view>    <view class="flex-item bc_blue">3</view>  </view></view>

                    view

                    Bug & Tip

                    1. tip: 如果需要使用滚动视图,请使用 scroll-view


                    scroll-view


                    可滚动视图区域。

                    属性名类型默认值说明
                    scroll-xBooleanfalse允许横向滚动
                    scroll-yBooleanfalse允许纵向滚动
                    upper-thresholdNumber50距顶部/左边多远时(单位px),触发 scrolltoupper 事件
                    lower-thresholdNumber50距底部/右边多远时(单位px),触发 scrolltolower 事件
                    scroll-topNumber 设置竖向滚动条位置
                    scroll-leftNumber 设置横向滚动条位置
                    scroll-into-viewString 值应为某子元素id(id不能以数字开头)。设置哪个方向可滚动,则在哪个方向滚动到该元素
                    scroll-with-animationBooleanfalse在设置滚动条位置时使用动画过渡
                    enable-back-to-topBooleanfalseiOS点击顶部状态栏、安卓双击标题栏时,滚动条返回顶部,只支持竖向
                    bindscrolltoupperEventHandle 滚动到顶部/左边,会触发 scrolltoupper 事件
                    bindscrolltolowerEventHandle 滚动到底部/右边,会触发 scrolltolower 事件
                    bindscrollEventHandle 滚动时触发,event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}

                    使用竖向滚动时,需要给<scroll-view/>一个固定高度,通过 WXSS 设置 height。

                    示例代码:

                    <view class="section">  <view class="section__title">vertical scroll</view>  <scroll-view scroll-y style="height: 200px;" bindscrolltoupper="upper" bindscrolltolower="lower" bindscroll="scroll" scroll-into-view="{{toView}}" scroll-top="{{scrollTop}}">    <view id="green" class="scroll-view-item bc_green"></view>    <view id="red"  class="scroll-view-item bc_red"></view>    <view id="yellow" class="scroll-view-item bc_yellow"></view>    <view id="blue" class="scroll-view-item bc_blue"></view>  </scroll-view>  <view class="btn-area">    <button size="mini" bindtap="tap">click me to scroll into view </button>    <button size="mini" bindtap="tapMove">click me to scroll</button>  </view></view><view class="section section_gap">  <view class="section__title">horizontal scroll</view>  <scroll-view class="scroll-view_H" scroll-x="true" style="width: 100%">    <view id="green" class="scroll-view-item_H bc_green"></view>    <view id="red"  class="scroll-view-item_H bc_red"></view>    <view id="yellow" class="scroll-view-item_H bc_yellow"></view>    <view id="blue" class="scroll-view-item_H bc_blue"></view>  </scroll-view></view>


                    var order = ['red', 'yellow', 'blue', 'green', 'red']Page({  data: {    toView: 'red',    scrollTop: 100  },  upper: function(e) {    console.log(e)  },  lower: function(e) {    console.log(e)  },  scroll: function(e) {    console.log(e)  },  tap: function(e) {    for (var i = 0; i < order.length; ++i) {      if (order[i] === this.data.toView) {        this.setData({          toView: order[i + 1]        })        break      }    }  },  tapMove: function(e) {    this.setData({      scrollTop: this.data.scrollTop + 10    })  }})

                    scroll-view

                    Bug & Tip

                    1. tip: 请勿在scroll-view中使用textareamapcanvasvideo组件
                    2. tip: scroll-into-view的优先级高于scroll-top
                    3. tip: 在滚动scroll-view时会阻止页面回弹,所以在scroll-view中滚动,是无法触发onPullDownRefresh
                    4. tip: 若要使用下拉刷新,请使用页面的滚动,而不是scroll-view,这样也能通过点击顶部状态栏回到页面顶部


                    swiper


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

                    滑块视图容器。

                    属性类型默认值必填说明最低版本
                    indicator-dotsbooleanfalse是否显示面板指示点1.0.0
                    indicator-colorcolorrgba(0, 0, 0, .3)指示点颜色1.1.0
                    indicator-active-colorcolor#000000当前选中的指示点颜色1.1.0
                    autoplaybooleanfalse是否自动切换1.0.0
                    currentnumber0当前所在滑块的 index1.0.0
                    intervalnumber5000自动切换时间间隔1.0.0
                    durationnumber500滑动动画时长1.0.0
                    circularbooleanfalse是否采用衔接滑动1.0.0
                    verticalbooleanfalse滑动方向是否为纵向1.0.0
                    previous-marginstring"0px"前边距,可用于露出前一项的一小部分,接受 px 和 rpx 值1.9.0
                    next-marginstring"0px"后边距,可用于露出后一项的一小部分,接受 px 和 rpx 值1.9.0
                    display-multiple-itemsnumber1同时显示的滑块数量1.9.0
                    skip-hidden-item-layoutbooleanfalse是否跳过未显示的滑块布局,设为 true 可优化复杂情况下的滑动性能,但会丢失隐藏状态滑块的布局信息1.9.0
                    easing-functionstring"default"指定 swiper 切换缓动动画类型2.6.5
                    bindchangeeventhandlecurrent 改变时会触发 change 事件,event.detail = {current, source}1.0.0
                    bindtransitioneventhandleswiper-item 的位置发生改变时会触发 transition 事件,event.detail = {dx: dx, dy: dy}2.4.3
                    bindanimationfinisheventhandle动画结束时会触发 animationfinish 事件,event.detail 同上1.9.0

                    easing-function 的合法值

                    说明最低版本
                    default默认缓动函数
                    linear线性动画
                    easeInCubic缓入动画
                    easeOutCubic缓出动画
                    easeInOutCubic缓入缓出动画


                    从公共库v1.4.0开始,change事件返回detail中包含一个source字段,表示导致变更的原因,可能值如下:

                    • autoplay自动播放导致swiper变化;
                    • touch用户划动引起swiper变化;
                    • 其他原因将用空字符串表示。

                    注意:如果在 bindchange 的事件回调函数中使用 setData 改变 current 值,则有可能导致 setData 被不停地调用,因而通常情况下请在改变 current 值前检测 source 字段来判断是否是由于用户触摸引起。

                    swiper-item

                    基础库 1.0.0 开始支持,低版本需做兼容处理。

                    仅可放置在<swiper/>组件中,宽高自动设置为100%。

                    属性类型默认值必填说明最低版本
                    item-idstring该 swiper-item 的标识符1.9.0

                    示例代码:

                    <swiper indicator-dots="{{indicatorDots}}"  autoplay="{{autoplay}}" interval="{{interval}}" duration="{{duration}}">  <block wx:for="{{imgUrls}}">    <swiper-item>      <image src="{{item}}" class="slide-image" width="355" height="150"/>    </swiper-item>  </block></swiper><button bindtap="changeIndicatorDots"> indicator-dots </button><button bindtap="changeAutoplay"> autoplay </button><slider bindchange="intervalChange" show-value min="500" max="2000"/> interval<slider bindchange="durationChange" show-value min="1000" max="10000"/> duration
                    Page({  data: {    imgUrls: [      'http://img02.tooopen.com/images/20150928/tooopen_sy_143912755726.jpg',      'http://img06.tooopen.com/images/20160818/tooopen_sy_175866434296.jpg',      'http://img06.tooopen.com/images/20160818/tooopen_sy_175833047715.jpg'    ],    indicatorDots: false,    autoplay: false,    interval: 5000,    duration: 1000  },  changeIndicatorDots: function(e) {    this.setData({      indicatorDots: !this.data.indicatorDots    })  },  changeAutoplay: function(e) {    this.setData({      autoplay: !this.data.autoplay    })  },  intervalChange: function(e) {    this.setData({      interval: e.detail.value    })  },  durationChange: function(e) {    this.setData({      duration: e.detail.value    })  }})


                    movable-area

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

                    movable-view 的可移动区域

                    注意:movable-area 必须设置width和height属性,不设置默认为10px

                    movable-view

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

                    可移动的视图容器,在页面中可以拖拽滑动

                    属性名类型默认值说明
                    directionStringnonemovable-view的移动方向,属性值有all、vertical、horizontal、none
                    inertiaBooleanfalsemovable-view是否带有惯性
                    out-of-boundsBooleanfalse超过可移动区域后,movable-view是否还可以移动
                    xNumber 定义x轴方向的偏移,如果x的值不在可移动范围内,会自动移动到可移动范围;改变x的值会触发动画
                    yNumber 定义y轴方向的偏移,如果y的值不在可移动范围内,会自动移动到可移动范围;改变y的值会触发动画
                    dampingNumber20阻尼系数,用于控制x或y改变时的动画和过界回弹的动画,值越大移动越快
                    frictionNumber2摩擦系数,用于控制惯性滑动的动画,值越大摩擦力越大,滑动越快停止;必须大于0,否则会被设置成默认值

                    movable-view 必须设置width和height属性,不设置默认为10px

                    movable-view 默认为绝对定位,top和left属性为0px

                    当movable-view小于movable-area时,movable-view的移动范围是在movable-area内;当movable-view大于movable-area时,movable-view的移动范围必须包含movable-area(x轴方向和y轴方向分开考虑)

                    注意:movable-view必须在<movable-area/>组件中,并且必须是直接子节点,否则不能移动。

                    示例代码:

                    <view class="section">  <view class="section__title">movable-view区域小于movable-area</view>  <movable-area style="height: 200px;width: 200px;background: red;">    <movable-view style="height: 50px; width: 50px; background: blue;" x="{{x}}" y="{{y}}" direction="all">    </movable-view>  </movable-area>  <view class="btn-area">    <button size="mini" bindtap="tap">click me to move to (30px, 30px)</button>  </view>  <view class="section__title">movable-view区域大于movable-area</view>  <movable-area style="height: 100px;width: 100px;background: red;" direction="all">    <movable-view style="height: 200px; width: 200px; background: blue;">    </movable-view>  </movable-area></view>
                    Page({  data: {    x: 0,    y: 0  },  tap: function(e) {    this.setData({      x: 30,      y: 30    });  }})

                    cover-view

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

                    覆盖在原生组件之上的文本视图。

                    可覆盖的原生组件包括 mapvideocanvascameralive-playerlive-pusher

                    只支持嵌套 cover-view、cover-image,可在 cover-view 中使用 button。组件属性的长度单位默认为px,2.4.0起支持传入单位(rpx/px)。

                    属性类型默认值必填说明最低版本
                    scroll-topnumber/string设置顶部滚动偏移量,仅在设置了 overflow-y: scroll 成为滚动元素后生效2.1.0

                    提示

                    1. cover-viewcover-image的aria-role仅可设置为button,读屏模式下才可以点击,并朗读出“按钮”;为空时可以聚焦,但不可点击
                    2. 基础库 2.2.4 起支持 touch 相关事件,也可使用 hover-class 设置点击态
                    3. 基础库 2.1.0 起支持设置 scale rotate 的 css 样式,包括 transition 动画
                    4. 基础库 1.9.90 起 cover-view 支持 overflow: scroll,但不支持动态更新 overflow
                    5. 基础库 1.9.90 起最外层 cover-view 支持 position: fixed
                    6. 基础库 1.9.0 起支持插在 view 等标签下。在此之前只可嵌套在原生组件map、video、canvas、camera内,避免嵌套在其他组件内。
                    7. 基础库 1.6.0 起支持css transition动画,transition-property只支持transform (translateX, translateY)与opacity。
                    8. 基础库 1.6.0 起支持css opacity。
                    9. 事件模型遵循冒泡模型,但不会冒泡到原生组件。
                    10. 文本建议都套上cover-view标签,避免排版错误。
                    11. 只支持基本的定位、布局、文本样式。不支持设置单边的border、background-image、shadow、overflow: visible等。
                    12. 建议子节点不要溢出父节点
                    13. 支持使用 z-index 控制层级
                    14. 默认设置的样式有:white-space: nowrap; line-height: 1.2; display: block;
                    15. 自定义组件嵌套 cover-view 时,自定义组件的 slot 及其父节点暂不支持通过 wx:if 控制显隐,否则会导致 cover-view 不显示


                    cover-image

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

                    覆盖在原生组件之上的图片视图。可覆盖的原生组件同cover-view,支持嵌套在cover-view里。

                    属性类型默认值必填说明最低版本
                    srcstring图标路径,支持临时路径、网络地址(1.6.0起支持)、云文件ID(2.2.3起支持)。1.4.0
                    bindloadeventhandle图片加载成功时触发2.1.0
                    binderroreventhandle图片加载失败时触发2.1.0

                    支持的格式

                    格式iOSAndroid
                    JPG
                    PNG
                    SVGxx
                    WEBP
                    GIF
                    BASE64xx


                    icon

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

                    图标。组件属性的长度单位默认为px,2.4.0起支持传入单位(rpx/px)。

                    属性名类型默认值说明
                    typeString icon的类型,有效值:success, success_no_circle, info, warn, waiting, cancel, download, search, clear
                    sizeNumber23icon的大小,单位px
                    colorColor icon的颜色,同css的color

                    示例:

                    <view class="container">  <view class="icon-box">    <icon class="icon-box-img" type="success" size="93"></icon>    <view class="icon-box-ctn">      <view class="icon-box-title">成功</view>      <view class="icon-box-desc">用于表示操作顺利完成</view>    </view>  </view>  <view class="icon-box">    <icon class="icon-box-img" type="info" size="93"></icon>    <view class="icon-box-ctn">      <view class="icon-box-title">提示</view>      <view class="icon-box-desc">用于表示信息提示;也常用于缺乏条件的操作拦截,提示用户所需信息</view>    </view>  </view>  <view class="icon-box">    <icon class="icon-box-img" type="warn" size="93" color="#C9C9C9"></icon>    <view class="icon-box-ctn">      <view class="icon-box-title">普通警告</view>      <view class="icon-box-desc">用于表示操作后将引起一定后果的情况;也用于表示由于系统原因而造成的负向结果</view>    </view>  </view>  <view class="icon-box">    <icon class="icon-box-img" type="warn" size="93"></icon>    <view class="icon-box-ctn">      <view class="icon-box-title">强烈警告</view>      <view class="icon-box-desc">用于表示由于用户原因造成的负向结果;也用于表示操作后将引起不可挽回的严重后果的情况</view>    </view>  </view>  <view class="icon-box">    <icon class="icon-box-img" type="waiting" size="93"></icon>    <view class="icon-box-ctn">      <view class="icon-box-title">等待</view>      <view class="icon-box-desc">用于表示等待,告知用户结果需等待</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="success_no_circle" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">多选控件图标_已选择</view>      <view class="icon-box-desc">用于多选控件中,表示已选择该项目</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="circle" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">多选控件图标_未选择</view>      <view class="icon-box-desc">用于多选控件中,表示该项目可被选择,但还未选择</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="warn" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">错误提示</view>      <view class="icon-box-desc">用于在表单中表示出现错误</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="success" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">单选控件图标_已选择</view>      <view class="icon-box-desc">用于单选控件中,表示已选择该项目</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="download" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">下载</view>      <view class="icon-box-desc">用于表示可下载</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="info_circle" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">提示</view>      <view class="icon-box-desc">用于在表单中表示有信息提示</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="cancel" size="23"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">停止或关闭</view>      <view class="icon-box-desc">用于在表单中,表示关闭或停止</view>    </view>  </view>  <view class="icon-box">    <view class="icon-small-wrp">      <icon class="icon-small" type="search" size="14"></icon>    </view>    <view class="icon-box-ctn">      <view class="icon-box-title">搜索</view>      <view class="icon-box-desc">用于搜索控件中,表示可搜索</view>    </view>  </view></view>
                    Page({  data: {    iconSize: [20, 30, 40, 50, 60, 70],    iconColor: [      'red', 'orange', 'yellow', 'green', 'rgb(0,255,255)', 'blue', 'purple'    ],    iconType: [      'success', 'success_no_circle', 'info', 'warn', 'waiting', 'cancel', 'download', 'search', 'clear'    ]  }})

                    icon




                    text 

                    文本。
                    属性名类型默认值说明最低版本
                    selectableBooleanfalse文本是否可选1.1.0
                    spaceStringfalse显示连续空格1.4.0
                    decodeBooleanfalse是否解码1.4.0

                    space 有效值:

                    说明
                    ensp中文字符空格一半大小
                    emsp中文字符空格大小
                    nbsp根据字体设置的空格大小
                    Tips
                    • decode可以解析的有 &nbsp; &lt; &gt; &amp; &apos; &ensp; &emsp;
                    • 各个操作系统的空格标准并不一致。
                    • <text/> 组件内只支持 <text/> 嵌套。
                    • 除了文本节点以外的其他节点都无法长按选中。

                    示例:

                    代码片段

                    <view class="btn-area">  <view class="body-view">    <text>{{text}}</text>    <button bindtap="add">add line</button>    <button bindtap="remove">remove line</button>  </view></view>
                    var initData = 'this is first line
                    this is second line'var extraLine = [];Page({  data: {    text: initData  },  add: function(e) {    extraLine.push('other line')    this.setData({      text: initData + '
                    ' + extraLine.join('
                    ')    })  },  remove: function(e) {    if (extraLine.length > 0) {      extraLine.pop()      this.setData({        text: initData + '
                    ' + extraLine.join('
                    ')      })    }  }})




                    # rich-text

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

                    富文本。

                    属性类型默认值必填说明最低版本
                    nodesarray/string[]节点列表/HTML String1.4.0
                    spacestring显示连续空格2.4.1

                    space 的合法值

                    说明最低版本
                    ensp中文字符空格一半大小
                    emsp中文字符空格大小
                    nbsp根据字体设置的空格大小

                    # nodes

                    现支持两种节点,通过type来区分,分别是元素节点和文本节点,默认是元素节点,在富文本区域里显示的HTML节点 元素节点:type = node*

                    属性说明类型必填备注
                    name标签名string支持部分受信任的 HTML 节点
                    attrs属性object支持部分受信任的属性,遵循 Pascal 命名法
                    children子节点列表array结构和 nodes 一致

                    文本节点:type = text*

                    属性说明类型必填备注
                    text文本string支持entities

                    # 受信任的HTML节点及属性

                    全局支持class和style属性,不支持id属性。

                    节点属性
                    a
                    abbr
                    address
                    article
                    aside
                    b
                    bdi
                    bdodir
                    big
                    blockquote
                    br
                    caption
                    center
                    cite
                    code
                    colspan,width
                    colgroupspan,width
                    dd
                    del
                    div
                    dl
                    dt
                    em
                    fieldset
                    font
                    footer
                    h1
                    h2
                    h3
                    h4
                    h5
                    h6
                    header
                    hr
                    i
                    imgalt,src,height,width
                    ins
                    label
                    legend
                    li
                    mark
                    nav
                    olstart,type
                    p
                    pre
                    q
                    rt
                    ruby
                    s
                    section
                    small
                    span
                    strong
                    sub
                    sup
                    tablewidth
                    tbody
                    tdcolspan,height,rowspan,width
                    tfoot
                    thcolspan,height,rowspan,width
                    thead
                    trcolspan,height,rowspan,width
                    tt
                    u
                    ul

                    # Bug & Tip

                    1. tip: nodes 不推荐使用 String 类型,性能会有所下降。
                    2. tip: rich-text 组件内屏蔽所有节点的事件。
                    3. tip: attrs 属性不支持 id ,支持 class 。
                    4. tip: name 属性大小写不敏感。
                    5. tip: 如果使用了不受信任的HTML节点,该节点及其所有子节点将会被移除。
                    6. tip: img 标签仅支持网络图片。
                    7. tip: 如果在自定义组件中使用 rich-text 组件,那么仅自定义组件的 wxss 样式对 rich-text 中的 class 生效。

                    # 示例代码

                    在开发者工具中预览效果

                    JavaScript

                    const htmlSnip =`<div class="div_class">  <h1>Title</h1>  <p class="p">    Life is&nbsp;<i>like</i>&nbsp;a box of    <b>&nbsp;chocolates</b>.  </p></div>`const nodeSnip =`Page({  data: {    nodes: [{      name: 'div',      attrs: {        class: 'div_class',        style: 'line-height: 60px; color: red;'      },      children: [{        type: 'text',        text: 'You never know what you're gonna get.'      }]    }]  }})`Page({  onShareAppMessage() {    return {      title: 'rich-text',      path: 'page/component/pages/rich-text/rich-text'    }  },  data: {    htmlSnip,    nodeSnip,    renderedByHtml: false,    renderedByNode: false,    nodes: [{      name: 'div',      attrs: {        class: 'div_class',        style: 'line-height: 60px; color: #1AAD19;'      },      children: [{        type: 'text',        text: 'You never know what you're gonna get.'      }]    }]  },  renderHtml() {    this.setData({      renderedByHtml: true    })  },  renderNode() {    this.setData({      renderedByNode: true    })  },  enterCode(e) {    console.log(e.detail.value)    this.setData({      htmlSnip: e.detail.value    })  }})

                     WXML

                    <view class="container">  <view class="page-body">    <view class="page-section">      <view class="page-section-title">通过HTML String渲染</view>      <view class="page-content">        <scroll-view scroll-y>{{htmlSnip}}</scroll-view>        <button style="margin: 30rpx 0" type="primary" bindtap="renderHtml">渲染HTML</button>        <block wx:if="{{renderedByHtml}}">          <rich-text nodes="{{htmlSnip}}"></rich-text>        </block>      </view>    </view>    <view class="page-section">      <view class="page-section-title">通过节点渲染</view>      <view class="page-content">        <scroll-view scroll-y>{{nodeSnip}}</scroll-view>        <button style="margin: 30rpx 0" type="primary" bindtap="renderNode">渲染Node</button>        <block wx:if="{{renderedByNode}}">          <rich-text nodes="{{nodes}}"></rich-text>        </block>      </view>    </view>  </view></view>


                    progress

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

                    进度条。组件属性的长度单位默认为px,2.4.0起支持传入单位(rpx/px)。

                    属性类型默认值必填说明最低版本
                    percentnumber百分比0~1001.0.0
                    show-infobooleanfalse在进度条右侧显示百分比1.0.0
                    border-radiusnumber/string0圆角大小2.3.1
                    font-sizenumber/string16右侧百分比字体大小2.3.1
                    stroke-widthnumber/string6进度条线的宽度1.0.0
                    colorstring#09BB07进度条颜色(请使用activeColor)1.0.0
                    activeColorstring#09BB07已选择的进度条的颜色1.0.0
                    backgroundColorstring#EBEBEB未选择的进度条的颜色1.0.0
                    activebooleanfalse进度条从左往右的动画1.0.0
                    active-modestringbackwardsbackwards: 动画从头播;forwards:动画从上次结束点接着播1.7.0
                    durationnumber30进度增加1%所需毫秒数2.8.2
                    bindactiveendeventhandle动画完成事件2.4.1

                    示例代码

                    <view class="progress-box">  <progress percent="20" show-info stroke-width="3"/></view><view class="progress-box">  <progress percent="40" active stroke-width="3" />  <icon class="progress-cancel" type="cancel"></icon></view><view class="progress-box">  <progress percent="60" active stroke-width="3" /></view><view class="progress-box">  <progress percent="80" color="#10AEFF" active stroke-width="3" /></view>


                    progress


                    button

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

                    按钮。

                    属性类型默认值必填说明最低版本
                    sizestringdefault按钮的大小1.0.0
                    typestringdefault按钮的样式类型1.0.0
                    plainbooleanfalse按钮是否镂空,背景色透明1.0.0
                    disabledbooleanfalse是否禁用1.0.0
                    loadingbooleanfalse名称前是否带 loading 图标1.0.0
                    form-typestring用于 form 组件,点击分别会触发 form 组件的 submit/reset 事件1.0.0
                    open-typestring微信开放能力1.1.0
                    hover-classstringbutton-hover指定按钮按下去的样式类。当 hover-class="none" 时,没有点击态效果1.0.0
                    hover-stop-propagationbooleanfalse指定是否阻止本节点的祖先节点出现点击态1.5.0
                    hover-start-timenumber20按住后多久出现点击态,单位毫秒1.0.0
                    hover-stay-timenumber70手指松开后点击态保留时间,单位毫秒1.0.0
                    langstringen指定返回用户信息的语言,zh_CN 简体中文,zh_TW 繁体中文,en 英文。1.3.0
                    session-fromstring会话来源,open-type="contact"时有效1.4.0
                    send-message-titlestring当前标题会话内消息卡片标题,open-type="contact"时有效1.5.0
                    send-message-pathstring当前分享路径会话内消息卡片点击跳转小程序路径,open-type="contact"时有效1.5.0
                    send-message-imgstring截图会话内消息卡片图片,open-type="contact"时有效1.5.0
                    app-parameterstring打开 APP 时,向 APP 传递的参数,open-type=launchApp时有效1.9.5
                    show-message-cardbooleanfalse是否显示会话内消息卡片,设置此参数为 true,用户进入客服会话会在右下角显示"可能要发送的小程序"提示,用户点击后可以快速发送小程序消息,open-type="contact"时有效1.5.0
                    bindgetuserinfoeventhandle用户点击该按钮时,会返回获取到的用户信息,回调的detail数据与wx.getUserInfo返回的一致,open-type="getUserInfo"时有效1.3.0
                    bindcontacteventhandle客服消息回调,open-type="contact"时有效1.5.0
                    bindgetphonenumbereventhandle获取用户手机号回调,open-type=getPhoneNumber时有效1.2.0
                    binderroreventhandle当使用开放能力时,发生错误的回调,open-type=launchApp时有效1.9.5
                    bindopensettingeventhandle在打开授权设置页后回调,open-type=openSetting时有效2.0.7
                    bindlaunchappeventhandle打开 APP 成功的回调,open-type=launchApp时有效2.4.4

                    size 的合法值

                    说明最低版本
                    default默认大小
                    mini小尺寸

                    type 的合法值

                    说明最低版本
                    primary绿色
                    default白色
                    warn红色

                    form-type 的合法值

                    说明最低版本
                    submit提交表单
                    reset重置表单

                    open-type 的合法值

                    说明最低版本
                    contact打开客服会话,如果用户在会话中点击消息卡片后返回小程序,可以从 bindcontact 回调中获得具体信息,具体说明1.1.0
                    share触发用户转发,使用前建议先阅读使用指引1.2.0
                    getPhoneNumber获取用户手机号,可以从bindgetphonenumber回调中获取到用户信息,具体说明1.2.0
                    getUserInfo获取用户信息,可以从bindgetuserinfo回调中获取到用户信息1.3.0
                    launchApp打开APP,可以通过app-parameter属性设定向APP传的参数具体说明1.9.5
                    openSetting打开授权设置页2.0.7
                    feedback打开“意见反馈”页面,用户可提交反馈内容并上传日志,开发者可以登录小程序管理后台后进入左侧菜单“客服反馈”页面获取到反馈内容2.1.0

                    lang 的合法值

                    说明最低版本
                    en英文
                    zh_CN简体中文
                    zh_TW繁体中文

                    提示:

                    1. button-hover 默认为{background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}
                    2. bindgetphonenumber 从1.2.0 开始支持,但是在1.5.3以下版本中无法使用wx.canIUse进行检测,建议使用基础库版本进行判断。
                    3. 在bindgetphonenumber 等返回加密信息的回调中调用 wx.login 登录,可能会刷新登录态。此时服务器使用 code 换取的 sessionKey 不是加密时使用的 sessionKey,导致解密失败。建议开发者提前进行 login;或者在回调中先使用 checkSession 进行登录态检查,避免 login 刷新登录态。
                    4. 从 2.1.0 起,button 可作为原生组件的子节点嵌入,以便在原生组件上使用 open-type 的能力。
                    5. 目前设置了 form-type 的 button 只会对当前组件中的 form 有效。因而,将 button 封装在自定义组件中,而 form 在自定义组件外,将会使这个 button 的 form-type 失效。

                    示例代码:

                    /** 修改button默认的点击态样式类**/.button-hover {  background-color: red;}/** 添加自定义button点击态样式类**/.other-button-hover {  background-color: blue;}
                    WXML文件<button type="default" size="{{defaultSize}}" loading="{{loading}}" plain="{{plain}}"        disabled="{{disabled}}" bindtap="default" hover-class="other-button-hover"> default </button><button type="primary" size="{{primarySize}}" loading="{{loading}}" plain="{{plain}}"        disabled="{{disabled}}" bindtap="primary"> primary </button><button type="warn" size="{{warnSize}}" loading="{{loading}}" plain="{{plain}}"        disabled="{{disabled}}" bindtap="warn"> warn </button><button bindtap="setDisabled">点击设置以上按钮disabled属性</button><button bindtap="setPlain">点击设置以上按钮plain属性</button><button bindtap="setLoading">点击设置以上按钮loading属性</button><button open-type="contact">进入客服会话</button>
                    JS文件var types = ['default', 'primary', 'warn']var pageObject = {  data: {    defaultSize: 'default',    primarySize: 'default',    warnSize: 'default',    disabled: false,    plain: false,    loading: false  },  setDisabled: function(e) {    this.setData({      disabled: !this.data.disabled    })  },  setPlain: function(e) {    this.setData({      plain: !this.data.plain    })  },  setLoading: function(e) {    this.setData({      loading: !this.data.loading    })  }}for (var i = 0; i < types.length; ++i) {  (function(type) {    pageObject[type] = function(e) {      var key = type + 'Size'      var changedData = {}      changedData[key] =        this.data[key] === 'default' ? 'mini' : 'default'      this.setData(changedData)    }  })(types[i])}Page(pageObject)




                    微信小程序表单组件 checkbox

                    checkbox-group

                    多项选择器,内部由多个checkbox组成。

                    属性名 类型 默认值 说明
                    bindchange EventHandle   <checkbox-group/>中选中项发生改变是触发change事件,detail = {value:[选中的checkbox的value的数组]}

                    checkbox

                    多选项目。

                    属性名 类型 默认值 说明
                    value String   <checkbox/>标识,选中时触发<checkbox-group/>的change事件,并携带<checkbox/>的value
                    disabled Boolean false 是否禁用
                    checked Boolean false 当前是否选中,可用来设置默认选中
                    color Color   checkbox的颜色,同css的color

                    示例:

                    <checkbox-group bindchange="checkboxChange">    <label class="checkbox" wx:for-items="{{items}}">        <checkbox value="{{item.name}}" checked="{{item.checked}}"/>{{item.value}}    </label></checkbox-group>
                    Page({  data: {    items: [      {name: 'USA', value: '美国'},      {name: 'CHN', value: '中国', checked: 'true'},      {name: 'BRA', value: '巴西'},      {name: 'JPN', value: '日本'},      {name: 'ENG', value: '英国'},      {name: 'TUR', value: '法国'},    ]  },  checkboxChange: function(e) {    console.log('checkbox发生change事件,携带value值为:', e.detail.value)  }})

                    checkbox

                    微信小程序form

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

                    表单。将组件内的用户输入的switch input checkbox slider radio picker 提交。

                    当点击 form 表单中 form-type 为 submit 的 button 组件时,会将表单组件中的 value 值进行提交,需要在表单组件中加上 name 来作为 key。

                    属性类型默认值必填说明最低版本
                    report-submitbooleanfalse是否返回 formId 用于发送模板消息1.0.0
                    report-submit-timeoutnumber0等待一段时间(毫秒数)以确认 formId 是否生效。如果未指定这个参数,formId 有很小的概率是无效的(如遇到网络失败的情况)。指定这个参数将可以检测 formId 是否有效,以这个参数的时间作为这项检测的超时时间。如果失败,将返回 requestFormId:fail 开头的 formId2.6.2
                    bindsubmiteventhandle携带 form 中的数据触发 submit 事件,event.detail = {value : {'name': 'value'} , formId: ''}1.0.0
                    bindreseteventhandle表单重置时会触发 reset 事件1.0.0

                    示例代码:

                    <form bindsubmit="formSubmit" bindreset="formReset">    <view class="section section_gap">        <view class="section__title">switch</view>        <switch name="switch"/>    </view>    <view class="section section_gap">        <view class="section__title">slider</view>        <slider name="slider" show-value ></slider>    </view>    <view class="section">        <view class="section__title">input</view>        <input name="input" placeholder="please input here" />    </view>    <view class="section section_gap">        <view class="section__title">radio</view>        <radio-group name="radio-group">            <label><radio value="radio1"/>radio1</label>            <label><radio value="radio2"/>radio2</label>        </radio-group>    </view>    <view class="section section_gap">        <view class="section__title">checkbox</view>        <checkbox-group name="checkbox">            <label><checkbox value="checkbox1"/>checkbox1</label>            <label><checkbox value="checkbox2"/>checkbox2</label>        </checkbox-group>    </view>    <view class="btn-area">        <button formType="submit">Submit</button>        <button formType="reset">Reset</button>    </view></form>
                    Page({  formSubmit: function(e) {    console.log('form发生了submit事件,携带数据为:', e.detail.value)  },  formReset: function() {    console.log('form发生了reset事件')  }})

                    form


                    input

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

                    输入框。该组件是原生组件,使用时请注意相关限制

                    属性类型默认值必填说明最低版本
                    valuestring输入框的初始内容1.0.0
                    typestringtextinput 的类型1.0.0
                    passwordbooleanfalse是否是密码类型1.0.0
                    placeholderstring输入框为空时占位符1.0.0
                    placeholder-stylestring指定 placeholder 的样式1.0.0
                    placeholder-classstringinput-placeholder指定 placeholder 的样式类1.0.0
                    disabledbooleanfalse是否禁用1.0.0
                    maxlengthnumber140最大输入长度,设置为 -1 的时候不限制最大长度1.0.0
                    cursor-spacingnumber0指定光标与键盘的距离,取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离1.0.0
                    auto-focusbooleanfalse(即将废弃,请直接使用 focus )自动聚焦,拉起键盘1.0.0
                    focusbooleanfalse获取焦点1.0.0
                    confirm-typestringdone设置键盘右下角按钮的文字,仅在type='text'时生效1.1.0
                    confirm-holdbooleanfalse点击键盘右下角按钮时是否保持键盘不收起1.1.0
                    cursornumber指定focus时的光标位置1.5.0
                    selection-startnumber-1光标起始位置,自动聚集时有效,需与selection-end搭配使用1.9.0
                    selection-endnumber-1光标结束位置,自动聚集时有效,需与selection-start搭配使用1.9.0
                    adjust-positionbooleantrue键盘弹起时,是否自动上推页面1.9.90
                    hold-keyboardbooleanfalsefocus时,点击页面的时候不收起键盘2.8.2
                    bindinputeventhandle键盘输入时触发,event.detail = {value, cursor, keyCode},keyCode 为键值,2.1.0 起支持,处理函数可以直接 return 一个字符串,将替换输入框的内容。1.0.0
                    bindfocuseventhandle输入框聚焦时触发,event.detail = { value, height },height 为键盘高度,在基础库 1.9.90 起支持1.0.0
                    bindblureventhandle输入框失去焦点时触发,event.detail = {value: value}1.0.0
                    bindconfirmeventhandle点击完成按钮时触发,event.detail = {value: value}1.0.0
                    bindkeyboardheightchangeeventhandle键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration}2.7.0

                    type 的合法值

                    说明最低版本
                    text文本输入键盘
                    number数字输入键盘
                    idcard身份证输入键盘
                    digit带小数点的数字键盘

                    confirm-type 的合法值

                    说明最低版本
                    send右下角按钮为“发送”
                    search右下角按钮为“搜索”
                    next右下角按钮为“下一个”
                    go右下角按钮为“前往”
                    done右下角按钮为“完成”

                    提示:

                    1. confirm-type的最终表现与手机输入法本身的实现有关,部分安卓系统输入法和第三方输入法可能不支持或不完全支持
                    2. input 组件是一个原生组件,字体是系统字体,所以无法设置 font-family
                    3. 在 input 聚焦期间,避免使用 css 动画
                    4. 对于将 input 封装在自定义组件中、而 form 在自定义组件外的情况, form 将不能获得这个自定义组件中 input 的值。此时需要使用自定义组件的 内置 behaviors wx://form-field
                    5. 键盘高度发生变化,keyboardheightchange事件可能会多次触发,开发者对于相同的height值应该忽略掉
                    6. 微信版本 6.3.30, focus 属性设置无效
                    7. 微信版本 6.3.30, placeholder 在聚焦时出现重影问题

                    示例代码:

                    <view class="page-body">  <view class="page-section">    <view class="weui-cells__title">可以自动聚焦的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" auto-focus placeholder="将会获取焦点"/>      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">控制最大输入长度的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" maxlength="10" placeholder="最大输入长度为10" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">实时获取输入值:{{inputValue}}</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input"  maxlength="10" bindinput="bindKeyInput" placeholder="输入同步到view中"/>      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">控制输入的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input"  bindinput="bindReplaceInput" placeholder="连续的两个1会变成2" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">控制键盘的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input"  bindinput="bindHideKeyboard" placeholder="输入123自动收起键盘" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">数字输入的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" type="number" placeholder="这是一个数字输入框" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">密码输入的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" password type="text" placeholder="这是一个密码输入框" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">带小数点的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" type="digit" placeholder="带小数点的数字键盘"/>      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">身份证输入的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" type="idcard" placeholder="身份证输入键盘" />      </view>    </view>  </view>  <view class="page-section">    <view class="weui-cells__title">控制占位符颜色的input</view>    <view class="weui-cells weui-cells_after-title">      <view class="weui-cell weui-cell_input">        <input class="weui-input" placeholder-style="color:#F76260" placeholder="占位符字体是红色的" />      </view>    </view>  </view></view>
                    Page({  data: {    focus: false,    inputValue: ''  },  bindKeyInput: function (e) {    this.setData({      inputValue: e.detail.value    })  },  bindReplaceInput: function (e) {    var value = e.detail.value    var pos = e.detail.cursor    var left    if (pos !== -1) {      // 光标在中间      left = e.detail.value.slice(0, pos)      // 计算光标的位置      pos = left.replace(/11/g, '2').length    }    // 直接返回对象,可以对输入进行过滤处理,同时可以控制光标的位置    return {      value: value.replace(/11/g, '2'),      cursor: pos    }    // 或者直接返回字符串,光标在最后边    // return value.replace(/11/g,'2'),  },  bindHideKeyboard: function (e) {    if (e.detail.value === '123') {      // 收起键盘      wx.hideKeyboard()    }  }})

                    1595573794(1)


                    label

                    用来改进表单组件的可用性,使用for属性找到对应的id,或者将控件放在该标签下,当点击时,就会触发对应的控件。

                    for优先级高于内部控件,内部有多个控件的时候默认触发第一个控件。

                    目前可以绑定的控件有:<button/>, <checkbox/>, <radio/>, <switch/>

                    属性名 类型 说明
                    for String 绑定控件的id

                    示例代码:

                    <view class="section section_gap"><view class="section__title">表单组件在label内</view><checkbox-group class="group" bindchange="checkboxChange">    <view class="label-1" wx:for-items="{{checkboxItems}}">        <label>            <checkbox hidden value="{{item.name}}" checked="{{item.checked}}"></checkbox>            <view class="label-1__icon">                <view class="label-1__icon-checked" style="opacity:{{item.checked ? 1: 0}}"></view>            </view>            <text class="label-1__text">{{item.value}}</text>        </label>    </view></checkbox-group></view><view class="section section_gap"><view class="section__title">label用for标识表单组件</view><radio-group class="group" bindchange="radioChange">    <view class="label-2" wx:for-items="{{radioItems}}">        <radio id="{{item.name}}" hidden value="{{item.name}}" checked="{{item.checked}}"></radio>        <view class="label-2__icon">            <view class="label-2__icon-checked" style="opacity:{{item.checked ? 1: 0}}"></view>        </view>        <label class="label-2__text" for="{{item.name}}"><text>{{item.name}}</text></label>    </view></radio-group></view>
                    Page({  data: {    checkboxItems: [      {name: 'USA', value: '美国'},      {name: 'CHN', value: '中国', checked: 'true'},      {name: 'BRA', value: '巴西'},      {name: 'JPN', value: '日本', checked: 'true'},      {name: 'ENG', value: '英国'},      {name: 'TUR', value: '法国'},    ],    radioItems: [      {name: 'USA', value: '美国'},      {name: 'CHN', value: '中国', checked: 'true'},      {name: 'BRA', value: '巴西'},      {name: 'JPN', value: '日本'},      {name: 'ENG', value: '英国'},      {name: 'TUR', value: '法国'},    ],    hidden: false  },  checkboxChange: function(e) {    var checked = e.detail.value    var changed = {}    for (var i = 0; i < this.data.checkboxItems.length; i ++) {      if (checked.indexOf(this.data.checkboxItems[i].name) !== -1) {        changed['checkboxItems['+i+'].checked'] = true      } else {        changed['checkboxItems['+i+'].checked'] = false      }    }    this.setData(changed)  },  radioChange: function(e) {    var checked = e.detail.value    var changed = {}    for (var i = 0; i < this.data.radioItems.length; i ++) {      if (checked.indexOf(this.data.radioItems[i].name) !== -1) {        changed['radioItems['+i+'].checked'] = true      } else {        changed['radioItems['+i+'].checked'] = false      }    }    this.setData(changed)  }})
                    .label-1, .label-2{    margin-bottom: 15px;}.label-1__text, .label-2__text {    display: inline-block;    vertical-align: middle;}.label-1__icon {    position: relative;    margin-right: 10px;    display: inline-block;    vertical-align: middle;    width: 18px;    height: 18px;    background: #fcfff4;}.label-1__icon-checked {    position: absolute;    top: 3px;    left: 3px;    width: 12px;    height: 12px;    background: #1aad19;}.label-2__icon {    position: relative;    display: inline-block;    vertical-align: middle;    margin-right: 10px;    width: 18px;    height: 18px;    background: #fcfff4;    border-radius: 50px;}.label-2__icon-checked {    position: absolute;    left: 3px;    top: 3px;    width: 12px;    height: 12px;    background: #1aad19;    border-radius: 50%;}.label-4_text{    text-align: center;    margin-top: 15px;}

                    label

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

                    从底部弹起的滚动选择器。

                    属性类型默认值必填说明最低版本
                    header-textstring选择器的标题,仅安卓可用2.11.0
                    modestringselector选择器类型1.0.0
                    disabledbooleanfalse是否禁用1.0.0
                    bindcanceleventhandle取消选择时触发1.9.90

                    mode 的合法值

                    说明最低版本
                    selector普通选择器
                    multiSelector多列选择器
                    time时间选择器
                    date日期选择器
                    region省市区选择器

                    除了上述通用的属性,对于不同的mode,picker拥有不同的属性。

                    普通选择器:mode = selector

                    属性名类型默认值说明最低版本
                    rangearray/object array[]mode 为 selector 或 multiSelector 时,range 有效
                    range-keystring当 range 是一个 Object Array 时,通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
                    valuenumber0表示选择了 range 中的第几个(下标从 0 开始)
                    bindchangeeventhandlevalue 改变时触发 change 事件,event.detail = {value}

                    多列选择器:mode = multiSelector

                    属性名类型默认值说明最低版本
                    rangearray/object array[]mode 为 selector 或 multiSelector 时,range 有效
                    range-keystring当 range 是一个 Object Array 时,通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
                    valuearray[]表示选择了 range 中的第几个(下标从 0 开始)
                    bindchangeeventhandlevalue 改变时触发 change 事件,event.detail = {value}
                    bindcolumnchangeeventhandle列改变时触发

                    时间选择器:mode = time

                    属性名类型默认值说明最低版本
                    valuestring表示选中的时间,格式为"hh:mm"
                    startstring表示有效时间范围的开始,字符串格式为"hh:mm"
                    endstring表示有效时间范围的结束,字符串格式为"hh:mm"
                    bindchangeeventhandlevalue 改变时触发 change 事件,event.detail = {value}

                    日期选择器:mode = date

                    属性名类型默认值说明最低版本
                    valuestring当天表示选中的日期,格式为"YYYY-MM-DD"
                    startstring表示有效日期范围的开始,字符串格式为"YYYY-MM-DD"
                    endstring表示有效日期范围的结束,字符串格式为"YYYY-MM-DD"
                    fieldsstringday有效值 year,month,day,表示选择器的粒度
                    bindchangeeventhandlevalue 改变时触发 change 事件,event.detail = {value}

                    fields 有效值:*

                    说明
                    year选择器粒度为年
                    month选择器粒度为月份
                    day选择器粒度为天

                    省市区选择器:mode = region 1.4.0

                    属性名类型默认值说明最低版本
                    valuearray[]表示选中的省市区,默认选中每一列的第一个值
                    custom-itemstring可为每一列的顶部添加一个自定义的项1.5.0
                    bindchangeeventhandlevalue 改变时触发 change 事件,event.detail = {value, code, postcode},其中字段 code 是统计用区划代码,postcode 是邮政编码


                    示例代码:

                    <view class="section">    <view class="sectiontitle">普通选择器</view>    <picker bindchange="bindPickerChange" value="{{index}}" range="{{array}}">        <view class="picker">            当前选择: {{array[index]}}        </view>    </picker></view>    <view class="sectiontitle">多列选择器    <picker mode="multiSelector" bindchange="bindMultiPickerChange" bindcolumnchange="bindMultiPickerColumnChange" value="{{multiIndex}}">            当前选择: {{multiArray[0][multiIndex[0]]}},{{multiArray[1][multiIndex[1]]}},{{multiArray[2][multiIndex[2]]}}     <view class="section">    <view class="sectiontitle">时间选择器</view>    <picker mode="time" value="{{time}}" start="09:01" end="21:01" bindchange="bindTimeChange">        <view class="picker">            当前选择: {{time}}        </view>    </picker></view>

                    <view class="section"> <view class="sectiontitle">日期选择器</view> <picker mode="date" value="{{date}}" start="2015-09-01" end="2017-09-01" bindchange="bindDateChange"> <view class="picker"> 当前选择: {{date}} </view> </picker></view>

                    省市区选择器 当前选择: {{region[0]}},{{region[1]}},{{region[2]}}

                    Page({  data: {    array: ['美国', '中国', '巴西', '日本'],    objectArray: [      {        id: 0,        name: '美国'      },      {        id: 1,        name: '中国'      },      {        id: 2,        name: '巴西'      },      {        id: 3,        name: '日本'      }    ],    index: 0,    multiArray: [['无脊柱动物', '脊柱动物'], ['扁性动物', '线形动物', '环节动物', '软体动物', '节肢动物'], ['猪肉绦虫', '吸血虫']],    objectMultiArray: [      [        {          id: 0,          name: '无脊柱动物'        },        {          id: 1,          name: '脊柱动物'        }      ], [        {          id: 0,          name: '扁性动物'        },        {          id: 1,          name: '线形动物'        },        {          id: 2,          name: '环节动物'        },        {          id: 3,          name: '软体动物'        },        {          id: 3,          name: '节肢动物'        }      ], [        {          id: 0,          name: '猪肉绦虫'        },        {          id: 1,          name: '吸血虫'        }      ]    ],    multiIndex: [0, 0, 0],    date: '2016-09-01',    time: '12:01',    region: ['广东省', '广州市', '海珠区']  },  bindPickerChange: function(e) {    console.log('picker发送选择改变,携带值为', e.detail.value)    this.setData({      index: e.detail.value    })  },  bindMultiPickerChange: function (e) {    console.log('picker发送选择改变,携带值为', e.detail.value)    this.setData({      multiIndex: e.detail.value    })  },  bindMultiPickerColumnChange: function (e) {    console.log('修改的列为', e.detail.column, ',值为', e.detail.value);    var data = {      multiArray: this.data.multiArray,      multiIndex: this.data.multiIndex    };    data.multiIndex[e.detail.column] = e.detail.value;    switch (e.detail.column) {      case 0:        switch (data.multiIndex[0]) {          case 0:            data.multiArray[1] = ['扁性动物', '线形动物', '环节动物', '软体动物', '节肢动物'];            data.multiArray[2] = ['猪肉绦虫', '吸血虫'];            break;          case 1:            data.multiArray[1] = ['鱼', '两栖动物', '爬行动物'];            data.multiArray[2] = ['鲫鱼', '带鱼'];            break;        }        data.multiIndex[1] = 0;        data.multiIndex[2] = 0;        break;      case 1:        switch (data.multiIndex[0]) {          case 0:            switch (data.multiIndex[1]) {              case 0:                data.multiArray[2] = ['猪肉绦虫', '吸血虫'];                break;              case 1:                data.multiArray[2] = ['蛔虫'];                break;              case 2:                data.multiArray[2] = ['蚂蚁', '蚂蟥'];                break;              case 3:                data.multiArray[2] = ['河蚌', '蜗牛', '蛞蝓'];                break;              case 4:                data.multiArray[2] = ['昆虫', '甲壳动物', '蛛形动物', '多足动物'];                break;            }            break;          case 1:            switch (data.multiIndex[1]) {              case 0:                data.multiArray[2] = ['鲫鱼', '带鱼'];                break;              case 1:                data.multiArray[2] = ['青蛙', '娃娃鱼'];                break;              case 2:                data.multiArray[2] = ['蜥蜴', '龟', '壁虎'];                break;            }            break;        }        data.multiIndex[2] = 0;        console.log(data.multiIndex);        break;    }    this.setData(data);  },  bindDateChange: function(e) {    console.log('picker发送选择改变,携带值为', e.detail.value)    this.setData({      date: e.detail.value    })  },  bindTimeChange: function(e) {    console.log('picker发送选择改变,携带值为', e.detail.value)    this.setData({      time: e.detail.value    })  },  bindRegionChange: function (e) {    console.log('picker发送选择改变,携带值为', e.detail.value)    this.setData({      region: e.detail.value    })  }})

                    picker




                    picker-view


                    嵌入页面的滚动选择器

                    属性名类型说明最低版本
                    valueNumberArray数组中的数字依次表示 picker-view 内的 picker-view-colume 选择的第几项(下标从 0 开始),数字大于 picker-view-column 可选项长度时,选择最后一项。 
                    indicator-styleString设置选择器中间选中框的样式 
                    indicator-classString设置选择器中间选中框的类名1.1.0
                    bindchangeEventHandle当滚动选择,value 改变时触发 change 事件,event.detail = {value: value};value为数组,表示 picker-view 内的 picker-view-column 当前选择的是第几项(下标从 0 开始) 

                    注意:其中只可放置<picker-view-column/>组件,其他节点不会显示。

                    picker-view-column

                    仅可放置于<picker-view />中,其孩子节点的高度会自动设置成与picker-view的选中框的高度一致。

                    示例代码:

                    <view>  <view>{{year}}年{{month}}月{{day}}日</view>  <picker-view indicator-style="height: 50px;" style="width: 100%; height: 300px;" value="{{value}}" bindchange="bindChange">    <picker-view-column>      <view wx:for="{{years}}" style="line-height: 50px">{{item}}年</view>    </picker-view-column>    <picker-view-column>      <view wx:for="{{months}}" style="line-height: 50px">{{item}}月</view>    </picker-view-column>    <picker-view-column>      <view wx:for="{{days}}" style="line-height: 50px">{{item}}日</view>    </picker-view-column>  </picker-view></view>
                    const date = new Date()const years = []const months = []const days = []for (let i = 1990; i <= date.getFullYear(); i++) {  years.push(i)}for (let i = 1 ; i <= 12; i++) {  months.push(i)}for (let i = 1 ; i <= 31; i++) {  days.push(i)}Page({  data: {    years: years,    year: date.getFullYear(),    months: months,    month: 2,    days: days,    day: 2,    year: date.getFullYear(),    value: [9999, 1, 1],  },  bindChange: function(e) {    const val = e.detail.value    this.setData({      year: this.data.years[val[0]],      month: this.data.months[val[1]],      day: this.data.days[val[2]]    })  }})

                    picker_view

                    微信小程序单选框radio

                    radio-group

                    单项选择器,内部由多个<radio/>组成。

                    属性名 类型 默认值 说明
                    bindchange EventHandle   <radio-group/>中的选中项发生变化时触发change事件,event.detail = {value: 选中项radio的value}

                    radio


                    ​ 单选项目

                    属性名类型默认值说明
                    valueString <radio/>标识。当该<radio/>选中时,<radio-group/> 的change 事件会携带<radio/>的value
                    checkedBooleanfalse当前是否选中
                    disabledBooleanfalse是否禁用
                    colorColor radio的颜色,同css的color

                    <radio-group class="radio-group" bindchange="radioChange">    <label class="radio" wx:for="{{items}}">        <radio value="{{item.name}}" checked="{{item.checked}}"/>{{item.value}}    </label></radio-group>
                    Page({   data: {    items: [      {name: 'USA', value: '美国'},      {name: 'CHN', value: '中国', checked: 'true'},      {name: 'BRA', value: '巴西'},      {name: 'JPN', value: '日本'},      {name: 'ENG', value: '英国'},      {name: 'TUR', value: '法国'},    ]  },  radioChange: function(e) {    console.log('radio发生change事件,携带value值为:', e.detail.value)  }})

                    radio

                    slider

                    滑动选择器。

                    属性名类型默认值说明最低版本
                    minNumber0最小值
                    maxNumber100最大值
                    stepNumber1步长,取值必须大于 0,并且可被(max - min)整除
                    disabledBooleanfalse是否禁用
                    valueNumber0当前取值
                    colorColor#e9e9e9背景条的颜色(请使用 backgroundColor)
                    selected-colorColor#1aad19已选择的颜色(请使用 activeColor)
                    activeColorColor#1aad19已选择的颜色
                    backgroundColorColor#e9e9e9背景条的颜色
                    show-valueBooleanfalse是否显示当前 value
                    bindchangeEventHandle完成一次拖动后触发的事件,event.detail = {value: value}
                    bindchangingEventHandle拖动过程中触发的事件,event.detail = {value: value}1.7.0

                    示例代码:

                    <view class="section section_gap">    <text class="section__title">设置left/right icon</text>    <view class="body-view">        <slider bindchange="slider1change" left-icon="cancel" right-icon="success_no_circle"/>    </view></view><view class="section section_gap">    <text class="section__title">设置step</text>    <view class="body-view">        <slider bindchange="slider2change" step="5"/>    </view></view><view class="section section_gap">    <text class="section__title">显示当前value</text>    <view class="body-view">        <slider bindchange="slider3change" show-value/>    </view></view><view class="section section_gap">    <text class="section__title">设置最小/最大值</text>    <view class="body-view">        <slider bindchange="slider4change" min="50" max="200" show-value/>    </view></view>
                    var pageData = {}for(var i = 1; i < 5; ++i) {  (function (index) {    pageData['slider' + index + 'change'] = function(e) {      console.log('slider' + 'index' + '发生 change 事件,携带值为', e.detail.value)    }  })(i);}Page(pageData)



                    switch

                    开关选择器。

                    属性名类型默认值说明
                    checkedBooleanfalse是否选中
                    disabledBooleanfalse是否禁用
                    typeStringswitch样式,有效值:switch, checkbox
                    bindchangeEventHandle checked 改变时触发change事件,event.detail={ value}
                    colorString #04BE02switch的颜色,同css的color
                    <view class="body-view">    <switch checked bindchange="switch1Change"/>    <switch bindchange="switch2Change"/></view>
                    page({  switch1Checked: function (e){    console.log('switch1 发生 change 事件,携带值为', e.detail.value)  },  switch2Change: function (e){    console.log('switch2 发生 change 事件,携带值为', e.detail.value)  }})

                    switch


                    textarea

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

                    多行输入框。该组件是原生组件,使用时请注意相关限制。

                    属性类型默认值必填说明最低版本
                    valuestring输入框的内容1.0.0
                    placeholderstring输入框为空时占位符1.0.0
                    placeholder-stylestring指定 placeholder 的样式,目前仅支持color,font-size和font-weight1.0.0
                    placeholder-classstringtextarea-placeholder指定 placeholder 的样式类1.0.0
                    disabledbooleanfalse是否禁用1.0.0
                    maxlengthnumber140最大输入长度,设置为 -1 的时候不限制最大长度1.0.0
                    auto-focusbooleanfalse自动聚焦,拉起键盘。1.0.0
                    focusbooleanfalse获取焦点1.0.0
                    auto-heightbooleanfalse是否自动增高,设置auto-height时,style.height不生效1.0.0
                    fixedbooleanfalse如果 textarea 是在一个 position:fixed 的区域,需要显示指定属性 fixed 为 true1.0.0
                    cursor-spacingnumber0指定光标与键盘的距离。取textarea距离底部的距离和cursor-spacing指定的距离的最小值作为光标与键盘的距离1.0.0
                    cursornumber-1指定focus时的光标位置1.5.0
                    show-confirm-barbooleantrue是否显示键盘上方带有”完成“按钮那一栏1.6.0
                    selection-startnumber-1光标起始位置,自动聚集时有效,需与selection-end搭配使用1.9.0
                    selection-endnumber-1光标结束位置,自动聚集时有效,需与selection-start搭配使用1.9.0
                    adjust-positionbooleantrue键盘弹起时,是否自动上推页面1.9.90
                    hold-keyboardbooleanfalsefocus时,点击页面的时候不收起键盘2.8.2
                    disable-default-paddingbooleanfalse是否去掉 iOS 下的默认内边距2.10.0
                    confirm-typestringreturn设置键盘右下角按钮的文字2.13.0
                    confirm-holdbooleanfalse点击键盘右下角按钮时是否保持键盘不收起2.16.0
                    bindfocuseventhandle输入框聚焦时触发,event.detail = { value, height },height 为键盘高度,在基础库 1.9.90 起支持1.0.0
                    bindblureventhandle输入框失去焦点时触发,event.detail = {value, cursor}1.0.0
                    bindlinechangeeventhandle输入框行数变化时调用,event.detail = {height: 0, heightRpx: 0, lineCount: 0}1.0.0
                    bindinputeventhandle当键盘输入时,触发 input 事件,event.detail = {value, cursor, keyCode},keyCode 为键值,目前工具还不支持返回keyCode参数。bindinput 处理函数的返回值并不会反映到 textarea 上1.0.0
                    bindconfirmeventhandle点击完成时, 触发 confirm 事件,event.detail = {value: value}1.0.0
                    bindkeyboardheightchangeeventhandle键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration}2.7.0


                    confirm-type 的合法值

                    说明最低版本
                    send右下角按钮为“发送”
                    search右下角按钮为“搜索”
                    next右下角按钮为“下一个”
                    go右下角按钮为“前往”
                    done右下角按钮为“完成”
                    return右下角按钮为“换行”

                    Bug & Tip

                    1. tip: textareablur 事件会晚于页面上的 tap 事件,如果需要在 button 的点击事件获取 textarea,可以使用 formbindsubmit
                    2. tip: 不建议在多行文本上对用户的输入进行修改,所以 textareabindinput 处理函数并不会将返回值反映到 textarea 上。
                    3. tip : 键盘高度发生变化,keyboardheightchange事件可能会多次触发,开发者对于相同的height值应该忽略掉
                    4. bug: 微信版本 6.3.30textarea 在列表渲染时,新增加的 textarea 在自动聚焦时的位置计算错误。

                    示例代码

                    在开发者工具中预览效果

                    <view class="section">  <textarea bindblur="bindTextAreaBlur" auto-height placeholder="自动变高" /></view><view class="section">  <textarea placeholder="placeholder颜色是红色的" placeholder-style="color:red;"  /></view><view class="section">  <textarea placeholder="这是一个可以自动聚焦的textarea" auto-focus /></view><view class="section">  <textarea placeholder="这个只有在按钮点击的时候才聚焦" focus="{{focus}}" />  <view class="btn-area">    <button bindtap="bindButtonTap">使得输入框获取焦点</button>  </view></view><view class="section">  <form bindsubmit="bindFormSubmit">    <textarea placeholder="form 中的 textarea" name="textarea"/>    <button form-type="submit"> 提交 </button>  </form></view>
                    //textarea.jsPage({  data: {    height: 20,    focus: false  },  bindButtonTap: function() {    this.setData({      focus: true    })  },  bindTextAreaBlur: function(e) {    console.log(e.detail.value)  },  bindFormSubmit: function(e) {    console.log(e.detail.value.textarea)  }})

                    editor

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

                    富文本编辑器,可以对图片、文字进行编辑。

                    编辑器导出内容支持带标签的 html和纯文本的 text,编辑器内部采用 delta 格式进行存储。

                    通过setContents接口设置内容时,解析插入的 html 可能会由于一些非法标签导致解析错误,建议开发者在小程序内使用时通过 delta 进行插入。

                    富文本组件内部引入了一些基本的样式使得内容可以正确的展示,开发时可以进行覆盖。需要注意的是,在其它组件或环境中使用富文本组件导出的html时,需要额外引入 这段样式,并维护<ql-container><ql-editor></ql-editor></ql-container>的结构。

                    图片控件仅初始化时设置有效。

                    相关 api:EditorContext

                    属性类型默认值必填说明最低版本
                    read-onlybooleanfalse设置编辑器为只读2.7.0
                    placeholderstring提示信息2.7.0
                    show-img-sizebooleanfalse点击图片时显示图片大小控件2.7.0
                    show-img-toolbarbooleanfalse点击图片时显示工具栏控件2.7.0
                    show-img-resizebooleanfalse点击图片时显示修改尺寸控件2.7.0
                    bindreadyeventhandle编辑器初始化完成时触发2.7.0
                    bindfocuseventhandle编辑器聚焦时触发,event.detail = {html, text, delta}2.7.0
                    bindblureventhandle编辑器失去焦点时触发,detail = {html, text, delta}2.7.0
                    bindinputeventhandle编辑器内容改变时触发,detail = {html, text, delta}2.7.0
                    bindstatuschangeeventhandle通过 Context 方法改变编辑器内样式时触发,返回选区已设置的样式2.7.0

                    编辑器内支持部分 HTML 标签和内联样式,不支持class和id

                    支持的标签

                    不满足的标签会被忽略,<div>会被转行为<p>储存。

                    类型节点
                    行内元素<span> <strong> <b> <ins> <em> <i> <u> <a> <del> <s> <sub> <sup> <img>
                    块级元素<p> <h1> <h2> <h3> <h4> <h5> <h6> <hr> <ol> <ul> <li>

                    支持的内联样式

                    内联样式仅能设置在行内元素或块级元素上,不能同时设置。例如 font-size 归类为行内元素属性,在 p 标签上设置是无效的。

                    类型样式
                    块级样式text-align direction margin margin-top margin-left margin-right margin-bottom
                    padding padding-top padding-left padding-right padding-bottom line-height text-indent
                    行内样式font font-size font-style font-variant font-weight font-family
                    letter-spacing text-decoration color background-color

                    提示:

                    1. 使用 catchtouchend 绑定事件则不会使编辑器失去焦点(2.8.3)
                    2. 插入的 html 中事件绑定会被移除
                    3. formats 中的 color 属性会统一以 hex 格式返回
                    4. 粘贴时仅纯文本内容会被拷贝进编辑器
                    5. 插入 html 到编辑器内时,编辑器会删除一些不必要的标签,以保证内容的统一。例如<p><span>xxx</span></p>会改写为<p>xxx</p>
                    6. 编辑器聚焦时页面会被上推,系统行为以保证编辑区可见


                    navigator

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

                    页面链接。

                    属性名类型默认值说明
                    target
                    Stringself在哪个目标上发生跳转,默认当前小程序,可选值self/miniProgram
                    urlString 应用内的跳转链接
                    open-typeStringnavigate跳转方式
                    deltaNumber 当 open-type 为 'navigateBack' 时有效,表示回退的层数
                    app-id
                    String
                     当target="miniProgram"时有效,要打开的小程序 appId
                    path
                    String
                     当target="miniProgram"时有效,打开的页面路径,如果为空则打开首页
                    extra-data
                    Object
                     当target="miniProgram"时有效,需要传递给目标小程序的数据,目标小程序可在 App.onLaunch()App.onShow() 中获取到这份数据。
                    version
                    version
                    release当target="miniProgram"时有效,要打开的小程序版本,有效值 develop(开发版),trial(体验版),release(正式版),仅在当前小程序为开发版或体验版时此参数有效;如果当前小程序是正式版,则打开的小程序必定是正式版。
                    hover-classStringnavigator-hover指定点击时的样式类,当hover-class="none"时,没有点击态效果
                    hover-stop-propagation
                    Boolean
                    false
                    指定是否阻止本节点的祖先节点出现点击态
                    hover-start-timeNumber50按住后多久出现点击态,单位毫秒
                    hover-stay-timeNumber600手指松开后点击态保留时间,单位毫秒
                    bindsuccess
                    String
                    当target="miniProgram"时有效,跳转小程序成功
                    bindfail
                    String
                    当target="miniProgram"时有效,跳转小程序失败
                    bindcomplete
                    String
                    当target="miniProgram"时有效,跳转小程序完成


                    open-type 有效值:

                    说明最低版本
                    navigate对应wx.navigateTo的功能 
                    redirect对应wx.redirectTo的功能 
                    switchTab对应wx.switchTab的功能 
                    reLaunch对应wx.reLaunch的功能1.1.0
                    navigateBack对应wx.navigateBack的功能1.1.0
                    exit
                    退出小程序,target="miniProgram"时生效
                    2.1.0

                    注:navigator-hover默认为{background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}, <navigator/>的子节点背景色应为透明色

                    示例代码:

                    /** wxss **//** 修改默认的navigator点击态 **/.navigator-hover {    color:blue;}/** 自定义其他点击态样式类 **/.other-navigator-hover {    color:red;}
                    <!-- sample.wxml --><view class="btn-area">  <navigator url="/page/navigate/navigate?title=navigate" hover-class="navigator-hover">跳转到新页面</navigator>  <navigator url="../../redirect/redirect/redirect?title=redirect" open-type="redirect" hover-class="other-navigator-hover">在当前页打开</navigator>  <navigator url="/page/index/index" open-type="switchTab" hover-class="other-navigator-hover">切换 Tab</navigator></view>
                    <!-- navigator.wxml --><view style="text-align:center"> {{title}} </view><view> 点击左上角返回回到之前页面 </view>
                    <!-- redirect.wxml --><view style="text-align:center"> {{title}} </view><view> 点击左上角返回回到上级页面 </view>
                    // redirect.js navigator.jsPage({  onLoad: function(options) {    this.setData({      title: options.title    })  }})


                    functional-page-navigator

                    基础库 2.9.0 开始支持,低版本需做兼容处理。

                    页面导航条配置节点,用于指定导航栏的一些属性。只能是 page-meta 组件内的第一个节点,需要配合它一同使用。

                    通过这个节点可以获得类似于调用 wx.setNavigationBarTitle wx.setNavigationBarColor 等接口调用的效果。

                    属性类型默认值必填说明最低版本
                    titlestring导航条标题2.9.0
                    loadingbooleanfalse是否在导航条显示 loading 加载提示2.9.0
                    front-colorstring导航条前景颜色值,包括按钮、标题、状态栏的颜色,仅支持 #ffffff 和 #0000002.9.0
                    background-colorstring导航条背景颜色值,有效值为十六进制颜色2.9.0
                    color-animation-durationnumber0改变导航栏颜色时的动画时长,默认为 0 (即没有动画效果)2.9.0
                    color-animation-timing-funcnumber"linear"改变导航栏颜色时的动画方式,支持 linear 、 easeIn 、 easeOut 和 easeInOut2.9.0

                    示例代码

                    <page-meta>  <navigation-bar    title="{{nbTitle}}"    loading="{{nbLoading}}"    front-color="{{nbFrontColor}}"    background-color="{{nbBackgroundColor}}"    color-animation-duration="2000"    color-animation-timing-func="easeIn"  /></page-meta>
                    Page({  data: {    nbFrontColor: '#000000',    nbBackgroundColor: '#ffffff',  },  onLoad() {    this.setData({      nbTitle: '新标题',      nbLoading: true,      nbFrontColor: '#ffffff',      nbBackgroundColor: '#000000',    })  }})


                    audio


                    音频。

                    属性名类型默认值说明
                    idString audio 组件的唯一标识符
                    srcString 要播放音频的资源地址
                    loopBooleanfalse是否循环播放
                    controlsBooleantrue是否显示默认控件
                    posterString 默认控件上的音频封面的图片资源地址,如果 controls 属性值为 false 则设置 poster 无效
                    nameString未知音频默认控件上的音频名字,如果 controls 属性值为 false 则设置 name 无效
                    authorString未知作者默认控件上的作者名字,如果 controls 属性值为 false 则设置 author 无效
                    binderrorEventHandle 当发生错误时触发 error 事件,detail = {errMsg: MediaError.code}
                    bindplayEventHandle 当开始/继续播放时触发play事件
                    bindpauseEventHandle 当暂停播放时触发 pause 事件
                    bindtimeupdateEventHandle 当播放进度改变时触发 timeupdate 事件,detail = {currentTime, duration}
                    bindendedEventHandle 当播放到末尾时触发 ended 事件

                    MediaError.code

                    返回错误码描述
                    MEDIA_ERR_ABORTED获取资源被用户禁止
                    MEDIA_ERR_NETWORD网络错误
                    MEDIA_ERR_DECODE解码错误
                    MEDIA_ERR_SRC_NOT_SUPPOERTED不合适资源

                    示例代码:

                    <!-- audio.wxml --><audio poster="{{poster}}" name="{{name}}" author="{{author}}" src="{{src}}" id="myAudio" controls loop></audio><button type="primary" bindtap="audioPlay">播放</button><button type="primary" bindtap="audioPause">暂停</button><button type="primary" bindtap="audio14">设置当前播放时间为14秒</button><button type="primary" bindtap="audioStart">回到开头</button>
                    // audio.jsPage({  onReady: function (e) {    // 使用 wx.createAudioContext 获取 audio 上下文 context    this.audioCtx = wx.createAudioContext('myAudio')  },  data: {    poster: 'http://y.gtimg.cn/music/photo_new/T002R300x300M000003rsKF44GyaSk.jpg?max_age=2592000',    name: '此时此刻',    author: '许巍',    src: 'http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E06DCBDC9AB7C49FD713D632D313AC4858BACB8DDD29067D3C601481D36E62053BF8DFEAF74C0A5CCFADD6471160CAF3E6A&fromtag=46',  },  audioPlay: function () {    this.audioCtx.play()  },  audioPause: function () {    this.audioCtx.pause()  },  audio14: function () {    this.audioCtx.seek(14)  },  audioStart: function () {    this.audioCtx.seek(0)  }})

                    audio

                    相关api:wx.createAudioContext

                    微信小程序image


                    图片。

                    属性名 类型 默认值 说明
                    src String   图片资源地址
                    mode String 'scaleToFill' 图片裁剪、缩放的模式
                    binderror HandleEvent   当错误发生时,发布到AppService的事件名,事件对象event.detail = { errMsg: 'something wrong' }
                    bindload HandleEvent   当图片载入完毕时,发布到AppService的事件名,事件对象event.detail = {height:'图片高度px', width:'图片宽度px'
                    }

                    注:image组件默认宽度300px、高度225px

                    mode 有效值:

                    mode有13种模式,其中4种是缩放模式,9种是裁剪模式。

                    模式说明
                    缩放scaleToFill不保持纵横比缩放图片,使图片的宽高完全拉伸至填满 image 元素
                    缩放aspectFit保持纵横比缩放图片,使图片的长边能完全显示出来。也就是说,可以完整地将图片显示出来。
                    缩放aspectFill保持纵横比缩放图片,只保证图片的短边能完全显示出来。也就是说,图片通常只在水平或垂直方向是完整的,另一个方向将会发生截取。
                    缩放widthFix宽度不变,高度自动变化,保持原图宽高比不变
                    裁剪top不缩放图片,只显示图片的顶部区域
                    裁剪bottom不缩放图片,只显示图片的底部区域
                    裁剪center不缩放图片,只显示图片的中间区域
                    裁剪left不缩放图片,只显示图片的左边区域
                    裁剪right不缩放图片,只显示图片的右边区域
                    裁剪top left不缩放图片,只显示图片的左上边区域
                    裁剪top right不缩放图片,只显示图片的右上边区域
                    裁剪bottom left不缩放图片,只显示图片的左下边区域
                    裁剪bottom right不缩放图片,只显示图片的右下边区域


                    示例:

                    <view class="page">  <view class="page__hd">    <text class="page__title">image</text>    <text class="page__desc">图片</text>  </view>  <view class="page__bd">    <view class="section section_gap" wx:for="{{array}}" wx:for-item="item">      <view class="section__title">{{item.text}}</view>      <view class="section__ctn">        <image style="width: 200px; height: 200px; background-color: #eeeeee;" mode="{{item.mode}}" src="{{src}}"></image>      </view>    </view>  </view></view>
                    Page({  data: {    array: [{      mode: 'scaleToFill',      text: 'scaleToFill:不保持纵横比缩放图片,使图片完全适应'    }, {      mode: 'aspectFit',      text: 'aspectFit:保持纵横比缩放图片,使图片的长边能完全显示出来'    }, {      mode: 'aspectFill',      text: 'aspectFill:保持纵横比缩放图片,只保证图片的短边能完全显示出来'    }, {      mode: 'top',      text: 'top:不缩放图片,只显示图片的顶部区域'    }, {      mode: 'bottom',      text: 'bottom:不缩放图片,只显示图片的底部区域'    }, {      mode: 'center',      text: 'center:不缩放图片,只显示图片的中间区域'    }, {      mode: 'left',      text: 'left:不缩放图片,只显示图片的左边区域'    }, {      mode: 'right',      text: 'right:不缩放图片,只显示图片的右边边区域'    }, {      mode: 'top left',      text: 'top left:不缩放图片,只显示图片的左上边区域'    }, {      mode: 'top right',      text: 'top right:不缩放图片,只显示图片的右上边区域'    }, {      mode: 'bottom left',      text: 'bottom left:不缩放图片,只显示图片的左下边区域'    }, {      mode: 'bottom right',      text: 'bottom right:不缩放图片,只显示图片的右下边区域'    }],    src: '../../resources/cat.jpg'  },  imageError: function(e) {    console.log('image3发生error事件,携带值为', e.detail.errMsg)  }})

                    原图

                    image

                    scaleToFill

                    不保持纵横比缩放图片,使图片完全适应

                    image

                    aspectFit

                    保持纵横比缩放图片,使图片的长边能完全显示出来

                    image

                    aspectFill

                    保持纵横比缩放图片,只保证图片的短边能完全显示出来

                    image

                    top

                    不缩放图片,只显示图片的顶部区域

                    image

                    bottom

                    不缩放图片,只显示图片的底部区域

                    image

                    center

                    不缩放图片,只显示图片的中间区域

                    image

                    left

                    不缩放图片,只显示图片的左边区域

                    image

                    right

                    不缩放图片,只显示图片的右边边区域

                    image

                    top left

                    不缩放图片,只显示图片的左上边区域

                    image

                    top right

                    不缩放图片,只显示图片的右上边区域

                    image

                    bottom left

                    不缩放图片,只显示图片的左下边区域

                    image

                    bottom right

                    不缩放图片,只显示图片的右下边区域

                    image

                    video

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

                    视频(v2.4.0 起支持同层渲染)。相关api:wx.createVideoContext

                    属性类型默认值必填说明最低版本
                    srcstring要播放视频的资源地址,支持网络路径、本地临时路径、云文件ID(2.3.0)1.0.0
                    durationnumber指定视频时长1.1.0
                    controlsbooleantrue是否显示默认播放控件(播放/暂停按钮、播放进度、时间)1.0.0
                    danmu-listArray.<object>弹幕列表1.0.0
                    danmu-btnbooleanfalse是否显示弹幕按钮,只在初始化时有效,不能动态变更1.0.0
                    enable-danmubooleanfalse是否展示弹幕,只在初始化时有效,不能动态变更1.0.0
                    autoplaybooleanfalse是否自动播放1.0.0
                    loopbooleanfalse是否循环播放1.4.0
                    mutedbooleanfalse是否静音播放1.4.0
                    initial-timenumber0指定视频初始播放位置1.6.0
                    page-gesturebooleanfalse在非全屏模式下,是否开启亮度与音量调节手势(废弃,见 vslide-gesture)1.6.0
                    directionnumber设置全屏时视频的方向,不指定则根据宽高比自动判断1.7.0
                    show-progressbooleantrue若不设置,宽度大于240时才会显示1.9.0
                    show-fullscreen-btnbooleantrue是否显示全屏按钮1.9.0
                    show-play-btnbooleantrue是否显示视频底部控制栏的播放按钮1.9.0
                    show-center-play-btnbooleantrue是否显示视频中间的播放按钮1.9.0
                    enable-progress-gesturebooleantrue是否开启控制进度的手势1.9.0
                    object-fitstringcontain当视频大小与 video 容器大小不一致时,视频的表现形式1.0.0
                    posterstring视频封面的图片网络资源地址或云文件ID(2.3.0)。若 controls 属性值为 false 则设置 poster 无效1.0.0
                    show-mute-btnbooleanfalse是否显示静音按钮2.4.0
                    titlestring视频的标题,全屏时在顶部展示2.4.0
                    play-btn-positionstringbottom播放按钮的位置2.4.0
                    enable-play-gesturebooleanfalse是否开启播放手势,即双击切换播放/暂停2.4.0
                    auto-pause-if-navigatebooleantrue当跳转到本小程序的其他页面时,是否自动暂停本页面的视频播放2.5.0
                    auto-pause-if-open-nativebooleantrue当跳转到其它微信原生页面时,是否自动暂停本页面的视频2.5.0
                    vslide-gesturebooleanfalse在非全屏模式下,是否开启亮度与音量调节手势(同 page-gesture)2.6.2
                    vslide-gesture-in-fullscreenbooleantrue在全屏模式下,是否开启亮度与音量调节手势2.6.2
                    ad-unit-idstring视频前贴广告单元ID,更多详情可参考开放能力视频前贴广告2.8.1
                    poster-for-crawlerstring用于给搜索等场景作为视频封面展示,建议使用无播放 icon 的视频封面图,只支持网络地址
                    show-casting-buttonbooleanfalse显示投屏按钮。只安卓且同层渲染下生效,支持 DLNA 协议2.10.2
                    picture-in-picture-modestring/Array设置小窗模式: push, pop,空字符串或通过数组形式设置多种模式(如: ["push", "pop"])2.11.0
                    picture-in-picture-show-progressbooleanfalse是否在小窗模式下显示播放进度2.11.0
                    enable-auto-rotationbooleanfalse是否开启手机横屏时自动全屏,当系统设置开启自动旋转时生效2.11.0
                    show-screen-lock-buttonbooleanfalse是否显示锁屏按钮,仅在全屏时显示,锁屏后控制栏的操作2.11.0
                    bindplayeventhandle当开始/继续播放时触发play事件1.0.0
                    bindpauseeventhandle当暂停播放时触发 pause 事件1.0.0
                    bindendedeventhandle当播放到末尾时触发 ended 事件1.0.0
                    bindtimeupdateeventhandle播放进度变化时触发,event.detail = {currentTime, duration} 。触发频率 250ms 一次1.0.0
                    bindfullscreenchangeeventhandle视频进入和退出全屏时触发,event.detail = {fullScreen, direction},direction 有效值为 vertical 或 horizontal1.4.0
                    bindwaitingeventhandle视频出现缓冲时触发1.7.0
                    binderroreventhandle视频播放出错时触发1.7.0
                    bindprogresseventhandle加载进度变化时触发,只支持一段加载。event.detail = {buffered},百分比2.4.0
                    bindloadedmetadataeventhandle视频元数据加载完成时触发。event.detail = {width, height, duration}2.7.0
                    bindcontrolstoggleeventhandle切换 controls 显示隐藏时触发。event.detail = {show}2.9.5
                    bindenterpictureinpictureeventhandler播放器进入小窗2.11.0
                    bindleavepictureinpictureeventhandler播放器退出小窗2.11.0
                    bindseekcompleteeventhandlerseek 完成时触发2.12.0

                    direction 的合法值

                    说明最低版本
                    0正常竖向
                    90屏幕逆时针90度
                    -90屏幕顺时针90度

                    object-fit 的合法值

                    说明最低版本
                    contain包含
                    fill填充
                    cover覆盖

                    play-btn-position 的合法值

                    说明最低版本
                    bottomcontrols bar上
                    center视频中间

                    picture-in-picture-mode 的合法值

                    说明最低版本
                    []取消小窗
                    push路由 push 时触发小窗
                    pop路由 pop 时触发小窗

                    提示

                    1. tip:`video 默认宽度 300px、高度 225px,可通过 wxss 设置宽高。
                    2. tip:从 2.4.0 起 video 支持同层渲染。

                    支持的格式

                    格式iOSAndroid
                    mp4
                    movx
                    m4vx
                    3gp
                    avix
                    m3u8
                    webmx

                    支持的编码格式

                    格式iOSAndroid
                    H.264
                    HEVC
                    MPEG-4
                    VP9x

                    小窗特性说明

                    video 小窗支持以下三种触发模式(在组件上设置 picture-in-picture-mode 属性):

                    1. push 模式,即从当前页跳转至下一页时出现小窗(页面栈push)
                    2. pop 模式,即离开当前页面时触发(页面栈pop)
                    3. 以上两种路由行为均触发小窗

                    此外,小窗还支持以下特性:

                    • 小窗容器尺寸会根据原组件尺寸自动判断
                    • 点击小窗,用户会被导航回小窗对应的播放器页面
                    • 小窗出现后,用户可点击小窗右上角的关闭按钮或调用 context.exitPictureInPicture() 接口关闭小窗

                    当播放器进入小窗模式后,播放器所在页面处于 hide 状态(触发 onHide 生命周期),该页面不会被销毁。当小窗被关闭时,播放器所在页面会被 unload (触发 onUnload 生命周期)。

                    示例代码

                    video标签认宽度300px、高度225px,设置宽高需要通过wxss设置width和height。

                    示例代码: 

                    <view class="section tc">  <video src="{{src}}"   controls ></video>  <view class="btn-area">    <button bindtap="bindButtonTap">获取视频</button>  </view></view><view class="section tc">  <video id="myVideo" src="http://wxsnsdy.tc.qq.com/105/20210/snsdyvideodownload?filekey=30280201010421301f0201690402534804102ca905ce620b1241b726bc41dcff44e00204012882540400&bizid=1023&hy=SH&fileparam=302c020101042530230204136ffd93020457e3c4ff02024ef202031e8d7f02030f42400204045a320a0201000400" rel="external nofollow"  danmu-list="{{danmuList}}" enable-danmu danmu-btn controls></video>  <view class="btn-area">    <button bindtap="bindButtonTap">获取视频</button>    <input bindblur="bindInputBlur"/>    <button bindtap="bindSendDanmu">发送弹幕</button>  </view></view>
                    function getRandomColor () {  let rgb = []  for (let i = 0 ; i < 3; ++i){    let color = Math.floor(Math.random() * 256).toString(16)    color = color.length == 1 ? '0' + color : color    rgb.push(color)  }  return '#' + rgb.join('')}Page({  onReady: function (res) {    this.videoContext = wx.createVideoContext('myVideo')  },  inputValue: '',    data: {        src: '',    danmuList: [      {        text: '第 1s 出现的弹幕',        color: '#ff0000',        time: 1      },      {        text: '第 3s 出现的弹幕',        color: '#ff00ff',        time: 3    }]    },  bindInputBlur: function(e) {    this.inputValue = e.detail.value  },  bindButtonTap: function() {    var that = this    wx.chooseVideo({      sourceType: ['album', 'camera'],      maxDuration: 60,      camera: ['front','back'],      success: function(res) {        that.setData({          src: res.tempFilePath        })      }    })  },  bindSendDanmu: function () {    this.videoContext.sendDanmu({      text: this.inputValue,      color: getRandomColor()    })  }})

                    video

                    相关api:wx.createVideoContext

                    Bug & Tip

                    1. tip:video组件是由客户端创建的原生组件,它的层级是最高的。
                    2. tip: 请勿在scroll-view中使用video组件。
                    3. tip:css动画对video组件无效。


                    camera


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

                    系统相机。

                    需要用户授权 scope.camera

                    属性名类型默认值说明
                    device-positionStringback前置或后置,值为front, back
                    flashStringauto闪光灯,值为auto, on, off
                    bindstopEventHandle摄像头在非正常终止时触发,如退出后台等情况
                    binderrorEventHandle用户不允许使用摄像头时触发

                    相关api:wx.createCameraContext

                    Bug & Tip
                    1. tip: camera 组件是由客户端创建的原生组件,它的层级是最高的,不能通过 z-index 控制层级。可使用 cover-view cover-image覆盖在上面。
                    2. tip: 同一页面只能插入一个 camera 组件。
                    3. tip: 请勿在 scroll-view、swiper、picker-view、movable-view 中使用 camera 组件。

                    示例:

                    <!-- camera.wxml --><camera device-position="back" flash="off" binderror="error" style="width: 100%; height: 300px;"></camera><button type="primary" bindtap="takePhoto">拍照</button><view>预览</view><image mode="widthFix" src="{{src}}"></image>
                    // camera.jsPage({    takePhoto() {        const ctx = wx.createCameraContext()        ctx.takePhoto({            quality: 'high',            success: (res) => {                this.setData({                    src: res.tempImagePath                })            }        })    },    error(e) {        console.log(e.detail)    }})

                    live-pusher

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

                    实时音视频录制(v2.9.1 起支持同层渲染)。需要用户授权 scope.camera、scope.record。

                    暂只针对国内主体如下类目的小程序开放,需要先通过类目审核,再在小程序管理后台,「开发」-「接口设置」中自助开通该组件权限。

                    一级类目/主体类型二级类目小程序内容场景
                    社交直播涉及娱乐性质,如明星直播、生活趣事直播、宠物直播等。选择该类目后首次提交代码审核,需经当地互联网主管机关审核确认,预计审核时长7天左右
                    教育在线视频课程网课、在线培训、讲座等教育类直播
                    医疗互联网医院,公立医疗机构,私立医疗机构问诊、大型健康讲座等直播
                    金融银行、信托、公募基金、私募基金、证券/期货、证券、期货投资咨询、保险、征信业务、新三板信息服务平台、股票信息服务平台(港股/美股)、消费金融金融产品视频客服理赔、金融产品推广直播等
                    汽车汽车预售服务汽车预售、推广直播
                    政府主体帐号/政府相关工作推广直播、领导讲话直播等
                    工具视频客服不涉及以上几类内容的一对一视频客服服务,如企业售后一对一视频服务等
                    IT科技多方通信为多方提供电话会议/视频会议等服务

                    相关api:wx.createLivePusherContext

                    属性类型默认值必填说明最低版本
                    urlstring推流地址。目前仅支持 rtmp 格式1.7.0
                    modestringRTCSD(标清), HD(高清), FHD(超清), RTC(实时通话)1.7.0
                    autopushbooleanfalse自动推流1.7.0
                    mutedbooleanfalse是否静音。即将废弃,可用 enable-mic 替代1.7.0
                    enable-camerabooleantrue开启摄像头1.7.0
                    auto-focusbooleantrue自动聚集1.7.0
                    orientationstringvertical画面方向1.7.0
                    beautynumber0美颜,取值范围 0-9 ,0 表示关闭1.7.0
                    whitenessnumber0美白,取值范围 0-9 ,0 表示关闭1.7.0
                    aspectstring9:16宽高比,可选值有 3:49:161.7.0
                    min-bitratenumber200最小码率1.7.0
                    max-bitratenumber1000最大码率1.7.0
                    audio-qualitystringhigh高音质(48KHz)或低音质(16KHz),值为highlow1.7.0
                    waiting-imagestring进入后台时推流的等待画面1.7.0
                    waiting-image-hashstring等待画面资源的MD5值1.7.0
                    zoombooleanfalse调整焦距2.1.0
                    device-positionstringfront前置或后置,值为frontback2.3.0
                    background-mutebooleanfalse进入后台时是否静音(已废弃,默认退后台静音)1.7.0
                    mirrorbooleanfalse设置推流画面是否镜像,产生的效果在 live-player 反应到2.7.0
                    remote-mirrorbooleanfalse同 mirror 属性,后续 mirror 将废弃2.10.0
                    local-mirrorstringauto控制本地预览画面是否镜像2.10.0
                    audio-reverb-typenumber0音频混响类型2.10.0
                    enable-micbooleantrue开启或关闭麦克风2.10.0
                    enable-agcbooleanfalse是否开启音频自动增益2.10.0
                    enable-ansbooleanfalse是否开启音频噪声抑制2.10.0
                    audio-volume-typestringauto音量类型2.10.0
                    video-widthnumber360上推的视频流的分辨率宽度2.10.0
                    video-heightnumber640上推的视频流的分辨率高度2.10.0
                    beauty-stylestringsmooth设置美颜类型2.12.0
                    filterstringstandard设置色彩滤镜2.12.0
                    bindstatechangeeventhandle状态变化事件,detail = {code}1.7.0
                    bindnetstatuseventhandle网络状态通知,detail = {info}1.9.0
                    binderroreventhandle渲染错误事件,detail = {errMsg, errCode}1.7.4
                    bindbgmstarteventhandle背景音开始播放时触发2.4.0
                    bindbgmprogresseventhandle背景音进度变化时触发,detail = {progress, duration}2.4.0
                    bindbgmcompleteeventhandle背景音播放完成时触发2.4.0
                    bindaudiovolumenotifyeventhandle返回麦克风采集的音量大小2.12.0

                    orientation 的合法值

                    说明最低版本
                    vertical竖直
                    horizontal水平

                    local-mirror 的合法值

                    说明最低版本
                    auto前置摄像头镜像,后置摄像头不镜像
                    enable前后置摄像头均镜像
                    disable前后置摄像头均不镜像

                    audio-reverb-type 的合法值

                    说明最低版本
                    0关闭
                    1KTV
                    2小房间
                    3大会堂
                    4低沉
                    5洪亮
                    6金属声
                    7磁性

                    audio-volume-type 的合法值

                    说明最低版本
                    auto自动
                    media媒体音量
                    voicecall通话音量

                    beauty-style 的合法值

                    说明最低版本
                    smooth光滑美颜
                    nature自然美颜

                    filter 的合法值

                    说明最低版本
                    standard标准
                    pink粉嫩
                    nostalgia怀旧
                    blues蓝调
                    romantic浪漫
                    cool清凉
                    fresher清新
                    solor日系
                    aestheticism唯美
                    whitening美白
                    cerisered樱红

                    注意:

                    1. tip:开发者工具上暂不支持。
                    2. tip:live-pusher 默认宽度为100%、无默认高度,请通过wxss设置宽高。
                    3. tip:waiting-image 属性在 2.3.0 起完整支持网络路径、临时文件和包内路径。
                    4. tip:请注意原生组件使用限制。
                    5. tip: 相关介绍和原理可参考此文章

                    错误码(errCode)

                    代码说明
                    10001用户禁止使用摄像头
                    10002用户禁止使用录音
                    10003背景音资源(BGM)加载失败
                    10004等待画面资源(waiting-image)加载失败

                    状态码(code)

                    代码说明
                    1001已经连接推流服务器
                    1002已经与服务器握手完毕,开始推流
                    1003打开摄像头成功
                    1004录屏启动成功
                    1005推流动态调整分辨率
                    1006推流动态调整码率
                    1007首帧画面采集完成
                    1008编码器启动
                    -1301打开摄像头失败
                    -1302打开麦克风失败
                    -1303视频编码失败
                    -1304音频编码失败
                    -1305不支持的视频分辨率
                    -1306不支持的音频采样率
                    -1307网络断连,且经多次重连抢救无效,更多重试请自行重启推流
                    -1308开始录屏失败,可能是被用户拒绝
                    -1309录屏失败,不支持的Android系统版本,需要5.0以上的系统
                    -1310录屏被其他应用打断了
                    -1311Android Mic打开成功,但是录不到音频数据
                    -1312录屏动态切横竖屏失败
                    1101网络状况不佳:上行带宽太小,上传数据受阻
                    1102网络断连, 已启动自动重连
                    1103硬编码启动失败,采用软编码
                    1104视频编码失败
                    1105新美颜软编码启动失败,采用老的软编码
                    1106新美颜软编码启动失败,采用老的软编码
                    3001RTMP -DNS解析失败
                    3002RTMP服务器连接失败
                    3003RTMP服务器握手失败
                    3004RTMP服务器主动断开,请检查推流地址的合法性或防盗链有效期
                    3005RTMP 读/写失败

                    网络状态数据(info)

                    键名说明
                    videoBitrate当前视频编/码器输出的比特率,单位 kbps
                    audioBitrate当前音频编/码器输出的比特率,单位 kbps
                    videoFPS当前视频帧率
                    videoGOP当前视频 GOP,也就是每两个关键帧(I帧)间隔时长,单位 s
                    netSpeed当前的发送/接收速度
                    netJitter网络抖动情况,抖动越大,网络越不稳定
                    videoWidth视频画面的宽度
                    videoHeight视频画面的高度


                    live-player

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

                    实时音视频播放(v2.9.1 起支持同层渲染)。

                    暂只针对国内主体如下类目的小程序开放,需要先通过类目审核,再在小程序管理后台,「开发」-「接口设置」中自助开通该组件权限。

                    一级类目/主体类型二级类目小程序内容场景
                    社交直播涉及娱乐性质,如明星直播、生活趣事直播、宠物直播等。选择该类目后首次提交代码审核,需经当地互联网主管机关审核确认,预计审核时长 7 天左右
                    教育在线视频课程网课、在线培训、讲座等教育类直播
                    医疗互联网医院,公立医疗机构,私立医疗机构问诊、大型健康讲座等直播
                    金融银行、信托、公募基金、私募基金、证券/期货、证券、期货投资咨询、保险、征信业务、新三板信息服务平台、股票信息服务平台(港股/美股)、消费金融金融产品视频客服理赔、金融产品推广直播等
                    汽车汽车预售服务汽车预售、推广直播
                    政府主体帐号/政府相关工作推广直播、领导讲话直播等
                    工具视频客服不涉及以上几类内容的一对一视频客服服务,如企业售后一对一视频服务等
                    IT科技多方通信为多方提供电话会议/视频会议等服务
                    属性类型默认值必填说明最低版本
                    srcstring音视频地址。目前仅支持 flvrtmp 格式1.7.0
                    modestringlive模式1.7.0
                    autoplaybooleanfalse自动播放1.7.0
                    mutedbooleanfalse是否静音1.7.0
                    orientationstringvertical画面方向1.7.0
                    object-fitstringcontain填充模式,可选值有 containfillCrop1.7.0
                    background-mutebooleanfalse进入后台时是否静音(已废弃,默认退后台静音)1.7.0
                    min-cachenumber1最小缓冲区,单位s(RTC 模式推荐 0.2s)1.7.0
                    max-cachenumber3最大缓冲区,单位s(RTC 模式推荐 0.8s)。缓冲区用来抵抗网络波动,缓冲数据越多,网络抗性越好,但时延越大。1.7.0
                    sound-modestringspeaker声音输出方式1.9.90
                    auto-pause-if-navigatebooleantrue当跳转到本小程序的其他页面时,是否自动暂停本页面的实时音视频播放2.5.0
                    auto-pause-if-open-nativebooleantrue当跳转到其它微信原生页面时,是否自动暂停本页面的实时音视频播放2.5.0
                    picture-in-picture-modestring/Array设置小窗模式: push, pop,空字符串或通过数组形式设置多种模式(如: ["push", "pop"])2.10.3
                    bindstatechangeeventhandle播放状态变化事件,detail = {code}1.7.0
                    bindfullscreenchangeeventhandle全屏变化事件,detail = {direction, fullScreen}1.7.0
                    bindnetstatuseventhandle网络状态通知,detail = {info}1.9.0
                    bindaudiovolumenotifyeventhandler播放音量大小通知,detail = {}2.10.0
                    bindenterpictureinpictureeventhandler播放器进入小窗2.11.0
                    bindleavepictureinpictureeventhandler播放器退出小窗2.11.0

                    mode 的合法值

                    说明最低版本
                    live直播
                    RTC实时通话,该模式时延更低

                    orientation 的合法值

                    说明最低版本
                    vertical竖直
                    horizontal水平

                    object-fit 的合法值

                    说明最低版本
                    contain图像长边填满屏幕,短边区域会被填充⿊⾊
                    fillCrop图像铺满屏幕,超出显示区域的部分将被截掉

                    sound-mode 的合法值

                    说明最低版本
                    speaker扬声器
                    ear听筒

                    picture-in-picture-mode 的合法值

                    说明最低版本
                    []取消小窗
                    push路由 push 时触发小窗
                    pop路由 pop 时触发小窗

                    状态码

                    代码说明
                    2001已经连接服务器
                    2002已经连接 RTMP 服务器,开始拉流
                    2003网络接收到首个视频数据包(IDR)
                    2004视频播放开始
                    2005视频播放进度
                    2006视频播放结束
                    2007视频播放Loading
                    2008解码器启动
                    2009视频分辨率改变
                    -2301网络断连,且经多次重连抢救无效,更多重试请自行重启播放
                    -2302获取加速拉流地址失败
                    2101当前视频帧解码失败
                    2102当前音频帧解码失败
                    2103网络断连, 已启动自动重连
                    2104网络来包不稳:可能是下行带宽不足,或由于主播端出流不均匀
                    2105当前视频播放出现卡顿
                    2106硬解启动失败,采用软解
                    2107当前视频帧不连续,可能丢帧
                    2108当前流硬解第一个I帧失败,SDK自动切软解
                    3001RTMP -DNS解析失败
                    3002RTMP服务器连接失败
                    3003RTMP服务器握手失败
                    3005RTMP 读/写失败,之后会发起网络重试

                    网络状态数据

                    键名说明
                    videoBitrate当前视频编/码器输出的比特率,单位 kbps
                    audioBitrate当前音频编/码器输出的比特率,单位 kbps
                    videoFPS当前视频帧率
                    videoGOP当前视频 GOP,也就是每两个关键帧(I帧)间隔时长,单位 s
                    netSpeed当前的发送/接收速度
                    netJitter网络抖动情况,为 0 时表示没有任何抖动,值越大表明网络抖动越大,网络越不稳定
                    videoWidth视频画面的宽度
                    videoHeight视频画面的高度

                    小窗特性说明

                    live-player 小窗支持以下三种触发模式(在组件上设置 picture-in-picture-mode 属性):

                    1. push 模式,即从当前页跳转至下一页时出现小窗(页面栈push)
                    2. pop 模式,即离开当前页面时触发(页面栈pop)
                    3. 以上两种路由行为均触发小窗

                    此外,小窗还支持以下特性:

                    • 小窗容器尺寸会根据原组件尺寸自动判断
                    • 点击小窗,用户会被导航回小窗对应的播放器页面
                    • 小窗出现后,用户可点击小窗右上角的关闭按钮或调用 context.exitPictureInPicture() 接口关闭小窗

                    当播放器进入小窗模式后,播放器所在页面处于 hide 状态(触发 onHide 生命周期),该页面不会被销毁。当小窗被关闭时,播放器所在页面会被 unload (触发 onUnload 生命周期)。

                    提示:

                    1. live-player 默认宽度300px、高度225px,可通过wxss设置宽高。
                    2. 开发者工具上暂不支持。

                    示例代码

                    <live-player src="https://domain/pull_stream" rel="external nofollow"  mode="RTC" autoplay bindstatechange="statechange" binderror="error" style="width: 300px; height: 225px;" />
                    Page({  statechange(e) {    console.log('live-player code:', e.detail.code)  },  error(e) {    console.error('live-player error:', e.detail.errMsg)  }})


                    voip-room

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

                    多人音视频对话。需用户授权 scope.camera、scope.record。相关接口: wx.joinVoIPChat

                    暂只针对国内主体如下类目的小程序开放,需要先通过类目审核,再在小程序管理后台,「开发」-「接口设置」中自助开通该组件权限。

                    一级类目/主体类型二级类目小程序内容场景
                    教育在线视频课程网课、在线培训、讲座等教育类直播
                    医疗互联网医院,公立医院问诊、大型健康讲座等直播
                    医疗私立医疗机构/
                    金融银行、信托、基金、证券/期货、证券、期货投资咨询、保险、征信业务、新三板信息服务平台、股票信息服务平台(港股/美股)、消费金融金融产品视频客服理赔、金融产品推广直播等
                    汽车汽车预售服务汽车预售、推广直播
                    政府主体帐号/政府相关工作推广直播、领导讲话直播等
                    IT 科技多方通信在线会议
                    IT 科技硬件设备智能硬件

                    开通该组件权限后,开发者可在 joinVoIPChat 成功后,获取房间成员的 openid,传递给 voip-room 组件,以显示成员画面。

                    属性类型默认值必填说明最低版本
                    openidstring进入房间用户的 openid2.11.0
                    modestringcamera对话窗口类型,自身传入 camera,其它用户传入 video2.11.0
                    device-positionstringfront仅在 mode 为 camera 时有效,前置或后置,值为frontback2.11.0
                    binderroreventhandle创建对话窗口失败时触发2.11.0

                    Bug & Tip

                    1. tip:开发者工具上暂不支持
                    2. tip:请注意原生组件使用限制

                    示例代码

                    <block wx:for="{{openIdList}}" wx:key="*this">  <voip-room    openid="{{item}}"    mode="{{selfOpenId === item ? 'camera' : 'video'}}">  </voip-room></block>


                    基础库 1.0.0 开始支持,低版本需做兼容处理。

                    地图(v2.7.0 起支持同层渲染)。相关api wx.createMapContext

                    个性化地图能力可在小程序后台“开发-开发者工具-腾讯位置服务”申请开通。 小程序内地图组件应使用同一 subkey,可通过 layer-style(地图官网设置的样式 style 编号)属性选择不同的底图风格。 组件属性的长度单位默认为px,2.4.0起支持传入单位(rpx/px)。

                    示例小程序

                    属性类型默认值必填说明最低版本
                    longitudenumber中心经度1.0.0
                    latitudenumber中心纬度1.0.0
                    scalenumber16缩放级别,取值范围为3-201.0.0
                    markersArray.<marker>标记点1.0.0
                    coversArray.<cover>即将移除,请使用 markers1.0.0
                    polylineArray.<polyline>路线1.0.0
                    circlesArray.<circle>1.0.0
                    controlsArray.<control>控件(即将废弃,建议使用 cover-view 代替)1.0.0
                    include-pointsArray.<point>缩放视野以包含所有给定的坐标点1.0.0
                    show-locationbooleanfalse显示带有方向的当前定位点1.0.0
                    polygonsArray.<polygon>多边形2.3.0
                    subkeystring个性化地图使用的key2.3.0
                    layer-stylenumber1个性化地图配置的 style,不支持动态修改
                    rotatenumber0旋转角度,范围 0 ~ 360, 地图正北和设备 y 轴角度的夹角2.5.0
                    skewnumber0倾斜角度,范围 0 ~ 40 , 关于 z 轴的倾角2.5.0
                    enable-3Dbooleanfalse展示3D楼块(工具暂不支持)2.3.0
                    show-compassbooleanfalse显示指南针2.3.0
                    show-scalebooleanfalse显示比例尺,工具暂不支持2.8.0
                    enable-overlookingbooleanfalse开启俯视2.3.0
                    enable-zoombooleantrue是否支持缩放2.3.0
                    enable-scrollbooleantrue是否支持拖动2.3.0
                    enable-rotatebooleanfalse是否支持旋转2.3.0
                    enable-satellitebooleanfalse是否开启卫星图2.7.0
                    enable-trafficbooleanfalse是否开启实时路况2.7.0
                    settingobject配置项2.8.2
                    bindtapeventhandle点击地图时触发,2.9.0起返回经纬度信息1.0.0
                    bindmarkertapeventhandle点击标记点时触发,e.detail = {markerId}1.0.0
                    bindlabeltapeventhandle点击label时触发,e.detail = {markerId}2.9.0
                    bindcontroltapeventhandle点击控件时触发,e.detail = {controlId}1.0.0
                    bindcallouttapeventhandle点击标记点对应的气泡时触发e.detail = {markerId}1.2.0
                    bindupdatedeventhandle在地图渲染更新完成时触发1.6.0
                    bindregionchangeeventhandle视野发生变化时触发,2.3.0
                    bindpoitapeventhandle点击地图poi点时触发,e.detail = {name, longitude, latitude}2.3.0

                    regionchange 返回值

                    视野改变时,regionchange 会触发两次,返回的 type 值分别为 begin / end。

                    2.8.0起 begin 阶段返回 causedBy,有效值为 gesture(手势触发) & update(接口触发)

                    2.3.0起 end 阶段返回 causedBy,有效值为 drag(拖动导致)、scale(缩放导致)、update(调用更新接口导致) rotate、skew仅在 end 阶段返回

                    e = {  causedBy,  type,  detail: {    rotate,    skew  }}

                    setting

                    提供 setting 对象统一设置地图配置。同时对于一些动画属性如 rotate 和 skew,通过 setData 分开设置时无法同时生效,需通过 settting 统一修改。

                    // 默认值const setting = {  skew: 0,  rotate: 0,  showLocation: false,  showScale: false,  subKey: '',  layerStyle: -1,  enableZoom: true,  enableScroll: true,  enableRotate: false,  showCompass: false,  enable3D: false,  enableOverlooking: false,  enableSatellite: false,  enableTraffic: false,}this.setData({  // 仅设置的属性会生效,其它的不受影响  setting: {    enable3D: true,    enableTraffic: true  }})

                    marker

                    标记点用于在地图上显示标记的位置

                    属性说明类型必填备注最低版本
                    id标记点 idnumbermarker 点击事件回调会返回此 id。建议为每个 marker 设置上 number 类型 id,保证更新 marker 时有更好的性能。
                    latitude纬度number浮点数,范围 -90 ~ 90
                    longitude经度number浮点数,范围 -180 ~ 180
                    title标注点名string点击时显示,callout存在时将被忽略
                    zIndex显示层级number2.3.0
                    iconPath显示的图标string项目目录下的图片路径,支持网络路径、本地路径、代码包路径(2.3.0)
                    rotate旋转角度number顺时针旋转的角度,范围 0 ~ 360,默认为 0
                    alpha标注的透明度number默认 1,无透明,范围 0 ~ 1
                    width标注图标宽度number/string默认为图片实际宽度
                    height标注图标高度number/string默认为图片实际高度
                    callout自定义标记点上方的气泡窗口Object支持的属性见下表,可识别换行符。1.2.0
                    label为标记点旁边增加标签Object支持的属性见下表,可识别换行符。1.2.0
                    anchor经纬度在标注图标的锚点,默认底边中点Object{x, y},x 表示横向(0-1),y 表示竖向(0-1)。{x: .5, y: 1} 表示底边中点1.2.0
                    aria-label无障碍访问,(属性)元素的额外描述string2.5.0

                    marker 上的气泡 callout

                    属性说明类型最低版本
                    content文本string1.2.0
                    color文本颜色string1.2.0
                    fontSize文字大小number1.2.0
                    borderRadius边框圆角number1.2.0
                    borderWidth边框宽度number2.3.0
                    borderColor边框颜色string2.3.0
                    bgColor背景色string1.2.0
                    padding文本边缘留白number1.2.0
                    display'BYCLICK':点击显示; 'ALWAYS':常显string1.2.0
                    textAlign文本对齐方式。有效值: left, right, centerstring1.6.0
                    anchorX横向偏移量,向右为正数number2.11.0
                    anchorY纵向偏移量,向下为正数number2.11.0

                    marker 上的气泡 label

                    属性说明类型最低版本
                    content文本string1.2.0
                    color文本颜色string1.2.0
                    fontSize文字大小number1.2.0
                    xlabel的坐标(废弃)number1.2.0
                    ylabel的坐标(废弃)number1.2.0
                    anchorXlabel的坐标,原点是 marker 对应的经纬度number2.1.0
                    anchorYlabel的坐标,原点是 marker 对应的经纬度number2.1.0
                    borderWidth边框宽度number1.6.0
                    borderColor边框颜色string1.6.0
                    borderRadius边框圆角number1.6.0
                    bgColor背景色string1.6.0
                    padding文本边缘留白number1.6.0
                    textAlign文本对齐方式。有效值: left, right, centerstring1.6.0

                    polyline

                    指定一系列坐标点,从数组第一项连线至最后一项

                    属性说明类型必填备注最低版本
                    points经纬度数组array[{latitude: 0, longitude: 0}]
                    color线的颜色string十六进制
                    width线的宽度number
                    dottedLine是否虚线boolean默认 false
                    arrowLine带箭头的线boolean默认 false,开发者工具暂不支持该属性1.2.0
                    arrowIconPath更换箭头图标string在 arrowLine 为 true 时生效1.6.0
                    borderColor线的边框颜色string1.2.0
                    borderWidth线的厚度number1.2.0

                    polygon

                    指定一系列坐标点,根据 points 坐标数据生成闭合多边形

                    属性说明类型必填备注最低版本
                    points经纬度数组array[{latitude: 0, longitude: 0}]2.3.0
                    strokeWidth描边的宽度number2.3.0
                    strokeColor描边的颜色string十六进制2.3.0
                    fillColor填充颜色string十六进制
                    zIndex设置多边形Z轴数值number2.3.0

                    circle

                    在地图上显示圆

                    属性说明类型必填备注
                    latitude纬度number浮点数,范围 -90 ~ 90
                    longitude经度number浮点数,范围 -180 ~ 180
                    color描边的颜色string十六进制
                    fillColor填充颜色string十六进制
                    radius半径number
                    strokeWidth描边的宽度number

                    control

                    在地图上显示控件,控件不随着地图移动。即将废弃,请使用 cover-view

                    属性说明类型必填备注
                    id控件idnumber在控件点击事件回调会返回此id
                    position控件在地图的位置object控件相对地图位置
                    iconPath显示的图标string项目目录下的图片路径,支持本地路径、代码包路径
                    clickable是否可点击boolean默认不可点击

                    position

                    属性说明类型必填备注
                    left距离地图的左边界多远number默认为0
                    top距离地图的上边界多远number默认为0
                    width控件宽度number默认为图片宽度
                    height控件高度number默认为图片高度

                    bindregionchange 返回值

                    属性说明类型备注
                    type视野变化开始、结束时触发string视野变化开始为begin,结束为end
                    causedBy导致视野变化的原因string拖动地图导致(drag)、缩放导致(scale)、调用接口导致(update)

                    Bug & Tip

                    1. tip:个性化地图暂不支持工具中调试。请先使用微信客户端进行测试。
                    2. tip:地图中的颜色值color/borderColor/bgColor等需使用6位(8位)十六进制表示,8位时后两位表示alpha值,如:#000000AA
                    3. tip:地图组件的经纬度必填, 如果不填经纬度则默认值是北京的经纬度。
                    4. tip: map 组件使用的经纬度是火星坐标系,调用 wx.getLocation 接口需要指定 type 为 gcj02
                    5. tip:从 2.8.0 起 map 支持同层渲染,更多请参考原生组件使用限制
                    6. tip:请注意原生组件使用限制

                    比例尺

                    scale34567891011
                    比例1000km500km200km100km50km50km20km10km5km
                    scale121314151617181920
                    比例2km1km500m200m100m50m50m20m10m

                    示例代码

                    在开发者工具中预览效果

                    <!-- map.wxml --><map id="map" longitude="113.324520" latitude="23.099994" scale="14" controls="{{controls}}" bindcontroltap="controltap" markers="{{markers}}" bindmarkertap="markertap" polyline="{{polyline}}" bindregionchange="regionchange" show-location style="width: 100%; height: 300px;"></map>
                    // map.jsPage({  data: {    markers: [{      iconPath: "/resources/others.png",      id: 0,      latitude: 23.099994,      longitude: 113.324520,      width: 50,      height: 50    }],    polyline: [{      points: [{        longitude: 113.3245211,        latitude: 23.10229      }, {        longitude: 113.324520,        latitude: 23.21229      }],      color:"#FF0000DD",      width: 2,      dottedLine: true    }],    controls: [{      id: 1,      iconPath: '/resources/location.png',      position: {        left: 0,        top: 300 - 50,        width: 50,        height: 50      },      clickable: true    }]  },  regionchange(e) {    console.log(e.type)  },  markertap(e) {    console.log(e.detail.markerId)  },  controltap(e) {    console.log(e.detail.controlId)  }})


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

                    画布。2.9.0 起支持一套新 Canvas 2D 接口(需指定 type 属性),同时支持同层渲染,原有接口不再维护。相关api:获取 canvas 实例

                    属性类型默认值必填说明最低版本
                    typestring指定 canvas 类型,支持 2d (2.9.0) 和 webgl (2.7.0)2.7.0
                    canvas-idstringcanvas 组件的唯一标识符,若指定了 type 则无需再指定该属性1.0.0
                    disable-scrollbooleanfalse当在 canvas 中移动时且有绑定手势事件时,禁止屏幕滚动以及下拉刷新1.0.0
                    bindtouchstarteventhandle手指触摸动作开始1.0.0
                    bindtouchmoveeventhandle手指触摸后移动1.0.0
                    bindtouchendeventhandle手指触摸动作结束1.0.0
                    bindtouchcanceleventhandle手指触摸动作被打断,如来电提醒,弹窗1.0.0
                    bindlongtapeventhandle手指长按 500ms 之后触发,触发了长按事件后进行移动不会触发屏幕的滚动1.0.0
                    binderroreventhandle当发生错误时触发 error 事件,detail = {errMsg}1.0.0

                    Bug & Tip

                    1. tip:canvas 标签默认宽度300px、高度150px
                    2. tip:同一页面中的 canvas-id 不可重复,如果使用一个已经出现过的 canvas-id,该 canvas 标签对应的画布将被隐藏并不再正常工作
                    3. tip:请注意原生组件使用限制
                    4. tip:开发者工具中默认关闭了 GPU 硬件加速,可在开发者工具的设置中开启“硬件加速”提高 WebGL 的渲染性能
                    5. tip: WebGL 支持通过 getContext('webgl', { alpha: true }) 获取透明背景的画布
                    6. tip: Canvas 2D(新接口)需要显式设置画布宽高 (默认为 300x150)
                    7. bug: 避免设置过大的宽高,在安卓下会有crash的问题

                    Canvas 2D 示例代码

                    在开发者工具中预览效果

                      <!-- canvas.wxml -->  <canvas type="2d" id="myCanvas"></canvas>
                    // canvas.jsPage({  onReady() {    const query = wx.createSelectorQuery()    query.select('#myCanvas')      .fields({ node: true, size: true })      .exec((res) => {        const canvas = res[0].node        const ctx = canvas.getContext('2d')        const dpr = wx.getSystemInfoSync().pixelRatio        canvas.width = res[0].width * dpr        canvas.height = res[0].height * dpr        ctx.scale(dpr, dpr)        ctx.fillRect(0, 0, 100, 100)      })  }})

                    WebGL 示例代码

                    在开发者工具中预览效果

                      <!-- canvas.wxml -->  <canvas type="webgl" id="myCanvas"></canvas>
                    // canvas.jsPage({  onReady() {    const query = wx.createSelectorQuery()    query.select('#myCanvas').node().exec((res) => {      const canvas = res[0].node      const gl = canvas.getContext('webgl')      gl.clearColor(1, 0, 1, 1)      gl.clear(gl.COLOR_BUFFER_BIT)    })  }})

                    示例代码(旧的接口)

                    在开发者工具中预览效果 下载

                    <!-- canvas.wxml --><canvas style="width: 300px; height: 200px;" canvas-id="firstCanvas"></canvas><!-- 当使用绝对定位时,文档流后边的 canvas 的显示层级高于前边的 canvas --><canvas style="width: 400px; height: 500px;" canvas-id="secondCanvas"></canvas><!-- 因为 canvas-id 与前一个 canvas 重复,该 canvas 不会显示,并会发送一个错误事件到 AppService --><canvas style="width: 400px; height: 500px;" canvas-id="secondCanvas" binderror="canvasIdErrorCallback"></canvas>
                    Page({  canvasIdErrorCallback: function (e) {    console.error(e.detail.errMsg)  },  onReady: function (e) {    // 使用 wx.createContext 获取绘图上下文 context    var context = wx.createCanvasContext('firstCanvas')    context.setStrokeStyle("#00ff00")    context.setLineWidth(5)    context.rect(0, 0, 200, 200)    context.stroke()    context.setStrokeStyle("#ff0000")    context.setLineWidth(2)    context.moveTo(160, 100)    context.arc(100, 100, 60, 0, 2 * Math.PI, true)    context.moveTo(140, 100)    context.arc(100, 100, 40, 0, Math.PI, false)    context.moveTo(85, 80)    context.arc(80, 80, 5, 0, 2 * Math.PI, true)    context.moveTo(125, 80)    context.arc(120, 80, 5, 0, 2 * Math.PI, true)    context.stroke()    context.draw()  }})




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

                    用于展示微信开放的数据。

                    属性类型默认值必填说明最低版本
                    typestring开放数据类型1.4.0
                    open-gidstring当 type="groupName" 时生效, 群 id1.4.0
                    langstringen当 type="user*" 时生效,以哪种语言展示 userInfo1.4.0
                    default-textstring数据为空时的默认文案2.8.1
                    default-avatarstring用户头像为空时的默认图片,支持相对路径和网络图片路径2.8.1
                    binderroreventhandle群名称或用户信息为空时触发2.8.1

                    type 的合法值

                    说明最低版本
                    groupName拉取群名称1.4.0
                    userNickName用户昵称1.9.90
                    userAvatarUrl用户头像1.9.90
                    userGender用户性别1.9.90
                    userCity用户所在城市1.9.90
                    userProvince用户所在省份1.9.90
                    userCountry用户所在国家1.9.90
                    userLanguage用户的语言1.9.90

                    lang 的合法值

                    说明最低版本
                    en英文
                    zh_CN简体中文
                    zh_TW繁体中文

                    Bug & Tip

                    1. tip:只有当前用户在此群内才能拉取到群名称
                    2. tip:关于 open-gid 的获取请使用 wx.getShareInfo

                    示例代码

                    <open-data type="groupName" open-gid="xxxxxx"></open-data><open-data type="userAvatarUrl"></open-data><open-data type="userGender" lang="zh_CN"></open-data>


                    web-view

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

                    web-view 组件是一个可以用来承载网页的容器,会自动铺满整个小程序页面。个人类型与海外类型的小程序暂不支持使用。

                    属性名类型默认值说明
                    srcStringnonewebview 指向网页的链接。需登录小程序管理后台配置域名白名单。

                    示例代码:

                    <!-- wxml --><!-- 指向微信公众平台首页的web-view --><web-view src="https://mp.weixin.qq.com/" rel="external nofollow" ></web-view>

                    相关接口 1

                    <web-view/>网页中可使用JSSDK 1.3.0提供的接口返回小程序页面。 支持的接口有:

                    接口名说明最低版本
                    wx.miniProgram.navigateTo参数与小程序接口一致1.6.4
                    wx.miniProgram.navigateBack参数与小程序接口一致1.6.4
                    wx.miniProgram.switchTab参数与小程序接口一致1.6.5
                    wx.miniProgram.reLaunch参数与小程序接口一致1.6.5
                    wx.miniProgram.redirectTo参数与小程序接口一致1.6.5

                    示例代码:

                    <!-- html --><script type="text/javascript" src="https://res.wx.qq.com/open/js/jweixin-1.3.0.js" rel="external nofollow" ></script>// javascriptwx.miniProgram.navigateTo({url: '/path/to/page'})

                    相关接口 2

                    <web-view/>网页中仅支持以下JSSDK接口:

                    接口模块接口说明具体接口
                    判断客户端是否支持jscheckJSApi
                    图像接口拍照或上传chooseImage
                    预览图片previewImage
                    上传图片uploadImage
                    下载图片downloadImage
                    获取本地图片getLocalImgData
                    音频接口开始录音startRecord
                    停止录音stopRecord
                    监听录音自动停止onVoiceRecordEnd
                    播放语音playVoice
                    暂停播放pauseVoice
                    停止播放stopVoice
                    监听语音播放完毕onVoicePlayEnd
                    上传接口uploadVoice
                    下载接口downloadVoice
                    智能接口识别音频translateVoice
                    设备信息获取网络状态getNetworkType
                    地理位置使用内置地图getLocation
                    获取地理位置openLocation
                    摇一摇周边开启ibeaconstartSearchBeacons
                    关闭ibeaconstopSearchBeacons
                    监听ibeacononSearchBeacons
                    微信扫一扫调起微信扫一扫scanQRCode
                    微信卡券拉取使用卡券列表chooseCard
                    批量添加卡券接口addCard
                    查看微信卡包的卡券openCard
                    长按识别小程序圆形码
                    相关接口 3

                    用户分享时可获取当前<web-view/>的URL,即在onShareAppMessage回调中返回webViewUrl参数。

                    示例代码:

                    Page({  onShareAppMessage(options) {    console.log(options.webViewUrl)  }})
                    相关接口 4

                    在网页内可通过window.__wxjs_environment变量判断是否在小程序环境。

                    示例代码:

                    // web-view下的页面内wx.ready(function() {    console.log(window.__wxjs_environment === 'miniprogram') // true})

                    Bug & Tip

                    1. 网页内iframe的域名也需要配置到域名白名单。
                    2. 开发者工具上,可以在 <web-view/> 组件上通过右键 - 调试,打开 <web-view/> 组件的调试。
                    3. 每个页面只能有一个<web-view/>,<web-view/>会自动铺满整个页面,并覆盖其他组件。
                    4. <web-view/>网页与小程序之间不支持除JSSDK提供的接口之外的通信。
                    5. 在iOS中,若存在JSSDK接口调用无响应的情况,可在<web-view/>的src后面加个#wechat_redirect解决。

                    ad

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

                    Banner 广告。

                    属性类型默认值必填说明最低版本
                    unit-idstring广告单元id,可在小程序管理后台的流量主模块新建1.9.94
                    ad-intervalsnumber广告自动刷新的间隔时间,单位为秒,参数值必须大于等于30(该参数不传入时 Banner 广告不会自动刷新)2.3.1
                    bindloadeventhandle广告加载成功的回调2.2.1
                    binderroreventhandle广告加载失败的回调,event.detail = {errCode: 1002}2.2.1
                    bindcloseeventhandle广告关闭的回调2.6.5

                    错误码信息与解决方案表

                    错误码是通过binderror回调获取到的错误信息。

                    代码异常情况理由解决方案
                    1000后端错误调用失败该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
                    1001参数错误使用方法错误可以前往developers.weixin.qq.com确认具体教程(小程序和小游戏分别有各自的教程,可以在顶部选项中,“设计”一栏的右侧进行切换。
                    1002广告单元无效可能是拼写错误、或者误用了其他APP的广告ID请重新前往mp.weixin.qq.com确认广告位ID。
                    1003内部错误该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
                    1004无适合的广告广告不是每一次都会出现,这次没有出现可能是由于该用户不适合浏览广告属于正常情况,且开发者需要针对这种情况做形态上的兼容。
                    1005广告组件审核中你的广告正在被审核,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
                    1006广告组件被驳回你的广告审核失败,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
                    1007广告组件被驳回你的广告能力已经被封禁,封禁期间无法展现广告请前往mp.weixin.qq.com确认小程序广告封禁状态。
                    1008广告单元已关闭该广告位的广告能力已经被关闭请前往mp.weixin.qq.com重新打开对应广告位的展现。

                    提示:

                    1. 在无广告展示时,ad 标签不会占用高度
                    2. ad 组件不支持触发 bindtap 等触摸相关事件
                    3. 目前可以给 ad 标签设置 wxss 样式调整广告宽度,以使广告与页面更融洽,但请遵循小程序流量主应用规范
                    4. 监听到error回调后,开发者可以针对性的处理,比如隐藏广告组件的父容器,以保证用户体验,但不要移除广告组件,否则将无法收到bindload的回调。


                    official-account

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

                    公众号关注组件。当用户扫小程序码打开小程序时,开发者可在小程序内配置公众号关注组件,方便用户快捷关注公众号,可嵌套在原生组件内。

                    Tips

                    1. 使用组件前,需前往小程序后台,在“设置”->“关注公众号”中设置要展示的公众号。注:设置的公众号需与小程序主体一致。
                    2. 在一个小程序的生命周期内,只有从以下场景进入小程序,才具有展示引导关注公众号组件的能力:当小程序从扫小程序码场景(场景值1047,场景值1124)打开时当小程序从聊天顶部场景(场景值1089)中的「最近使用」内打开时,若小程序之前未被销毁,则该组件保持上一次打开小程序时的状态当从其他小程序返回小程序(场景值1038)时,若小程序之前未被销毁,则该组件保持上一次打开小程序时的状态
                    3. 为便于开发者调试,基础库 2.7.3 版本起开发版小程序增加以下场景展示公众号组件:开发版小程序从扫二维码(场景值 1011)打开 — 体验版小程序打开
                    4. 组件限定最小宽度为300px,高度为定值84px。
                    5. 每个页面只能配置一个该组件。
                    属性名类型说明
                    bindloadEventHandle组件加载成功时触发
                    binderrorEventHandle组件加载失败时触发

                    detail 对象

                    属性名类型说明
                    statusNumber状态码
                    errMsgString错误信息
                    status 有效值
                    说明
                    -2网络错误
                    -1数据解析错误
                    0加载成功
                    1小程序关注公众号功能被封禁
                    2关联公众号被封禁
                    3关联关系解除或未选中关联公众号
                    4未开启关注公众号功能
                    5场景值错误
                    6重复创建

                    示例代码

                    <official-account></official-account>


                    ad-custom

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

                    原生模板 广告。

                    属性类型默认值必填说明最低版本
                    unit-idstring广告单元id,可在小程序管理后台的流量主模块新建2.10.4
                    ad-intervalsnumber广告自动刷新的间隔时间,单位为秒,参数值必须大于等于30(该参数不传入时 模板 广告不会自动刷新)2.10.4
                    bindloadeventhandle广告加载成功的回调2.10.4
                    binderroreventhandle广告加载失败的回调,event.detail = {errCode: 1002}2.10.4

                    错误码信息与解决方案表

                    错误码是通过binderror回调获取到的错误信息。

                    代码异常情况理由解决方案
                    1000后端错误调用失败该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
                    1001参数错误使用方法错误可以前往developers.weixin.qq.com确认具体教程(小程序和小游戏分别有各自的教程,可以在顶部选项中,“设计”一栏的右侧进行切换。
                    1002广告单元无效可能是拼写错误、或者误用了其他APP的广告ID请重新前往mp.weixin.qq.com确认广告位ID。
                    1003内部错误该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
                    1004无适合的广告广告不是每一次都会出现,这次没有出现可能是由于该用户不适合浏览广告属于正常情况,且开发者需要针对这种情况做形态上的兼容。
                    1005广告组件审核中你的广告正在被审核,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
                    1006广告组件被驳回你的广告审核失败,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
                    1007广告组件被驳回你的广告能力已经被封禁,封禁期间无法展现广告请前往mp.weixin.qq.com确认小程序广告封禁状态。
                    1008广告单元已关闭该广告位的广告能力已经被关闭请前往mp.weixin.qq.com重新打开对应广告位的展现。

                    Bug & Tip

                    1. tip:在无广告展示时,ad-custom 标签不会占用高度
                    2. tip:ad-custom 组件不支持触发 bindtap 等触摸相关事件
                    3. tip:目前可以给 ad-custom 标签设置 wxss 样式调整广告宽度,以使广告与页面更融洽,但请遵循小程序流量主应用规范
                    4. tip:监听到error回调后,开发者可以针对性的处理,比如隐藏广告组件的父容器,以保证用户体验,但不要移除广告组件,否则将无法收到bindload的回调
                    5. tip:不同模板涉及一些不同的使用场景,具体方式请参考模板编辑器


                    contact-button


                    客服会话按钮,用于在页面上显示一个客服会话按钮,用户点击该按钮后会进入客服会话。

                    属性名类型默认值说明
                    sizeNumber18会话按钮大小,有效值 18-27,单位:px
                    typeStringdefault-dark会话按钮的样式类型
                    session-fromString 用户从该按钮进入会话时,开发者将收到带上本参数的事件推送。本参数可用于区分用户进入客服会话的来源。

                    type 有效值:

                    说明
                    default-dark 
                    default-light 

                    示例代码

                    <contact-button   type="default-light"   size="20"  session-from="weapp"></contact-button>

                    相关api:详见客服消息接口文档

                    相关组件:button 组件通过设置 open-type="contact" 亦可进入客服会话

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

                    页面属性配置节点,用于指定页面的一些属性、监听页面事件。只能是页面内的第一个节点。可以配合 navigation-bar 组件一同使用。

                    通过这个节点可以获得类似于调用 wx.setBackgroundTextStyle wx.setBackgroundColor 等接口调用的效果。

                    属性类型默认值必填说明最低版本
                    background-text-stylestring下拉背景字体、loading 图的样式,仅支持 dark 和 light2.9.0
                    background-colorstring窗口的背景色,必须为十六进制颜色值2.9.0
                    background-color-topstring顶部窗口的背景色,必须为十六进制颜色值,仅 iOS 支持2.9.0
                    background-color-bottomstring底部窗口的背景色,必须为十六进制颜色值,仅 iOS 支持2.9.0
                    scroll-topstring""滚动位置,可以使用 px 或者 rpx 为单位,在被设置时,页面会滚动到对应位置2.9.0
                    scroll-durationnumber300滚动动画时长2.9.0
                    page-stylestring""页面根节点样式,页面根节点是所有页面节点的祖先节点,相当于 HTML 中的 body 节点2.9.0
                    body-font-sizestring""页面 page 的字体大小,可以设置为 system ,表示使用当前用户设置的微信字体大小2.11.0
                    root-font-sizestring""页面的根字体大小,页面中的所有 rem 单位,将使用这个字体大小作为参考值,即 1rem 等于这个字体大小;自小程序版本 2.11.0 起,也可以设置为 system2.9.0
                    bindresizeeventhandle页面尺寸变化时会触发 resize 事件, event.detail = { size: { windowWidth, windowHeight } }2.9.0
                    bindscrolleventhandle页面滚动时会触发 scroll 事件, event.detail = { scrollTop }2.9.0
                    bindscrolldoneeventhandle如果通过改变 scroll-top 属性来使页面滚动,页面滚动结束后会触发 scrolldone 事件2.9.0

                    示例代码

                    <page-meta  background-text-style="{{bgTextStyle}}"  background-color="{{bgColor}}"  background-color-top="{{bgColorTop}}"  background-color-bottom="{{bgColorBottom}}"  scroll-top="{{scrollTop}}"  page-style="color: green"  root-font-size="16px">  <navigation-bar    title="{{nbTitle}}"    loading="{{nbLoading}}"    front-color="{{nbFrontColor}}"    background-color="{{nbBackgroundColor}}"  /></page-meta>
                    Page({  data: {    bgTextStyle: 'dark',    scrollTop: '200rpx',    bgColor: '#ff0000',    bgColorTop: '#00ff00',    bgColorBottom: '#0000ff',    nbTitle: '标题',    nbLoading: false,    nbFrontColor: '#000000',    nbBackgroundColor: '#ffffff',  },})


                    native-component

                    原生组件

                    小程序中的部分组件是由客户端创建的原生组件,这些组件有:

                    • camera
                    • canvas
                    • input(仅在focus时表现为原生组件)
                    • live-player
                    • live-pusher
                    • map
                    • textarea
                    • video

                    原生组件的使用限制

                    由于原生组件脱离在 WebView 渲染流程外,因此在使用时有以下限制:

                    • 原生组件的层级是最高的,所以页面中的其他组件无论设置 z-index 为多少,都无法盖在原生组件上。后插入的原生组件可以覆盖之前的原生组件。
                    • 原生组件还无法在 picker-view 中使用。基础库 2.4.4 以下版本,原生组件不支持在 scroll-view、swiper、movable-view 中使用。
                    • 部分CSS样式无法应用于原生组件,例如:无法对原生组件设置 CSS 动画无法定义原生组件为 position: fixed不能在父级节点使用 overflow: hidden 来裁剪原生组件的显示区域
                    • 原生组件的事件监听不能使用 bind:eventname 的写法,只支持 bindeventname。原生组件也不支持 catch 和 capture 的事件绑定方式。
                    • 原生组件会遮挡 vConsole 弹出的调试面板。 在工具上,原生组件是用web组件模拟的,因此很多情况并不能很好的还原真机的表现,建议开发者在使用到原生组件时尽量在真机上进行调试。*

                    cover-view 与 cover-image

                    为了解决原生组件层级最高的限制。小程序专门提供了 cover-view 和 cover-image 组件,可以覆盖在部分原生组件上面。这两个组件也是原生组件,但是使用限制与其他原生组件有所不同。

                    原生组件同层渲染

                    同层渲染是为了解决原生组件的层级问题,在支持同层渲染后,原生组件与其它组件可以随意叠加,有关层级的限制将不再存在。但需要注意的是,组件内部仍由原生渲染,样式一般还是对原生组件内部无效。当前 video, map, live-player, live-pusher, canvas(2d) 组件已支持同层渲染。

                    原生组件相对层级

                    为了可以调整原生组件之间的相对层级位置,小程序在 v2.7.0 及以上版本支持在样式中声明 z-index 来指定原生组件的层级。该 z-index 仅调整原生组件之间的层级顺序,其层级仍高于其他非原生组件。


                    aria-component

                    无障碍访问

                    为了更好地满足视障人士对于小程序的访问需求,基础库自2.7.1起,支持部分ARIA标签。

                    无障碍特性在读屏模式下可以访问,iOS可通过设置->通用->辅助功能->旁白打开。

                    以 view 组件为例,开发者可以增加aria-role和aria-label属性。 其中aria-role表示组件的角色,当设置为'img'时,读屏模式下聚焦后系统会朗读出'图像'。设置为'button'时,聚焦后后系统朗读出'按钮'。 aria-label表示组件附带的额外信息,聚焦后系统会自动朗读出来。

                    小程序已经内置了一些无障碍的特性,对于非原生组件,开发者可以添加以下无障碍标签。

                    aria-hiddenaria-rolearia-labelaria-checkedaria-disabled
                    aria-describedbyaria-expandedaria-haspopuparia-selectedaria-required
                    aria-orientationaria-valueminaria-valuemaxaria-valuenowaria-readonly
                    aria-multiselectablearia-controlstabindexaria-labelledbyria-orientation
                    aia-multiselectablearia-labelledby

                    示例代码

                    <view aria-role="button"  aria-label="提交表单">提交</view>

                    提示:

                    1. 安卓和iOS读屏模式下设置aria-role后朗读的内容不同系统之间会有差异
                    2. 可设置的aria-role可参看 Using Aria中的Widget Roles,部分role的设置在移动端可能无效。


                    aria-component

                    无障碍访问

                    为了更好地满足视障人士对于小程序的访问需求,基础库自2.7.1起,支持部分ARIA标签。

                    无障碍特性在读屏模式下可以访问,iOS可通过设置->通用->辅助功能->旁白打开。

                    以 view 组件为例,开发者可以增加aria-role和aria-label属性。 其中aria-role表示组件的角色,当设置为'img'时,读屏模式下聚焦后系统会朗读出'图像'。设置为'button'时,聚焦后后系统朗读出'按钮'。 aria-label表示组件附带的额外信息,聚焦后系统会自动朗读出来。

                    小程序已经内置了一些无障碍的特性,对于非原生组件,开发者可以添加以下无障碍标签。

                    aria-hiddenaria-rolearia-labelaria-checkedaria-disabled
                    aria-describedbyaria-expandedaria-haspopuparia-selectedaria-required
                    aria-orientationaria-valueminaria-valuemaxaria-valuenowaria-readonly
                    aria-multiselectablearia-controlstabindexaria-labelledbyria-orientation
                    aia-multiselectablearia-labelledby

                    示例代码

                    <view aria-role="button"  aria-label="提交表单">提交</view>

                    提示:

                    1. 安卓和iOS读屏模式下设置aria-role后朗读的内容不同系统之间会有差异
                    2. 可设置的aria-role可参看 Using Aria中的Widget Roles,部分role的设置在移动端可能无效。


                    每个微信小程序需要事先设置一个通讯域名,小程序可以跟指定的域名与进行网络通信。包括普通 HTTPS 请求(wx.request)、 WebSocket 通信(wx.connectSocket)、上传文件(wx.uploadFile)和下载文件(wx.downloadFile)。

                    网络API列表:

                    API说明
                    wx.request发起网络请求
                    wx.uploadFile上传文件
                    wx.downloadFile下载文件
                    wx.connectSocket创建 WebSocket 连接
                    wx.onSocketOpen监听 WebSocket 打开
                    wx.onSocketError监听 WebSocket 错误
                    wx.sendSocketMessage发送 WebSocket 消息
                    wx.onSocketMessage接受 WebSocket 消息
                    wx.closeSocket关闭 WebSocket 连接
                    wx.onSocketClose监听 WebSocket 关闭

                    Tip

                    1. tip: 网络请求的 referer 是不可以设置的,格式固定为https://servicewechat.com/{appid}/{version}/page-frame.html,其中{appid}为小程序的 appid,{version}为小程序的版本号,版本号为 0 表示为开发版。
                    2. tip: 小程序进入后台运行后(非置顶聊天),如果 5s 内网络请求没有结束,会回调错误信息 "fail interrupted";在回到前台之前,网络请求接口调用都会无法调用。

                    RequestTask wx.request(Object object)

                    发起 HTTPS 网络请求。使用前请注意阅读相关说明。

                    参数

                    Object object

                    属性类型默认值必填说明最低版本
                    urlstring开发者服务器接口地址
                    datastring/object/ArrayBuffer请求的参数
                    headerObject设置请求的 header,header 中不能设置 Referer。
                    content-type 默认为 application/json
                    timeoutnumber超时时间,单位为毫秒2.10.0
                    methodstringGETHTTP 请求方法
                    dataTypestringjson返回的数据格式
                    responseTypestringtext响应的数据类型1.7.0
                    enableHttp2booleanfalse开启 http22.10.4
                    enableQuicbooleanfalse开启 quic2.10.4
                    enableCachebooleanfalse开启 cache2.10.4
                    successfunction接口调用成功的回调函数
                    failfunction接口调用失败的回调函数
                    completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                    object.method 的合法值

                    说明最低版本
                    OPTIONSHTTP 请求 OPTIONS
                    GETHTTP 请求 GET
                    HEADHTTP 请求 HEAD
                    POSTHTTP 请求 POST
                    PUTHTTP 请求 PUT
                    DELETEHTTP 请求 DELETE
                    TRACEHTTP 请求 TRACE
                    CONNECTHTTP 请求 CONNECT

                    object.dataType 的合法值

                    说明最低版本
                    json返回的数据为 JSON,返回后会对返回的数据进行一次 JSON.parse
                    其他不对返回的内容进行 JSON.parse

                    object.responseType 的合法值

                    说明最低版本
                    text响应的数据为文本
                    arraybuffer响应的数据为 ArrayBuffer

                    object.success 回调函数

                    参数
                    Object res
                    属性类型说明最低版本
                    datastring/Object/Arraybuffer开发者服务器返回的数据
                    statusCodenumber开发者服务器返回的 HTTP 状态码
                    headerObject开发者服务器返回的 HTTP Response Header1.2.0
                    cookiesArray.<string>开发者服务器返回的 cookies,格式为字符串数组2.10.0
                    profileObject网络请求过程中一些调试信息2.10.4

                    res.profile 的结构

                    属性类型说明
                    redirectStartnumber第一个 HTTP 重定向发生时的时间。有跳转且是同域名内的重定向才算,否则值为 0
                    redirectEndnumber最后一个 HTTP 重定向完成时的时间。有跳转且是同域名内部的重定向才算,否则值为 0
                    fetchStartnumber组件准备好使用 HTTP 请求抓取资源的时间,这发生在检查本地缓存之前
                    domainLookupStartnumberDNS 域名查询开始的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等
                    domainLookupEndnumberDNS 域名查询完成的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等
                    connectStartnumberHTTP(TCP) 开始建立连接的时间,如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接开始的时间
                    connectEndnumberHTTP(TCP) 完成建立连接的时间(完成握手),如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接完成的时间。注意这里握手结束,包括安全连接建立完成、SOCKS 授权通过
                    SSLconnectionStartnumberSSL建立连接的时间,如果不是安全连接,则值为 0
                    SSLconnectionEndnumberSSL建立完成的时间,如果不是安全连接,则值为 0
                    requestStartnumberHTTP请求读取真实文档开始的时间(完成建立连接),包括从本地读取缓存。连接错误重连时,这里显示的也是新建立连接的时间
                    requestEndnumberHTTP请求读取真实文档结束的时间
                    responseStartnumberHTTP 开始接收响应的时间(获取到第一个字节),包括从本地读取缓存
                    responseEndnumberHTTP 响应全部接收完成的时间(获取到最后一个字节),包括从本地读取缓存
                    rttnumber当次请求连接过程中实时 rtt
                    estimate_nettypestring评估的网络状态 slow 2g/2g/3g/4g
                    httpRttEstimatenumber协议层根据多个请求评估当前网络的 rtt(仅供参考)
                    transportRttEstimatenumber传输层根据多个请求评估的当前网络的 rtt(仅供参考)
                    downstreamThroughputKbpsEstimatenumber评估当前网络下载的kbps
                    throughputKbpsnumber当前网络的实际下载kbps
                    peerIPstring当前请求的IP
                    portnumber当前请求的端口
                    socketReusedboolean是否复用连接
                    sendBytesCountnumber发送的字节数
                    receivedBytedCountnumber收到字节数

                    返回值

                    RequestTask

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

                    请求任务对象

                    data 参数说明

                    最终发送给服务器的数据是 String 类型,如果传入的 data 不是 String 类型,会被转换成 String 。转换规则如下:

                    • 对于 GET 方法的数据,会将数据转换成 query string(encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...)
                    • 对于 POST 方法且 header['content-type'] 为 application/json 的数据,会对数据进行 JSON 序列化
                    • 对于 POST 方法且 header['content-type'] 为 application/x-www-form-urlencoded 的数据,会将数据转换成 query string (encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...)

                    示例代码

                    wx.request({  url: 'test.php', //仅为示例,并非真实的接口地址  data: {    x: '',    y: ''  },  header: {    'content-type': 'application/json' // 默认值  },  success (res) {    console.log(res.data)  }})

                    RequestTask

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

                    网络请求任务对象

                    方法

                    RequestTask.abort()

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

                    中断请求任务


                    RequestTask.offHeadersReceived(function callback)

                    基础库 2.1.0 开始支持,低版本需做兼容处理。

                    取消监听 HTTP Response Header 事件

                    参数

                    function callback

                    HTTP Response Header 事件的回调函数


                    RequestTask.onHeadersReceived(function callback)

                    基础库 2.1.0 开始支持,低版本需做兼容处理。

                    监听 HTTP Response Header 事件。会比请求完成事件更早

                    参数

                    function callback

                    HTTP Response Header 事件的回调函数

                    参数

                    Object res
                    属性类型说明
                    headerObject开发者服务器返回的 HTTP Response Header


                    示例代码

                    const requestTask = wx.request({  url: 'test.php', //仅为示例,并非真实的接口地址  data: {    x: '' ,    y: ''  },  header: {    'content-type': 'application/json'  },  success (res) {    console.log(res.data)  }})requestTask.abort() // 取消请求任务


                    wx.uploadFile(OBJECT)


                    将本地资源上传到开发者服务器。如页面通过 wx.chooseImage 等接口获取到一个本地资源的临时文件路径后,可通过此接口将本地资源上传到指定服务器。客户端发起一个HTTPS POST请求,其中Content-Typemultipart/form-data

                    OBJECT参数说明:

                    参数类型必填说明
                    urlString开发者服务器url
                    filePathString要上传文件资源的路径
                    nameString文件对应的key , 开发者在服务器端通过这个key可以获取到文件二进制内容
                    headerObjectHTTP 请求 Header,header中不能设置Referer
                    formDataObjectHTTP 请求中其他额外的form data
                    successFunction接口调用成功的回调函数
                    failFunction接口调用失败的回调函数
                    completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                    success返回参数说明:

                    参数类型说明
                    dataString开发者服务器返回的数据
                    statusCodeNumberHTTP状态码

                    示例代码:

                    wx.chooseImage({  success:function(res){    var tempFilePaths = res.tempFilePaths    wx.uploadFile({      url: 'http://example.weixin.qq.com/upload', //仅为示例,非真实的接口地址      filePath: tempFilePaths[0],      name:"file",      formData:{        "user":"test"      }      success: function(res){        var data = res.data        //do something      }    })  }})

                    返回值:

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

                    返回一个uploadTask对象,通过uploadTask,可监听上传进度变化事件,以及取消上传任务。

                    uploadTask

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

                    一个可以监听上传进度变化事件,以及取消上传任务的对象

                    方法:

                    UploadTask.abort()

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

                    中断上传任务


                    UploadTask.offHeadersReceived(function callback)

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

                    取消监听 HTTP Response Header 事件

                    参数

                    function callback

                    HTTP Response Header 事件的回调函数


                    UploadTask.offProgressUpdate(function callback)

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

                    取消监听上传进度变化事件

                    参数

                    function callback

                    上传进度变化事件的回调函数


                    UploadTask.onHeadersReceived(function callback)

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

                    监听 HTTP Response Header 事件。会比请求完成事件更早

                    参数

                    function callback

                    HTTP Response Header 事件的回调函数

                    参数

                    Object res
                    属性类型说明
                    headerObject开发者服务器返回的 HTTP Response Header


                    UploadTask.onProgressUpdate(function callback)

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

                    监听上传进度变化事件

                    参数

                    function callback

                    上传进度变化事件的回调函数

                    参数

                    Object res
                    属性类型说明
                    progressnumber上传进度百分比
                    totalBytesSentnumber已经上传的数据长度,单位 Bytes
                    totalBytesExpectedToSendnumber预期需要上传的数据总长度,单位 Bytes


                    示例代码:

                    const uploadTask = wx.uploadFile({    url: 'http://example.weixin.qq.com/upload', //仅为示例,非真实的接口地址    filePath: tempFilePaths[0],    name: 'file',    formData:{        'user': 'test'    },    success: function(res){        var data = res.data        //do something    }})uploadTask.onProgressUpdate((res) => {    console.log('上传进度', res.progress)    console.log('已经上传的数据长度', res.totalBytesSent)    console.log('预期需要上传的数据总长度', res.totalBytesExpectedToSend)})uploadTask.abort() // 取消上传任务

                    Bug & Tip

                    1. tip: 最大并发限制是 10 个
                    2. tip: 默认超时时间和最大超时时间都是 60s


                    wx.downloadFile(OBJECT)

                    下载文件资源到本地。客户端直接发起一个HTTP GET请求,返回文件的本地临时路径。

                    参数

                    Object object

                    属性类型默认值必填说明最低版本
                    urlstring下载资源的 url
                    headerObjectHTTP 请求的 Header,Header 中不能设置 Referer
                    timeoutnumber超时时间,单位为毫秒2.10.0
                    filePathstring指定文件下载后存储的路径 (本地路径)1.8.0
                    successfunction接口调用成功的回调函数
                    failfunction接口调用失败的回调函数
                    completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                    object.success 回调函数

                    参数
                    Object res
                    属性类型说明最低版本
                    tempFilePathstring临时文件路径 (本地路径)。没传入 filePath 指定文件存储路径时会返回,下载后的文件会存储到一个临时文件
                    filePathstring用户文件路径 (本地路径)。传入 filePath 时会返回,跟传入的 filePath 一致
                    statusCodenumber开发者服务器返回的 HTTP 状态码
                    profileObject网络请求过程中一些调试信息2.10.4

                    res.profile 的结构

                    属性类型说明
                    redirectStartnumber第一个 HTTP 重定向发生时的时间。有跳转且是同域名内的重定向才算,否则值为 0
                    redirectEndnumber最后一个 HTTP 重定向完成时的时间。有跳转且是同域名内部的重定向才算,否则值为 0
                    fetchStartnumber组件准备好使用 HTTP 请求抓取资源的时间,这发生在检查本地缓存之前
                    domainLookupStartnumberDNS 域名查询开始的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等
                    domainLookupEndnumberDNS 域名查询完成的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等
                    connectStartnumberHTTP(TCP) 开始建立连接的时间,如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接开始的时间
                    connectEndnumberHTTP(TCP) 完成建立连接的时间(完成握手),如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接完成的时间。注意这里握手结束,包括安全连接建立完成、SOCKS 授权通过
                    SSLconnectionStartnumberSSL建立连接的时间,如果不是安全连接,则值为 0
                    SSLconnectionEndnumberSSL建立完成的时间,如果不是安全连接,则值为 0
                    requestStartnumberHTTP请求读取真实文档开始的时间(完成建立连接),包括从本地读取缓存。连接错误重连时,这里显示的也是新建立连接的时间
                    requestEndnumberHTTP请求读取真实文档结束的时间
                    responseStartnumberHTTP 开始接收响应的时间(获取到第一个字节),包括从本地读取缓存
                    responseEndnumberHTTP 响应全部接收完成的时间(获取到最后一个字节),包括从本地读取缓存
                    rttnumber当次请求连接过程中实时 rtt
                    estimate_nettypestring评估的网络状态 slow 2g/2g/3g/4g
                    httpRttEstimatenumber协议层根据多个请求评估当前网络的 rtt(仅供参考)
                    transportRttEstimatenumber传输层根据多个请求评估的当前网络的 rtt(仅供参考)
                    downstreamThroughputKbpsEstimatenumber评估当前网络下载的kbps
                    throughputKbpsnumber当前网络的实际下载kbps
                    peerIPstring当前请求的IP
                    portnumber当前请求的端口
                    socketReusedboolean是否复用连接
                    sendBytesCountnumber发送的字节数
                    receivedBytedCountnumber收到字节数

                    返回值

                    DownloadTask

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

                    一个可以监听下载进度变化事件和取消下载的对象


                    示例代码:

                    wx.downloadFile({  url: 'https://example.com/audio/123', //仅为示例,并非真实的资源  success (res) {    // 只要服务器有响应数据,就会把响应内容写入文件并进入 success 回调,业务需要自行判断是否下载到了想要的内容    if (res.statusCode === 200) {      wx.playVoice({        filePath: res.tempFilePath      })    }  }})



                    DownloadTask

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

                    一个可以监听下载进度变化事件,以及取消下载任务的对象

                    方法:

                    DownloadTask.abort()

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

                    中断下载任务


                    DownloadTask.offHeadersReceived(function callback)

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

                    取消监听 HTTP Response Header 事件

                    参数

                    function callback

                    HTTP Response Header 事件的回调函数


                    DownloadTask.offProgressUpdate(function callback)

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

                    取消监听下载进度变化事件

                    参数

                    function callback

                    下载进度变化事件的回调函数

                      DownloadTask.onHeadersReceived(function callback)

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

                      监听 HTTP Response Header 事件。会比请求完成事件更早

                      参数

                      function callback

                      HTTP Response Header 事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      headerObject开发者服务器返回的 HTTP Response Header

                      DownloadTask.onProgressUpdate(function callback)

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

                      监听下载进度变化事件

                      参数

                      function callback

                      下载进度变化事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      progressnumber下载进度百分比
                      totalBytesWrittennumber已经下载的数据长度,单位 Bytes
                      totalBytesExpectedToWritenumber预期需要下载的数据总长度,单位 Bytes


                      wx.connectSocket(OBJECT)


                      创建一个 WebSocket 连接;一个微信小程序同时只能有一个 WebSocket 连接,如果当前已存在一个 WebSocket 连接,会自动关闭该连接,并重新创建一个 WebSocket 连接。

                      OBJECT参数说明:

                      参数类型必填说明最低版本
                      urlString开发者服务器接口地址,必须是 wss 协议,且域名必须是后台配置的合法域名 
                      dataObject请求的数据 
                      headerObjectHTTP Header , header 中不能设置 Referer 
                      methodString默认是GET,有效值: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT 
                      protocolsStringArray子协议数组1.4.0
                      successFunction接口调用成功的回调函数 
                      failFunction接口调用失败的回调函数 
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行) 

                      示例代码:
                      wx.connectSocket({    url: 'test.php',  data:{    x: '',    y: ''  },  header:{     'content-type': 'application/json'  },  protocols: ['protocol1'],  method:"GET"})

                      wx.onSocketOpen(CALLBACK)


                      监听WebSocket连接打开事件。

                      示例代码:

                      wx.connectSocket({  url: 'test.php'})wx.onSocketOpen(function(res) {  console.log('WebSocket连接已打开!')})

                      wx.onSocketError(CALLBACK)


                      监听WebSocket错误。

                      示例代码:

                      wx.connectSocket({  url: 'test.php'})wx.onSocketOpen(function(res){  console.log('WebSocket连接已打开!')})wx.onSocketError(function(res){  console.log('WebSocket连接打开失败,请检查!')})

                      wx.sendSocketMessage(OBJECT)


                      通过 WebSocket 连接发送数据,需要先 wx.connectSocket,并在 wx.onSocketOpen 回调之后才能发送。

                      OBJECT参数说明:

                      参数类型必填说明
                      dataString/ArrayBuffer需要发送的内容
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      var socketOpen = falsevar socketMsgQueue = []wx.connectSocket({  url: 'test.php'})wx.onSocketOpen(function(res) {  socketOpen = true  for (var i = 0; i < socketMsgQueue.length; i++){     sendSocketMessage(socketMsgQueue[i])  }  socketMsgQueue = []})function sendSocketMessage(msg) {  if (socketOpen) {    wx.sendSocketMessage({      data:msg    })  } else {     socketMsgQueue.push(msg)  }}

                      wx.onSocketMessage(CALLBACK)


                      监听WebSocket接受到服务器的消息事件。

                      CALLBACK返回参数:

                      参数类型说明
                      dataString/ArrayBuffer服务器返回的消息

                      示例代码:

                      wx.connectSocket({  url: 'test.php'})wx.onSocketMessage(function(res) {  console.log('收到服务器内容:' + res.data)})

                      wx.closeSocket(OBJECT)


                      关闭WebSocket连接。

                      参数类型必填说明最低版本
                      codeNumber一个数字值表示关闭连接的状态号,表示连接被关闭的原因。如果这个参数没有被指定,默认的取值是1000 (表示正常连接关闭)1.4.0
                      reasonString一个可读的字符串,表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本(不是字符)1.4.0
                      successFunction接口调用成功的回调函数 
                      failFunction接口调用失败的回调函数 
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行) 

                      wx.onSocketClose(CALLBACK)


                      监听WebSocket关闭。

                      wx.connectSocket({  url: 'test.php'})//注意这里有时序问题,//如果 wx.connectSocket 还没回调 wx.onSocketOpen,而先调用 wx.closeSocket,那么就做不到关闭 WebSocket 的目的。//必须在 WebSocket 打开期间调用 wx.closeSocket 才能关闭。wx.onSocketOpen(function() {  wx.closeSocket()})wx.onSocketClose(function(res) {  console.log('WebSocket 已关闭!')})

                      返回值:

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

                      返回一个 SocketTask。

                      Bug & Tip

                      1. tip: createSocket 链接默认和最大超时时间都是 60s
                      2. tip: 网络请求的 referer 是不可以设置的,格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中{appid}为小程序的 appid,{version}为小程序的版本号,版本号为 0 表示为开发版。

                      SocketTask

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

                      WebSocket 任务,可通过 wx.connectSocket() 接口创建返回。

                      方法

                      SocketTask.send(OBJECT)

                      通过 WebSocket 连接发送数据。

                      OBJECT参数说明:

                      参数类型必填说明
                      dataString/ArrayBuffer需要发送的内容
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)
                      SocketTask.close(OBJECT)

                      关闭 WebSocket 连接。

                      OBJECT参数说明:

                      参数类型必填说明
                      codeNumber一个数字值表示关闭连接的状态号,表示连接被关闭的原因。如果这个参数没有被指定,默认的取值是1000 (表示正常连接关闭)
                      reasonString一个可读的字符串,表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本(不是字符)
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)
                      SocketTask.onOpen(CALLBACK)

                      监听 WebSocket 连接打开事件。

                      SocketTask.onClose(CALLBACK)

                      监听 WebSocket 连接关闭事件。

                      SocketTask.onError(CALLBACK)

                      监听 WebSocket 错误。

                      CALLBACK返回参数:

                      参数类型说明
                      errMsgString错误信息
                      SocketTask.onMessage(CALLBACK)

                      监听WebSocket接受到服务器的消息事件。

                      CALLBACK返回参数:

                      参数类型说明
                      dataString/ArrayBuffer服务器返回的消息

                      wx.stopLocalServiceDiscovery(Object object)

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

                      停止搜索 mDNS 服务

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      task not found在当前没有处在搜索服务中的情况下调用 stopLocalServiceDiscovery

                      wx.startLocalServiceDiscovery(Object object)

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

                      开始搜索局域网下的 mDNS 服务。搜索的结果会通过 wx.onLocalService* 事件返回。

                      参数

                      Object object

                      属性类型默认值必填说明
                      serviceTypestring要搜索的服务类型
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      invalid paramserviceType 为空
                      scan task already exist在当前 startLocalServiceDiscovery 发起的搜索未停止的情况下,再次调用 startLocalServiceDiscovery

                      示例代码

                          wx.startLocalServiceDiscovery({      // 当前手机所连的局域网下有一个 _http._tcp. 类型的服务      serviceType: '_http._tcp.',      success: console.log,      fail: console.log    })

                      注意

                      1. wx.startLocalServiceDiscovery 是一个消耗性能的行为,开始 30 秒后会自动 stop 并执行 wx.onLocalServiceDiscoveryStop 注册的回调函数。
                      2. 在调用 wx.startLocalServiceDiscovery 后,在这次搜索行为停止后才能发起下次 wx.startLocalServiceDiscovery。停止本次搜索行为的操作包括调用 wx.stopLocalServiceDiscovery 和 30 秒后系统自动 stop 本次搜索。

                      wx.onLocalServiceResolveFail(function callback)

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

                      监听 mDNS 服务解析失败的事件

                      参数

                      function callback

                      mDNS 服务解析失败的事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      serviceTypestring服务的类型
                      serviceNamestring服务的名称

                      wx.onLocalServiceLost(function callback)

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

                      监听 mDNS 服务离开的事件

                      参数

                      function callback

                      mDNS 服务离开的事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      serviceTypestring服务的类型
                      serviceNamestring服务的名称

                      wx.onLocalServiceFound(function callback)

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

                      监听 mDNS 服务发现的事件

                      参数

                      function callback

                      mDNS 服务发现的事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      serviceTypestring服务的类型
                      serviceNamestring服务的名称
                      ipstring服务的 ip 地址
                      portnumber服务的端口

                      wx.onLocalServiceDiscoveryStop(function callback)

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

                      监听 mDNS 服务停止搜索的事件

                      参数

                      function callback

                      mDNS 服务停止搜索的事件的回调函数


                      wx.offLocalServiceResolveFail(function callback)

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

                      取消监听 mDNS 服务解析失败的事件

                      参数

                      function callback

                      mDNS 服务解析失败的事件的回调函数


                      wx.offLocalServiceLost(function callback)

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

                      取消监听 mDNS 服务离开的事件

                      参数

                      function callback

                      mDNS 服务离开的事件的回调函数


                      wx.offLocalServiceFound(function callback)

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

                      取消监听 mDNS 服务发现的事件

                      参数

                      function callback

                      mDNS 服务发现的事件的回调函数


                      wx.offLocalServiceDiscoveryStop(function callback)

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

                      取消监听 mDNS 服务停止搜索的事件

                      参数

                      function callback

                      mDNS 服务停止搜索的事件的回调函数


                      UDPSocket wx.createUDPSocket()

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

                      创建一个 UDP Socket 实例。使用前请注意阅读相关说明。

                      返回值

                      UDPSocket

                      一个 UDP Socket 实例


                      UDPSocket

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

                      一个 UDP Socket 实例,默认使用 IPv4 协议。

                      方法:

                      number UDPSocket.bind(number port)

                      绑定一个系统随机分配的可用端口,或绑定一个指定的端口号

                      参数

                      number port

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

                      指定要绑定的端口号,不传则返回系统随机分配的可用端口

                      返回值

                      number

                      绑定成功的端口号

                      示例代码

                      const udp = wx.createUDPSocket()const port = udp.bind()


                      UDPSocket.close()

                      关闭 UDP Socket 实例,相当于销毁。 在关闭之后,UDP Socket 实例不能再发送消息,每次调用 UDPSocket.send 将会触发错误事件,并且 message 事件回调函数也不会再也执行。在 UDPSocket 实例被创建后将被 Native 强引用,保证其不被 GC。在 UDPSocket.close 后将解除对其的强引用,让 UDPSocket 实例遵从 GC。


                      UDPSocket.offClose(function callback)

                      取消监听关闭事件

                      参数

                      function callback

                      关闭事件的回调函数


                      UDPSocket.offError(function callback)

                      取消监听错误事件

                      参数

                      function callback

                      错误事件的回调函数


                      UDPSocket.offListening(function callback)

                      取消监听开始监听数据包消息的事件

                      参数

                      function callback

                      开始监听数据包消息的事件的回调函数


                      UDPSocket.offMessage(function callback)

                      取消监听收到消息的事件

                      参数

                      function callback

                      收到消息的事件的回调函数


                      UDPSocket.onClose(function callback)

                      监听关闭事件

                      参数

                      function callback

                      关闭事件的回调函数


                      UDPSocket.onError(function callback)

                      监听错误事件

                      参数

                      function callback

                      错误事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      errMsgstring错误信息


                      UDPSocket.onListening(function callback)

                      监听开始监听数据包消息的事件

                      参数

                      function callback

                      开始监听数据包消息的事件的回调函数


                      UDPSocket.onMessage(function callback)

                      监听收到消息的事件

                      参数

                      function callback

                      收到消息的事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      messageArrayBuffer收到的消息
                      remoteInfoObject消息来源的结构化信息

                      remoteInfo 的结构

                      属性类型说明
                      addressstring发送消息的 socket 的地址
                      familystring使用的协议族,为 IPv4 或者 IPv6
                      portnumber端口号
                      sizenumbermessage 的大小,单位:字节


                      UDPSocket.send(Object object)

                      向指定的 IP 和 port 发送消息

                      参数

                      Object object

                      属性类型默认值必填说明
                      addressstring要发消息的地址。在基础库 2.9.3 及之前版本可以是一个和本机同网段的 IP 地址,也可以是在安全域名列表内的域名地址;在基础库 2.9.4 及之后版本,可以是任意 IP 和域名
                      portnumber要发送消息的端口号
                      messagestring/ArrayBuffer要发送的数据
                      offsetnumber0发送数据的偏移量,仅当 message 为 ArrayBuffer 类型时有效
                      lengthnumbermessage.byteLength发送数据的长度,仅当 message 为 ArrayBuffer 类型时有效

                      示例代码

                        const udp = wx.createUDPSocket()  udp.bind()  udp.send({    address: '192.168.193.2',    port: 8848,    message: 'hello, how are you'  })


                      MapContext wx.createMapContext(string mapId, Object this)

                      创建 map 上下文 MapContext 对象。

                      参数

                      string mapId

                      map 组件的 id

                      Object this

                      在自定义组件下,当前组件实例的this,以操作组件内 map 组件

                      返回值

                      MapContext


                      MapContext 实例,可通过 wx.createMapContext 获取。

                      MapContext 通过 id 跟一个 map 组件绑定,操作对应的 map 组件。

                      方法

                      MapContext.getCenterLocation()

                      获取当前地图中心的经纬度。返回的是 gcj02 坐标系,可以用于 wx.openLocation()

                      MapContext.moveToLocation(Object object)

                      将地图中心移置当前定位点,此时需设置地图组件 show-locationtrue2.8.0 起支持将地图中心移动到指定位置。

                      MapContext.translateMarker(Object object)

                      平移marker,带动画

                      MapContext.includePoints(Object object)

                      缩放视野展示所有经纬度

                      MapContext.getRegion()

                      获取当前地图的视野范围

                      MapContext.getRotate()

                      获取当前地图的旋转角

                      MapContext.getSkew()

                      获取当前地图的倾斜角

                      MapContext.getScale()

                      获取当前地图的缩放级别

                      MapContext.setCenterOffset(Object object)

                      设置地图中心点偏移,向后向下为增长,屏幕比例范围(0.25~0.75),默认偏移为[0.5, 0.5]

                      MapContext.removeCustomLayer(Object object)

                      移除个性化图层。

                      MapContext.addCustomLayer(Object object)

                      添加个性化图层。

                      示例代码

                      <!-- map.wxml --><map id="myMap" show-location /><button type="primary" bindtap="getCenterLocation">获取位置</button><button type="primary" bindtap="moveToLocation">移动位置</button><button type="primary" bindtap="translateMarker">移动标注</button><button type="primary" bindtap="includePoints">缩放视野展示所有经纬度</button>
                      // map.jsPage({  onReady: function (e) {    // 使用 wx.createMapContext 获取 map 上下文    this.mapCtx = wx.createMapContext('myMap')  },  getCenterLocation: function () {    this.mapCtx.getCenterLocation({      success: function(res){        console.log(res.longitude)        console.log(res.latitude)      }    })  },  moveToLocation: function () {    this.mapCtx.moveToLocation()  },  translateMarker: function() {    this.mapCtx.translateMarker({      markerId: 0,      autoRotate: true,      duration: 1000,      destination: {        latitude:23.10229,        longitude:113.3345211,      },      animationEnd() {        console.log('animation end')      }    })  },  includePoints: function() {    this.mapCtx.includePoints({      padding: [10],      points: [{        latitude:23.10229,        longitude:113.3345211,      }, {        latitude:23.00229,        longitude:113.3345211,      }]    })  }})


                      wx.saveImageToPhotosAlbum(Object object)

                      基础库 1.2.0 开始支持,低版本需做兼容处理
                      调用前需要 用户授权 scope.writePhotosAlbum

                      保存图片到系统相册。

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring图片文件路径,可以是临时文件路径或永久文件路径 (本地路径) ,不支持网络路径
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.saveImageToPhotosAlbum({  success(res) { }})


                      wx.previewMedia(Object object)

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

                      预览图片和视频。

                      参数

                      Object object

                      属性类型默认值必填说明
                      sourcesArray.<Object>需要预览的资源列表
                      currentcurrent0当前显示的资源序号
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.sources 的结构

                      属性类型默认值必填说明
                      urlString图片或视频的地址
                      typeStringimage资源的类型,默认为图片
                      posterstring视频的封面图片

                      type 的合法值

                      说明最低版本
                      image图片
                      video视频




                      wx.previewImage(Object object)

                      在新页面中全屏预览图片。预览的过程中用户可以进行保存图片、发送给朋友等操作。

                      参数

                      Object object

                      属性类型默认值必填说明
                      urlsArray.<string>需要预览的图片链接列表。2.2.3 起支持云文件ID。
                      currentstringurls 的第一张当前显示图片的链接
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.previewImage({  current: '', // 当前显示图片的http链接  urls: [] // 需要预览的图片http链接列表})


                      wx.getImageInfo(Object object)

                      获取图片信息。网络图片需先配置download域名才能生效。

                      参数

                      Object object

                      属性类型默认值必填说明
                      srcstring图片的路径,支持网络路径、本地路径、代码包路径
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明最低版本
                      widthnumber图片原始宽度,单位px。不考虑旋转。
                      heightnumber图片原始高度,单位px。不考虑旋转。
                      pathstring图片的本地路径
                      orientationstring拍照时设备方向1.9.90
                      typestring图片格式1.9.90

                      res.orientation 的合法值

                      说明最低版本
                      up默认方向(手机横持拍照),对应 Exif 中的 1。或无 orientation 信息。
                      up-mirrored同 up,但镜像翻转,对应 Exif 中的 2
                      down旋转180度,对应 Exif 中的 3
                      down-mirrored同 down,但镜像翻转,对应 Exif 中的 4
                      left-mirrored同 left,但镜像翻转,对应 Exif 中的 5
                      right顺时针旋转90度,对应 Exif 中的 6
                      right-mirrored同 right,但镜像翻转,对应 Exif 中的 7
                      left逆时针旋转90度,对应 Exif 中的 8

                      示例代码

                      wx.getImageInfo({  src: 'images/a.jpg',  success (res) {    console.log(res.width)    console.log(res.height)  }})wx.chooseImage({  success (res) {    wx.getImageInfo({      src: res.tempFilePaths[0],      success (res) {        console.log(res.width)        console.log(res.height)      }    })  }})


                      wx.compressImage(Object object)

                      基础库 2.4.0 开始支持,低版本需做兼容处理。

                      压缩图片接口,可选压缩质量

                      参数

                      Object object

                      属性类型默认值必填说明
                      srcstring图片路径,图片的路径,支持本地路径、代码包路径
                      qualitynumber80压缩质量,范围0~100,数值越小,质量越低,压缩率越高(仅对jpg有效)。
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      tempFilePathstring压缩后图片的临时文件路径 (本地路径)

                      示例代码

                      wx.compressImage({  src: '', // 图片路径  quality: 80 // 压缩质量})


                      wx.chooseMessageFile(Object object)

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

                      从客户端会话选择文件。

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      countnumber最多可以选择的文件个数,可以 0~100
                      typestring'all'所选的文件的类型
                      extensionArray.<string>根据文件拓展名过滤,仅 type==file 时有效。每一项都不能是空字符串。默认不过滤。2.6.0
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.type 的合法值

                      说明最低版本
                      all从所有文件选择
                      video只能选择视频文件
                      image只能选择图片文件
                      file可以选择除了图片和视频之外的其它的文件

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      tempFilesArray.<Object>返回选择的文件的本地临时文件对象数组

                      res.tempFiles 的结构

                      属性类型说明
                      pathstring本地临时文件路径 (本地路径)
                      sizenumber本地临时文件大小,单位 B
                      namestring选择的文件名称
                      typestring选择的文件类型
                      timenumber选择的文件的会话发送时间,Unix时间戳,工具暂不支持此属性

                      type 的合法值

                      说明最低版本
                      video选择了视频文件
                      image选择了图片文件
                      file选择了除图片和视频的文件
                      wx.chooseMessageFile({  count: 10,  type: 'image',  success (res) {    // tempFilePath可以作为img标签的src属性显示图片    const tempFilePaths = res.tempFiles  }})


                      wx.chooseImage(Object object)

                      从本地相册选择图片或使用相机拍照。

                      参数

                      Object object

                      属性类型默认值必填说明
                      countnumber9最多可以选择的图片张数
                      sizeTypeArray.<string>['original', 'compressed']所选的图片的尺寸
                      sourceTypeArray.<string>['album', 'camera']选择图片的来源
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.sizeType 的合法值

                      说明最低版本
                      original原图
                      compressed压缩图

                      object.sourceType 的合法值

                      说明最低版本
                      album从相册选图
                      camera使用相机

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明最低版本
                      tempFilePathsArray.<string>图片的本地临时文件路径列表 (本地路径)
                      tempFilesArray.<Object>图片的本地临时文件列表1.2.0

                      res.tempFiles 的结构

                      属性类型说明
                      pathstring本地临时文件路径 (本地路径)
                      sizenumber本地临时文件大小,单位 B
                      wx.chooseImage({  count: 1,  sizeType: ['original', 'compressed'],  sourceType: ['album', 'camera'],  success (res) {    // tempFilePath可以作为img标签的src属性显示图片    const tempFilePaths = res.tempFilePaths  }})


                      wx.saveVideoToPhotosAlbum(Object object)

                      基础库 1.2.0 开始支持,低版本需做兼容处理
                      调用前需要 用户授权 scope.writePhotosAlbum

                      保存视频到系统相册。支持mp4视频格式。

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring视频文件路径,可以是临时文件路径也可以是永久文件路径 (本地路径)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.saveVideoToPhotosAlbum({  filePath: 'wxfile://xxx',  success (res) {    console.log(res.errMsg)  }})


                      wx.openVideoEditor(Object object)

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

                      打开视频编辑器

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring视频源的路径,只支持本地路径
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      durationnumber剪辑后生成的视频文件的时长,单位毫秒(ms)
                      sizenumber剪辑后生成的视频文件大小,单位字节数(byte)
                      tempFilePathstring编辑后生成的视频文件的临时路径
                      tempThumbPathstring编辑后生成的缩略图文件的临时路径


                      wx.getVideoInfo(Object object)

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

                      获取视频详细信息。

                      参数

                      Object object

                      属性类型默认值必填说明
                      srcstring视频文件路径,可以是临时文件路径也可以是永久文件路径
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      orientationstring画面方向
                      typestring视频格式
                      durationnumber视频长度
                      sizenumber视频大小,单位 kB
                      heightnumber视频的长,单位 px
                      widthnumber视频的宽,单位 px
                      fpsnumber视频帧率
                      bitratenumber视频码率,单位 kbps

                      res.orientation 的合法值

                      说明最低版本
                      up默认
                      down180度旋转
                      left逆时针旋转90度
                      right顺时针旋转90度
                      up-mirrored同up,但水平翻转
                      down-mirrored同down,但水平翻转
                      left-mirrored同left,但垂直翻转
                      right-mirrored同right,但垂直翻转




                      VideoContext wx.createVideoContext(string id, Object this)

                      创建 video 上下文 VideoContext 对象。

                      参数

                      string id

                      video 组件的 id

                      Object this

                      在自定义组件下,当前组件实例的this,以操作组件内 video 组件

                      返回值

                      VideoContext


                      wx.compressVideo(Object object)

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

                      压缩视频接口。开发者可指定压缩质量 quality 进行压缩。当需要更精细的控制时,可指定 bitrate、fps、和 resolution,当 quality 传入时,这三个参数将被忽略。原视频的相关信息可通过 getVideoInfo 获取。

                      参数

                      Object object

                      属性类型默认值必填说明
                      srcstring视频文件路径,可以是临时文件路径也可以是永久文件路径
                      qualitystring压缩质量
                      bitratenumber码率,单位 kbps
                      fpsnumber帧率
                      resolutionnumber相对于原视频的分辨率比例,取值范围(0, 1]
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.quality 的合法值

                      说明最低版本
                      low
                      medium
                      high

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      tempFilePathstring压缩后的临时文件地址
                      sizestring压缩后的大小,单位 kB


                      wx.chooseVideo(Object object)

                      拍摄视频或从手机相册中选视频。

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      sourceTypeArray.<string>['album', 'camera']视频选择的来源
                      compressedbooleantrue是否压缩所选择的视频文件1.6.0
                      maxDurationnumber60拍摄视频最长拍摄时间,单位秒
                      camerastring'back'默认拉起的是前置或者后置摄像头。部分 Android 手机下由于系统 ROM 不支持无法生效
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.sourceType 的合法值

                      说明最低版本
                      album从相册选择视频
                      camera使用相机拍摄视频

                      object.camera 的合法值

                      说明最低版本
                      back默认拉起后置摄像头
                      front默认拉起前置摄像头

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      tempFilePathstring选定视频的临时文件路径 (本地路径)
                      durationnumber选定视频的时间长度
                      sizenumber选定视频的数据量大小
                      heightnumber返回选定视频的高度
                      widthnumber返回选定视频的宽度

                      示例代码

                      wx.chooseVideo({  sourceType: ['album','camera'],  maxDuration: 60,  camera: 'back',  success(res) {    console.log(res.tempFilePath)  }})


                      wx.chooseMedia(Object object)

                      基础库 2.10.0 开始支持,低版本需做兼容处理。

                      拍摄或从手机相册中选择图片或视频。

                      参数

                      Object object

                      属性类型默认值必填说明
                      countnumber9最多可以选择的文件个数
                      mediaTypeArray.<string>['image', 'video']文件类型
                      sourceTypeArray.<string>['album', 'camera']图片和视频选择的来源
                      maxDurationnumber10拍摄视频最长拍摄时间,单位秒。时间范围为 3s 至 30s 之间
                      sizeTypeArray.<string>['original', 'compressed']仅对 mediaType 为 image 时有效,是否压缩所选文件
                      camerastring'back'仅在 sourceType 为 camera 时生效,使用前置或后置摄像头
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.mediaType 的合法值

                      说明最低版本
                      image只能拍摄图片或从相册选择图片
                      video只能拍摄视频或从相册选择视频

                      object.sourceType 的合法值

                      说明最低版本
                      album从相册选择
                      camera使用相机拍摄

                      object.camera 的合法值

                      说明最低版本
                      back使用后置摄像头
                      front使用前置摄像头

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      tempFilesArray.<Object>本地临时文件列表
                      typestring文件类型,有效值有 image 、video

                      res.tempFiles 的结构

                      属性类型说明
                      tempFilePathstring本地临时文件路径 (本地路径)
                      sizenumber本地临时文件大小,单位 B
                      durationnumber视频的时间长度
                      heightnumber视频的高度
                      widthnumber视频的宽度
                      thumbTempFilePathstring视频缩略图临时文件路径

                      示例代码

                      wx.chooseMedia({  count: 9,  mediaType: ['image','video'],  sourceType: ['album', 'camera'],  maxDuration: 30,  camera: 'back',  success(res) {    console.log(res.tempFiles.tempFilePath)    console.log(res.tempFiles.size)  }})


                      VideoContext

                      VideoContext 实例,可通过 wx.createVideoContext 获取。

                      VideoContext 通过 id 跟一个 video 组件绑定,操作对应的 video 组件。

                      方法:

                      VideoContext.exitFullScreen()

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

                      退出全屏

                      VideoContext.exitPictureInPicture(Object object)

                      退出小窗,该方法可在任意页面调用

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      VideoContext.hideStatusBar()

                      基础库 2.1.0 开始支持,低版本需做兼容处理。

                      隐藏状态栏,仅在iOS全屏下有效

                      VideoContext.pause()

                      暂停视频

                      VideoContext.play()

                      播放视频

                      VideoContext.playbackRate(number rate)

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

                      设置倍速播放

                      参数

                      number rate

                      倍率,支持 0.5/0.8/1.0/1.25/1.5,2.6.3 起支持 2.0 倍速

                      VideoContext.requestFullScreen(Object object)

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

                      进入全屏。若有自定义内容需在全屏时展示,需将内容节点放置到 video 节点内。

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      directionnumber设置全屏时视频的方向,不指定则根据宽高比自动判断。1.7.0

                      object.direction 的合法值

                      说明最低版本
                      0正常竖向
                      90屏幕逆时针90度
                      -90屏幕顺时针90度

                      VideoContext.seek(number position)

                      跳转到指定位置

                      参数

                      number position

                      跳转到的位置,单位 s

                      VideoContext.sendDanmu(Object data)

                      发送弹幕

                      参数

                      Object data

                      弹幕内容

                      属性类型默认值必填说明
                      textstring弹幕文字
                      colorstring弹幕颜色

                      VideoContext.showStatusBar()

                      基础库 2.1.0 开始支持,低版本需做兼容处理。

                      显示状态栏,仅在iOS全屏下有效

                      VideoContext.stop()

                      基础库 1.7.0 开始支持,低版本需做兼容处理。

                      停止视频

                      示例代码

                      在开发者工具中预览效果

                      <view class="section tc">  <video id="myVideo" src="http://wxsnsdy.tc.qq.com/105/20210/snsdyvideodownload?filekey=30280201010421301f0201690402534804102ca905ce620b1241b726bc41dcff44e00204012882540400&bizid=1023&hy=SH&fileparam=302c020101042530230204136ffd93020457e3c4ff02024ef202031e8d7f02030f42400204045a320a0201000400" rel="external nofollow"  enable-danmu danmu-btn controls></video>  <view class="btn-area">    <input bindblur="bindInputBlur"/>    <button bindtap="bindSendDanmu">发送弹幕</button>  </view></view>

                      function getRandomColor () {  let rgb = []  for (let i = 0 ; i < 3; ++i) {    let color = Math.floor(Math.random() * 256).toString(16)    color = color.length == 1 ? '0' + color : color    rgb.push(color)  }  return '#' + rgb.join('')}Page({  onReady (res) {    this.videoContext = wx.createVideoContext('myVideo')  },  inputValue: '',  bindInputBlur (e) {    this.inputValue = e.detail.value  },  bindSendDanmu () {    this.videoContext.sendDanmu({      text: this.inputValue,      color: getRandomColor()    })  }})


                      wx.stopVoice(Object object)

                      从基础库 1.6.0 开始,本接口停止维护,请使用 wx.createInnerAudioContext 代替

                      结束播放语音。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.startRecord({  success (res) {    const tempFilePath = res.tempFilePath    wx.playVoice({      filePath: tempFilePath,    })    setTimeout(() => { wx.stopVoice() }, 5000)  }})


                      wx.setInnerAudioOption(Object object)

                      基础库 2.3.0 开始支持,低版本需做兼容处理。

                      设置 InnerAudioContext 的播放选项。设置之后对当前小程序全局生效。

                      参数

                      Object object

                      属性类型默认值必填说明
                      mixWithOtherbooleantrue是否与其他音频混播,设置为 true 之后,不会终止其他应用或微信内的音乐
                      obeyMuteSwitchbooleantrue(仅在 iOS 生效)是否遵循静音开关,设置为 false 之后,即使是在静音模式下,也能播放声音
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      相关回答


                      wx.playVoice(Object object)

                      从基础库 1.6.0 开始,本接口停止维护,请使用 wx.createInnerAudioContext 代替

                      开始播放语音。同时只允许一个语音文件正在播放,如果前一个语音文件还没播放完,将中断前一个语音播放。

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      filePathstring需要播放的语音文件的文件路径 (本地路径)
                      durationnumber60指定录音时长,到达指定的录音时长后会自动停止录音,单位:秒1.6.0
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.startRecord({  success (res) {    const tempFilePath = res.tempFilePath    wx.playVoice({      filePath: tempFilePath,      complete () { }    })  }})


                      wx.pauseVoice(Object object)

                      从基础库 1.6.0 开始,本接口停止维护,请使用 wx.createInnerAudioContext 代替

                      暂停正在播放的语音。再次调用 wx.playVoice 播放同一个文件时,会从暂停处开始播放。如果想从头开始播放,需要先调用 wx.stopVoice。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.startRecord({  success (res) {    const tempFilePath = res.tempFilePath    wx.playVoice({      filePath: tempFilePath    })    setTimeout(() => { wx.pauseVoice() }, 5000)  }})


                      wx.getAvailableAudioSources(Object object)

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

                      获取当前支持的音频输入源

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      audioSourcesArray.<string>支持的音频输入源列表,可在 RecorderManager.start() 接口中使用。返回值定义参考 https://developer.android.com/reference/kotlin/android/media/MediaRecorder.AudioSource

                      res.audioSources 的合法值

                      说明最低版本
                      auto自动设置,默认使用手机麦克风,插上耳麦后自动切换使用耳机麦克风,所有平台适用
                      buildInMic手机麦克风,仅限 iOS
                      headsetMic耳机麦克风,仅限 iOS
                      mic麦克风(没插耳麦时是手机麦克风,插耳麦时是耳机麦克风),仅限 Android
                      camcorder同 mic,适用于录制音视频内容,仅限 Android
                      voice_communication同 mic,适用于实时沟通,仅限 Android
                      voice_recognition同 mic,适用于语音识别,仅限 Android




                      InnerAudioContext wx.createInnerAudioContext()

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

                      创建内部 audio 上下文 InnerAudioContext 对象。

                      返回值

                      InnerAudioContext


                      AudioContext wx.createAudioContext(string id, Object this)

                      从基础库 1.6.0 开始,本接口停止维护,请使用 wx.createInnerAudioContext 代替

                      创建 audio 上下文 AudioContext 对象。

                      参数

                      string id

                      audio 组件的 id

                      Object this

                      在自定义组件下,当前组件实例的this,以操作组件内 audio 组件

                      返回值

                      AudioContext


                      InnerAudioContext

                      InnerAudioContext 实例,可通过 wx.createInnerAudioContext 接口获取实例。



                      属性


                      string src

                      音频资源的地址,用于直接播放。2.2.3 开始支持云文件ID


                      number startTime

                      开始播放的位置(单位:s),默认为 0


                      boolean autoplay

                      是否自动开始播放,默认为 false


                      boolean loop

                      是否循环播放,默认为 false


                      boolean obeyMuteSwitch

                      是否遵循系统静音开关,默认为 true。当此参数为 false 时,即使用户打开了静音开关,也能继续发出声音。从 2.3.0 版本开始此参数不生效,使用 wx.setInnerAudioOption 接口统一设置。


                      number volume

                      音量。范围 0~1。默认为 1


                      number playbackRate

                      播放速度。范围 0.5-2.0,默认为 1。(Android 需要 6 及以上版本)


                      number duration

                      当前音频的长度(单位 s)。只有在当前有合法的 src 时返回(只读)


                      number currentTime

                      当前音频的播放位置(单位 s)。只有在当前有合法的 src 时返回,时间保留小数点后 6 位(只读)


                      boolean paused

                      当前是是否暂停或停止状态(只读)


                      number buffered

                      音频缓冲的时间点,仅保证当前播放时间点到此时间点内容已缓冲(只读)



                      方法:

                      InnerAudioContext.destroy()

                      销毁当前实例


                      InnerAudioContext.offCanplay(function callback)

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

                      取消监听音频进入可以播放状态的事件

                      参数

                      function callback

                      音频进入可以播放状态的事件的回调函数



                      InnerAudioContext.offEnded(function callback)

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

                      取消监听音频自然播放至结束的事件

                      参数

                      function callback

                      音频自然播放至结束的事件的回调函数


                      InnerAudioContext.offError(function callback)

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

                      取消监听音频播放错误事件

                      参数

                      function callback

                      音频播放错误事件的回调函数


                      InnerAudioContext.offPause(function callback)

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

                      取消监听音频暂停事件

                      参数

                      function callback

                      音频暂停事件的回调函数


                      InnerAudioContext.offPlay(function callback)

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

                      取消监听音频播放事件

                      参数

                      function callback

                      音频播放事件的回调函数


                      InnerAudioContext.offSeeked(function callback)

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

                      取消监听音频完成跳转操作的事件

                      参数

                      function callback

                      音频完成跳转操作的事件的回调函数


                      InnerAudioContext.offSeeking(function callback)

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

                      取消监听音频进行跳转操作的事件

                      参数

                      function callback

                      音频进行跳转操作的事件的回调函数


                      InnerAudioContext.offStop(function callback)

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

                      取消监听音频停止事件

                      参数

                      function callback

                      音频停止事件的回调函数


                      InnerAudioContext.offTimeUpdate(function callback)

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

                      取消监听音频播放进度更新事件

                      参数

                      function callback

                      音频播放进度更新事件的回调函数


                      InnerAudioContext.offWaiting(function callback)

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

                      取消监听音频加载中事件

                      参数

                      function callback

                      音频加载中事件的回调函数


                      InnerAudioContext.onCanplay(function callback)

                      监听音频进入可以播放状态的事件。但不保证后面可以流畅播放

                      参数

                      function callback

                      音频进入可以播放状态的事件的回调函数


                      InnerAudioContext.onEnded(function callback)

                      监听音频自然播放至结束的事件

                      参数

                      function callback

                      音频自然播放至结束的事件的回调函数


                      InnerAudioContext.onError(function callback)

                      监听音频播放错误事件

                      参数

                      function callback

                      音频播放错误事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      errMsgstring
                      errCodenumber

                      errCode 的合法值

                      说明最低版本
                      10001系统错误
                      10002网络错误
                      10003文件错误
                      10004格式错误
                      -1未知错误


                      InnerAudioContext.onPause(function callback)

                      监听音频暂停事件

                      参数

                      function callback

                      音频暂停事件的回调函数


                      InnerAudioContext.onPlay(function callback)

                      监听音频播放事件

                      参数

                      function callback

                      音频播放事件的回调函数


                      InnerAudioContext.onSeeked(function callback)

                      监听音频完成跳转操作的事件

                      参数

                      function callback

                      音频完成跳转操作的事件的回调函数


                      InnerAudioContext.onSeeking(function callback)

                      监听音频进行跳转操作的事件

                      参数

                      function callback

                      音频进行跳转操作的事件的回调函数


                      InnerAudioContext.onStop(function callback)

                      监听音频停止事件

                      参数

                      function callback

                      音频停止事件的回调函数


                      InnerAudioContext.onTimeUpdate(function callback)

                      监听音频播放进度更新事件

                      参数

                      function callback

                      音频播放进度更新事件的回调函数


                      InnerAudioContext.onWaiting(function callback)

                      监听音频加载中事件。当音频因为数据不足,需要停下来加载时会触发

                      参数

                      function callback

                      音频加载中事件的回调函数


                      InnerAudioContext.pause()

                      暂停。暂停后的音频再播放会从暂停处开始播放



                      InnerAudioContext.play()

                      播放


                      InnerAudioContext.seek(number position)

                      跳转到指定位置

                      参数

                      number position

                      跳转的时间,单位 s。精确到小数点后 3 位,即支持 ms 级别精确度


                      InnerAudioContext.stop()

                      停止。停止后的音频再播放会从头开始播放。



                      支持格式

                      格式iOSAndroid
                      flacx
                      m4a
                      oggx
                      apex
                      amrx
                      wmax
                      wav
                      mp3
                      mp4x
                      aac
                      aiffx
                      cafx

                      示例代码:

                      const innerAudioContext = wx.createInnerAudioContext()innerAudioContext.autoplay = trueinnerAudioContext.src = 'http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E061FF02C31F716658E5C81F5594D561F2E88B854E81CAAB7806D5E4F103E55D33C16F3FAC506D1AB172DE8600B37E43FAD&fromtag=46'innerAudioContext.onPlay(() => {  console.log('开始播放')})innerAudioContext.onError((res) => {  console.log(res.errMsg)  console.log(res.errCode)})


                      AudioContext

                      AudioContext 实例,可通过 wx.createAudioContext 获取。

                      AudioContext 通过 id 跟一个 audio 组件绑定,操作对应的 audio 组件。


                      方法:

                      AudioContext.pause()

                      暂停音频。


                      AudioContext.play()

                      播放音频。


                      AudioContext.seek(number position)

                      跳转到指定位置。

                      参数

                      number position

                      跳转位置,单位 s


                      AudioContext.setSrc(string src)

                      设置音频地址

                      参数

                      string src

                      音频地址


                      示例代码:

                      <!-- audio.wxml --><audio  src="{{src}}" id="myAudio" ></audio><button type="primary" bindtap="audioPlay">播放</button><button type="primary" bindtap="audioPause">暂停</button><button type="primary" bindtap="audio14">设置当前播放时间为14秒</button><button type="primary" bindtap="audioStart">回到开头</button>
                      // audio.jsPage({  onReady (e) {    // 使用 wx.createAudioContext 获取 audio 上下文 context    this.audioCtx = wx.createAudioContext('myAudio')    this.audioCtx.setSrc('http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E06DCBDC9AB7C49FD713D632D313AC4858BACB8DDD29067D3C601481D36E62053BF8DFEAF74C0A5CCFADD6471160CAF3E6A&fromtag=46')    this.audioCtx.play()  },  data: {    src: ''  },  audioPlay () {    this.audioCtx.play()  },  audioPause () {    this.audioCtx.pause()  },  audio14 () {    this.audioCtx.seek(14)  },  audioStart () {    this.audioCtx.seek(0)  }})


                      wx.stopBackgroundAudio(Object object)

                      从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

                      停止播放音乐。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.stopBackgroundAudio()


                      wx.seekBackgroundAudio(Object object)

                      从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

                      控制音乐播放进度。

                      参数

                      Object object

                      属性类型默认值必填说明
                      positionnumber音乐位置,单位:秒
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.seekBackgroundAudio({  position: 30})


                      wx.playBackgroundAudio(Object object)

                      从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

                      使用后台播放器播放音乐。对于微信客户端来说,只能同时有一个后台音乐在播放。当用户离开小程序后,音乐将暂停播放;当用户在其他小程序占用了音乐播放器,原有小程序内的音乐将停止播放。

                      参数

                      Object object

                      属性类型默认值必填说明
                      dataUrlstring音乐链接,目前支持的格式有 m4a, aac, mp3, wav
                      titlestring音乐标题
                      coverImgUrlstring封面URL
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.playBackgroundAudio({  dataUrl: '',  title: '',  coverImgUrl: ''})


                      wx.pauseBackgroundAudio(Object object)

                      从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

                      暂停播放音乐。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.pauseBackgroundAudio()


                      wx.onBackgroundAudioStop(function callback)

                      从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

                      监听音乐停止事件。

                      参数

                      function callback

                      音乐停止事件的回调函数


                      wx.onBackgroundAudioPlay(function callback)

                      从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

                      监听音乐播放事件。

                      参数

                      function callback

                      音乐播放事件的回调函数


                      wx.onBackgroundAudioPause(function callback)

                      从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

                      监听音乐暂停事件。

                      参数

                      function callback

                      音乐暂停事件的回调函数


                      wx.getBackgroundAudioPlayerState(Object object)

                      从基础库 1.2.0 开始,本接口停止维护,请使用 wx.getBackgroundAudioManager 代替

                      获取后台音乐播放状态。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      durationnumber选定音频的长度(单位:s),只有在音乐播放中时返回
                      currentPositionnumber选定音频的播放位置(单位:s),只有在音乐播放中时返回
                      statusnumber播放状态
                      downloadPercentnumber音频的下载进度百分比,只有在音乐播放中时返回
                      dataUrlstring歌曲数据链接,只有在音乐播放中时返回

                      res.status 的合法值

                      说明最低版本
                      0暂停中
                      1播放中
                      2没有音乐播放

                      示例代码

                      wx.getBackgroundAudioPlayerState({  success (res) {    const status = res.status    const dataUrl = res.dataUrl    const currentPosition = res.currentPosition    const duration = res.duration    const downloadPercent = res.downloadPercent  }})


                      BackgroundAudioManager wx.getBackgroundAudioManager()

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

                      获取全局唯一的背景音频管理器。 小程序切入后台,如果音频处于播放状态,可以继续播放。但是后台状态不能通过调用API操纵音频的播放状态。

                      从微信客户端6.7.2版本开始,若需要在小程序切后台后继续播放音频,需要在 app.json 中配置 requiredBackgroundModes 属性。开发版和体验版上可以直接生效,正式版还需通过审核。

                      返回值

                      BackgroundAudioManager


                      BackgroundAudioManager

                      BackgroundAudioManager 实例,可通过 wx.getBackgroundAudioManager 获取。

                      属性

                      string src

                      音频的数据源(2.2.3 开始支持云文件ID)。默认为空字符串,当设置了新的 src 时,会自动开始播放,目前支持的格式有 m4a, aac, mp3, wav。


                      number startTime

                      音频开始播放的位置(单位:s)。


                      string title

                      音频标题,用于原生音频播放器音频标题(必填)。原生音频播放器中的分享功能,分享出去的卡片标题,也将使用该值。


                      string epname

                      专辑名,原生音频播放器中的分享功能,分享出去的卡片简介,也将使用该值。


                      string singer

                      歌手名,原生音频播放器中的分享功能,分享出去的卡片简介,也将使用该值。


                      string coverImgUrl

                      封面图 URL,用于做原生音频播放器背景图。原生音频播放器中的分享功能,分享出去的卡片配图及背景也将使用该图。


                      string webUrl

                      页面链接,原生音频播放器中的分享功能,分享出去的卡片简介,也将使用该值。


                      string protocol

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

                      音频协议。默认值为 'http',设置 'hls' 可以支持播放 HLS 协议的直播音频。


                      number playbackRate

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

                      播放速度。范围 0.5-2.0,默认为 1。(Android 需要 6 及以上版本)


                      number duration

                      当前音频的长度(单位:s),只有在有合法 src 时返回。(只读)


                      number currentTime

                      当前音频的播放位置(单位:s),只有在有合法 src 时返回。(只读)


                      boolean paused

                      当前是否暂停或停止。(只读)


                      number buffered

                      音频已缓冲的时间,仅保证当前播放时间点到此时间点内容已缓冲。(只读)



                      方法:

                      BackgroundAudioManager.onCanplay(function callback)

                      监听背景音频进入可播放状态事件。 但不保证后面可以流畅播放

                      参数

                      function callback

                      背景音频进入可播放状态事件的回调函数


                      BackgroundAudioManager.onEnded(function callback)

                      监听背景音频自然播放结束事件

                      参数

                      function callback

                      背景音频自然播放结束事件的回调函数


                      BackgroundAudioManager.onError(function callback)

                      监听背景音频播放错误事件

                      参数

                      function callback

                      背景音频播放错误事件的回调函数


                      BackgroundAudioManager.onNext(function callback)

                      监听用户在系统音乐播放面板点击下一曲事件(仅iOS)

                      参数

                      function callback

                      用户在系统音乐播放面板点击下一曲事件的回调函数


                      BackgroundAudioManager.onPause(function callback)

                      监听背景音频暂停事件

                      参数

                      function callback

                      背景音频暂停事件的回调函数


                      BackgroundAudioManager.onPlay(function callback)

                      监听背景音频播放事件

                      参数

                      function callback

                      背景音频播放事件的回调函数


                      BackgroundAudioManager.onPrev(function callback)

                      监听用户在系统音乐播放面板点击上一曲事件(仅iOS)

                      参数

                      function callback

                      用户在系统音乐播放面板点击上一曲事件的回调函数


                      BackgroundAudioManager.onSeeked(function callback)

                      监听背景音频完成跳转操作事件

                      参数

                      function callback

                      背景音频完成跳转操作事件的回调函数


                      BackgroundAudioManager.onSeeking(function callback)

                      监听背景音频开始跳转操作事件

                      参数

                      function callback

                      背景音频开始跳转操作事件的回调函数


                      BackgroundAudioManager.onStop(function callback)

                      监听背景音频停止事件

                      参数

                      function callback

                      背景音频停止事件的回调函数


                      BackgroundAudioManager.onTimeUpdate(function callback)

                      监听背景音频播放进度更新事件,只有小程序在前台时会回调。

                      参数

                      function callback

                      背景音频播放进度更新事件的回调函数


                      BackgroundAudioManager.onWaiting(function callback)

                      监听音频加载中事件。当音频因为数据不足,需要停下来加载时会触发

                      参数

                      function callback

                      音频加载中事件的回调函数



                      BackgroundAudioManager.pause()

                      暂停音乐

                      错误

                      错误码错误信息说明
                      10001系统错误
                      10002网络错误
                      10003文件错误
                      10004格式错误
                      -1未知错误



                      BackgroundAudioManager.play()

                      播放音乐

                      错误

                      错误码错误信息说明
                      10001系统错误
                      10002网络错误
                      10003文件错误
                      10004格式错误
                      -1未知错误



                      BackgroundAudioManager.seek(number currentTime)

                      跳转到指定位置

                      参数

                      number currentTime

                      跳转的位置,单位 s。精确到小数点后 3 位,即支持 ms 级别精确度

                      错误

                      错误码错误信息说明
                      10001系统错误
                      10002网络错误
                      10003文件错误
                      10004格式错误
                      -1未知错误



                      BackgroundAudioManager.stop()

                      停止音乐

                      错误

                      错误码错误信息说明
                      10001系统错误
                      10002网络错误
                      10003文件错误
                      10004格式错误
                      -1未知错误

                      示例代码

                      const backgroundAudioManager = wx.getBackgroundAudioManager()backgroundAudioManager.title = '此时此刻'backgroundAudioManager.epname = '此时此刻'backgroundAudioManager.singer = '许巍'backgroundAudioManager.coverImgUrl = 'http://y.gtimg.cn/music/photo_new/T002R300x300M000003rsKF44GyaSk.jpg?max_age=2592000'// 设置了 src 之后会自动播放backgroundAudioManager.src = 'http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E061FF02C31F716658E5C81F5594D561F2E88B854E81CAAB7806D5E4F103E55D33C16F3FAC506D1AB172DE8600B37E43FAD&fromtag=46'


                      LivePusherContext wx.createLivePusherContext()

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

                      创建 live-pusher 上下文 LivePusherContext 对象。

                      返回值

                      LivePusherContext


                      LivePlayerContext wx.createLivePlayerContext(string id, Object this)

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

                      创建 live-player 上下文 LivePlayerContext 对象。

                      参数

                      string id

                      live-player 组件的 id

                      Object this

                      在自定义组件下,当前组件实例的this,以操作组件内 live-player 组件

                      返回值

                      LivePlayerContext


                      LivePlayerContext

                      LivePlayerContext 实例,可通过 wx.createLivePlayerContext 获取。

                      LivePlayerContext 通过 id 跟一个 live-player 组件绑定,操作对应的 live-player 组件。



                      方法:

                      LivePlayerContext.exitFullScreen(Object object)

                      退出全屏

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePlayerContext.exitPictureInPicture(Object object)

                      退出小窗,该方法可在任意页面调用

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePlayerContext.mute(Object object)

                      静音

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePlayerContext.pause(Object object)

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

                      暂停

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePlayerContext.play(Object object)

                      播放

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePlayerContext.requestFullScreen(Object object)

                      进入全屏

                      参数

                      Object object

                      属性类型默认值必填说明
                      directionnumber0设置全屏时的方向
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.direction 的合法值

                      说明最低版本
                      0正常竖向
                      90屏幕逆时针90度
                      -90屏幕顺时针90度


                      LivePlayerContext.resume(Object object)

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

                      恢复

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePlayerContext.snapshot(string quality)

                      基础库 2.7.1 开始支持,低版本需做兼容处理。

                      截图

                      参数

                      string quality

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

                      图片的质量,默认原图。有效值为 raw、compressed


                      LivePlayerContext.stop(Object object)

                      停止

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext 实例,可通过 wx.createLivePusherContext 获取。

                      LivePusherContext 与页面内唯一的 live-pusher 组件绑定,操作对应的 live-pusher 组件。



                      方法:


                      LivePusherContext.pause(Object object)

                      暂停推流

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.pauseBGM(Object object)

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

                      暂停背景音

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.playBGM(Object object)

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

                      播放背景音

                      参数

                      Object object

                      属性类型默认值必填说明
                      urlstring加入背景混音的资源地址
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.resume(Object object)

                      恢复推流

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.resumeBGM(Object object)

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

                      恢复背景音

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.setBGMVolume(Object object)

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

                      设置背景音音量

                      参数

                      Object object

                      属性类型默认值必填说明
                      volumestring音量大小,范围是 0-1
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.setMICVolume(Object object)

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

                      设置麦克风音量

                      参数

                      Object object

                      属性类型默认值必填说明
                      volumenumber音量大小,范围是 0.0-1.0
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.snapshot(string quality)

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

                      快照

                      参数

                      string quality

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

                      图片的质量,默认原图。有效值为 raw、compressed


                      LivePusherContext.start(Object object)

                      开始推流,同时开启摄像头预览

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.startPreview(Object object)

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

                      开启摄像头预览

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.stop(Object object)

                      停止推流,同时停止摄像头预览

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.stopBGM(Object object)

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

                      停止背景音

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.stopPreview(Object object)

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

                      关闭摄像头预览

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.switchCamera(Object object)

                      切换前后摄像头

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      LivePusherContext.toggleTorch(Object object)

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

                      切换手电筒

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      wx.startRecord(Object object)

                      调用前需要 用户授权 scope.record
                      从基础库 1.6.0 开始,本接口停止维护,请使用 wx.getRecorderManager 代替

                      开始录音。当主动调用 wx.stopRecord,或者录音超过1分钟时自动结束录音。当用户离开小程序时,此接口无法调用。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      tempFilePathstring录音文件的临时路径 (本地路径)

                      示例代码

                      wx.startRecord({  success (res) {    const tempFilePath = res.tempFilePath  }})setTimeout(function () {  wx.stopRecord() // 结束录音}, 10000)


                      wx.stopRecord(Object object)

                      从基础库 1.6.0 开始,本接口停止维护,请使用 wx.getRecorderManager 代替

                      停止录音。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.startRecord({  success (res) {    const tempFilePath = res.tempFilePath  }})setTimeout(function () {  wx.stopRecord() // 结束录音}, 10000)


                      RecorderManager wx.getRecorderManager()

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

                      获取全局唯一的录音管理器 RecorderManager

                      返回值

                      RecorderManager


                      RecorderManager

                      全局唯一的录音管理器


                      方法:

                      RecorderManager.onError(function callback)

                      监听录音错误事件

                      参数

                      function callback

                      录音错误事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      errMsgstring错误信息


                      RecorderManager.onFrameRecorded(function callback)

                      监听已录制完指定帧大小的文件事件。如果设置了 frameSize,则会回调此事件。

                      参数

                      function callback

                      已录制完指定帧大小的文件事件的兼容处理

                      参数

                      Object res
                      属性类型说明
                      frameBufferArrayBuffer录音分片数据
                      isLastFrameboolean当前帧是否正常录音结束前的最后一帧


                      RecorderManager.onInterruptionBegin(function callback)

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

                      监听录音因为受到系统占用而被中断开始事件。以下场景会触发此事件:微信语音聊天、微信视频聊天。此事件触发后,录音会被暂停。pause 事件在此事件后触发

                      参数

                      function callback

                      录音因为受到系统占用而被中断开始事件的回调函数


                      RecorderManager.onInterruptionEnd(function callback)

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

                      监听录音中断结束事件。在收到 interruptionBegin 事件之后,小程序内所有录音会暂停,收到此事件之后才可再次录音成功。

                      参数

                      function callback

                      录音中断结束事件的回调函数


                      RecorderManager.onPause(function callback)

                      监听录音暂停事件

                      参数

                      function callback

                      录音暂停事件的回调函数


                      RecorderManager.onResume(function callback)

                      监听录音继续事件

                      参数

                      function callback

                      录音继续事件的回调函数


                      RecorderManager.onStart(function callback)

                      监听录音开始事件

                      参数

                      function callback

                      录音开始事件的回调函数


                      RecorderManager.onStop(function callback)

                      监听录音结束事件

                      参数

                      function callback

                      录音结束事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      tempFilePathstring录音文件的临时路径 (本地路径)
                      durationnumber录音总时长,单位:ms
                      fileSizenumber录音文件大小,单位:Byte


                      RecorderManager.pause()

                      暂停录音


                      RecorderManager.resume()

                      继续录音


                      RecorderManager.start(Object object)

                      开始录音

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      durationnumber60000录音的时长,单位 ms,最大值 600000(10 分钟)
                      sampleRatenumber8000采样率
                      numberOfChannelsnumber2录音通道数
                      encodeBitRatenumber48000编码码率,有效值见下表格
                      formatstringaac音频格式
                      frameSizenumber指定帧大小,单位 KB。传入 frameSize 后,每录制指定帧大小的内容后,会回调录制的文件内容,不指定则不会回调。暂仅支持 mp3 格式。
                      audioSourcestringauto指定录音的音频输入源,可通过 wx.getAvailableAudioSources() 获取当前可用的音频源2.1.0

                      object.sampleRate 的合法值

                      说明最低版本
                      80008000 采样率
                      1102511025 采样率
                      1200012000 采样率
                      1600016000 采样率
                      2205022050 采样率
                      2400024000 采样率
                      3200032000 采样率
                      4410044100 采样率
                      4800048000 采样率

                      object.numberOfChannels 的合法值

                      说明最低版本
                      11 个通道
                      22 个通道

                      object.format 的合法值

                      说明最低版本
                      mp3mp3 格式
                      aacaac 格式
                      wavwav 格式
                      PCMpcm 格式

                      object.audioSource 的合法值

                      说明最低版本
                      auto自动设置,默认使用手机麦克风,插上耳麦后自动切换使用耳机麦克风,所有平台适用
                      buildInMic手机麦克风,仅限 iOS
                      headsetMic耳机麦克风,仅限 iOS
                      mic麦克风(没插耳麦时是手机麦克风,插耳麦时是耳机麦克风),仅限 Android
                      camcorder同 mic,适用于录制音视频内容,仅限 Android
                      voice_communication同 mic,适用于实时沟通,仅限 Android
                      voice_recognition同 mic,适用于语音识别,仅限 Android

                      采样率与编码码率限制

                      每种采样率有对应的编码码率范围有效值,设置不合法的采样率或编码码率会导致录音失败,具体对应关系如下表。

                      采样率编码码率
                      800016000 ~ 48000
                      1102516000 ~ 48000
                      1200024000 ~ 64000
                      1600024000 ~ 96000
                      2205032000 ~ 128000
                      2400032000 ~ 128000
                      3200048000 ~ 192000
                      4410064000 ~ 320000
                      4800064000 ~ 320000


                      RecorderManager.stop()

                      停止录音



                      示例代码

                      const recorderManager = wx.getRecorderManager()recorderManager.onStart(() => {  console.log('recorder start')})recorderManager.onPause(() => {  console.log('recorder pause')})recorderManager.onStop((res) => {  console.log('recorder stop', res)  const { tempFilePath } = res})recorderManager.onFrameRecorded((res) => {  const { frameBuffer } = res  console.log('frameBuffer.byteLength', frameBuffer.byteLength)})const options = {  duration: 10000,  sampleRate: 44100,  numberOfChannels: 1,  encodeBitRate: 192000,  format: 'aac',  frameSize: 50}recorderManager.start(options)


                      CameraContext wx.createCameraContext()

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

                      创建 camera 上下文 CameraContext 对象。

                      返回值

                      CameraContext


                      CameraContext

                      CameraContext 实例,可通过 wx.createCameraContext 获取。

                      CameraContext 与页面内唯一的 camera 组件绑定,操作对应的 camera 组件。



                      方法:

                      CameraFrameListener CameraContext.onCameraFrame(function callback)

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

                      获取 Camera 实时帧数据

                      参数

                      function callback

                      回调函数

                      参数

                      Object res
                      属性类型说明
                      widthnumber图像数据矩形的宽度
                      heightnumber图像数据矩形的高度
                      dataArrayBuffer图像像素点数据,一维数组,每四项表示一个像素点的 rgba

                      返回值

                      CameraFrameListener

                      注: 使用该接口需同时在 camera 组件属性中指定 frame-size。

                      示例代码

                      const context = wx.createCameraContext()const listener = context.onCameraFrame((frame) => {  console.log(frame.data instanceof ArrayBuffer, frame.width, frame.height)})listener.start()


                      CameraContext.setZoom(Object object)

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

                      设置缩放级别

                      参数

                      Object object

                      属性类型默认值必填说明
                      zoomnumber缩放级别,范围[1, maxZoom]。zoom 可取小数,精确到小数后一位。maxZoom 可在 bindinitdone 返回值中获取。
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      zoomnumber实际设置的缩放级别。由于系统限制,某些机型可能无法设置成指定值,会改用最接近的可设值。


                      CameraContext.startRecord(Object object)

                      开始录像

                      参数

                      Object object

                      属性类型默认值必填说明
                      timeoutCallbackfunction超过30s或页面 onHide 时会结束录像
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.timeoutCallback 回调函数

                      参数
                      Object res
                      属性类型说明
                      tempThumbPathstring封面图片文件的临时路径 (本地路径)
                      tempVideoPathstring视频的文件的临时路径 (本地路径)


                      CameraContext.stopRecord(Object object)

                      结束录像

                      参数

                      Object object

                      属性类型默认值必填说明
                      compressedbooleanfalse启动视频压缩,压缩效果同chooseVideo
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      tempThumbPathstring封面图片文件的临时路径 (本地路径)
                      tempVideoPathstring视频的文件的临时路径 (本地路径)


                      CameraContext.takePhoto(Object object)

                      拍摄照片

                      参数

                      Object object

                      属性类型默认值必填说明
                      qualitystringnormal成像质量
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.quality 的合法值

                      说明最低版本
                      high高质量
                      normal普通质量
                      low低质量

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      tempImagePathstring照片文件的临时路径 (本地路径),安卓是jpg图片格式,ios是png


                      CameraFrameListener

                      CameraContext.onCameraFrame() 返回的监听器。


                      方法:

                      CameraFrameListener.start(Object object)

                      开始监听帧数据

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      CameraFrameListener.stop(Object object)

                      停止监听帧数据

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      EditorContext 实例,可通过 wx.createSelectorQuery 获取。

                      EditorContext 通过 id 跟一个 editor 组件绑定,操作对应的 editor 组件。

                      方法:

                      EditorContext.blur(Object object)

                      基础库 2.8.3 开始支持,低版本需做兼容处理。

                      编辑器失焦,同时收起键盘。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.clear(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      清空编辑器内容

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.format(string name, string value)

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      修改样式

                      参数

                      string name

                      属性

                      string value

                      支持设置的样式列表

                      namevalueverson
                      bold2.7.0
                      italic2.7.0
                      underline2.7.0
                      strike2.7.0
                      ins2.7.0
                      scriptsub / super2.7.0
                      headerH1 / H2 / h3 / H4 / h5 / H62.7.0
                      alignleft / center / right / justify2.7.0
                      directionrtl2.7.0
                      indent-1 / +12.7.0
                      listordered / bullet / check2.7.0
                      colorhex color2.7.0
                      backgroundColorhex color2.7.0
                      margin/marginTop/marginBottom/marginLeft/marginRightcss style2.7.0
                      padding/paddingTop/paddingBottom/paddingLeft/paddingRightcss style2.7.0
                      font/fontSize/fontStyle/fontVariant/fontWeight/fontFamilycss style2.7.0
                      lineHeightcss style2.7.0
                      letterSpacingcss style2.7.0
                      textDecorationcss style2.7.0
                      textIndentcss style2.8.0
                      wordWrapcss style2.10.2
                      wordBreakcss style2.10.2
                      whiteSpacecss style2.10.2

                      对已经应用样式的选区设置会取消样式。css style 表示 css 中规定的允许值。


                      EditorContext.getContents(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      获取编辑器内容

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      htmlstring带标签的HTML内容
                      textstring纯文本内容
                      deltaObject表示内容的delta对象


                      EditorContext.getSelectionText(Object object)

                      基础库 2.10.2 开始支持,低版本需做兼容处理。

                      获取编辑器已选区域内的纯文本内容。当编辑器失焦或未选中一段区间时,返回内容为空。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      textstring纯文本内容


                      EditorContext.insertDivider(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      插入分割线

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.insertImage(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      插入图片。

                      地址为临时文件时,获取的编辑器html格式内容中 <img> 标签增加属性 data-local,delta 格式内容中图片 attributes 属性增加 data-local 字段,该值为传入的临时文件地址。

                      开发者可选择在提交阶段上传图片到服务器,获取到网络地址后进行替换。替换时对于html内容应替换掉 <img> 的 src 值,对于 delta 内容应替换掉 insert { image: abc } 值。

                      参数

                      Object object

                      属性类型默认值必填说明
                      srcstring图片地址,仅支持 http(s)、base64、云图片(2.8.0)、临时文件(2.8.3)。
                      altstring图像无法显示时的替代文本
                      widthstring图片宽度(pixels/百分比)
                      heightstring图片高度 (pixels/百分比)
                      extClassstring添加到图片 img 标签上的类名
                      dataObjectdata 被序列化为 name=value;name1=value2 的格式挂在属性 data-custom 上
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      this.editorCtx.insertImage({  src: 'xx',  width: '100px',  height: '50px',  extClass: className})


                      EditorContext.insertText(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      覆盖当前选区,设置一段文本

                      参数

                      Object object

                      属性类型默认值必填说明
                      textstring文本内容
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.redo(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      恢复

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.removeFormat(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      清除当前选区的样式

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.scrollIntoView()

                      基础库 2.8.3 开始支持,低版本需做兼容处理。

                      使得编辑器光标处滚动到窗口可视区域内。


                      EditorContext.setContents(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      初始化编辑器内容,html和delta同时存在时仅delta生效

                      参数

                      Object object

                      属性类型默认值必填说明
                      htmlstring带标签的HTML内容
                      deltaObject表示内容的delta对象
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.undo(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理。

                      撤销

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext

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

                      EditorContext 实例,可通过 wx.createSelectorQuery 获取。

                      EditorContext 通过 id 跟一个 editor 组件绑定,操作对应的 editor 组件。



                      方法:

                      EditorContext.blur(Object object)

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

                      编辑器失焦,同时收起键盘。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.clear(Object object)

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

                      清空编辑器内容

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.format(string name, string value)

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

                      修改样式

                      参数

                      string name

                      属性

                      string value

                      支持设置的样式列表

                      namevalueverson
                      bold2.7.0
                      italic2.7.0
                      underline2.7.0
                      strike2.7.0
                      ins2.7.0
                      scriptsub / super2.7.0
                      headerH1 / H2 / h3 / H4 / h5 / H62.7.0
                      alignleft / center / right / justify2.7.0
                      directionrtl2.7.0
                      indent-1 / +12.7.0
                      listordered / bullet / check2.7.0
                      colorhex color2.7.0
                      backgroundColorhex color2.7.0
                      margin/marginTop/marginBottom/marginLeft/marginRightcss style2.7.0
                      padding/paddingTop/paddingBottom/paddingLeft/paddingRightcss style2.7.0
                      font/fontSize/fontStyle/fontVariant/fontWeight/fontFamilycss style2.7.0
                      lineHeightcss style2.7.0
                      letterSpacingcss style2.7.0
                      textDecorationcss style2.7.0
                      textIndentcss style2.8.0
                      wordWrapcss style2.10.2
                      wordBreakcss style2.10.2
                      whiteSpacecss style2.10.2

                      对已经应用样式的选区设置会取消样式。css style 表示 css 中规定的允许值。


                      EditorContext.getContents(Object object)

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

                      获取编辑器内容

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      htmlstring带标签的HTML内容
                      textstring纯文本内容
                      deltaObject表示内容的delta对象


                      EditorContext.getSelectionText(Object object)

                      基础库 2.10.2 开始支持,低版本需做兼容处理

                      获取编辑器已选区域内的纯文本内容。当编辑器失焦或未选中一段区间时,返回内容为空。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      textstring纯文本内容


                      EditorContext.insertDivider(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      插入分割线

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.insertImage(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      插入图片。

                      地址为临时文件时,获取的编辑器html格式内容中 <img> 标签增加属性 data-local,delta 格式内容中图片 attributes 属性增加 data-local 字段,该值为传入的临时文件地址。

                      开发者可选择在提交阶段上传图片到服务器,获取到网络地址后进行替换。替换时对于html内容应替换掉 <img> 的 src 值,对于 delta 内容应替换掉 insert { image: abc } 值。

                      参数

                      Object object

                      属性类型默认值必填说明
                      srcstring图片地址,仅支持 http(s)、base64、云图片(2.8.0)、临时文件(2.8.3)。
                      altstring图像无法显示时的替代文本
                      widthstring图片宽度(pixels/百分比)
                      heightstring图片高度 (pixels/百分比)
                      extClassstring添加到图片 img 标签上的类名
                      dataObjectdata 被序列化为 name=value;name1=value2 的格式挂在属性 data-custom 上
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      this.editorCtx.insertImage({  src: 'xx',  width: '100px',  height: '50px',  extClass: className})


                      EditorContext.insertText(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      覆盖当前选区,设置一段文本

                      参数

                      Object object

                      属性类型默认值必填说明
                      textstring文本内容
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.redo(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      恢复

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.removeFormat(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      清除当前选区的样式

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.scrollIntoView()

                      基础库 2.8.3 开始支持,低版本需做兼容处理

                      使得编辑器光标处滚动到窗口可视区域内。

                      EditorContext.setContents(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      初始化编辑器内容,html和delta同时存在时仅delta生效

                      参数

                      Object object

                      属性类型默认值必填说明
                      htmlstring带标签的HTML内容
                      deltaObject表示内容的delta对象
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      EditorContext.undo(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      撤销

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      MediaContainer wx.createMediaContainer()

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      创建音视频处理容器,最终可将容器中的轨道合成一个视频

                      返回值

                      MediaContainer


                      MediaContainer

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      可通过 wx.createMediaContainer 创建。

                      MediaContainer 音视频处理容器,可以进行音频混音等操作



                      方法:

                      MediaContainer.addTrack(MediaTrack track)

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      将音频或视频轨道添加到容器

                      参数

                      MediaTrack track

                      要添加的音频或视频轨道


                      MediaContainer.destroy()

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      将容器销毁,释放资源


                      MediaContainer.export()

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      将容器内的轨道合并并导出视频文件


                      MediaContainer.extractDataSource(Object object)

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      将传入的视频源分离轨道。不会自动将轨道添加到待合成的容器里。

                      参数

                      Object object

                      属性类型默认值必填说明
                      sourcestring视频源地址,只支持本地文件


                      MediaContainer.removeTrack(MediaTrack track)

                      基础库 2.9.0 开始支持,低版本需做兼容处理兼容处理

                      将音频或视频轨道从容器中移除

                      参数

                      MediaTrack track

                      要移除的音频或视频轨道



                      MediaTrack

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      可通过 MediaContainer.extractDataSource 返回。

                      MediaTrack 音频或视频轨道,可以对轨道进行一些操作

                      属性

                      string kind

                      轨道类型,只读

                      kind 的合法值

                      说明最低版本
                      audio音频轨道
                      video视频轨道

                      number duration

                      轨道长度,只读

                      number volume

                      音量,音频轨道下有效,可写


                      wx.updateVoIPChatMuteConfig(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      更新实时语音静音设置

                      参数

                      Object object

                      属性类型默认值必填说明
                      muteConfigObject静音设置
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.muteConfig 的结构

                      属性类型默认值必填说明
                      muteMicrophoneBooleanfalse是否静音麦克风
                      muteEarphoneBooleanfalse是否静音耳机


                      wx.onVoIPChatSpeakersChanged(function callback)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      监听实时语音通话成员通话状态变化事件。有成员开始/停止说话时触发回调

                      参数

                      function callback

                      实时语音通话成员通话状态变化事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      openIdListArray.<String>还在实时语音通话中的成员 openId 名单
                      errCodeNumber错误码
                      errMsgString调用结果(错误原因)


                      wx.onVoIPChatMembersChanged(function callback)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      监听实时语音通话成员在线状态变化事件。有成员加入/退出通话时触发回调

                      参数

                      function callback

                      实时语音通话成员在线状态变化事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      openIdListArray.<String>还在实时语音通话中的成员 openId 名单
                      errCodeNumber错误码
                      errMsgString调用结果


                      wx.onVoIPChatInterrupted(function callback)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      监听被动断开实时语音通话事件。包括小游戏切入后端时断开

                      参数

                      function callback

                      被动断开实时语音通话事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      errCodeNumber错误码
                      errMsgString调用结果(错误原因)


                      wx.onOnVoIPVideoMembersChanged(function callback)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      监听实时语音通话成员视频状态变化事件。

                      参数

                      function callback

                      实时语音通话成员视频状态变化事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      openIdListArray.<String>开启视频的成员名单
                      errCodeNumber错误码
                      errMsgString调用结果


                      wx.offVoIPChatMembersChanged(function callback)

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      取消监听实时语音通话成员在线状态变化事件。

                      参数

                      function callback

                      实时语音通话成员在线状态变化事件的回调函数


                      wx.offVoIPChatInterrupted(function callback)

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      取消监听被动断开实时语音通话事件。

                      参数

                      function callback

                      被动断开实时语音通话事件的回调函数


                      wx.offOnVoIPVideoMembersChanged(function callback)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      取消监听实时语音通话成员视频状态变化事件

                      参数

                      function callback

                      实时语音通话成员视频状态变化事件的回调函数


                      wx.joinVoIPChat(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理
                      调用前需要 用户授权 scope.record

                      加入 (创建) 实时语音通话,更多信息可见 实时语音指南

                      参数

                      Object object

                      属性类型默认值必填说明
                      roomTypeStringvoice房间类型
                      signatureString签名,用于验证小游戏的身份
                      nonceStrString验证所需的随机字符串
                      timeStampNumber验证所需的时间戳
                      groupIdString小游戏内此房间/群聊的 ID。同一时刻传入相同 groupId 的用户会进入到同个实时语音房间。
                      muteConfigObject静音设置
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.roomType 的合法值

                      说明最低版本
                      voice音频房间,用于语音通话
                      video视频房间,结合 voip-room 组件可显示成员画面

                      object.muteConfig 的结构

                      属性类型默认值必填说明
                      muteMicrophoneBooleanfalse是否静音麦克风
                      muteEarphoneBooleanfalse是否静音耳机

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      openIdListArray.<String>在此通话中的成员 openId 名单
                      errCodeNumber错误码
                      errMsgString调用结果

                      错误

                      错误码错误信息说明
                      -1当前已在房间内
                      -2录音设备被占用,可能是当前正在使用微信内语音通话或系统通话
                      -3加入会话期间退出(可能是用户主动退出,或者退后台、来电等原因),因此加入失败
                      -1000系统错误


                      wx.exitVoIPChat(Object object)

                      基础库 2.7.0 开始支持,低版本需做兼容处理

                      退出(销毁)实时语音通话

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      MediaRecorder wx.createMediaRecorder(Object canvas, Object options)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      创建 WebGL 画面录制器,可逐帧录制在 WebGL 上渲染的画面并导出视频文件

                      参数

                      Object canvas

                      WebGL 对象,通过 SelectorQuery 获取到的 node 对象

                      Object options

                      属性类型默认值必填说明
                      durationnumber600指定录制的时长(s),到达自动停止。最大 7200,最小 5
                      videoBitsPerSecondnumber1000视频比特率(kbps),最小值 600,最大值 3000
                      gopnumber12视频关键帧间隔
                      fpsnumber24视频 fps

                      返回值

                      MediaRecorder


                      MediaRecorder

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      可通过 wx.createMediaRecorder 创建。

                      MediaRecorder WebGL 画面录制器,可以进行录制相关操作,在结束录制时导出视频文件



                      方法:

                      MediaRecorder.destroy()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      销毁录制器


                      MediaRecorder.off(string eventName, function callback)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      取消监听录制事件。当对应事件触发时,该回调函数不再执行。

                      参数

                      string eventName

                      事件名

                      function callback

                      事件触发时执行的回调函数


                      MediaRecorder.on(string eventName, function callback)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      注册监听录制事件的回调函数。当对应事件触发时,回调函数会被执行。

                      参数

                      string eventName

                      事件名

                      eventName 的合法值

                      说明最低版本
                      start录制开始事件。
                      stop录制结束事件。返回 {tempFilePath, duration, fileSize}

                      function callback

                      事件触发时执行的回调函数


                      MediaRecorder.pause()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      暂停录制


                      MediaRecorder.requestFrame(function callback)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      请求下一帧录制,在 callback 里完成一帧渲染后开始录制当前帧

                      参数

                      function callback


                      MediaRecorder.resume()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      恢复录制


                      MediaRecorder.start()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      开始录制


                      MediaRecorder.stop()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      结束录制


                      VideoDecoder wx.createVideoDecoder()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      创建视频解码器,可逐帧获取解码后的数据

                      返回值

                      VideoDecoder


                      VideoDecoder

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      可通过 wx.createVideoDecoder 创建。

                      VideoDecoder 视频解码器,可以进行视频解码相关操作,逐帧获取解码数据



                      方法:

                      Object VideoDecoder.getFrameData()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      获取下一帧的解码数据

                      返回值

                      Object

                      视频帧数据,若取不到则返回 null。当缓冲区为空的时候可能暂停取不到数据。

                      属性类型说明
                      widthnumber帧数据宽度
                      heightnumber帧数据高度
                      dataArrayBuffer帧数据
                      pkPtsnumber帧原始 pts
                      pkDtsnumber帧原始 dts


                      VideoDecoder.off(string eventName, function callback)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      取消监听录制事件。当对应事件触发时,该回调函数不再执行

                      参数

                      string eventName

                      事件名

                      function callback

                      事件触发时执行的回调函数


                      VideoDecoder.on(string eventName, function callback)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      注册监听录制事件的回调函数。当对应事件触发时,回调函数会被执行

                      参数

                      string eventName

                      事件名

                      eventName 的合法值

                      说明最低版本
                      start开始事件。返回 {width, height}
                      stop结束事件。
                      seekseek 完成事件。
                      bufferchange缓冲区变化事件。
                      ended解码结束事件。

                      function callback

                      事件触发时执行的回调函数


                      VideoDecoder.remove()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      移除解码器


                      VideoDecoder.seek(number position)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      跳到某个时间点解码

                      参数

                      number position

                      跳转的解码位置,单位 ms


                      VideoDecoder.start(Object object)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      开始解码

                      参数

                      Object object

                      属性类型默认值必填说明
                      sourcestring需要解码的视频源文件,只支持本地路径
                      modenumber1解码模式。0:按 pts 解码;1:以最快速度解码


                      VideoDecoder.stop()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      停止解码


                      wx.saveFileToDisk(Object object)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      保存文件系统的文件到用户磁盘,仅在 PC 端支持

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring待保存文件路径
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      wx.saveFile(Object object)

                      保存文件到本地。注意:saveFile 会把临时文件移动,因此调用成功后传入的 tempFilePath 将不可用

                      参数

                      Object object

                      属性类型默认值必填说明
                      tempFilePathstring需要保存的文件的临时路径 (本地路径)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      savedFilePathnumber存储后的文件路径 (本地路径)

                      示例代码

                      wx.chooseImage({  success: function(res) {    const tempFilePaths = res.tempFilePaths    wx.saveFile({      tempFilePath: tempFilePaths[0],      success (res) {        const savedFilePath = res.savedFilePath      }    })  }})

                      注意

                      本地文件存储的大小限制为 10M


                      wx.removeSavedFile(Object object)

                      删除本地缓存文件

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring需要删除的文件路径 (本地路径)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.getSavedFileList({ success (res) {   if (res.fileList.length > 0){     wx.removeSavedFile({       filePath: res.fileList[0].filePath,       complete (res) {         console.log(res)       }     })   } }})


                      wx.openDocument(Object object)

                      删除本地缓存文件。微信客户端 7.0.12 版本前默认显示右上角菜单按钮,之后的版本默认不显示,需主动传入 showMenu。

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      filePathstring文件路径 (本地路径) ,可通过 downloadFile 获得
                      showMenubooleanfalse是否显示右上角菜单2.11.0
                      fileTypestring文件类型,指定文件类型打开文件1.4.0
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fileType 的合法值

                      说明最低版本
                      docdoc 格式
                      docxdocx 格式
                      xlsxls 格式
                      xlsxxlsx 格式
                      pptppt 格式
                      pptxpptx 格式
                      pdfpdf 格式

                      示例代码

                      wx.downloadFile({  // 示例 url,并非真实存在  url: 'http://example.com/somefile.pdf',  success: function (res) {    const filePath = res.tempFilePath    wx.openDocument({      filePath: filePath,      success: function (res) {        console.log('打开文档成功')      }    })  }})


                      wx.getSavedFileList(Object object)

                      获取该小程序下已保存的本地缓存文件列表

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      fileListArray.<Object>文件数组,每一项是一个 FileItem

                      res.fileList 的结构

                      属性类型说明
                      filePathstring文件路径 (本地路径)
                      sizenumber本地文件大小,以字节为单位
                      createTimenumber文件保存时的时间戳,从1970/01/01 08:00:00 到当前时间的秒数

                      示例代码

                      wx.getSavedFileList({  success (res) {    console.log(res.fileList)  }})


                      wx.getSavedFileInfo(Object object)

                      获取本地文件的文件信息。此接口只能用于获取已保存到本地的文件,若需要获取临时文件信息,请使用 wx.getFileInfo() 接口。

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring文件路径 (本地路径)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      sizenumber文件大小,单位 B
                      createTimenumber文件保存时的时间戳,从1970/01/01 08:00:00 到该时刻的秒数

                      示例代码

                      wx.getSavedFileList({  success (res) {    console.log(res.fileList)  }})


                      FileSystemManager wx.getFileSystemManager()

                      基础库 1.9.9 开始支持,低版本需做兼容处理

                      获取全局唯一的文件管理器

                      返回值

                      FileSystemManager

                      文件管理器


                      wx.getFileInfo(Object object)

                      基础库 1.4.0 开始支持,低版本需做兼容处理

                      获取文件信息

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring本地文件路径 (本地路径)
                      digestAlgorithmstring'md5'计算文件摘要的算法
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.digestAlgorithm 的合法值

                      说明最低版本
                      md5md5 算法
                      sha1sha1 算法

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      sizenumber文件大小,以字节为单位
                      digeststring按照传入的 digestAlgorithm 计算得出的的文件摘要

                      示例代码

                      wx.getFileInfo({  success (res) {    console.log(res.size)    console.log(res.digest)  }})


                      FileSystemManager

                      基础库 1.9.9 开始支持,低版本需做兼容处理

                      文件管理器


                      方法:

                      FileSystemManager.access(Object object)

                      判断文件/目录是否存在

                      参数

                      Object object

                      属性类型默认值必填说明
                      pathstring要判断是否存在的文件/目录路径 (本地路径)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail no such file or directory ${path}文件/目录不存在



                      FileSystemManager.accessSync(string path)

                      FileSystemManager.access 的同步版本

                      参数

                      string path

                      要判断是否存在的文件/目录路径 (本地路径)

                      错误

                      错误码错误信息说明
                      fail no such file or directory ${path}文件/目录不存在


                      FileSystemManager.appendFile(Object object)

                      基础库 2.1.0 开始支持,低版本需做兼容处理

                      在文件结尾追加内容

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring要追加内容的文件路径 (本地路径)
                      datastring/ArrayBuffer要追加的文本或二进制数据
                      encodingstringutf8指定写入文件的字符编码
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.encoding 的合法值

                      说明最低版本
                      ascii
                      base64
                      binary
                      hex
                      ucs2以小端序读取
                      ucs-2以小端序读取
                      utf16le以小端序读取
                      utf-16le以小端序读取
                      utf-8
                      utf8
                      latin1

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail no such file or directory, open ${filePath}指定的 filePath 文件不存在
                      fail illegal operation on a directory, open "${filePath}"指定的 filePath 是一个已经存在的目录
                      fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
                      fail sdcard not mounted指定的 filePath 是一个已经存在的目录


                      FileSystemManager.appendFileSync(string filePath, string|ArrayBuffer data, string encoding)

                      基础库 2.1.0 开始支持,低版本需做兼容处理

                      FileSystemManager.appendFile 的同步版本

                      参数

                      string filePath

                      要追加内容的文件路径 (本地路径)

                      string|ArrayBuffer data

                      要追加的文本或二进制数据

                      string encoding

                      指定写入文件的字符编码

                      encoding 的合法值

                      说明最低版本
                      ascii
                      base64
                      binary
                      hex
                      ucs2以小端序读取
                      ucs-2以小端序读取
                      utf16le以小端序读取
                      utf-16le以小端序读取
                      utf-8
                      utf8
                      latin1

                      错误

                      错误码错误信息说明
                      fail no such file or directory, open ${filePath}指定的 filePath 文件不存在
                      fail illegal operation on a directory, open "${filePath}"指定的 filePath 是一个已经存在的目录
                      fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
                      fail sdcard not mounted指定的 filePath 是一个已经存在的目录


                      FileSystemManager.copyFile(Object object)

                      复制文件

                      参数

                      Object object

                      属性类型默认值必填说明
                      srcPathstring源文件路径,支持本地路径
                      destPathstring目标文件路径,支持本地路径
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail permission denied, copyFile ${srcPath} -> ${destPath}指定目标文件路径没有写权限
                      fail no such file or directory, copyFile ${srcPath} -> ${destPath}源文件不存在,或目标文件路径的上层目录不存在
                      fail the maximum size of the file storage limit is exceeded存储空间不足


                      FileSystemManager.copyFileSync(string srcPath, string destPath)

                      FileSystemManager.copyFile 的同步版本

                      参数

                      string srcPath

                      源文件路径,支持本地路径

                      string destPath

                      目标文件路径,支持本地路径

                      错误

                      错误码错误信息说明
                      fail permission denied, copyFile ${srcPath} -> ${destPath}指定目标文件路径没有写权限
                      fail no such file or directory, copyFile ${srcPath} -> ${destPath}源文件不存在,或目标文件路径的上层目录不存在
                      fail the maximum size of the file storage limit is exceeded存储空间不足


                      FileSystemManager.getFileInfo(Object object)

                      获取该小程序下的 本地临时文件 或 本地缓存文件 信息

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring要读取的文件路径 (本地路径)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      sizenumber文件大小,以字节为单位

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail file not exist指定的 filePath 找不到文件


                      FileSystemManager.getSavedFileList(Object object)

                      获取该小程序下已保存的本地缓存文件列表

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      fileListArray.<Object>文件数组

                      res.fileList 的结构

                      属性类型说明
                      filePathstring文件路径 (本地路径)
                      sizenumber本地文件大小,以字节为单位
                      createTimenumber文件保存时的时间戳,从1970/01/01 08:00:00 到当前时间的秒数


                      FileSystemManager.mkdir(Object object)

                      创建目录

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      dirPathstring创建的目录路径 (本地路径)
                      recursivebooleanfalse是否在递归创建该目录的上级目录后再创建该目录。如果对应的上级目录已经存在,则不创建该上级目录。如 dirPath 为 a/b/c/d 且 recursive 为 true,将创建 a 目录,再在 a 目录下创建 b 目录,以此类推直至创建 a/b/c 目录下的 d 目录。2.3.0
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail no such file or directory ${dirPath}上级目录不存在
                      fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
                      fail file already exists ${dirPath}有同名文件或目录


                      FileSystemManager.mkdirSync(string dirPath, boolean recursive)

                      FileSystemManager.mkdir 的同步版本

                      参数

                      string dirPath

                      创建的目录路径 (本地路径)

                      boolean recursive

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      是否在递归创建该目录的上级目录后再创建该目录。如果对应的上级目录已经存在,则不创建该上级目录。如 dirPath 为 a/b/c/d 且 recursive 为 true,将创建 a 目录,再在 a 目录下创建 b 目录,以此类推直至创建 a/b/c 目录下的 d 目录。

                      错误

                      错误码错误信息说明
                      fail no such file or directory ${dirPath}上级目录不存在
                      fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
                      fail file already exists ${dirPath}有同名文件或目录


                      FileSystemManager.readdir(Object object)

                      读取目录内文件列表

                      参数

                      Object object

                      属性类型默认值必填说明
                      dirPathstring要读取的目录路径 (本地路径)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      filesArray.<string>指定目录下的文件名数组。

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail no such file or directory ${dirPath}目录不存在
                      fail not a directory ${dirPath}dirPath 不是目录
                      fail permission denied, open ${dirPath}指定的 filePath 路径没有读权限


                      Array.<string> FileSystemManager.readdirSync(string dirPath)

                      FileSystemManager.readdir 的同步版本

                      参数

                      string dirPath

                      要读取的目录路径 (本地路径)

                      返回值

                      Array.<string> files

                      指定目录下的文件名数组。

                      错误

                      错误码错误信息说明
                      fail no such file or directory ${dirPath}目录不存在
                      fail not a directory ${dirPath}dirPath 不是目录
                      fail permission denied, open ${dirPath}指定的 filePath 路径没有读权限


                      FileSystemManager.readFile(Object object)

                      读取本地文件内容

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      filePathstring要读取的文件的路径 (本地路径)
                      encodingstring指定读取文件的字符编码,如果不传 encoding,则以 ArrayBuffer 格式读取文件的二进制内容
                      positionstring从文件指定位置开始读,如果不指定,则从文件头开始读。读取的范围应该是左闭右开区间 [position, position+length)。有效范围:[0, fileLength - 1]。单位:byte2.10.0
                      lengthstring指定文件的长度,如果不指定,则读到文件末尾。有效范围:[1, fileLength]。单位:byte2.10.0
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.encoding 的合法值

                      说明最低版本
                      ascii
                      base64
                      binary
                      hex
                      ucs2以小端序读取
                      ucs-2以小端序读取
                      utf16le以小端序读取
                      utf-16le以小端序读取
                      utf-8
                      utf8
                      latin1

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      datastring/ArrayBuffer文件内容

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail no such file or directory, open ${filePath}指定的 filePath 所在目录不存在
                      fail permission denied, open ${dirPath}指定的 filePath 路径没有读权限


                      string|ArrayBuffer FileSystemManager.readFileSync(string filePath, string encoding, string position, string length)

                      FileSystemManager.readFile 的同步版本

                      参数

                      string filePath

                      要读取的文件的路径 (本地路径)

                      string encoding

                      指定读取文件的字符编码,如果不传 encoding,则以 ArrayBuffer 格式读取文件的二进制内容

                      encoding 的合法值

                      说明最低版本
                      ascii
                      base64
                      binary
                      hex
                      ucs2以小端序读取
                      ucs-2以小端序读取
                      utf16le以小端序读取
                      utf-16le以小端序读取
                      utf-8
                      utf8
                      latin1

                      string position

                      基础库 2.10.0 开始支持,低版本需做兼容处理

                      从文件指定位置开始读,如果不指定,则从文件头开始读。读取的范围应该是左闭右开区间 [position, position+length)。有效范围:[0, fileLength - 1]。单位:byte

                      string length

                      基础库 2.10.0 开始支持,低版本需做兼容处理

                      指定文件的长度,如果不指定,则读到文件末尾。有效范围:[1, fileLength]。单位:byte

                      返回值

                      string|ArrayBuffer data

                      文件内容

                      错误

                      错误码错误信息说明
                      fail no such file or directory, open ${filePath}指定的 filePath 所在目录不存在
                      fail permission denied, open ${dirPath}指定的 filePath 路径没有读权限


                      FileSystemManager.removeSavedFile(Object object)

                      删除该小程序下已保存的本地缓存文件

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring需要删除的文件路径 (本地路径)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail file not exist指定的 tempFilePath 找不到文件


                      FileSystemManager.rename(Object object)

                      重命名文件。可以把文件从 oldPath 移动到 newPath

                      参数

                      Object object

                      属性类型默认值必填说明
                      oldPathstring源文件路径,支持本地路径
                      newPathstring新文件路径,支持本地路径
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail permission denied, rename ${oldPath} -> ${newPath}指定源文件或目标文件没有写权限
                      fail no such file or directory, rename ${oldPath} -> ${newPath}源文件不存在,或目标文件路径的上层目录不存在


                      FileSystemManager.renameSync(string oldPath, string newPath)

                      FileSystemManager.rename 的同步版本

                      参数

                      string oldPath

                      源文件路径,支持本地路径

                      string newPath

                      新文件路径,支持本地路径

                      错误

                      错误码错误信息说明
                      fail permission denied, rename ${oldPath} -> ${newPath}指定源文件或目标文件没有写权限
                      fail no such file or directory, rename ${oldPath} -> ${newPath}源文件不存在,或目标文件路径的上层目录不存在


                      FileSystemManager.rmdir(Object object)

                      删除目录

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      dirPathstring要删除的目录路径 (本地路径)
                      recursivebooleanfalse是否递归删除目录。如果为 true,则删除该目录和该目录下的所有子目录以及文件。2.3.0
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail no such file or directory ${dirPath}目录不存在
                      fail directory not empty目录不为空
                      fail permission denied, open ${dirPath}指定的 dirPath 路径没有写权限


                      FileSystemManager.rmdirSync(string dirPath, boolean recursive)

                      FileSystemManager.rmdir 的同步版本

                      参数

                      string dirPath

                      要删除的目录路径 (本地路径)

                      boolean recursive

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      是否递归删除目录。如果为 true,则删除该目录和该目录下的所有子目录以及文件。

                      错误

                      错误码错误信息说明
                      fail no such file or directory ${dirPath}目录不存在
                      fail directory not empty目录不为空
                      fail permission denied, open ${dirPath}指定的 dirPath 路径没有写权限


                      FileSystemManager.saveFile(Object object)

                      保存临时文件到本地。此接口会移动临时文件,因此调用成功后,tempFilePath 将不可用。

                      参数

                      Object object

                      属性类型默认值必填说明
                      tempFilePathstring临时存储文件路径 (本地路径)
                      filePathstring要存储的文件路径 (本地路径)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      savedFilePathstring存储后的文件路径 (本地路径)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail tempFilePath file not exist指定的 tempFilePath 找不到文件
                      fail permission denied, open "${filePath}"指定的 filePath 路径没有写权限
                      fail no such file or directory "${dirPath}"上级目录不存在
                      fail the maximum size of the file storage limit is exceeded存储空间不足


                      string FileSystemManager.saveFileSync(string tempFilePath, string filePath)

                      FileSystemManager.saveFile 的同步版本

                      参数

                      string tempFilePath

                      临时存储文件路径 (本地路径)

                      string filePath

                      要存储的文件路径 (本地路径)

                      返回值

                      string savedFilePath

                      存储后的文件路径 (本地路径)

                      错误

                      错误码错误信息说明
                      fail tempFilePath file not exist指定的 tempFilePath 找不到文件
                      fail permission denied, open "${filePath}"指定的 filePath 路径没有写权限
                      fail no such file or directory "${dirPath}"上级目录不存在
                      fail the maximum size of the file storage limit is exceeded存储空间不足


                      FileSystemManager.stat(Object object)

                      获取文件 Stats 对象

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      pathstring文件/目录路径 (本地路径)
                      recursivebooleanfalse是否递归获取目录下的每个文件的 Stats 信息2.3.0
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      statsStats/Object当 recursive 为 false 时,res.stats 是一个 Stats 对象。当 recursive 为 true 且 path 是一个目录的路径时,res.stats 是一个 Object,key 以 path 为根路径的相对路径,value 是该路径对应的 Stats 对象。

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail permission denied, open ${path}指定的 path 路径没有读权限
                      fail no such file or directory ${path}文件不存在

                      示例代码

                      recursive 为 false 时

                      let fs = wx.getFileSystemManager()fs.stat({  path: `${wx.env.USER_DATA_PATH}/testDir`,  success: res => {    console.log(res.stats.isDirectory())  }})

                      recursive 为 true 时

                      fs.stat({  path: `${wx.env.USER_DATA_PATH}/testDir`,  recursive: true,  success: res => {    Object.keys(res.stats).forEach(path => {      let stats = res.stats[path]      console.log(path, stats.isDirectory())    })  }})


                      Stats|Object FileSystemManager.statSync(string path, boolean recursive)

                      FileSystemManager.stat 的同步版本

                      参数

                      string path

                      文件/目录路径 (本地路径)

                      boolean recursive

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      是否递归获取目录下的每个文件的 Stats 信息

                      返回值

                      Stats|Object stats

                      当 recursive 为 false 时,res.stats 是一个 Stats 对象。当 recursive 为 true 且 path 是一个目录的路径时,res.stats 是一个 Object,key 以 path 为根路径的相对路径,value 是该路径对应的 Stats 对象。

                      错误

                      错误码错误信息说明
                      fail permission denied, open ${path}指定的 path 路径没有读权限
                      fail no such file or directory ${path}文件不存在

                      示例代码

                      recursive 为 false 时

                      let fs = wx.getFileSystemManager()fs.stat({  path: `${wx.env.USER_DATA_PATH}/testDir`,  success: res => {    console.log(res.stats.isDirectory())  }})

                      recursive 为 true 时

                      fs.stat({  path: `${wx.env.USER_DATA_PATH}/testDir`,  recursive: true,  success: res => {    Object.keys(res.stats).forEach(path => {      let stats = res.stats[path]      console.log(path, stats.isDirectory())    })  }})


                      FileSystemManager.unlink(Object object)

                      删除文件

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring要删除的文件路径 (本地路径)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值


                      说明最低版本
                      fail permission denied, open ${path}指定的 path 路径没有读权限
                      fail no such file or directory ${path}文件不存在
                      fail operation not permitted, unlink ${filePath}传入的 filePath 是一个目录


                      FileSystemManager.unlinkSync(string filePath)

                      FileSystemManager.unlink 的同步版本

                      参数

                      string filePath

                      要删除的文件路径 (本地路径)

                      错误

                      错误码错误信息说明
                      fail permission denied, open ${path}指定的 path 路径没有读权限
                      fail no such file or directory ${path}文件不存在
                      fail operation not permitted, unlink ${filePath}传入的 filePath 是一个目录


                      FileSystemManager.unzip(Object object)

                      解压文件

                      参数

                      Object object

                      属性类型默认值必填说明
                      zipFilePathstring源文件路径,支持本地路径, 只可以是 zip 压缩文件
                      targetPathstring目标目录路径, 支持本地路径
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail permission denied, unzip ${zipFilePath} -> ${destPath}指定目标文件路径没有写权限
                      fail no such file or directory, unzip ${zipFilePath} -> "${destPath}源文件不存在,或目标文件路径的上层目录不存在


                      FileSystemManager.writeFile(Object object)

                      写文件

                      参数

                      Object object

                      属性类型默认值必填说明
                      filePathstring要写入的文件路径 (本地路径)
                      datastring/ArrayBuffer要写入的文本或二进制数据
                      encodingstringutf8指定写入文件的字符编码
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.encoding 的合法值

                      说明最低版本
                      ascii
                      base64
                      binary
                      hex
                      ucs2以小端序读取
                      ucs-2以小端序读取
                      utf16le以小端序读取
                      utf-16le以小端序读取
                      utf-8
                      utf8
                      latin1

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgstring错误信息

                      res.errMsg 的合法值

                      说明最低版本
                      fail no such file or directory, open ${filePath}指定的 filePath 所在目录不存在
                      fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
                      fail the maximum size of the file storage limit is exceeded存储空间不足


                      FileSystemManager.writeFileSync(string filePath, string|ArrayBuffer data, string encoding)

                      FileSystemManager.writeFile 的同步版本

                      参数

                      string filePath

                      要写入的文件路径 (本地路径)

                      string|ArrayBuffer data

                      要写入的文本或二进制数据

                      string encoding

                      指定写入文件的字符编码

                      encoding 的合法值

                      说明最低版本
                      ascii
                      base64
                      binary
                      hex
                      ucs2以小端序读取
                      ucs-2以小端序读取
                      utf16le以小端序读取
                      utf-16le以小端序读取
                      utf-8
                      utf8
                      latin1

                      错误

                      错误码错误信息说明
                      fail no such file or directory, open ${filePath}指定的 filePath 所在目录不存在
                      fail permission denied, open ${dirPath}指定的 filePath 路径没有写权限
                      fail the maximum size of the file storage limit is exceeded存储空间不足




                      Stats

                      描述文件状态的对象


                      属性

                      属性说明
                      string mode文件的类型和存取的权限,对应 POSIX stat.st_mode
                      number size文件大小,单位:B,对应 POSIX stat.st_size
                      number lastAccessedTime文件最近一次被存取或被执行的时间,UNIX 时间戳,对应 POSIX stat.st_atime
                      number lastModifiedTime文件最后一次被修改的时间,UNIX 时间戳,对应 POSIX stat.st_mtime

                      方法:

                      boolean Stats.isDirectory()

                      判断当前文件是否一个目录

                      返回值

                      boolean

                      表示当前文件是否一个目录

                      boolean Stats.isFile()

                      判断当前文件是否一个普通文件

                      返回值

                      boolean

                      表示当前文件是否一个普通文件


                      每个微信小程序都可以有自己的本地缓存,可以通过wx.setStorage(wx.setStorageSync)、wx.getStorage(wx.getStorageSync)、wx.clearStorage(wx.clearStorageSync)可以对本地缓存进行设置、获取和清理。同一个微信用户,同一个小程序 storage 上限为 10MB。localStorage 以用户维度隔离,同一台设备上,A 用户无法读取到 B 用户的数据。

                      注意: localStorage是永久存储的,但是我们不建议将关键信息全部存在localStorage,以防用户换设备的情况。

                      wx.setStorage(OBJECT)


                      将数据存储在本地缓存中指定的key中,会覆盖掉原来该key对应的内容,这是一个异步接口。

                      OBJECT参数说明:

                      参数类型必填说明
                      keyString本地缓存中的指定的 key
                      dataObject/String需要存储的内容
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.setStorage({  key:"key"  data:"value"})

                      wx.setStorageSync(KEY,DATA)


                      ​将data存储在本地缓存中指定的key中,会覆盖掉原来该key对应的内容,这是一个同步接口。

                      参数说明:

                      参数类型必填说明
                      keyString本地缓存中的指定的key
                      dataObject/String需要存储的内容

                      示例代码

                      try {   wx.setStorageSync("key","value")} catch (e) {}

                      wx.getStorage(OBJECT)


                      从本地缓存中异步获取指定key对应的内容。

                      OBJECT参数说明:

                      参数类型必填说明
                      keyString本地缓存中的指定的 key
                      successFunction接口调用的回调函数,res = {data: key对应的内容}
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数类型说明
                      dataStringkey对应的内容

                      示例代码:

                      wx.getStorage({  key:'key',  success: function(res){      console.log(res.data)  } })

                      wx.getStorageSync(KEY)


                      ​从本地缓存中同步获取指定key对应的内容。

                      参数说明:

                      参数类型必填说明
                      keyString本地缓存中的指定的key

                      示例代码:

                      try {  var value = wx.getStorageSync('key')  if (value) {      // Do something with return value  }} catch (e) {  // Do something when catch error}

                      wx.getStorageInfo(OBJECT)

                      异步获取当前storage的相关信息

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用的回调函数,详见返回参数说明
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数类型说明
                      keysString Array当前storage中所有的key
                      currentSizeNumber当前占用的空间大小, 单位kb
                      limitSizeNumber限制的空间大小,单位kb

                      示例代码:

                      wx.getStorageInfo({  success: function(res) {    console.log(res.keys)    console.log(res.currentSize)    console.log(res.limitSize)  }})

                      wx.getStorageInfoSync

                      同步获取当前storage的相关信息

                      示例代码:

                      try {  var res = wx.getStorageInfoSync()  console.log(res.keys)  console.log(res.currentSize)  console.log(res.limitSize)} catch (e) {  // Do something when catch error}

                      wx.removeStorage(OBJECT)

                      从本地缓存中异步移除指定 key 。

                      OBJECT参数说明:

                      参数类型必填说明
                      keyString本地缓存中的指定的 key
                      successFunction接口调用的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.removeStorage({  key: 'key',  success: function(res) {    console.log(res.data)  } })

                      wx.removeStorageSync(KEY)

                      从本地缓存中同步移除指定 key 。

                      参数说明:

                      参数类型必填说明
                      keyString本地缓存中的指定的 key

                      示例代码:

                      try {  wx.removeStorageSync('key')} catch (e) {  // Do something when catch error}

                      wx.clearStorage()


                      ​清理本地数据缓存。

                      示例代码:

                      wx.clearStorage()

                      wx.clearStorageSync()


                      同步清理本地数据缓存

                      示例代码:

                      try {    wx.clearStorageSync()} catch(e) {  // Do something when catch error}

                      Bug & Tip

                      1. tip: 本地数据存储的大小限制为 10MB


                      wx.getLocation(OBJECT)

                      获取当前的地理位置、速度。当用户离开小程序后,此接口无法调用;当用户点击“显示在聊天顶部”时,此接口可继续调用。

                      OBJECT参数说明:

                      参数 类型 必填 说明
                      type String 默认为"wgs84"返回gps坐标,"gcj02"返回可用于wx.openLocation的坐标
                      success Function 接口调用成功的回调函数,返回内容详见返回参数说明。
                      fail Function 接口调用失败的回调函数
                      complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数说明最低版本
                      latitude纬度,浮点数,范围为-90~90,负数表示南纬 
                      longitude经度,浮点数,范围为-180~180,负数表示西经 
                      speed速度,浮点数,单位m/s 
                      accuracy位置的精确度 
                      altitude高度,单位 m1.2.0
                      verticalAccuracy垂直精度,单位 m(Android 无法获取,返回 0)1.2.0
                      horizontalAccuracy水平精度,单位 m1.2.0

                      示例代码:

                      wx.getLocation({  type: 'wgs84',  success: function(res) {    var latitude = res.latitude    var longitude = res.longitude    var speed = res.speed    var accuracy = res.accuracy  }})


                      wx.chooseLocation(OBJECT)


                      打开地图选择位置。

                      需要用户授权 scope.userLocation

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数,返回内容详见返回参数说明。
                      cancelFunction用户取消时调用
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数说明
                      name位置名称
                      address详细地址
                      latitude纬度,浮点数,范围为-90~90,负数表示南纬
                      longitude经度,浮点数,范围为-180~180,负数表示西经



                      wx.getLocation(OBJECT)


                      获取当前的地理位置、速度。当用户离开小程序后,此接口无法调用;当用户点击“显示在聊天顶部”时,此接口可继续调用。

                      OBJECT参数说明:

                      参数类型必填说明
                      typeString默认为 wgs84 返回 gps 坐标,gcj02 返回可用于wx.openLocation的坐标
                      successFunction接口调用成功的回调函数,返回内容详见返回参数说明。
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数说明最低版本
                      latitude纬度,浮点数,范围为-90~90,负数表示南纬
                      longitude经度,浮点数,范围为-180~180,负数表示西经
                      speed速度,浮点数,单位m/s
                      accuracy位置的精确度
                      altitude高度,单位 m1.2.0
                      verticalAccuracy垂直精度,单位 m(Android 无法获取,返回 0)1.2.0
                      horizontalAccuracy水平精度,单位 m1.2.0

                      示例代码:

                      wx.getLocation({  type: 'wgs84',  success: function(res) {    var latitude = res.latitude    var longitude = res.longitude    var speed = res.speed    var accuracy = res.accuracy  }})

                      wx.chooseLocation(OBJECT)


                      打开地图选择位置。

                      需要用户授权 scope.userLocation

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数,返回内容详见返回参数说明。
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数说明
                      name位置名称
                      address详细地址
                      latitude纬度,浮点数,范围为-90~90,负数表示南纬
                      longitude经度,浮点数,范围为-180~180,负数表示西经

                      wx.openLocation(OBJECT)


                      ​使用微信内置地图查看位置。

                      需要用户授权 scope.userLocation

                      OBJECT参数说明:

                      参数类型必填说明
                      latitudeFloat纬度,范围为-90~90,负数表示南纬
                      longitudeFloat经度,范围为-180~180,负数表示西经
                      scaleINT缩放比例,范围5~18,默认为18
                      nameString位置名
                      addressString地址的详细说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.getLocation({  type: 'gcj02', //返回可以用于wx.openLocation的经纬度  success: function(res) {    var latitude = res.latitude    var longitude = res.longitude    wx.openLocation({      latitude: latitude,      longitude: longitude,      scale: 28    })  }})

                      Bug & Tip

                      1. bug: iOS 6.3.30 type 参数不生效,只会返回 wgs84 类型的坐标信息


                      wx.createMapContext(mapId)


                      创建并返回 map 上下文 mapContext 对象。在自定义组件下,第二个参数传入组件实例this,以操作组件内 <map/> 组件


                      mapContext

                      mapContext通过 mapId 跟一个<map/>组件绑定,通过它可以操作对应的<map/>组件。

                      mapContext 对象的方法列表

                      方法参数说明最低版本
                      getCenterLocationOBJECT获取当前地图中心的经纬度,返回的是 gcj02 坐标系,可以用于 wx.openLocation 
                      moveToLocation将地图中心移动到当前定位点,需要配合map组件的show-location使用 
                      translateMarkerOBJECT平移marker,带动画1.2.0
                      includePointsOBJECT缩放视野展示所有经纬度1.2.0
                      getRegionOBJECT获取当前地图的视野范围1.4.0
                      getScaleOBJECT获取当前地图的缩放级别1.4.0

                      getCenterLocation 的 OBJECT 参数列表

                      参数类型必填说明
                      successFunction接口调用成功的回调函数 ,res = { longitude: "经度", latitude: "纬度"}
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      translateMarker 的 OBJECT 参数列表

                      参数类型必填说明
                      markerIdNumber指定marker
                      destinationObject指定marker移动到的目标点
                      autoRotateBoolean移动过程中是否自动旋转marker
                      rotateNumbermarker的旋转角度
                      durationNumber动画持续时长,默认值1000ms,平移与旋转分别计算
                      animationEndFunction动画结束回调函数
                      failFunction接口调用失败的回调函数

                      includePoints 的 OBJECT 参数列表

                      参数类型必填说明
                      pointsArray要显示在可视区域内的坐标点列表,[{latitude, longitude}]
                      paddingArray坐标点形成的矩形边缘到地图边缘的距离,单位像素。格式为[上,右,下,左],安卓上只能识别数组第一项,上下左右的padding一致。开发者工具暂不支持padding参数。

                      getRegion 的 OBJECT 参数列表

                      参数类型必填说明
                      successFunction接口调用成功的回调函数,res = {southwest, northeast},西南角与东北角的经纬度
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      getScale 的 OBJECT 参数列表

                      参数类型必填说明
                      successFunction接口调用成功的回调函数,res = {scale}
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)


                      示例代码:

                      <!-- map.wxml --><map id="myMap" show-location /><button type="primary" bindtap="getCenterLocation">获取位置</button><button type="primary" bindtap="moveToLocation">移动位置</button><button type="primary" bindtap="translateMarker">移动标注</button><button type="primary" bindtap="includePoints">缩放视野展示所有经纬度</button>
                      // map.jsPage({  onReady: function (e) {    // 使用 wx.createMapContext 获取 map 上下文    this.mapCtx = wx.createMapContext('myMap')  },  getCenterLocation: function () {    this.mapCtx.getCenterLocation({      success: function(res){        console.log(res.longitude)        console.log(res.latitude)      }    })  },  moveToLocation: function () {    this.mapCtx.moveToLocation()  },  translateMarker: function() {    this.mapCtx.translateMarker({      markerId: 0,      autoRotate: true,      duration: 1000,      destination: {        latitude:23.10229,        longitude:113.3345211,      },      animationEnd() {        console.log('animation end')      }    })  },  includePoints: function() {    this.mapCtx.includePoints({      padding: [10],      points: [{        latitude:23.10229,        longitude:113.3345211,      }, {        latitude:23.00229,        longitude:113.3345211,      }]    })  }})


                      wx.onLocationChange(function callback)

                      基础库 2.8.1 开始支持,低版本需做兼容处理

                      监听实时地理位置变化事件,需结合 wx.startLocationUpdateBackground、wx.startLocationUpdate使用。

                      参数

                      function callback

                      实时地理位置变化事件的回调函数

                      参数

                      Object res
                      属性类型说明最低版本
                      latitudenumber纬度,范围为 -90~90,负数表示南纬
                      longitudenumber经度,范围为 -180~180,负数表示西经
                      speednumber速度,单位 m/s
                      accuracynumber位置的精确度
                      altitudenumber高度,单位 m1.2.0
                      verticalAccuracynumber垂直精度,单位 m(Android 无法获取,返回 0)1.2.0
                      horizontalAccuracynumber水平精度,单位 m1.2.0

                      示例代码

                       const _locationChangeFn = function(res) {  console.log('location change', res) } wx.onLocationChange(_locationChangeFn) wx.offLocationChange(_locationChangeFn)

                      wx.offLocationChange(function callback)

                      基础库 2.8.1 开始支持,低版本需做兼容处理

                      取消监听实时地理位置变化事件

                      参数

                      function callback

                      实时地理位置变化事件的回调函数


                      微信小程序API设备概览

                      wx.getSystemInfo(OBJECT)


                      获取系统信息。

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success回调参数说明:

                      属性说明
                      model手机型号
                      pixelRatio设备像素比
                      windowWidth窗口宽度
                      windowHeight窗口高度
                      language微信设置的语言
                      version微信版本号
                      system操作系统版本
                      platform客户端平台

                      示例代码:

                      wx.getSystemInfo({  success: function(res) {    console.log(res.model)    console.log(res.pixelRatio)    console.log(res.windowWidth)    console.log(res.windowHeight)    console.log(res.language)    console.log(res.version)    console.log(res.platform)  }})

                      wx.getSystemInfoSync()


                      获取系统信息同步接口

                      示例代码:

                      try {  var res = wx.getSystemInfoSync()  console.log(res.model)  console.log(res.pixelRatio)  console.log(res.windowWidth)  console.log(res.windowHeight)  console.log(res.language)  console.log(res.version)  console.log(res.platform)} catch (e) {  // Do something when catch error}

                      wx.getSystemInfo(OBJECT)

                      获取系统信息。

                      OBJECT参数说明:

                      参数 类型 必填 说明
                      success Function 接口调用成功的回调
                      fail Function 接口调用失败的回调函数
                      complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

                      success回调参数说明:

                      参数 说明 最低版本
                      model 手机型号  
                      pixelRatio 设备像素比  
                      screenWidth 屏幕宽度 1.1.0
                      screenHeight 屏幕高度 1.1.0
                      windowWidth 可使用窗口宽度  
                      windowHeight 可使用窗口高度  
                      language 微信设置的语言  
                      version 微信版本号  
                      system 操作系统版本  
                      platform 客户端平台  
                      fontSizeSetting 用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准,单位:px 1.5.0
                      SDKVersion 客户端基础库版本 1.1.0


                      示例代码:

                      wx.getSystemInfo({
                      success: function(res) {
                      console.log(res.model)
                      console.log(res.pixelRatio)
                      console.log(res.windowWidth)
                      console.log(res.windowHeight)
                      console.log(res.language)
                      console.log(res.version)
                      console.log(res.platform)

                      }
                      })

                      wx.getSystemInfoSync()

                      获取系统信息同步接口

                      同步返回参数说明:

                      参数 说明 最低版本
                      model 手机型号  
                      pixelRatio 设备像素比  
                      screenWidth 屏幕宽度 1.1.0
                      screenHeight 屏幕高度 1.1.0
                      windowWidth 可使用窗口宽度  
                      windowHeight 可使用窗口高度  
                      language 微信设置的语言  
                      version 微信版本号  
                      system 操作系统版本  
                      platform 客户端平台  
                      SDKVersion 客户端基础库版本 1.1.0

                      示例代码:

                      try {
                      var res = wx.getSystemInfoSync()
                      console.log(res.model)
                      console.log(res.pixelRatio)
                      console.log(res.windowWidth)
                      console.log(res.windowHeight)
                      console.log(res.language)
                      console.log(res.version)
                      console.log(res.platform)
                      } catch (e) {
                      // Do something when catch error
                      }

                      wx.canIUse(String)

                      判断小程序的API,回调,参数,组件等是否在当前版本可用。

                      String参数说明: 使用${API}.${method}.${param}.${options}或者${component}.${attribute}.${option}方式来调用,例如:

                      • ${API}代表 API 名字
                      • ${method}代表调用方式,有效值为returnsuccessobjectcallback
                      • ${param}代表参数或者返回值
                      • ${options}代表参数的可选值
                      • ${component}代表组件名字
                      • ${attribute}代表组件属性
                      • ${option}代表组件属性的可选值

                      例子:

                      wx.canIUse('openBluetoothAdapter')wx.canIUse('getSystemInfoSync.return.screenWidth')
                      wx.canIUse('getSystemInfo.success.screenWidth')
                      wx.canIUse('showToast.object.image')
                      wx.canIUse('onCompassChange.callback.direction')
                      wx.canIUse('request.object.method.GET')
                      wx.canIUse('contact-button')
                      wx.canIUse('text.selectable')
                      wx.canIUse('button.open-type.contact')


                      wx.getNetworkType(OBJECT)

                      获取网络类型。

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功,返回网络类型 networkType
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数说明
                      networkType网络类型
                      wx.getNetworkType({  success: function(res) {    // 返回网络类型, 有效值:    // wifi/2g/3g/4g/unknown(Android下不常见的网络类型)/none(无网络)    var networkType = res.networkType  }})

                      wx.onNetworkStatusChange(CALLBACK)

                      基础库 1.1.0 开始支持,低版本需做兼容处理

                      监听网络状态变化。

                      CALLBACK返回参数:

                      参数类型说明
                      isConnectedBoolean当前是否有网络连接
                      networkTypeString网络类型

                      networkType 有效值:

                      说明
                      wifiwifi 网络
                      2g2g 网络
                      3g3g 网络
                      4g4g 网络
                      none无网络
                      unknownAndroid下不常见的网络类型

                      示例代码:

                      wx.onNetworkStatusChange(function(res) {  console.log(res.isConnected)  console.log(res.networkType)})

                      wx.offNetworkStatusChange(function callback)

                      基础库 2.9.3 开始支持,低版本需做兼容处理

                      取消监听网络状态变化事件,参数为空,则取消所有的事件监听。

                      参数

                      function callback

                      网络状态变化事件的回调函数

                      wx.onAccelerometerChange(CALLBACK)


                      监听重力感应数据,频率:5次/秒,接口调用后会自动开始监听,可使用wx.stopAccelerometer停止监听。

                      CALLBACK返回参数:

                      参数类型说明
                      xNumberX 轴
                      yNumberY 轴
                      zNumberZ 轴

                      示例代码:

                      wx.onAccelerometerChange(function(res) {  console.log(res.x)  console.log(res.y)  console.log(res.z)})

                      wx.startAccelerometer(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      微信客户端 6.5.6 版本开始支持

                      开始监听加速度数据。

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.startAccelerometer()

                      wx.stopAccelerometer(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      微信客户端 6.5.6 版本开始支持

                      停止监听加速度数据。

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.stopAccelerometer()

                      wx.offAccelerometerChange(function callback)


                      基础库 2.9.3 开始支持,低版本需做兼容处理

                      取消监听加速度数据事件,参数为空,则取消所有的事件监听。

                      参数

                      function callback

                      加速度数据事件的回调函数


                      wx.onCompassChange(CALLBACK)

                      监听罗盘数据,频率:5次/秒,接口调用后会自动开始监听,可使用wx.stopCompass停止监听。

                      CALLBACK返回参数:

                      参数类型说明
                      directionNumber面对的方向度数

                      示例代码:

                      wx.onCompassChange(function (res) {  console.log(res.direction)})

                      wx.startCompass(OBJECT)

                      基础库 1.1.0 开始支持,低版本需做兼容处理

                      开始监听罗盘数据。

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.startCompass()

                      wx.stopCompass(OBJECT)

                      基础库 1.1.0 开始支持,低版本需做兼容处理

                      停止监听罗盘数据。

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.stopCompass()

                      wx.offCompassChange(function callback)


                      基础库 2.9.3 开始支持,低版本需做兼容处理

                      取消监听罗盘数据变化事件,参数为空,则取消所有的事件监听。

                      参数

                      function callback

                      罗盘数据变化事件的回调函数


                      wx.makePhoneCall(OBJECT)


                      OBJECT参数说明:

                      参数类型必填说明
                      phoneNumberString需要拨打的电话号码
                      successFunction接口调用成功的回调
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.makePhoneCall({  phoneNumber: '1340000' //仅为示例,并非真实的电话号码})

                      wx.scanCode(Object object)

                      调起客户端扫码界面进行扫码

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      onlyFromCamerabooleanfalse是否只能从相机扫码,不允许从相册选择图片1.2.0
                      scanTypeArray.<string>['barCode', 'qrCode']扫码类型1.7.0
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.scanType 的合法值

                      说明最低版本
                      barCode一维码
                      qrCode二维码
                      datamatrixData Matrix 码
                      pdf417PDF417 条码

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      resultstring所扫码的内容
                      scanTypestring所扫码的类型
                      charSetstring所扫码的字符集
                      pathstring当所扫的码为当前小程序二维码时,会返回此字段,内容为二维码携带的 path
                      rawDatastring原始数据,base64编码

                      res.scanType 的合法值

                      说明最低版本
                      QR_CODE二维码
                      AZTEC一维码
                      CODABAR一维码
                      CODE_39一维码
                      CODE_93一维码
                      CODE_128一维码
                      DATA_MATRIX二维码
                      EAN_8一维码
                      EAN_13一维码
                      ITF一维码
                      MAXICODE一维码
                      PDF_417二维码
                      RSS_14一维码
                      RSS_EXPANDED一维码
                      UPC_A一维码
                      UPC_E一维码
                      UPC_EAN_EXTENSION一维码
                      WX_CODE二维码
                      CODE_25一维码

                      示例代码

                      // 允许从相机和相册扫码wx.scanCode({  success (res) {    console.log(res)  }})// 只允许从相机扫码wx.scanCode({  onlyFromCamera: true,  success (res) {    console.log(res)  }})


                      wx.setClipboardData(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      设置系统剪贴板的内容。

                      OBJECT参数说明:

                      参数类型必填说明
                      dataString需要设置的内容
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.setClipboardData({  data: 'data',  success: function(res) {    wx.getClipboardData({      success: function(res) {        console.log(res.data) // data      }    })  }})

                      wx.getClipboardData(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      获取系统剪贴板内容

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数类型说明
                      dataString剪贴板的内容

                      示例代码:

                      wx.getClipboardData({  success: function(res){    console.log(res.data)  }})

                      蓝牙适配器接口


                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      iOS 微信客户端 6.5.6 版本开始支持,Android 客户端暂不支持

                      wx.openBluetoothAdapter(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      初始化蓝牙适配器

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction成功则返回成功初始化信息
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.openBluetoothAdapter({  success: function (res) {    console.log(res)  }})

                      Bug & Tip

                      1. tip: 由于系统的问题,目前仅在 mac 版的开发工具上支持蓝牙调试
                      2. tip: 基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      wx.closeBluetoothAdapter(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      关闭蓝牙模块。调用该方法将断开所有已建立的链接并释放系统资源

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction成功则返回成功关闭模块信息
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.closeBluetoothAdapter({  success: function (res) {    console.log(res)  }})

                      wx.getBluetoothAdapterState(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      获取本机蓝牙适配器状态

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      discoveringBoolean是否正在搜索设备
                      availableBoolean蓝牙适配器是否可用
                      errMsgString成功:ok,错误:详细信息

                      示例代码:

                      wx.getBluetoothAdapterState({  success: function (res) {    console.log(res)  }})

                      wx.onBluetoothAdapterStateChange(CALLBACK)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      监听蓝牙适配器状态变化事件

                      CALLBACK参数说明:

                      参数类型说明
                      availableboolean蓝牙适配器是否可用
                      discoveringboolean蓝牙适配器是否处于搜索状态

                      示例代码:

                      wx.onBluetoothAdapterStateChange(function(res) {  console.log(`adapterState changed, now is`, res)})

                      wx.startBluetoothDevicesDiscovery(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      开始搜寻附近的蓝牙外围设备。注意,该操作比较耗费系统资源,请在搜索并连接到设备后调用 stop 方法停止搜索。

                      OBJECT参数说明:

                      参数类型必填说明
                      servicesArray蓝牙设备主 service 的 uuid 列表
                      allowDuplicatesKeyboolean是否允许重复上报同一设备, 如果允许重复上报,则onDeviceFound 方法会多次上报同一设备,但是 RSSI 值会有不同
                      intervalinteger上报设备的间隔,默认为0,意思是找到新设备立即上报,否则根据传入的间隔上报
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      services参数说明:某些蓝牙设备会广播自己的主 service 的 uuid。如果这里传入该数组,那么根据该 uuid 列表,只搜索有这个主服务的设备。

                      success返回参数:

                      参数类型说明
                      errMsgstring成功:ok,错误:详细信息
                      isDiscoveringboolean当前蓝牙适配器是否处于搜索状态

                      示例代码:

                      // 以微信硬件平台的蓝牙智能灯为例,主服务的 UUID 是 FEE7。传入这个参数,只搜索主服务 UUID 为 FEE7 的设备wx.startBluetoothDevicesDiscovery({  services: ['FEE7'],  success: function (res) {    console.log(res)  }})

                      wx.stopBluetoothDevicesDiscovery(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      停止搜寻附近的蓝牙外围设备。请在确保找到需要连接的设备后调用该方法停止搜索。

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      errMsgstring成功:ok,错误:详细信息

                      adapterState

                      蓝牙适配器状态信息

                      参数类型说明
                      discoveringboolean是否正在搜索设备
                      availableboolean蓝牙适配器是否可用

                      示例代码:

                      wx.stopBluetoothDevicesDiscovery({  success: function (res) {    console.log(res)  }})

                      wx.getBluetoothDevices(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      获取所有已发现的蓝牙设备,包括已经和本机处于连接状态的设备

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      devicesArrayuuid 对应的的已连接设备列表
                      errMsgstring成功:ok,错误:详细信息

                      device 对象

                      蓝牙设备信息

                      参数类型说明
                      namestring蓝牙设备名称,某些设备可能没有
                      deviceIdstring用于区分设备的 id
                      RSSIint当前蓝牙设备的信号强度
                      advertisDataArrayBuffer当前蓝牙设备的广播内容(注意:vConsole 无法打印出 ArrayBuffer 类型数据)

                      示例代码:

                      wx.getBluetoothDevices({  success: function (res) {    console.log(res)  }})

                      Bug & Tip

                      1. tip: Mac系统可能无法获取advertisDataRSSI,请使用真机调试
                      2. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址,iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

                      wx.getConnectedBluetoothDevices(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      根据 uuid 获取处于已连接状态的设备

                      OBJECT参数说明:

                      参数类型必填说明
                      servicesArray蓝牙设备主 service 的 uuid 列表
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      devicesArray搜索到的设备列表
                      errMsgstring成功:ok,错误:详细信息

                      device对象

                      蓝牙设备信息

                      参数类型说明
                      namestring蓝牙设备名称,某些设备可能没有
                      deviceIdstring用于区分设备的 id

                      示例代码:

                      wx.getConnectedBluetoothDevices({  success: function (res) {    console.log(res)  }})

                      Bug & Tip

                      1. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址,iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

                      wx.onBluetoothDeviceFound(CALLBACK)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      监听寻找到新设备的事件

                      CALLBACK参数说明:

                      参数类型说明
                      devicesArray新搜索到的设备列表

                      device对象

                      参数类型说明
                      deviceIdstring蓝牙设备 id,参考 device 对象
                      namestring蓝牙设备名称,参考 device 对象
                      RSSIint当前蓝牙设备的信号强度
                      advertisDataArrayBuffer当前蓝牙设备的广播内容(注意:vConsole 无法打印出 ArrayBuffer 类型数据)

                      示例代码:

                      wx.onBluetoothDeviceFound(function(devices) {  console.log('new device list has founded')  console.dir(devices)})

                      Bug & Tip

                      1. tip: Mac系统可能无法获取advertisDataRSSI,请使用真机调试
                      2. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址,iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

                      低功耗蓝牙接口

                      wx.createBLEConnection(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      连接低功耗蓝牙设备

                      OBJECT参数说明:

                      参数类型必填说明
                      deviceIdstring蓝牙设备 id,参考 getDevices 接口
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      errMsgstring成功:ok,错误:详细信息

                      示例代码:

                      wx.createBLEConnection({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  success: function (res) {    console.log(res)  }})

                      wx.closeBLEConnection(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      断开与低功耗蓝牙设备的连接

                      OBJECT参数说明:

                      参数类型必填说明
                      deviceIdstring蓝牙设备 id,参考 getDevices 接口
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      errMsgstring成功:ok,错误:详细信息

                      示例代码:

                      wx.closeBLEConnection({  success: function (res) {    console.log(res)  }})

                      wx.getBLEDeviceServices(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      获取蓝牙设备所有 service(服务)

                      OBJECT参数说明:

                      参数类型必填说明
                      deviceIdstring蓝牙设备 id,参考 getDevices 接口
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      servicesarray设备服务列表
                      errMsgstring成功:ok,错误:详细信息

                      service对象

                      蓝牙设备service(服务)信息

                      参数类型说明
                      uuidstring蓝牙设备服务的 uuid
                      isPrimaryboolean该服务是否为主服务

                      示例代码:

                      wx.getBLEDeviceServices({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  success: function (res) {    console.log('device services:', res.services)  }})

                      wx.getBLEDeviceCharacteristics(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      获取蓝牙设备所有 characteristic(特征值)

                      OBJECT参数说明:

                      参数类型必填说明
                      deviceIdstring蓝牙设备 id,参考 device 对象
                      serviceIdstring蓝牙服务 uuid
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      characteristicsarray设备特征值列表
                      errMsgstring成功:ok,错误:详细信息

                      characteristic对象

                      蓝牙设备characteristic(特征值)信息

                      参数类型说明
                      uuidstring蓝牙设备特征值的 uuid
                      propertiesobject该特征值支持的操作类型

                      properties对象

                      参数类型说明
                      readboolean该特征值是否支持 read 操作
                      writeboolean该特征值是否支持 write 操作
                      notifyboolean该特征值是否支持 notify 操作
                      indicateboolean该特征值是否支持 indicate 操作

                      示例代码:

                      wx.getBLEDeviceCharacteristics({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,  success: function (res) {    console.log('device getBLEDeviceCharacteristics:', res.characteristics)  }})

                      wx.readBLECharacteristicValue(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      读取低功耗蓝牙设备的特征值的二进制数据值。注意:必须设备的特征值支持read才可以成功调用,具体参照 characteristic 的 properties 属性

                      OBJECT参数说明:

                      参数类型必填说明
                      deviceIdstring蓝牙设备 id,参考 device 对象
                      serviceIdstring蓝牙特征值对应服务的 uuid
                      characteristicIdstring蓝牙特征值的 uuid
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      characteristicobject设备特征值信息
                      errMsgstring成功:ok,错误:详细信息

                      characteristic对象

                      蓝牙设备characteristic(特征值)信息

                      参数类型说明
                      characteristicIdstring蓝牙设备特征值的 uuid
                      serviceIdobject蓝牙设备特征值对应服务的 uuid
                      valueArrayBuffer蓝牙设备特征值对应的二进制值(注意:vConsole 无法打印出 ArrayBuffer 类型数据)

                      示例代码:

                      // 必须在这里的回调才能获取wx.onBLECharacteristicValueChange(function(characteristic) {  console.log('characteristic value comed:', characteristic)})wx.readBLECharacteristicValue({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取  characteristicId: characteristicId,  success: function (res) {    console.log('readBLECharacteristicValue:', res.characteristic.value)  }})

                      Bug & Tip

                      1. tip: 并行调用多次读写接口存在读写失败的可能性。
                      2. tip:read接口读取到的信息需要在onBLECharacteristicValueChange方法注册的回调中获取。

                      wx.writeBLECharacteristicValue(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      向低功耗蓝牙设备特征值中写入二进制数据。注意:必须设备的特征值支持write才可以成功调用,具体参照 characteristic 的 properties 属性

                      tips: 并行调用多次读写接口存在读写失败的可能性

                      OBJECT参数说明:

                      参数类型必填说明
                      deviceIdstring蓝牙设备 id,参考 device 对象
                      serviceIdstring蓝牙特征值对应服务的 uuid
                      characteristicIdstring蓝牙特征值的 uuid
                      valueArrayBuffer蓝牙设备特征值对应的二进制值(注意:vConsole 无法打印出 ArrayBuffer 类型数据)
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      errMsgstring成功:ok,错误:详细信息

                      示例代码:

                      // 这里的回调可以获取到 write 导致的特征值改变wx.onBLECharacteristicValueChange(function(characteristic) {  console.log('characteristic value changed:', characteristic)})// 向蓝牙设备发送一个0x00的16进制数据let buffer = new ArrayBuffer(1)let dataView = new DataView(buffer)dataView.setUint8(0, 0)wx.writeBLECharacteristicValue({  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取  characteristicId: characteristicId,  // 这里的value是ArrayBuffer类型  value: buffer,  success: function (res) {    console.log('writeBLECharacteristicValue success', res.errMsg)  }})

                      wx.notifyBLECharacteristicValueChanged(OBJECT)


                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      启用低功耗蓝牙设备特征值变化时的 notify 功能。注意:必须设备的特征值支持notify才可以成功调用,具体参照 characteristic 的 properties 属性

                      另外,必须先启用notify才能监听到设备 characteristicValueChange 事件

                      OBJECT参数说明:

                      参数类型必填说明
                      deviceIdstring蓝牙设备 id,参考 device 对象
                      serviceIdstring蓝牙特征值对应服务的 uuid
                      characteristicIdstring蓝牙特征值的 uuid
                      statebooleantrue: 启用 notify; false: 停用 notify
                      successFunction成功则返回本机蓝牙适配器状态
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数:

                      参数类型说明
                      errMsgstring成功:ok,错误:详细信息

                      示例代码:

                      wx.notifyBLECharacteristicValueChanged({  state: true, // 启用 notify 功能  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取  deviceId: deviceId,  // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取  serviceId: serviceId,  // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取  characteristicId: characteristicId,  success: function (res) {    console.log('notifyBLECharacteristicValueChanged success', res.errMsg)  }})

                      wx.onBLEConnectionStateChanged(CALLBACK)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      监听低功耗蓝牙连接的错误事件,包括设备丢失,连接异常断开等等。

                      CALLBACK参数说明:

                      参数类型说明
                      deviceIdstring蓝牙设备 id,参考 device 对象
                      connectedboolean连接目前的状态

                      示例代码:

                      wx.onBLEConnectionStateChanged(function(res) {  // 该方法回调中可以用于处理连接意外断开等异常情况  console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)})

                      wx.onBLECharacteristicValueChange(CALLBACK)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      监听低功耗蓝牙设备的特征值变化。必须先启用notify接口才能接收到设备推送的notification。

                      CALLBACK参数说明:

                      参数类型说明
                      deviceIdstring蓝牙设备 id,参考 device 对象
                      serviceIdstring特征值所属服务 uuid
                      characteristicIdstring特征值 uuid
                      valueArrayBuffer特征值最新的值(注意:vConsole 无法打印出 ArrayBuffer 类型数据)

                      示例代码:

                      wx.onBLECharacteristicValueChange(function(res) {  console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`)})

                      蓝牙错误码(errCode)列表

                      错误码说明备注
                      0ok正常
                      10000not init未初始化蓝牙适配器
                      10001not available当前蓝牙适配器不可用
                      10002no device没有找到指定设备
                      10003connection fail连接失败
                      10004no service没有找到指定服务
                      10005no characteristic没有找到指定特征值
                      10006no connection当前连接已断开
                      10007property not support当前特征值不支持此操作
                      10008system error其余所有系统上报的异常
                      10009system not supportAndroid 系统特有,系统版本低于 4.3 不支持BLE
                      10010no descriptor没有找到指定描述符

                      wx.makeBluetoothPair(Object object)

                      基础库 2.12.0 开始支持,低版本需做兼容处理

                      蓝牙配对接口,仅安卓使用。安卓上蓝牙连接时,部分设备需先配对。

                      参数

                      Object object

                      属性类型默认值必填说明
                      deviceIdstring蓝牙设备 id
                      pinArrayBufferpin 码
                      timeoutnumber20超时时间
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      wx.startBeaconDiscovery(OBJECT)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      开始搜索附近的iBeacon设备

                      OBJECT参数说明:

                      参数名类型必填说明
                      uuidsStringArrayiBeacon设备广播的 uuids
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      errMsgString调用结果

                      示例代码:

                      wx.startBeaconDiscovery({    success(res) {    }})

                      wx.stopBeaconDiscovery(OBJECT)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      停止搜索附近的iBeacon设备

                      OBJECT参数说明:

                      参数名类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      errMsgString调用结果

                      wx.getBeacons(OBJECT)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      获取所有已搜索到的iBeacon设备

                      OBJECT参数说明:

                      参数名类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      beaconsObjectArrayiBeacon 设备列表
                      errMsgString调用结果

                      iBeacon 结构:

                      参数类型说明
                      uuidStringiBeacon 设备广播的 uuid
                      majorStringiBeacon 设备的主 id
                      minorStringiBeacon 设备的次 id
                      proximityNumber表示设备距离的枚举值
                      accuracyNumberiBeacon 设备的距离
                      rssiNumber表示设备的信号强度

                      wx.onBeaconUpdate(CALLBACK)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      监听iBeacon设备的更新事件

                      CALLBACK返回参数说明:

                      参数名类型说明
                      beaconsarray object当前搜寻到的所有 iBeacon 设备列表

                      iBeacon 结构:

                      参数类型说明
                      uuidStringiBeacon 设备广播的 uuid
                      majorStringiBeacon 设备的主 id
                      minorStringiBeacon 设备的次 id
                      proximityNumber表示设备距离的枚举值
                      accuracyNumberiBeacon 设备的距离
                      rssiNumber表示设备的信号强度

                      wx.onBeaconServiceChange(CALLBACK)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      监听iBeacon服务的状态变化

                      CALLBACK返回参数说明:

                      参数名类型说明
                      availableBoolean服务目前是否可用
                      discoveringBoolean目前是否处于搜索状态

                      错误码列表

                      错误码说明备注
                      0ok正常
                      11000unsupport系统或设备不支持
                      11001bluetooth service unavailable蓝牙服务不可用
                      11002location service unavailable位置服务不可用
                      11003already start已经开始搜索

                      wx.setScreenBrightness(OBJECT)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      设置屏幕亮度。

                      OBJECT参数说明:

                      参数类型必填说明
                      valueNumber屏幕亮度值,范围 0~1,0 最暗,1 最亮
                      successFunction接口调用成功
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      wx.getScreenBrightness(OBJECT)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      获取屏幕亮度。

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数类型说明
                      valueNumber屏幕亮度值,范围 0~1,0 最暗,1 最亮

                      wx.setKeepScreenOn(OBJECT)

                      基础库 1.4.0 开始支持,低版本需做兼容处理

                      设置是否保持常亮状态。仅在当前小程序生效,离开小程序后设置失效。

                      OBJECT参数说明:

                      参数名类型必填说明
                      keepScreenOnBoolean是否保持屏幕常亮
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      errMsgString调用结果

                      示例代码:

                      // 保持屏幕常亮wx.setKeepScreenOn({    keepScreenOn: true})


                      wx.onUserCaptureScreen(CALLBACK)

                      基础库 1.4.0 开始支持,低版本需做兼容处理

                      监听用户主动截屏事件,用户使用系统截屏按键截屏时触发此事件

                      CALLBACK返回参数:

                      示例代码:

                      wx.onUserCaptureScreen(function(res) {    console.log('用户截屏了')})

                      wx.vibrateLong(OBJECT)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      使手机发生较长时间的振动(400ms)

                      OBJECT参数说明:

                      参数名类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      wx.vibrateShort(OBJECT)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      使手机发生较短时间的振动(15ms)

                      OBJECT参数说明:

                      参数名类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      Bug & Tip

                      1. tipvibrateShort接口仅在 iPhone7/iPhone7Plus 及 Android 机型生效
                      2. tip:getScreenBrightness接口若安卓系统设置中开启了自动调节亮度功能,则屏幕亮度会根据光线自动调整,该接口仅能获取自动调节亮度之前的值,而非实时的亮度值。

                      wx.addPhoneContact(OBJECT)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      调用后,用户可以选择将该表单以“新增联系人”或“添加到已有联系人”的方式,写入手机系统通讯录,完成手机通讯录联系人和联系方式的增加。

                      OBJECT参数说明:

                      参数类型必填说明
                      photoFilePathString头像本地文件路径
                      nickNameString昵称
                      lastNameString姓氏
                      middleNameString中间名
                      firstNameString名字
                      remarkString备注
                      mobilePhoneNumberString手机号
                      weChatNumberString微信号
                      addressCountryString联系地址国家
                      addressStateString联系地址省份
                      addressCityString联系地址城市
                      addressStreetString联系地址街道
                      addressPostalCodeString联系地址邮政编码
                      organizationString公司
                      titleString职位
                      workFaxNumberString工作传真
                      workPhoneNumberString工作电话
                      hostNumberString公司电话
                      emailString电子邮件
                      urlString网站
                      workAddressCountryString工作地址国家
                      workAddressStateString工作地址省份
                      workAddressCityString工作地址城市
                      workAddressStreetString工作地址街道
                      workAddressPostalCodeString工作地址邮政编码
                      homeFaxNumberString住宅传真
                      homePhoneNumberString住宅电话
                      homeAddressCountryString住宅地址国家
                      homeAddressStateString住宅地址省份
                      homeAddressCityString住宅地址城市
                      homeAddressStreetString住宅地址街道
                      homeAddressPostalCodeString住宅地址邮政编码
                      successFunction接口调用成功
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      回调结果:

                      回调类型errMsg说明
                      successok添加成功
                      failfail cancel用户取消操作
                      failfail ${detail}调用失败,detail 加上详细信息

                      wx.onMemoryWarning(function callback)

                      基础库 2.0.2 开始支持,低版本需做兼容处理

                      监听内存不足告警事件。

                      当 iOS/Android 向小程序进程发出内存警告时,触发该事件。触发该事件不意味小程序被杀,大部分情况下仅仅是告警,开发者可在收到通知后回收一些不必要资源避免进一步加剧内存紧张。

                      参数

                      function callback

                      内存不足告警事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      levelnumber内存告警等级,只有 Android 才有,对应系统宏定义

                      level 的合法值

                      说明最低版本
                      5TRIM_MEMORY_RUNNING_MODERATE
                      10TRIM_MEMORY_RUNNING_LOW
                      15TRIM_MEMORY_RUNNING_CRITICAL

                      示例代码

                      wx.onMemoryWarning(function () {  console.log('onMemoryWarningReceive')})

                      wx.offMemoryWarning(function callback)

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      取消监听内存不足告警事件。

                      参数

                      function callback

                      内存不足告警事件的回调函数


                      wx.stopGyroscope(Object object)

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      停止监听陀螺仪数据。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      wx.startGyroscope(Object object)

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      开始监听陀螺仪数据。

                      参数

                      Object object

                      属性类型默认值必填说明
                      intervalstringnormal监听陀螺仪数据回调函数的执行频率
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.interval 的合法值

                      说明最低版本
                      game适用于更新游戏的回调频率,在 20ms/次 左右
                      ui适用于更新 UI 的回调频率,在 60ms/次 左右
                      normal普通的回调频率,在 200ms/次 左右

                      wx.onGyroscopeChange(function callback)

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      监听陀螺仪数据变化事件。频率根据 wx.startGyroscope() 的 interval 参数。可以使用 wx.stopGyroscope() 停止监听。

                      参数

                      function callback

                      陀螺仪数据变化事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      xnumberx 轴的角速度
                      ynumbery 轴的角速度
                      znumberz 轴的角速度

                      wx.offGyroscopeChange(function callback)

                      基础库 2.9.3 开始支持,低版本需做兼容处理

                      取消监听陀螺仪数据变化事件。

                      参数

                      function callback

                      陀螺仪数据变化事件的回调函数


                      wx.stopDeviceMotionListening(Object object)

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      停止监听设备方向的变化。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      wx.startDeviceMotionListening(Object object)

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      开始监听设备方向的变化。

                      参数

                      Object object

                      属性类型默认值必填说明
                      intervalstringnormal监听设备方向的变化回调函数的执行频率
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.interval 的合法值

                      说明最低版本
                      game适用于更新游戏的回调频率,在 20ms/次 左右
                      ui适用于更新 UI 的回调频率,在 60ms/次 左右
                      normal普通的回调频率,在 200ms/次 左右

                      wx.onDeviceMotionChange(function callback)

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      监听设备方向变化事件。频率根据 wx.startDeviceMotionListening() 的 interval 参数。可以使用 wx.stopDeviceMotionListening() 停止监听。

                      参数

                      function callback

                      设备方向变化事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      alphanumber当 手机坐标 X/Y 和 地球 X/Y 重合时,绕着 Z 轴转动的夹角为 alpha,范围值为 [0, 2*PI)。逆时针转动为正。
                      betanumber当手机坐标 Y/Z 和地球 Y/Z 重合时,绕着 X 轴转动的夹角为 beta。范围值为 [-1*PI, PI) 。顶部朝着地球表面转动为正。也有可能朝着用户为正。
                      gammanumber当手机 X/Z 和地球 X/Z 重合时,绕着 Y 轴转动的夹角为 gamma。范围值为 [-1*PI/2, PI/2)。右边朝着地球表面转动为正。

                      wx.offDeviceMotionChange(function callback)

                      基础库 2.9.3 开始支持,低版本需做兼容处理

                      取消监听设备方向变化事件,参数为空,则取消所有的事件监听。

                      参数

                      function callback

                      设备方向变化事件的回调函数


                      wx.offDeviceMotionChange(function callback)

                      基础库 2.9.3 开始支持,低版本需做兼容处理

                      取消监听设备方向变化事件,参数为空,则取消所有的事件监听。

                      参数

                      function callback

                      设备方向变化事件的回调函数


                      基础库 2.9.3 开始支持,低版本需做兼容处理

                      取消监听设备方向变化事件,参数为空,则取消所有的事件监听。

                      参数

                      function callback

                      设备方向变化事件的回调函数


                      Object wx.getBatteryInfoSync()

                      wx.getBatteryInfo 的同步版本

                      返回值

                      Object res

                      属性类型说明
                      levelstring设备电量,范围 1 - 100
                      isChargingboolean是否正在充电中

                      wx.getBatteryInfo(Object object)

                      获取设备电量。同步 API wx.getBatteryInfoSync 在 iOS 上不可用。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      levelstring设备电量,范围 1 - 100
                      isChargingboolean是否正在充电中


                      wx.stopWifi(Object object)

                      基础库 1.6.0 开始支持,低版本需做兼容处理

                      关闭 Wi-Fi 模块。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      错误

                      错误码错误信息说明
                      0ok正常
                      12000not init未先调用 startWifi 接口
                      12001system not support当前系统不支持相关能力
                      12002password error Wi-Fi密码错误
                      12003connection timeout连接超时
                      12004duplicate request重复连接 Wi-Fi
                      12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
                      12006gps not turned onAndroid 特有,未打开 GPS 定位开关
                      12007user denied用户拒绝授权链接 Wi-Fi
                      12008invalid SSID无效 SSID
                      12009system config err系统运营商配置拒绝连接 Wi-Fi
                      12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
                      12011weapp in background应用在后台无法配置 Wi-Fi
                      12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

                      示例代码

                      wx.stopWifi({  success (res) {    console.log(res.errMsg)  }})

                      wx.startWifi(Object object)

                      基础库 1.6.0 开始支持,低版本需做兼容处理

                      初始化 Wi-Fi 模块。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      错误

                      错误码错误信息说明
                      0ok正常
                      12000not init未先调用 startWifi 接口
                      12001system not support当前系统不支持相关能力
                      12002password error Wi-Fi密码错误
                      12003connection timeout连接超时
                      12004duplicate request重复连接 Wi-Fi
                      12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
                      12006gps not turned onAndroid 特有,未打开 GPS 定位开关
                      12007user denied用户拒绝授权链接 Wi-Fi
                      12008invalid SSID无效 SSID
                      12009system config err系统运营商配置拒绝连接 Wi-Fi
                      12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
                      12011weapp in background应用在后台无法配置 Wi-Fi
                      12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

                      示例代码

                      wx.startWifi({  success (res) {    console.log(res.errMsg)  }})

                      wx.setWifiList(Object object)

                      基础库 1.6.0 开始支持,低版本需做兼容处理

                      设置 wifiList 中 AP 的相关信息。在 onGetWifiList 回调后调用,iOS特有接口。

                      参数

                      Object object

                      属性类型默认值必填说明
                      wifiListArray.<Object>提供预设的 Wi-Fi 信息列表
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.wifiList 的结构

                      属性类型默认值必填说明
                      SSIDstringWi-Fi 的 SSID
                      BSSIDstringWi-Fi 的 BSSID
                      passwordstringWi-Fi 设备密码

                      错误

                      错误码错误信息说明
                      0ok正常
                      12000not init未先调用 startWifi 接口
                      12001system not support当前系统不支持相关能力
                      12002password error Wi-Fi密码错误
                      12003connection timeout连接超时
                      12004duplicate request重复连接 Wi-Fi
                      12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
                      12006gps not turned onAndroid 特有,未打开 GPS 定位开关
                      12007user denied用户拒绝授权链接 Wi-Fi
                      12008invalid SSID无效 SSID
                      12009system config err系统运营商配置拒绝连接 Wi-Fi
                      12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
                      12011weapp in background应用在后台无法配置 Wi-Fi
                      12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

                      注意

                      • 该接口只能在 onGetWifiList 回调之后才能调用。
                      • 此时客户端会挂起,等待小程序设置 Wi-Fi 信息,请务必尽快调用该接口,若无数据请传入一个空数组。
                      • 有可能随着周边 Wi-Fi 列表的刷新,单个流程内收到多次带有存在重复的 Wi-Fi 列表的回调。

                      示例代码

                      wx.onGetWifiList(function(res) {  if (res.wifiList.length) {    wx.setWifiList({      wifiList: [{        SSID: res.wifiList[0].SSID,        BSSID: res.wifiList[0].BSSID,        password: '123456'      }]    })  } else {    wx.setWifiList({      wifiList: []    })  }})wx.getWifiList()


                      wx.onWifiConnected(function callback)

                      基础库 1.6.0 开始支持,低版本需做兼容处理

                      监听连接上 Wi-Fi 的事件

                      参数

                      function callback

                      连接上 Wi-Fi 的事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      wifiWifiInfoWi-Fi 信息

                      wx.onGetWifiList(function callback)

                      基础库 1.6.0 开始支持,低版本需做兼容处理

                      监听获取到 Wi-Fi 列表数据事件

                      参数

                      function callback

                      获取到 Wi-Fi 列表数据事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      wifiListArray.<WifiInfo>Wi-Fi 列表数据

                      wx.offWifiConnected(function callback)

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      取消监听连接上 Wi-Fi 的事件。

                      参数

                      function callback

                      连接上 Wi-Fi 的事件的回调函数


                      wx.offGetWifiList(function callback)

                      基础库 2.9.0 开始支持,低版本需做兼容处理

                      取消监听获取到 Wi-Fi 列表数据事件。

                      参数

                      function callback

                      获取到 Wi-Fi 列表数据事件的回调函数


                      wx.getWifiList(Object object)

                      基础库 1.6.0 开始支持,低版本需做兼容处理

                      请求获取 Wi-Fi 列表。在 onGetWifiList 注册的回调中返回 wifiList 数据。 Android 调用前需要 用户授权 scope.userLocation。

                      iOS 将跳转到系统的 Wi-Fi 界面,Android 不会跳转。 iOS 11.0 及 iOS 11.1 两个版本因系统问题,该方法失效。但在 iOS 11.2 中已修复。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      错误

                      错误码错误信息说明
                      0ok正常
                      12000not init未先调用 startWifi 接口
                      12001system not support当前系统不支持相关能力
                      12002password error Wi-Fi密码错误
                      12003connection timeout连接超时
                      12004duplicate request重复连接 Wi-Fi
                      12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
                      12006gps not turned onAndroid 特有,未打开 GPS 定位开关
                      12007user denied用户拒绝授权链接 Wi-Fi
                      12008invalid SSID无效 SSID
                      12009system config err系统运营商配置拒绝连接 Wi-Fi
                      12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
                      12011weapp in background应用在后台无法配置 Wi-Fi
                      12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

                      wx.getConnectedWifi(Object object)

                      基础库 1.6.0 开始支持,低版本需做兼容处理

                      获取已连接中的 Wi-Fi 信息。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      wifiWifiInfo Wi-Fi 信息

                      错误

                      错误码错误信息说明
                      0ok正常
                      12000not init未先调用 startWifi 接口
                      12001system not support当前系统不支持相关能力
                      12002password error Wi-Fi密码错误
                      12003connection timeout连接超时
                      12004duplicate request重复连接 Wi-Fi
                      12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
                      12006gps not turned onAndroid 特有,未打开 GPS 定位开关
                      12007user denied用户拒绝授权链接 Wi-Fi
                      12008invalid SSID无效 SSID
                      12009system config err系统运营商配置拒绝连接 Wi-Fi
                      12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
                      12011weapp in background应用在后台无法配置 Wi-Fi
                      12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

                      wx.connectWifi(Object object)

                      基础库 1.6.0 开始支持,低版本需做兼容处理

                      连接 Wi-Fi。若已知 Wi-Fi 信息,可以直接利用该接口连接。仅 Android 与 iOS 11 以上版本支持。

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      SSIDstringWi-Fi 设备 SSID
                      BSSIDstringWi-Fi 设备 BSSID
                      passwordstringWi-Fi 设备密码
                      maunalbooleanfalse跳转到系统设置页进行连接,仅安卓生效2.12.0
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      错误

                      错误码错误信息说明
                      0ok正常
                      12000not init未先调用 startWifi 接口
                      12001system not support当前系统不支持相关能力
                      12002password error Wi-Fi密码错误
                      12003connection timeout连接超时
                      12004duplicate request重复连接 Wi-Fi
                      12005wifi not turned onAndroid 特有,未打开 Wi-Fi 开关
                      12006gps not turned onAndroid 特有,未打开 GPS 定位开关
                      12007user denied用户拒绝授权链接 Wi-Fi
                      12008invalid SSID无效 SSID
                      12009system config err系统运营商配置拒绝连接 Wi-Fi
                      12010system internal error系统其他错误,需要在 errmsg 打印具体的错误原因
                      12011weapp in background应用在后台无法配置 Wi-Fi
                      12013wifi config may be expired系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试

                      示例代码

                      wx.connectWifi({  SSID: '',  password: '',  success (res) {    console.log(res.errMsg)  }})

                      WifiInfo

                      Wifi 信息

                      属性

                      string SSID

                      Wi-Fi 的 SSID

                      string BSSID

                      Wi-Fi 的 BSSID

                      boolean secure

                      Wi-Fi 是否安全

                      number signalStrength

                      Wi-Fi 信号强度

                      number frequency

                      基础库 2.12.0 开始支持,低版本需做兼容处理。

                      Wi-Fi 频段单位 MHz


                      wx.stopHCE(Object object)

                      基础库 1.7.0 开始支持,低版本需做兼容处理

                      关闭 NFC 模块。仅在安卓系统下有效。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      错误

                      错误码错误信息说明
                      0ok正常
                      13000当前设备不支持NFC
                      13001当前设备支持NFC,但系统NFC开关未开启
                      13002当前设备支持NFC,但不支持HCE
                      13003AID列表参数格式错误
                      13004未设置微信为默认NFC支付应用
                      13005返回的指令不合法
                      13006注册AID失败

                      示例代码

                      wx.stopHCE({  success (res) {    console.log(res.errMsg)  }})


                      wx.startHCE(Object object)

                      基础库 1.7.0 开始支持,低版本需做兼容处理

                      初始化 NFC 模块。

                      参数

                      Object object

                      属性类型默认值必填说明
                      aid_listArray.<string>需要注册到系统的 AID 列表
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      错误

                      错误码错误信息说明
                      0ok正常
                      13000当前设备不支持NFC
                      13001当前设备支持NFC,但系统NFC开关未开启
                      13002当前设备支持NFC,但不支持HCE
                      13003AID列表参数格式错误
                      13004未设置微信为默认NFC支付应用
                      13005返回的指令不合法
                      13006注册AID失败

                      示例代码

                      wx.startHCE({  aid_list: ['F222222222'],  success (res) {    console.log(res.errMsg)  }})


                      wx.sendHCEMessage(Object object)

                      基础库 1.7.0 开始支持,低版本需做兼容处理

                      发送 NFC 消息。仅在安卓系统下有效。

                      参数

                      Object object

                      属性类型默认值必填说明
                      dataArrayBuffer二进制数据
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      错误

                      错误码错误信息说明
                      0ok正常
                      13000当前设备不支持NFC
                      13001当前设备支持NFC,但系统NFC开关未开启
                      13002当前设备支持NFC,但不支持HCE
                      13003AID列表参数格式错误
                      13004未设置微信为默认NFC支付应用
                      13005返回的指令不合法
                      13006注册AID失败

                      示例代码

                      const buffer = new ArrayBuffer(1)const dataView = new DataView(buffer)dataView.setUint8(0, 0)wx.startHCE({  success (res) {    wx.onHCEMessage(function(res) {      if (res.messageType === 1) {        wx.sendHCEMessage({data: buffer})      }    })  }})


                      wx.onHCEMessage(function callback)

                      基础库 1.7.0 开始支持,低版本需做兼容处理

                      监听接收 NFC 设备消息事件,仅能注册一个监听

                      参数

                      function callback

                      接收 NFC 设备消息事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      messageTypenumber消息类型
                      dataArrayBuffermessageType=1 时 ,客户端接收到 NFC 设备的指令
                      reasonnumbermessageType=2 时,原因

                      messageType 的合法值


                      说明最低版本
                      1HCE APDU Command类型,小程序需对此指令进行处理,并调用 sendHCEMessage 接口返回处理指令
                      2设备离场事件类型


                      wx.offHCEMessage(function callback)

                      基础库 2.8.1 开始支持,低版本需做兼容处理

                      接收 NFC 设备消息事件,取消事件监听。

                      参数

                      function callback

                      接收 NFC 设备消息事件的回调函数


                      NFCAdapter wx.getNFCAdapter()

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取 NFC 实例

                      返回值

                      NFCAdapter

                      NFC 实例

                      错误

                      错误码错误信息说明
                      13000设备不支持NFC
                      13001系统NFC开关未打开
                      13010未知错误
                      13019user is not authorized用户未授权
                      13011invalid parameter参数无效
                      13012parse NdefMessage failed将参数解析为NdefMessage失败
                      13021NFC discovery already started已经开始NFC扫描
                      13018NFC discovery has not started尝试在未开始NFC扫描时停止NFC扫描
                      13022Tech already connected标签已经连接
                      13023Tech has not connected尝试在未连接标签时断开连接
                      13013NFC tag has not been discovered未扫描到NFC标签
                      13014invalid tech无效的标签技术
                      13015unavailable tech从标签上获取对应技术失败
                      13024function not support当前标签技术不支持该功能
                      13017system internal error相关读写操作失败
                      13016connect fail连接失败




                      wx.getHCEState(Object object)

                      基础库 1.7.0 开始支持,低版本需做兼容处理

                      判断当前设备是否支持 HCE 能力。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      错误

                      错误码错误信息说明
                      0ok正常
                      13000当前设备不支持NFC
                      13001当前设备支持NFC,但系统NFC开关未开启
                      13002当前设备支持NFC,但不支持HCE
                      13003AID列表参数格式错误
                      13004未设置微信为默认NFC支付应用
                      13005返回的指令不合法
                      13006注册AID失败

                      示例代码

                      wx.getHCEState({  success (res) {    console.log(res.errCode)  }})


                      IsoDep

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      IsoDep 标签


                      方法:

                      IsoDep.close(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      断开连接

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      IsoDep.connect(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      连接 NFC 标签

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      IsoDep.getHistoricalBytes(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取复位信息

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      histBytesArrayBuffer返回历史二进制数据


                      IsoDep.getMaxTransceiveLength(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取最大传输长度

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      lengthnumber最大传输长度


                      IsoDep.setTimeout(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      设置超时时间

                      参数

                      Object object

                      属性类型默认值必填说明
                      timeoutnumber设置超时时间 (ms)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      IsoDep.transceive(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      发送数据

                      参数

                      Object object

                      属性类型默认值必填说明
                      dataArrayBuffer需要传递的二进制数据
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      dataArrayBuffer


                      MifareClassic

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      MifareClassic 标签


                      方法:

                      MifareClassic.close(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      断开连接

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      MifareClassic.connect(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      连接 NFC 标签

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      MifareClassic.getMaxTransceiveLength(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取最大传输长度

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      lengthnumber最大传输长度


                      MifareClassic.setTimeout(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      设置超时时间

                      参数

                      Object object

                      属性类型默认值必填说明
                      timeoutnumber设置超时时间 (ms)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      MifareClassic.transceive(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      发送数据

                      参数

                      Object object

                      属性类型默认值必填说明
                      dataArrayBuffer需要传递的二进制数据
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      dataArrayBuffer




                      MifareUltralight

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      MifareUltralight 标签


                      方法:

                      MifareUltralight.close(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      断开连接

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      MifareUltralight.connect(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      连接 NFC 标签

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      MifareUltralight.getMaxTransceiveLength(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取最大传输长度

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      lengthnumber最大传输长度


                      MifareUltralight.setTimeout(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      设置超时时间

                      参数

                      Object object

                      属性类型默认值必填说明
                      timeoutnumber设置超时时间 (ms)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      complete
                      function接口调用结束的回调函数(调用成功、失败都会执行)


                      MifareUltralight.transceive(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      发送数据

                      参数

                      Object object

                      属性类型默认值必填说明
                      dataArrayBuffer需要传递的二进制数据
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      dataArrayBuffer




                      Ndef

                      基础库 2.11.2 开始支持,低版本需做兼容处理。

                      Ndef 标签


                      方法:

                      Ndef.close(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      断开连接

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      Ndef.connect(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      连接 NFC 标签

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      Ndef.offNdefMessage(function callback)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      取消监听 Ndef 消息

                      参数

                      function callback


                      Ndef.onNdefMessage(function callback)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      监听 Ndef 消息

                      参数

                      function callback


                      Ndef.setTimeout(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      设置超时时间

                      参数

                      Object object

                      属性类型默认值必填说明
                      timeoutnumber设置超时时间 (ms)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      Ndef.writeNdefMessage(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      重写 Ndef 标签内容

                      参数

                      Object object

                      属性类型默认值必填说明
                      urisArrayuri 数组
                      textsArraytext 数组
                      recordsArray二进制对象数组, 需要指明 id, type 以及 payload (均为 ArrayBuffer 类型)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcA

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      NfcA 标签


                      方法:

                      NfcA.close(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      断开连接

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcA.connect(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      连接 NFC 标签

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcA.getAtqa(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取ATQA信息

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      atqaArrayBuffer返回 ATQA/SENS_RES 数据


                      NfcA.getMaxTransceiveLength(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取最大传输长度

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      lengthnumber最大传输长度


                      NfcA.getSak(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取SAK信息

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      saknumber返回 SAK/SEL_RES 数据


                      NfcA.setTimeout(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      设置超时时间

                      参数

                      Object object

                      属性类型默认值必填说明
                      timeoutnumber设置超时时间 (ms)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcA.transceive(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      发送数据

                      参数

                      Object object

                      属性类型默认值必填说明
                      dataArrayBuffer需要传递的二进制数据
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      dataArrayBuffer




                      NFCAdapter

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      属性

                      Object tech

                      标签类型枚举

                      属性类型说明
                      ndefstring对应Ndef实例,实例支持对NDEF格式的NFC标签上的NDEF数据的读写
                      nfcAstring对应NfcA实例,实例支持NFC-A (ISO 14443-3A)标准的读写
                      nfcBstring对应NfcB实例,实例支持NFC-B (ISO 14443-3B)标准的读写
                      isoDepstring对应IsoDep实例,实例支持ISO-DEP (ISO 14443-4)标准的读写
                      nfcFstring对应NfcF实例,实例支持NFC-F (JIS 6319-4)标准的读写
                      nfcVstring对应NfcV实例,实例支持NFC-V (ISO 15693)标准的读写
                      mifareClassicstring对应MifareClassic实例,实例支持MIFARE Classic标签的读写
                      mifareUltralightstring对应MifareUltralight实例,实例支持MIFARE Ultralight标签的读写

                      方法:

                      IsoDep NFCAdapter.getIsoDep()

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取IsoDep实例,实例支持ISO-DEP (ISO 14443-4)标准的读写

                      返回值

                      IsoDep


                      MifareClassic NFCAdapter.getMifareClassic()

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取MifareClassic实例,实例支持MIFARE Classic标签的读写

                      返回值

                      MifareClassic


                      MifareUltralight NFCAdapter.getMifareUltralight()

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取MifareUltralight实例,实例支持MIFARE Ultralight标签的读写

                      返回值

                      MifareUltralight


                      Ndef NFCAdapter.getNdef()

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取Ndef实例,实例支持对NDEF格式的NFC标签上的NDEF数据的读写

                      返回值

                      Ndef


                      NfcA NFCAdapter.getNfcA()

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取NfcA实例,实例支持NFC-A (ISO 14443-3A)标准的读写

                      返回值

                      NfcA


                      NfcB NFCAdapter.getNfcB()

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取NfcB实例,实例支持NFC-B (ISO 14443-3B)标准的读写

                      返回值

                      NfcB


                      NfcF NFCAdapter.getNfcF()

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取NfcF实例,实例支持NFC-F (JIS 6319-4)标准的读写

                      返回值

                      NfcF


                      NfcV NFCAdapter.getNfcV()

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取NfcV实例,实例支持NFC-V (ISO 15693)标准的读写

                      返回值

                      NfcV


                      NFCAdapter.offDiscovered(function callback)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      取消监听 NFC Tag

                      参数

                      function callback

                      的回调函数


                      NFCAdapter.onDiscovered(function callback)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      监听 NFC Tag

                      参数

                      function callback

                      的回调函数

                      参数

                      Object res
                      属性类型说明
                      techsArraytech 数组,用于匹配NFC卡片具体可以使用什么标准(NfcA等实例)处理
                      messagesArrayNdefMessage 数组


                      NFCAdapter.startDiscovery(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NFCAdapter.stopDiscovery(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)



                      NfcB

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      NfcB 标签


                      方法:

                      NfcB.close(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      断开连接

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcB.connect(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      连接 NFC 标签

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcB.getMaxTransceiveLength(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取最大传输长度

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      lengthnumber最大传输长度


                      NfcB.setTimeout(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      设置超时时间

                      参数

                      Object object

                      属性类型默认值必填说明
                      timeoutnumber设置超时时间 (ms)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcB.transceive(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      发送数据

                      参数

                      Object object

                      属性类型默认值必填说明
                      dataArrayBuffer需要传递的二进制数据
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      dataArrayBuffer


                      NfcF

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      NfcF 标签


                      方法:

                      NfcF.close(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      断开连接

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcF.connect(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      连接 NFC 标签

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcF.getMaxTransceiveLength(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取最大传输长度

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      lengthnumber最大传输长度


                      NfcF.setTimeout(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      设置超时时间

                      参数

                      Object object

                      属性类型默认值必填说明
                      timeoutnumber设置超时时间 (ms)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcF.transceive(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      发送数据

                      参数

                      Object object

                      属性类型默认值必填说明
                      dataArrayBuffer需要传递的二进制数据
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      dataArrayBuffer


                      NfcV

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      NfcV 标签


                      方法:

                      NfcV.close(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      断开连接

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcV.connect(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      连接 NFC 标签

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcV.getMaxTransceiveLength(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      获取最大传输长度

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      lengthnumber最大传输长度


                      NfcV.setTimeout(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      设置超时时间

                      参数

                      Object object

                      属性类型默认值必填说明
                      timeoutnumber设置超时时间 (ms)
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      NfcV.transceive(Object object)

                      基础库 2.11.2 开始支持,低版本需做兼容处理

                      发送数据

                      参数

                      Object object

                      属性类型默认值必填说明
                      dataArrayBuffer需要传递的二进制数据
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      dataArrayBuffer


                      wx.showToast(OBJECT)

                      显示消息提示框。

                      OBJECT参数说明:

                      参数类型必填说明最低版本
                      titleString提示的内容 
                      iconString图标,有效值"success"、"loading" 
                      imageString自定义图标的本地路径,image 的优先级高于 icon1.1.0
                      durationNumber提示的延迟时间,单位毫秒,默认:1500 
                      maskBoolean是否显示透明蒙层,防止触摸穿透,默认:false 
                      successFunction接口调用成功的回调函数 
                      failFunction接口调用失败的回调函数 
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行) 

                      示例代码:

                      wx.showToast({  title: '成功',  icon: 'success',  duration: 2000})

                      wx.showLoading(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      显示 loading 提示框, 需主动调用 wx.hideLoading 才能关闭提示框

                      OBJECT参数说明:

                      参数类型必填说明
                      titleString提示的内容
                      maskBoolean是否显示透明蒙层,防止触摸穿透,默认:false
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      wx.hideToast()

                      隐藏消息提示框

                      wx.hideLoading()


                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      隐藏loading提示框

                      wx.showLoading({  title: '加载中',})setTimeout(function(){  wx.hideLoading()},2000)

                      wx.showModal(OBJECT)

                      ​显示模态弹窗

                      OBJECT参数说明:

                      参数类型必填说明
                      titleString提示的标题
                      contentString提示的内容
                      showCancelBoolean是否显示取消按钮,默认为 true
                      cancelTextString取消按钮的文字,默认为"取消",最多 4 个字符
                      cancelColorHexColor取消按钮的文字颜色,默认为"#000000"
                      confirmTextString确定按钮的文字,默认为"确定",最多 4 个字符
                      confirmColorHexColor确定按钮的文字颜色,默认为"#3CC51F"
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      succes返回参数说明:

                      参数类型说明最低版本
                      confirmBoolean为 true 时,表示用户点击了确定按钮 
                      cancelBoolean为 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参数说明:

                      参数类型必填说明
                      itemListString Array按钮的文字数组,数组长度最大为6个
                      itemColorHexColor按钮的文字颜色,默认为"#000000"
                      successFunction接口调用成功的回调函数,详见返回参数说明
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数类型说明
                      tapIndexNumber用户点击的按钮,从上到下的顺序,从0开始

                      示例代码:

                      wx.showActionSheet({  itemList: ['A', 'B', 'C'],  success: function(res) {    console.log(res.tapIndex)  },  fail: function(res) {    console.log(res.errMsg)  }})

                      Bug & Tip

                      1. bug:Android6.3.30,wx.showModal 的返回的 confirm 一直为 true;
                      2. tip: wx.showActionSheet 点击取消或蒙层时,回调fail, errMsg 为 "showActionSheet:fail cancel";
                      3. tip: wx.showLoading 和 wx.showToast 同时只能显示一个,使用 wx.hideToast/wx.hideLoading 都可以关闭提示框;
                      4. tip: iOS wx.showModal 点击蒙层不会关闭模态弹窗,所以尽量避免使用“取消”分支中实现业务逻辑。

                      wx.setNavigationBarTitle(OBJECT)


                      动态设置当前页面的标题。

                      OBJECT参数说明:

                      参数类型必填说明
                      titleString页面标题
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.setNavigationBarTitle({  title: '当前页面'})

                      wx.showNavigationBarLoading()

                      在当前页面显示导航条加载动画。

                      wx.hideNavigationBarLoading()

                      隐藏导航条加载动画。

                      wx.setNavigationBarColor(OBJECT)

                      基础库 1.4.0 开始支持,低版本需做兼容处理

                      OBJECT参数说明:

                      参数名类型必填说明
                      frontColorString前景颜色值,包括按钮、标题、状态栏的颜色,仅支持 #ffffff 和 #000000
                      backgroundColorString背景颜色值,有效值为十六进制颜色
                      animationObject动画效果
                      animation.durationNumber动画变化时间,默认0,单位:毫秒
                      animation.timingFuncString动画变化方式,默认 linear
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      animation.timingFunc 有效值:

                      说明
                      linear动画从头到尾的速度是相同的。
                      easeIn动画以低速开始
                      easeOut动画以低速结束。
                      easeInOut动画以低速开始和结束。

                      success返回参数说明:

                      参数名类型说明
                      errMsgString调用结果

                      示例代码:

                      wx.setNavigationBarColor({    frontColor: '#ffffff',    backgroundColor: '#ff0000',    animation: {        duration: 400,        timingFunc: 'easeIn'    }})


                      wx.setTopBarText(OBJECT)

                      基础库 1.4.3 开始支持,低版本需做兼容处理

                      动设置置顶栏文字内容,只有当前小程序被置顶时能生效,如果当前小程序没有被置顶,也能调用成功,但是不会立即生效,只有在用户将这个小程序置顶后才换上设置的文字内容。注意:调用成功后,需间隔 5s 才能再次调用此接口,如果在 5s 内再次调用此接口,会回调 fail,errMsg:"setTopBarText: fail invoke too frequently"

                      OBJECT参数说明:

                      参数类型必填说明
                      textString置顶栏文字内容
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.setTopBarText({  text: 'hello, world!'})
                      为了满足大家查询需要,我们收集并整理了一份 : 微信小程序导航大全 你可以很方便的通过扫二维码去使用这些小程序。

                      wx.navigateTo(OBJECT)

                      保留当前页面,跳转到应用内的某个页面,使用wx.navigateBack可以返回到原页面。

                      OBJECT 参数说明:

                      参数类型必填说明
                      urlString需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数。参数与路径之间使用?分隔,参数键与参数值用=相连,不同参数用&分隔;如 'path?key=value&key2=value2'
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.navigateTo({  url: 'test?id=1'})
                      //test.jsPage({  onLoad: function(option){    console.log(option.query)  }})

                      注意:为了不让用户在使用小程序时造成困扰,我们规定页面路径只能是五层,请尽量避免多层级的交互方式。


                      wx.redirectTo(OBJECT)

                      关闭当前页面,跳转到应用内的某个页面。

                      OBJECT 参数说明:

                      参数类型必填说明
                      urlString需要跳转的应用内非 tabBar 的页面的路径,路径后可以带参数。参数与路径之间使用?分隔,参数键与参数值用=相连,不同参数用&分隔;如 'path?key=value&key2=value2'
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.redirectTo({  url: 'test?id=1'})

                      wx.reLaunch(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      关闭所有页面,打开到应用内的某个页面。

                      OBJECT 参数说明:

                      参数类型必填说明
                      urlString需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数。参数与路径之间使用?分隔,参数键与参数值用=相连,不同参数用&分隔;如 'path?key=value&key2=value2',如果跳转的页面路径是 tabBar 页面则不能带参数
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.reLaunch({  url: 'test?id=1'})
                      //test.jsPage({  onLoad: function(option){    console.log(option.query)  }})

                      wx.switchTab(OBJECT)

                      跳转到 tabBar 页面,并关闭其他所有非 tabBar 页面

                      OBJECT 参数说明:

                      参数类型必填说明
                      urlString需要跳转的 tabBar 页面的路径(需在 app.json 的 tabBar 字段定义的页面),路径后不能带参数
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      {  "tabBar": {    "list": [{      "pagePath": "index",      "text": "首页"    },{      "pagePath": "other",      "text": "其他"    }]  }}
                      wx.switchTab({  url: '/index'})

                      wx.navigateBack(OBJECT)

                      关闭当前页面,返回上一页面或多级页面。可通过 getCurrentPages()获取当前的页面栈,决定需要返回几层。

                      OBJECT 参数说明:

                      参数类型默认值说明
                      deltaNumber1返回的页面数,如果 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

                      1. tip: wx.navigateTo 和 wx.redirectTo 不允许跳转到 tabbar 页面,只能用 wx.switchTab 跳转到 tabbar 页面

                      wx.showNavigationBarLoading(Object object)

                      在当前页面显示导航条加载动画

                      OBJECT 参数说明:

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      wx.setNavigationBarTitle(Object object)

                      动态设置当前页面的标题

                      OBJECT 参数说明:

                      属性类型默认值必填说明
                      titlestring页面标题
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.setNavigationBarTitle({  title: '当前页面'})

                      wx.setNavigationBarColor(Object object)

                      基础库 1.4.0 开始支持,低版本需做兼容处理

                      设置页面导航条颜色

                      OBJECT 参数说明:

                      属性类型默认值必填说明
                      frontColorstring前景颜色值,包括按钮、标题、状态栏的颜色,仅支持 #ffffff 和 #000000
                      backgroundColorstring背景颜色值,有效值为十六进制颜色
                      animationObject动画效果
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.animation 的结构

                      属性类型默认值必填说明
                      durationnumber0动画变化时间,单位 ms
                      timingFuncstring'linear'动画变化方式

                      object.animation.timingFunc 的合法值

                      说明最低版本
                      'linear'动画从头到尾的速度是相同的
                      'easeIn'动画以低速开始
                      'easeOut'动画以低速结束
                      'easeInOut'动画以低速开始和结束

                      示例代码

                      wx.setNavigationBarColor({  frontColor: '#ffffff',  backgroundColor: '#ff0000',  animation: {    duration: 400,    timingFunc: 'easeIn'  }})

                      wx.hideNavigationBarLoading(Object object)

                      在当前页面隐藏导航条加载动画

                      OBJECT 参数说明:

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      wx.hideHomeButton(Object object)

                      基础库 2.8.3 开始支持,低版本需做兼容处理

                      隐藏返回首页按钮。微信7.0.7版本起,当用户打开的小程序最底层页面是非首页时,默认展示“返回首页”按钮,开发者可在页面 onShow 中调用 hideHomeButton 进行隐藏。

                      OBJECT 参数说明:

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      wx.createAnimation(OBJECT)


                      ​ 创建一个动画实例animation。调用实例的方法来描述动画。最后通过动画实例的export方法导出动画数据传递给组件的animation属性。

                      注意:export方法每次调用后会清掉之前的动画操作

                      OBJECT参数说明:

                      参数类型必填默认值说明
                      durationInteger400动画持续时间,单位ms
                      timingFunctionString"linear"定义动画的效果
                      delayInteger0动画延迟时间,单位 ms
                      transformOriginString"50% 50% 0"设置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) transform-function rotate3d

                      缩放:

                      方法 参数 说明
                      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) transform-function matrix
                      matrix3d   transform-function matrix3d

                      动画队列


                      调用动画操作方法后要调用step()来表示一组动画完成,可以在一组动画中调用任意多个动画方法,一组动画中的所有动画会同时开始,一组动画完成后才会进行下一组动画。step 可以传入一个跟wx.createAnimation()一样的配置参数用于指定当前组动画的配置。

                      示例:

                      <view animation="{{animationData}}" style="background:red,height:100rpx,width:100rpx"></view>
                      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:animation.export()    })  },  rotateThenScale: function () {    // 先旋转后放大    this.animation.rotate(45).step()    this.animation.scale(2, 2).step()    this.setData({      animationData:animation.export()    })  },  rotateAndScaleThenTranslate: function () {    // 先旋转同时放大,然后平移    this.animation.rotate(45).scale(2, 2).step()    this.animation.translate(100, 100).step({ duration: 1000 })    this.setData({      animationData:animation.export()    })  }})

                      bug & tip

                      1. bugiOS/Android6.3.30通过 step() 分隔动画,只有第一步动画能生效

                      wx.pageScrollTo(OBJECT)

                      基础库 1.4.0 开始支持,低版本需做兼容处理

                      将页面滚动到目标位置。

                      OBJECT参数说明:

                      属性 类型 默认值 必填 说明 最低版本
                       scrollTop number 否 滚动到页面的目标位置,单位 px 
                       duration number 300否  滚动动画的时长,单位 ms 
                       selector string 否  选择器 2.7.3
                       success function 否  接口调用成功的回调函数 
                       fail function 否  接口调用失败的回调函数 
                       complete function 否  接口调用结束的回调函数(调用成功、失败都会执行) 

                      selector 语法

                      selector类似于 CSS 的选择器,但仅支持下列语法。

                      • ID选择器:#the-id
                      • class选择器(可以连续指定多个):.a-class.another-class
                      • 子元素选择器:.the-parent > .the-child
                      • 后代选择器:.the-ancestor .the-descendant
                      • 跨自定义组件的后代选择器:.the-ancestor >>> .the-descendant
                      • 多选择器的并集:#a-node, .some-other-nodes

                      示例代码:

                      wx.pageScrollTo({  scrollTop: 0,  duration: 300})


                      API 接口


                      方法说明
                      createCanvasContext创建 canvas 绘图上下文(指定 canvasId)
                      createContext(不推荐使用)创建 canvas 绘图上下文
                      drawCanvas(不推荐使用)进行绘图
                      canvasToTempFilePath导出图片

                      context 对象的方法列表


                      颜色,样式,阴影

                      方法说明
                      setFillStyle设置填充样式
                      setStrokeStyle设置线条样式
                      setShadow设置阴影

                      渐变

                      方法说明
                      createLinearGradient创建一个线性渐变
                      createCircularGradient创建一个圆形渐变
                      addColorStop在渐变中的某一点添加一个颜色变化

                      线条样式

                      方法说明
                      setLineWidth设置线条宽度
                      setLineCap设置线条端点的样式
                      setLineJoin设置两线相交处的样式
                      setMiterLimit设置最大倾斜

                      矩形

                      方法说明
                      rect创建一个矩形
                      fillRect填充一个矩形
                      strokeRect画一个矩形(不填充)
                      clearRect在给定的矩形区域内,清除画布上的像素

                      路径

                      方法说明
                      fill对当前路径进行填充
                      stroke对当前路径进行描边
                      beginPath开始一个路径
                      closePath关闭一个路径
                      moveTo把路径移动到画布中的指定点,但不创建线条。
                      lineTo添加一个新点,然后在画布中创建从该点到最后指定点的线条。
                      arc添加一个弧形路径到当前路径,顺时针绘制。
                      quadraticCurveTo创建二次方贝塞尔曲线
                      bezierCurveTo创建三次方贝塞尔曲线

                      变形

                      方法说明
                      scale对横纵坐标进行缩放
                      rotate对坐标轴进行顺时针旋转
                      translate对坐标原点进行缩放

                      文字

                      方法说明
                      fillText在画布上绘制被填充的文本
                      setFontSize设置字体大小
                      setTextBaseline设置字体基准线
                      setTextAlign设置字体对齐方式

                      图片

                      方法说明
                      drawImage在画布上绘制图像

                      混合

                      方法说明
                      setGlobalAlpha设置全局画笔透明度

                      其他

                      方法说明
                      save保存当前绘图上下文
                      restore恢复之前保过的绘图上下文
                      draw进行绘图
                      getActions(不推荐使用)获取当前context上存储的绘图动作
                      clearActions(不推荐使用)清空当前的存储绘图动作

                      微信小程序 canvas接口和方法绘图接口和方法


                      在Canvas上画图


                      所有在<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)

                      第三步:画图

                      告诉<canvas/>组件你要将刚刚的描述绘制上去:

                      ctx.draw()

                      结果:

                      微信小程序 绘图接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      Canvas 坐标系


                      canvas 是在一个二维的网格当中。

                      左上角的坐标为(0, 0)

                      在之前的章节,我们用了这个方法fillRect(0, 0, 150, 75)

                      它的含义为:从左上角(0, 0)开始,画一个150 x 75px 的矩形。

                      坐标系例子:

                      我们可以在<canvas/>中加上一些事件,来观测它的坐标系

                      <canvas canvas-id="myCanvas"  style="margin: 5px; border:1px solid #d3d3d3;"  bindtouchstart="start"  bindtouchmove="move"  bindtouchend="end"/><view hidden="{{hidden}}">  Coordinates: ({{x}}, {{y}})</view>
                      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    })  }})

                      当你把手指放到 canvas 中,就会在下边显示出触碰点的坐标:

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 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 gradientconst grd = ctx.createLinearGradient(0, 0, 200, 0)grd.addColorStop(0, 'red')grd.addColorStop(1, 'white')// Fill with gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()



                      使用 createCircularGradient()

                      const ctx = wx.createCanvasContext('myCanvas')// Create circular gradientconst grd = ctx.createCircularGradient(75, 50, 50)grd.addColorStop(0, 'red')grd.addColorStop(1, 'white')// Fill with gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      Color

                      可以用以下几种方式来表示 canvas 中使用的颜色:

                      • RGB 颜色:如'rgb(255, 0, 0)'
                      • RGBA 颜色:如'rgba(255, 0, 0, 0.3)'
                      • 16 进制颜色:如'#FF0000'
                      • 预定义的颜色:如'red'

                      其中预定义颜色有以下148个:

                      Note: Color Name 大小写不敏感

                      Color NameHEX
                      AliceBlue#F0F8FF
                      AntiqueWhite#FAEBD7
                      Aqua#00FFFF
                      Aquamarine#7FFFD4
                      Azure#F0FFFF
                      Beige#F5F5DC
                      Bisque#FFE4C4
                      Black#000000
                      BlanchedAlmond#FFEBCD
                      Blue#0000FF
                      BlueViolet#8A2BE2
                      Brown#A52A2A
                      BurlyWood#DEB887
                      CadetBlue#5F9EA0
                      Chartreuse#7FFF00
                      Chocolate#D2691E
                      Coral#FF7F50
                      CornflowerBlue#6495ED
                      Cornsilk#FFF8DC
                      Crimson#DC143C
                      Cyan#00FFFF
                      DarkBlue#00008B
                      DarkCyan#008B8B
                      DarkGoldenRod#B8860B
                      DarkGray#A9A9A9
                      DarkGrey#A9A9A9
                      DarkGreen#006400
                      DarkKhaki#BDB76B
                      DarkMagenta#8B008B
                      DarkOliveGreen#556B2F
                      DarkOrange#FF8C00
                      DarkOrchid#9932CC
                      DarkRed#8B0000
                      DarkSalmon#E9967A
                      DarkSeaGreen#8FBC8F
                      DarkSlateBlue#483D8B
                      DarkSlateGray#2F4F4F
                      DarkSlateGrey#2F4F4F
                      DarkTurquoise#00CED1
                      DarkViolet#9400D3
                      DeepPink#FF1493
                      DeepSkyBlue#00BFFF
                      DimGray#696969
                      DimGrey#696969
                      DodgerBlue#1E90FF
                      FireBrick#B22222
                      FloralWhite#FFFAF0
                      ForestGreen#228B22
                      Fuchsia#FF00FF
                      Gainsboro#DCDCDC
                      GhostWhite#F8F8FF
                      Gold#FFD700
                      GoldenRod#DAA520
                      Gray#808080
                      Grey#808080
                      Green#008000
                      GreenYellow#ADFF2F
                      HoneyDew#F0FFF0
                      HotPink#FF69B4
                      IndianRed#CD5C5C
                      Indigo#4B0082
                      Ivory#FFFFF0
                      Khaki#F0E68C
                      Lavender#E6E6FA
                      LavenderBlush#FFF0F5
                      LawnGreen#7CFC00
                      LemonChiffon#FFFACD
                      LightBlue#ADD8E6
                      LightCoral#F08080
                      LightCyan#E0FFFF
                      LightGoldenRodYellow#FAFAD2
                      LightGray#D3D3D3
                      LightGrey#D3D3D3
                      LightGreen#90EE90
                      LightPink#FFB6C1
                      LightSalmon#FFA07A
                      LightSeaGreen#20B2AA
                      LightSkyBlue#87CEFA
                      LightSlateGray#778899
                      LightSlateGrey#778899
                      LightSteelBlue#B0C4DE
                      LightYellow#FFFFE0
                      Lime#00FF00
                      LimeGreen#32CD32
                      Linen#FAF0E6
                      Magenta#FF00FF
                      Maroon#800000
                      MediumAquaMarine#66CDAA
                      MediumBlue#0000CD
                      MediumOrchid#BA55D3
                      MediumPurple#9370DB
                      MediumSeaGreen#3CB371
                      MediumSlateBlue#7B68EE
                      MediumSpringGreen#00FA9A
                      MediumTurquoise#48D1CC
                      MediumVioletRed#C71585
                      MidnightBlue#191970
                      MintCream#F5FFFA
                      MistyRose#FFE4E1
                      Moccasin#FFE4B5
                      NavajoWhite#FFDEAD
                      Navy#000080
                      OldLace#FDF5E6
                      Olive#808000
                      OliveDrab#6B8E23
                      Orange#FFA500
                      OrangeRed#FF4500
                      Orchid#DA70D6
                      PaleGoldenRod#EEE8AA
                      PaleGreen#98FB98
                      PaleTurquoise#AFEEEE
                      PaleVioletRed#DB7093
                      PapayaWhip#FFEFD5
                      PeachPuff#FFDAB9
                      Peru#CD853F
                      Pink#FFC0CB
                      Plum#DDA0DD
                      PowderBlue#B0E0E6
                      Purple#800080
                      RebeccaPurple#663399
                      Red#FF0000
                      RosyBrown#BC8F8F
                      RoyalBlue#4169E1
                      SaddleBrown#8B4513
                      Salmon#FA8072
                      SandyBrown#F4A460
                      SeaGreen#2E8B57
                      SeaShell#FFF5EE
                      Sienna#A0522D
                      Silver#C0C0C0
                      SkyBlue#87CEEB
                      SlateBlue#6A5ACD
                      SlateGray#708090
                      SlateGrey#708090
                      Snow#FFFAFA
                      SpringGreen#00FF7F
                      SteelBlue#4682B4
                      Tan#D2B48C
                      Teal#008080
                      Thistle#D8BFD8
                      Tomato#FF6347
                      Turquoise#40E0D0
                      Violet#EE82EE
                      Wheat#F5DEB3
                      White#FFFFFF
                      WhiteSmoke#F5F5F5
                      Yellow#FFFF00
                      YellowGreen#9ACD32

                      微信小程序 canvas接口和方法绘图接口和方法


                      wx.createCanvasContext(canvasId)


                      定义

                      创建 canvas 绘图上下文(指定 canvasId)

                      Tip: 需要指定 canvasId,该绘图上下文只作用于对应的<canvas/>

                      参数

                      参数类型说明
                      canvasIdString画布表示,传入定义在<canvas/>的 canvas-id

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      wx.createContext (不推荐使用)


                      创建并返回绘图上下文。

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      drawCanvas (不推荐使用)


                      定义

                      用所提供的 actions 在所给的 canvas-id 对应的 canvas 上进行绘图。

                      参数

                      参数类型说明
                      canvasIdString画布标识,传入<canvas/>的 cavas-id
                      actionsArray绘图动作数组,由 wx.createContext 创建的 context,调用 getActions 方法导出绘图动作数组。
                      reserveBoolean(可选)本次绘制是否接着上一次绘制,即reserve参数为false,则在本次调用drawCanvas绘制之前native层应先清空画布再继续绘制;若reserver参数为true,则保留当前画布上的内容,本次调用drawCanvas绘制的内容覆盖在上面,默认 false

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      wx.canvasToTempFilePath(OBJECT)


                      把当前画布指定区域的内容导出生成指定大小的图片,并返回文件路径。

                      OBJECT参数说明:

                      参数类型必填说明最低版本
                      xNumber画布x轴起点(默认0)1.2.0
                      yNumber画布y轴起点(默认0)1.2.0
                      widthNumber画布宽度(默认为canvas宽度-x)1.2.0
                      heightNumber画布高度(默认为canvas高度-y)1.2.0
                      destWidthNumber输出图片宽度(默认为width)1.2.0
                      destHeightNumber输出图片高度(默认为height)1.2.0
                      canvasIdString画布标识,传入 <canvas/> 的 cavas-id
                      fileTypeString目标文件的类型,只支持 'jpg' 或 'png'。默认为 'png'1.7.0
                      qualityNumber图片的质量,取值范围为 (0, 1],不在范围内时当作1.0处理1.7.0
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)


                      示例代码

                      wx.canvasToTempFilePath({  x: 100,  y: 200,  width: 50,  height: 50,  destWidth: 100,  destHeight: 100,  canvasId: 'myCanvas',  success: function(res) {    console.log(res.tempFilePath)  } })

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.setFillStyle


                      定义

                      设置填充色。

                      Tip: 如果没有设置fillStyle,默认颜色为black

                      参数

                      参数类型定义 
                      colorColor Gradient Object填充色

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')ctx.setFillStyle('red')ctx.fillRect(10, 10, 150, 75)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.setStrokeStyle


                      定义

                      设置边框颜色。

                      Tip: 如果没有设置fillStyle,默认颜色为black

                      参数

                      参数类型定义 
                      colorColorGradient Object填充色

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')ctx.setStrokeStyle('red')ctx.strokeRect(10, 10, 150, 75)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.setShadow


                      定义

                      设置阴影样式。

                      Tip: 如果没有设置,offsetX 默认值为0, offsetY 默认值为0, blur 默认值为0,color 默认值为black

                      参数

                      参数类型范围定义
                      offsetXNumber 阴影相对于形状在水平方向的偏移
                      offsetYNumber 阴影相对于形状在竖直方向的偏移
                      blurNumber0~100阴影的模糊级别,数值越大越模糊
                      colorColor 阴影的颜色

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')ctx.setFillStyle('red')ctx.setShadow(10, 50, 50, 'blue')ctx.fillRect(10, 10, 150, 75)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.createLinearGradient


                      定义

                      创建一个线性的渐变颜色。

                      Tip: 需要使用addColorStop()来指定渐变点,至少要两个。

                      参数

                      参数类型定义
                      x0Number起点的x坐标
                      y0Number起点的y坐标
                      x1Number终点的x坐标
                      y1Number终点的y坐标

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')// Create linear gradientconst grd = ctx.createLinearGradient(0, 0, 200, 0)grd.addColorStop(0, 'red')grd.addColorStop(1, 'white')// Fill with gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.createCircularGradient


                      定义

                      创建一个圆形的渐变颜色。

                      Tip: 起点在圆心,终点在圆环。

                      Tip: 需要使用addColorStop()来指定渐变点,至少要两个。

                      参数

                      参数类型定义
                      xNumber圆心的x坐标
                      yNumber圆心的y坐标
                      rNumber圆的半径

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')// Create circular gradientconst grd = ctx.createCircularGradient(75, 50, 50)grd.addColorStop(0, 'red')grd.addColorStop(1, 'white')// Fill with gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.addColorStop


                      定义

                      创建一个颜色的渐变点。

                      Tip: 小于最小 stop 的部分会按最小 stop 的 color 来渲染,大于最大 stop 的部分会按最大 stop 的 color 来渲染。

                      Tip: 需要使用addColorStop()来指定渐变点,至少要两个。

                      参数

                      参数类型定义
                      stopNumber(0-1)表示渐变点在起点和终点中的位置
                      colorColor渐变点的颜色

                      例子

                      const ctx = wx.crateCanvasContext('myCanvas')// Create circular gradientconst grd = ctx.createCircularGradient(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 gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.setLineWidth


                      定义

                      设置线条的宽度。

                      参数

                      参数类型说明
                      lineWidthNumber线条的宽度(单位是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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.setLineCap


                      定义

                      设置线条的端点样式。

                      参数

                      参数类型范围说明
                      lineCapString'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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.setLineJoin


                      定义

                      设置线条的交点样式。

                      参数

                      参数类型范围说明
                      lineJoinString'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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.setMiterLimit


                      定义

                      设置最大斜接长度,斜接长度指的是在两条线交汇处内角和外角之间的距离。 当setLineJoin()为 miter 时才有效。超过最大倾斜长度的,连接处将以 lineJoin 为 bevel 来显示

                      参数

                      参数类型说明
                      miterLimitNumber最大斜接长度

                      例子

                      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()

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.rect


                      定义

                      创建一个矩形。

                      Tip: 用fill()或者stroke()方法将矩形真正的画到 canvas 中。

                      参数

                      参数类型说明
                      xNumber矩形路径左上角的x坐标
                      yNumber矩形路径左上角的y坐标
                      widthNumber矩形路径的宽度
                      heightNumber矩形路径的高度

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')ctx.rect(10, 10, 150, 75)ctx.setFillStyle('red')ctx.fill()ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.fillRect


                      定义

                      填充一个矩形。

                      Tip: 用setFillStyle()设置矩形的填充色,如果没设置默认是黑色。

                      参数

                      参数类型说明
                      xNumber矩形路径左上角的x坐标
                      yNumber矩形路径左上角的y坐标
                      widthNumber矩形路径的宽度
                      heightNumber矩形路径的高度

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')ctx.setFillStyle('red')ctx.fillRect(10, 10, 150, 75)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.strokeRect


                      定义

                      画一个矩形(非填充)。

                      Tip:setFillStroke()设置矩形线条的颜色,如果没设置默认是黑色。

                      参数

                      参数类型范围说明
                      xNumber 矩形路径左上角的x坐标
                      yNumber 矩形路径左上角的y坐标
                      widthNumber 矩形路径的宽度
                      heightNumber 矩形路径的高度

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')ctx.setStrokeStyle('red')ctx.strokeRect(10, 10, 150, 75)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.clearRect


                      定义

                      清除画布上在该矩形区域内的内容。

                      Tip: clearRect 并非画一个白色的矩形在地址区域,而是清空,为了有直观感受,对 canvas 加了一层背景色。

                      <canvas canvas-id="myCanvas" style="border: 1px solid; background: #123456;"/>

                      参数

                      参数类型说明
                      xNumber矩形区域左上角的x坐标
                      yNumber矩形区域左上角的y坐标
                      widthNumber矩形区域的宽度
                      heightNumber矩形区域的高度

                      例子

                      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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.fill


                      定义

                      对当前路径中的内容进行填充。默认的填充色为黑色。

                      Tip: 如果当前路径没有闭合,fill()方法会将起点和终点进行连接,然后填充,详情见例一。

                      Tip: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 pathctx.rect(10, 10, 100, 30)ctx.setFillStyle('yellow')ctx.fill()// begin another pathctx.beginPath()ctx.rect(10, 40, 100, 30)// only fill this rect, not in current pathctx.setFillStyle('blue')ctx.fillRect(10, 70, 100, 30)ctx.rect(10, 100, 100, 30)// it will fill current pathctx.setFillStyle('red')ctx.fill()ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      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 pathctx.rect(10, 10, 100, 30)ctx.setStrokeStyle('yellow')ctx.stroke()// begin another pathctx.beginPath()ctx.rect(10, 40, 100, 30)// only stoke this rect, not in current pathctx.setStrokeStyle('blue')ctx.strokeRect(10, 70, 100, 30)ctx.rect(10, 100, 100, 30)// it will stroke current pathctx.setStrokeStyle('red')ctx.stroke()ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.beginPath


                      定义

                      开始创建一个路径,需要调用fill或者stroke才会使用路径进行填充或描边。

                      Tip: 在最开始的时候相当于调用了一次beginPath()

                      Tip: 同一个路径内的多次setFillStyle()setStrokeStyle()setLineWidth()等设置,以最后一次设置为准。

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')// begin pathctx.rect(10, 10, 100, 30)ctx.setFillStyle('yellow')ctx.fill()// begin another pathctx.beginPath()ctx.rect(10, 40, 100, 30)// only fill this rect, not in current pathctx.setFillStyle('blue')ctx.fillRect(10, 70, 100, 30)ctx.rect(10, 100, 100, 30)// it will fill current pathctx.setFillStyle('red')ctx.fill()ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.closePath


                      定义

                      关闭一个路径

                      Tip: 关闭路径会连接起点和终点。

                      Tip: 如果关闭路径后没有调用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 pathctx.rect(10, 10, 100, 30)ctx.closePath()// begin another pathctx.beginPath()ctx.rect(10, 40, 100, 30)// only fill this rect, not in current pathctx.setFillStyle('blue')ctx.fillRect(10, 70, 100, 30)ctx.rect(10, 100, 100, 30)// it will fill current pathctx.setFillStyle('red')ctx.fill()ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.moveTo


                      定义

                      把路径移动到画布中的指定点,不创建线条。

                      Tip: 用stroke()方法来画线条

                      参数

                      参数类型说明
                      xNumber目标位置的x坐标
                      yNumber目标位置的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()

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.lineTo


                      定义

                      lineTo方法增加一个新点,然后创建一条从上次指定点到目标点的线。

                      Tip: 用stroke()方法来画线条

                      参数

                      参数类型说明
                      xNumber目标位置的x坐标
                      yNumber目标位置的y坐标

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')ctx.moveTo(10, 10)ctx.rect(10, 10, 100, 50)ctx.lineTo(110, 60)ctx.stroke()ctx.draw()

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      canvasContext.arc


                      定义

                      画一条弧线。

                      Tip: 创建一个圆可以用arc()方法指定起始弧度为0,终止弧度为2 * Math.PI

                      Tip: 用stroke()或者fill()方法来在 canvas 中画弧线。

                      参数

                      参数类型说明
                      xNumber圆的x坐标
                      yNumber圆的y坐标
                      rNumber圆的半径
                      sAngleNumber起始弧度,单位弧度(在3点钟方向)
                      eAngleNumber终止弧度
                      counterclockwiseBoolean可选。指定弧度的方向是逆时针还是顺时针。默认是false,即顺时针。

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')// Draw coordinatesctx.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 pointsctx.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 arcctx.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)

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.quadraticCurveTo


                      定义

                      创建二次贝塞尔曲线路径。

                      Tip: 曲线的起始点为路径中前一个点。

                      参数

                      参数类型说明
                      cpxNumber贝塞尔控制点的x坐标
                      cpyNumber贝塞尔控制点的y坐标
                      xNumber结束点的x坐标
                      yNumber结束点的y坐标

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')// Draw pointsctx.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 guidesctx.beginPath()ctx.moveTo(20, 20)ctx.lineTo(20, 100)ctx.lineTo(200, 20)ctx.setStrokeStyle('#AAAAAA')ctx.stroke()// Draw quadratic curvectx.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)

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.bezierCurveTo


                      定义

                      创建三次方贝塞尔曲线路径。

                      Tip: 曲线的起始点为路径中前一个点。

                      参数

                      参数类型说明
                      cp1xNumber第一个贝塞尔控制点的 x 坐标
                      cp1yNumber第一个贝塞尔控制点的 y 坐标
                      cp2xNumber第二个贝塞尔控制点的 x 坐标
                      cp2yNumber第二个贝塞尔控制点的 y 坐标
                      xNumber结束点的 x 坐标
                      yNumber结束点的 y 坐标

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')// Draw pointsctx.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 guidesctx.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 curvectx.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)

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.scale


                      定义

                      在调用scale方法后,之后创建的路径其横纵坐标会被缩放。多次调用scale,倍数会相乘。

                      参数

                      参数类型说明
                      scaleWidthNumber横坐标缩放的倍数 (1 = 100%,0.5 = 50%,2 = 200%)
                      scaleHeightNumber纵坐标轴缩放的倍数 (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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.rotate


                      定义

                      以原点为中心,原点可以用 translate方法修改。顺时针旋转当前坐标轴。多次调用rotate,旋转的角度会叠加。

                      参数

                      参数类型说明
                      rotateNumber旋转角度,以弧度计(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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.translate


                      定义

                      对当前坐标系的原点(0, 0)进行变换,默认的坐标系原点为页面左上角。

                      参数

                      参数类型说明
                      xNumber水平坐标平移量
                      yNumber竖直坐标平移量

                      例子

                      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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.setFontSize


                      定义

                      设置字体的字号。

                      参数

                      参数类型说明
                      fontSizeNumber字体的字号

                      例子

                      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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      绘图接口和方法

                      canvasContext.fillText


                      定义

                      在画布上绘制被填充的文本。

                      参数

                      string text

                      在画布上输出的文本

                      number x

                      绘制文本的左上角 x 坐标位置

                      number y

                      绘制文本的左上角 y 坐标位置

                      number maxWidth

                      需要绘制的最大宽度,可选

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')ctx.setFontSize(20)ctx.fillText('Hello', 20, 20)ctx.fillText('MINA', 100, 100)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法


                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.setTextAlign


                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      定义

                      用于设置文字的对齐

                      参数

                      参数类型定义
                      alignString可选值 '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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.setTextBaseline

                      基础库 1.4.0 开始支持,低版本需做兼容处理

                      定义

                      用于设置文字的水平对齐

                      参数

                      参数类型定义
                      textBaselineString可选值 '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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.drawImage


                      定义

                      绘制图像,图像保持原始尺寸。

                      参数

                      参数类型说明
                      imageResourceString所要绘制的图片资源
                      xNumber图像左上角的x坐标
                      yNumber图像左上角的y坐标
                      widthNumber图像宽度
                      heightNumber图像高度

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')wx.chooseImage({  success: function(res){    ctx.drawImage(res.tempFilePaths[0], 0, 0, 150, 100)    ctx.draw()  }})

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.setGlobalAlpha


                      定义

                      设置全局画笔透明度。

                      参数

                      参数类型范围说明
                      alphaNumber0~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()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.save


                      定义

                      保存当前的绘图上下文。

                      restore


                      定义

                      恢复之前保存的绘图上下文。

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')// save the default fill stylectx.save() ctx.setFillStyle('red')ctx.fillRect(10, 10, 150, 100)// restore to the previous saved statectx.restore()ctx.fillRect(50, 50, 150, 100)ctx.draw()


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.draw


                      定义

                      将之前在绘图上下文中的描述(路径、变形、样式)画到 canvas 中。

                      Tip: 绘图上下文需要由wx.createCanvasContext(canvasId)来创建。

                      参数

                      参数类型说明最低版本
                      reserveBoolean非必填。本次绘制是否接着上一次绘制,即reserve参数为false,则在本次调用drawCanvas绘制之前native层应先清空画布再继续绘制;若reserver参数为true,则保留当前画布上的内容,本次调用drawCanvas绘制的内容覆盖在上面,默认 false
                      callbackFunction绘制完成后回调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)


                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法


                      getActions (不推荐使用)


                      返回绘图上下文的绘图动作。

                      微信小程序 canvas接口和方法绘图接口和方法

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.clearActions (不推荐使用)


                      清空绘图上下文的绘图动作。

                      微信小程序 canvas接口和方法绘图接口和方法

                      canvasContext.measureText


                      基础库 1.9.90 开始支持,低版本需做兼容处理

                      定义

                      测量文本尺寸信息,目前仅返回文本宽度。同步接口。

                      参数

                      参数类型说明
                      textString要测量的文本

                      返回

                      返回 TextMetrics 对象,结构如下:

                      参数类型说明
                      widthNumber文本的宽度

                      例子

                      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

                      参数

                      属性值类型说明
                      typeString标识要使用哪种合成或混合模式操作

                      type 支持的操作有:

                      平台操作
                      安卓xor, source-over, source-atop, destination-out, lighter, overlay, darken, lighten, hard-light
                      iOSxor, 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

                      canvasContext.arcTo


                      基础库 1.9.90 开始支持,低版本需做兼容处理

                      定义

                      根据控制点和半径绘制圆弧路径。

                      语法

                      canvasContext.arcTo(x1, y1, x2, y2, radius)

                      参数

                      属性值类型说明
                      x1Number第一个控制点的 x 轴坐标
                      y1Number第一个控制点的 y 轴坐标
                      x2Number第二个控制点的 x 轴坐标
                      y2Number第二个控制点的 y 轴坐标
                      radiusNumber圆弧的半径

                      canvasContext.strokeText


                      基础库 1.9.90 开始支持,低版本需做兼容处理

                      定义

                      给定的 (x, y) 位置绘制文本描边的方法

                      语法

                      canvasContext.strokeText(text, x, y, maxWidth)

                      参数

                      属性值类型说明
                      textString要绘制的文本
                      xNumber文本起始点的 x 轴坐标
                      yNumber文本起始点的 y 轴坐标
                      maxWidthNumber需要绘制的最大宽度,可选

                      canvasContext.lineDashOffset


                      基础库 1.9.90 开始支持,低版本需做兼容处理

                      定义

                      设置虚线偏移量的属性

                      语法

                      canvasContext.lineDashOffset = value

                      参数

                      属性值类型说明
                      valueNumber偏移量,初始值为 0

                      canvasContext.createPattern


                      基础库 1.9.90 开始支持,低版本需做兼容处理

                      定义

                      对指定的图像创建模式的方法,可在指定的方向上重复元图像

                      语法

                      canvasContext.createPattern(image, repetition)

                      参数

                      属性值类型说明
                      imageString重复的图像源,仅支持包内路径和临时路径
                      repetitionString指定如何重复图像,有效值有: repeat, repeat-x, repeat-y, no-repeat

                      例子

                      const ctx = wx.createCanvasContext('myCanvas')const pattern = ctx.createPattern('/path/to/image', 'repeat-x')ctx.fillStyle = patternctx.fillRect(0, 0, 300, 150)ctx.draw()

                      onPullDownRefresh


                      在 Page 中定义 onPullDownRefresh 处理函数,监听该页面用户下拉刷新事件。

                      • 需要在configwindow选项中开启enablePullDownRefresh
                      • 当处理完数据刷新后,wx.stopPullDownRefresh可以停止当前页面的下拉刷新。

                      wx.startPullDownRefresh(OBJECT)

                      基础库 1.5.0 开始支持,低版本需做兼容处理

                      开始下拉刷新,调用后触发下拉刷新动画,效果与用户手动下拉刷新一致

                      Object参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      errMsgString接口调用结果

                      示例代码:

                      wx.startPullDownRefresh()

                      wx.stopPullDownRefresh()

                      停止当前页面下拉刷新。

                      示例代码:

                      Page({  onPullDownRefresh: function(){    wx.stopPullDownRefresh()  }})


                      wx.setBackgroundTextStyle(Object object)

                      基础库 2.1.0 开始支持,低版本需做兼容处理

                      动态设置下拉背景字体、loading 图的样式

                      参数

                      Object object

                      属性类型默认值必填说明
                      textStylestring下拉背景字体、loading 图的样式。
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.textStyle 的合法值

                      说明最低版本
                      darkdark 样式
                      lightlight 样式

                      示例代码

                      wx.setBackgroundTextStyle({  textStyle: 'dark' // 下拉背景字体、loading 图的样式为dark})

                      wx.setBackgroundColor(Object object)

                      基础库 2.1.0 开始支持,低版本需做兼容处理

                      动态设置窗口的背景色

                      参数

                      Object object

                      属性类型默认值必填说明
                      backgroundColorstring窗口的背景色,必须为十六进制颜色值
                      backgroundColorTopstring顶部窗口的背景色,必须为十六进制颜色值,仅 iOS 支持
                      backgroundColorBottomstring底部窗口的背景色,必须为十六进制颜色值,仅 iOS 支持
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.setBackgroundColor({  backgroundColor: '#ffffff', // 窗口的背景色为白色})wx.setBackgroundColor({  backgroundColorTop: '#ffffff', // 顶部窗口的背景色为白色  backgroundColorBottom: '#ffffff', // 底部窗口的背景色为白色})


                      wx.pageScrollTo(Object object)

                      基础库 1.4.0 开始支持,低版本需做兼容处理

                      将页面滚动到目标位置,支持选择器和滚动距离两种方式定位

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      scrollTopnumber滚动到页面的目标位置,单位 px
                      durationnumber300滚动动画的时长,单位 ms
                      selectorstring选择器2.7.3
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      selector 语法

                      selector类似于 CSS 的选择器,但仅支持下列语法。

                      • ID选择器:#the-id
                      • class选择器(可以连续指定多个):.a-class.another-class
                      • 子元素选择器:.the-parent > .the-child
                      • 后代选择器:.the-ancestor .the-descendant
                      • 跨自定义组件的后代选择器:.the-ancestor >>> .the-descendant
                      • 多选择器的并集:#a-node, .some-other-nodes

                      示例代码

                      wx.pageScrollTo({  scrollTop: 0,  duration: 300})


                      wx.loadFontFace(Object object)

                      基础库 2.1.0 开始支持,低版本需做兼容处理

                      动态加载网络字体,文件地址需为下载类型。'2.10.0'起支持全局生效,需在 app.js 中调用。

                      注意:

                      1. 字体文件返回的 contet-type 参考 font,格式不正确时会解析失败。
                      2. 字体链接必须是https(ios不支持http)
                      3. 字体链接必须是同源下的,或开启了cors支持,小程序的域名是servicewechat.com
                      4. canvas等原生组件不支持使用接口添加的字体
                      5. 工具里提示 Faild to load font可以忽略
                      6. '2.10.0' 以前仅在调用页面生效。

                      参数

                      Object object

                      属性类型默认值必填说明最低版本
                      globalbooleanfalse是否全局生效2.10.0
                      familystring定义的字体名称
                      sourcestring字体资源的地址。建议格式为 TTF 和 WOFF,WOFF2 在低版本的iOS上会不兼容。
                      descObject可选的字体描述符
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.desc 的结构

                      属性类型默认值必填说明
                      stylestring'normal'字体样式,可选值为 normal / italic / oblique
                      weightstring'normal'字体粗细,可选值为 normal / bold / 100 / 200../ 900
                      variantstring'normal'设置小型大写字母的字体显示文本,可选值为 normal / small-caps / inherit

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      statusstring加载字体结果

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      statusstring加载字体结果

                      object.complete 回调函数

                      参数
                      Object res
                      属性类型说明
                      statusstring加载字体结果

                      示例代码

                      在开发者工具中预览效果

                      wx.loadFontFace({  family: 'Bitstream Vera Serif Bold',  source: 'url("https://sungd.github.io/Pacifico.ttf")',  success: console.log})


                      wx.showTabBarRedDot(Object object)

                      基础库 1.9.0 开始支持,低版本需做兼容处理

                      显示 tabBar 某一项的右上角的红点

                      参数

                      Object object

                      属性类型默认值必填说明
                      indexnumbertabBar 的哪一项,从左边算起
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      wx.showTabBar(Object object)

                      基础库 1.9.0 开始支持,低版本需做兼容处理

                      显示 tabBar

                      参数

                      Object object

                      属性类型默认值必填说明
                      animationbooleanfalse是否需要动画效果
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)




                      wx.setTabBarStyle(Object object)

                      基础库 1.9.0 开始支持,低版本需做兼容处理

                      动态设置 tabBar 的整体样式

                      参数

                      Object object

                      属性类型默认值必填说明
                      colorstringtab 上的文字默认颜色,HexColor
                      selectedColorstringtab 上的文字选中时的颜色,HexColor
                      backgroundColorstringtab 的背景色,HexColor
                      borderStylestringtabBar上边框的颜色, 仅支持 black/white
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.setTabBarStyle({  color: '#FF0000',  selectedColor: '#00FF00',  backgroundColor: '#0000FF',  borderStyle: 'white'})




                      wx.setTabBarItem(Object object)

                      基础库 1.9.0 开始支持,低版本需做兼容处理

                      动态设置 tabBar 某一项的内容,2.7.0 起图片支持临时文件和网络文件。

                      参数

                      Object object

                      属性类型默认值必填说明
                      indexnumbertabBar 的哪一项,从左边算起
                      textstringtab 上的按钮文字
                      iconPathstring图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px,当 postion 为 top 时,此参数无效
                      selectedIconPathstring选中时的图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px ,当 postion 为 top 时,此参数无效
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.setTabBarItem({  index: 0,  text: 'text',  iconPath: '/path/to/iconPath',  selectedIconPath: '/path/to/selectedIconPath'})




                      wx.setTabBarBadge(Object object)

                      基础库 1.9.0 开始支持,低版本需做兼容处理

                      为 tabBar 某一项的右上角添加文本

                      参数

                      Object object

                      属性类型默认值必填说明
                      indexnumbertabBar 的哪一项,从左边算起
                      textstring显示的文本,超过 4 个字符则显示成 ...
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.setTabBarBadge({  index: 0,  text: '1'})




                      wx.removeTabBarBadge(Object object)

                      基础库 1.9.0 开始支持,低版本需做兼容处理

                      移除 tabBar 某一项右上角的文本

                      参数

                      Object object

                      属性类型默认值必填说明
                      indexnumbertabBar 的哪一项,从左边算起
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)




                      wx.hideTabBarRedDot(Object object)

                      基础库 1.9.0 开始支持,低版本需做兼容处理

                      隐藏 tabBar 某一项的右上角的红点

                      参数

                      Object object

                      属性类型默认值必填说明
                      indexnumbertabBar 的哪一项,从左边算起
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)




                      wx.hideTabBar(Object object)

                      基础库 1.9.0 开始支持,低版本需做兼容处理

                      隐藏 tabBar

                      参数

                      Object object

                      属性类型默认值必填说明
                      animationbooleanfalse是否需要动画效果
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      wx.setWindowSize(Object object)

                      基础库 2.10.1 开始支持,低版本需做兼容处理
                      从基础库 2.11.0 开始,本接口停止维护

                      设置窗口大小,该接口仅适用于 PC 平台,使用细则请参见指南

                      参数

                      Object object

                      属性类型默认值必填说明
                      widthnumber窗口宽度,以像素为单位
                      heightnumber窗口高度,以像素为单位
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)




                      wx.onWindowResize(function callback)

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      监听窗口尺寸变化事件

                      参数

                      function callback

                      窗口尺寸变化事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      sizeObject

                      size 的结构

                      属性类型说明
                      windowWidthnumber变化后的窗口宽度,单位 px
                      windowHeightnumber变化后的窗口高度,单位 px




                      wx.offWindowResize(function callback)

                      基础库 2.3.0 开始支持,低版本需做兼容处理

                      取消监听窗口尺寸变化事件

                      参数

                      function callback

                      窗口尺寸变化事件的回调函数


                      Object wx.getMenuButtonBoundingClientRect()

                      基础库 2.1.0 开始支持,低版本需做兼容处理

                      获取菜单按钮(右上角胶囊按钮)的布局位置信息。坐标信息以屏幕左上角为原点。

                      返回值

                      Object

                      菜单按钮的布局位置信息

                      属性类型说明
                      widthnumber宽度,单位:px
                      heightnumber高度,单位:px
                      topnumber上边界坐标,单位:px
                      rightnumber右边界坐标,单位:px
                      bottomnumber下边界坐标,单位:px
                      leftnumber左边界坐标,单位:px


                      wx.createSelectorQuery()

                      基础库 1.4.0 开始支持,低版本需做兼容处理

                      返回一个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 对象的方法列表:

                      方法参数说明
                      selectselector参考下面详细介绍
                      selectAllselector参考下面详细介绍
                      selectViewport 参考下面详细介绍
                      exec[callback]参考下面详细介绍

                      selectorQuery.select(selector)

                      在当前页面下选择第一个匹配选择器selector的节点,返回一个NodesRef对象实例,可以用于获取节点信息。

                      selector类似于CSS的选择器,但仅支持下列语法。

                      • ID选择器:#the-id
                      • class选择器(可以连续指定多个):.a-class.another-class
                      • 子元素选择器:.the-parent > #the-child.a-class
                      • 多选择器的并集:#a-node, .some-other-nodes

                      selectorQuery.selectAll(selector)

                      在当前页面下选择匹配选择器selector的节点,返回一个NodesRef对象实例。 与selectorQuery.selectNode(selector)不同的是,它选择所有匹配选择器的节点。

                      selectorQuery.selectViewport()

                      选择显示区域,可用于获取显示区域的尺寸、滚动位置等信息,返回一个NodesRef对象实例。

                      nodesRef.boundingClientRect([callback])

                      添加节点的布局位置的查询请求,相对于显示区域,以像素为单位。其功能类似于DOM的getBoundingClientRect。返回值是nodesRef对应的selectorQuery。

                      返回的节点信息中,每个节点的位置用leftrighttopbottomwidthheight字段描述。如果提供了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。

                      返回的节点信息中,每个节点的滚动位置用scrollLeftscrollHeight字段描述。如果提供了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 和事件绑定的属性值不可获取)

                      示例代码:

                      Page({  getFields: function(){    wx.createSelectorQuery().select('#the-id').fields({      dataset: true,      size: true,      scrollOffset: true,      properties: ['scrollX', 'scrollY']    }, function(res){      res.dataset    // 节点的dataset      res.width      // 节点的宽度      res.height     // 节点的高度      res.scrollLeft // 节点的水平滚动位置      res.scrollTop  // 节点的竖直滚动位置      res.scrollX    // 节点 scroll-x 属性的当前值      res.scrollY    // 节点 scroll-x 属性的当前值    }).exec()  }})

                      selectorQuery.exec([callback])

                      执行所有的请求,请求结果按请求次序构成数组,在callback的第一个参数中返回。

                      wx.getExtConfig(OBJECT)

                      基础库 1.1.0 开始支持,低版本需做兼容处理

                      获取第三方平台自定义的数据字段。

                      OBJECT参数说明:

                      参数类型必填返回
                      successFunction返回第三方平台自定义的数据
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数类型说明
                      errMsgString调用结果
                      extConfigObject第三方平台自定义的数据

                      Bug & Tip

                      1. wx.getExtConfig暂时无法通过wx.canIUse判断是否兼容,开发者需要自行判断wx.getExtConfig是否存在来兼容

                      示例代码:

                      if(wx.getExtConfig) {  wx.getExtConfig({    success: function (res) {      console.log(res.extConfig)    }  })}

                      wx.getExtConfigSync()

                      基础库 1.1.0 开始支持,低版本需做兼容处理

                      获取第三方平台自定义的数据字段的同步接口。

                      返回说明:

                      参数类型说明
                      extConfigObject第三方平台自定义的数据

                      Bug & Tip

                      1. wx.getExtConfigSync暂时无法通过wx.canIUse判断是否兼容,开发者需要自行判断wx.getExtConfigSync是否存在来兼容

                      示例代码:

                      let extConfig = wx.getExtConfigSync? wx.getExtConfigSync(): {}console.log(extConfig)

                      wx.login(OBJECT)


                      调用接口获取登录凭证(code)进而换取用户登录态信息,包括用户的唯一标识(openid) 及本次登录的 会话密钥(session_key)用户数据的加解密通讯需要依赖会话密钥完成。


                      OBJECT参数说明:

                      参数名类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      errMsgString调用结果
                      codeString用户允许登录后,回调内容会带上 code(有效期五分钟),开发者需要将 code 发送到开发者服务器后台,使用code 换取 session_key api,将 code 换成 openid 和 session_key

                      示例代码:

                      //app.jsApp({  onLaunch: function() {    wx.login({      success: function(res) {        if (res.code) {          //发起网络请求          wx.request({            url: 'https://test.com/onLogin',            data: {              code: res.code            }          })        } else {          console.log('获取用户登录态失败!' + res.errMsg)        }      }    });  }})

                      code 换取 session_key

                      ​这是一个 HTTPS 接口,开发者服务器使用登录凭证 code 获取 session_key 和 openid。其中 session_key 是对用户数据进行加密签名的密钥。为了自身应用安全,session_key 不应该在网络上传输

                      接口地址:

                      https://api.weixin.qq.com/sns/jscode2session?appid=APPID&secret=SECRET&js_code=JSCODE&grant_type=authorization_code

                      请求参数:

                      参数必填说明
                      appid小程序唯一标识
                      secret小程序的 app secret
                      js_code登录时获取的 code
                      grant_type填写为 authorization_code

                      返回参数:

                      参数说明
                      openid用户唯一标识
                      session_key会话密钥
                      unionid用户在开放平台的唯一标识符。本字段在满足一定条件的情况下才返回。具体参看UnionID机制说明

                      返回说明:

                      //正常返回的JSON数据包{      "openid": "OPENID",      "session_key": "SESSIONKEY"      "unionid":  "UNIONID"}//错误时返回JSON数据包(示例为Code无效){    "errcode": 40029,    "errmsg": "invalid code"}


                      wx.checkSession(OBJECT)


                      通过上述接口获得的用户登录态拥有一定的时效性。用户越久未使用小程序,用户登录态越有可能失效。反之如果用户一直在使用小程序,则用户登录态一直保持有效。具体时效逻辑由微信维护,对开发者透明。开发者只需要调用wx.checkSession接口检测当前用户登录态是否有效。登录态过期后开发者可以再调用wx.login获取新的用户登录态。

                      OBJECT参数说明:

                      参数名类型必填说明
                      successFunction接口调用成功的回调函数,登陆态未过期
                      failFunction接口调用失败的回调函数,登陆态已过期
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.checkSession({  success: function(){    //session 未过期,并且在本生命周期一直有效  },  fail: function(){    //登录态过期    wx.login() //重新登录    ....  }})


                      登录态维护

                      通过wx.login()获取到用户登录态之后,需要维护登录态。开发者要注意不应该直接把 session_key、openid 等字段作为用户的标识或者 session 的标识,而应该自己派发一个 session 登录态(请参考登录时序图)。对于开发者自己生成的 session,应该保证其安全性且不应该设置较长的过期时间。session 派发到小程序客户端之后,可将其存储在 storage ,用于后续通信使用。

                      通过wx.checkSession()检测用户登录态是否失效。并决定是否调用wx.login() 重新获取登录态

                      登录时序图

                      登录时序图


                      Bug & Tip

                      1. bug: iOS/Android 6.3.30,在 App.onLaunch 调用 wx.login 会出现异常;

                      用户数据的签名验证和加解密


                      数据签名校验

                      为了确保 开放接口 返回用户数据的安全性,微信会对明文数据进行签名。开发者可以根据业务需要对数据包进行签名校验,确保数据的完整性。

                      1. 签名校验算法涉及用户的session_key,通过 wx.login 登录流程获取用户session_key,并自行维护与应用自身登录态的对应关系。
                      2. 通过调用接口(如 wx.getUserInfo)获取数据时,接口会同时返回 rawData、signature,其中 signature = sha1( rawData + session_key )
                      3. 开发者将 signature、rawData 发送到开发者服务器进行校验。服务器利用用户对应的 session_key 使用相同的算法计算出签名 signature2 ,比对 signature 与 signature2 即可校验数据的完整性。

                      如wx.getUserInfo的数据校验:

                      接口返回的rawData:

                      {  "nickName": "Band",  "gender": 1,  "language": "zh_CN",  "city": "Guangzhou",  "province": "Guangdong",  "country": "CN",  "avatarUrl": "http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"}

                      用户的 session-key:

                      HyVFkGl5F5OQWJZZaNzBBg==

                      所以,用于签名的字符串为:

                      {"nickName":"Band","gender":1,"language":"zh_CN","city":"Guangzhou","province":"Guangdong","country":"CN","avatarUrl":"http://wx.qlogo.cn/mmopen/vi_32/1vZvI39NWFQ9XM4LtQpFrQJ1xlgZxx3w7bQxKARol6503Iuswjjn6nIGBiaycAjAtpujxyzYsrztuuICqIM5ibXQ/0"}HyVFkGl5F5OQWJZZaNzBBg==

                      使用sha1得到的结果为

                      75e81ceda165f4ffa64f4068af58c64b8f54b88c

                      加密数据解密算法

                      接口如果涉及敏感数据(如wx.getUserInfo当中的 openId 和unionId ),接口的明文内容将不包含这些敏感数据。开发者如需要获取敏感数据,需要对接口返回的加密数据( encryptedData )进行对称解密。解密算法如下:

                      1. 对称解密使用的算法为 AES-128-CBC,数据采用PKCS#7填充。
                      2. 对称解密的目标密文为 Base64_Decode(encryptedData),
                      3. 对称解密秘钥 aeskey = Base64_Decode(session_key), aeskey 是16字节
                      4. 对称解密算法初始向量 iv 会在数据接口中返回。

                      微信官方提供了多种编程语言的示例代码(点击下载)。每种语言类型的接口名字均一致。调用方式可以参照示例。

                      另外,为了应用能校验数据的有效性,我们会在敏感数据加上数据水印( watermark )

                      watermark参数说明:

                      参数类型说明
                      watermarkOBJECT数据水印
                      appidString敏感数据归属appid,开发者可校验此参数与自身appid是否一致
                      timestampDateInt敏感数据获取的时间戳, 开发者可以用于数据时效性校验

                      如接口wx.getUserInfo敏感数据当中的watermark:

                      {    "openId": "OPENID",    "nickName": "NICKNAME",    "gender": GENDER,    "city": "CITY",    "province": "PROVINCE",    "country": "COUNTRY",    "avatarUrl": "AVATARURL",    "unionId": "UNIONID",    "watermark":    {        "appid":"APPID",        "timestamp":TIMESTAMP    }}

                      注:此前提供的加密数据(encryptData)以及对应的加密算法将被弃用,请开发者不要再依赖旧逻辑。

                      wx.navigateToMiniProgram(OBJECT)


                      基础库 1.3.0 开始支持,低版本需做兼容处理

                      iOS 微信客户端 6.5.9 版本开始支持,Android 客户端即将在 6.5.10 版本开始支持,请先使用 iOS 客户端进行调试

                      打开同一公众号下关联的另一个小程序。

                      OBJECT参数说明:

                      参数名类型必填说明
                      appIdString要打开的小程序 appId
                      pathString打开的页面路径,如果为空则打开首页
                      extraDataObject需要传递给目标小程序的数据,目标小程序可在 App.onLaunch()App.onShow()中获取到这份数据。详情
                      envVersionString要打开的小程序版本,有效值 develop(开发版),trial(体验版),release(正式版) ,仅在当前小程序为开发版或体验版时此参数有效;如果当前小程序是体验版或正式版,则打开的小程序必定是正式版。默认值 release
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      errMsgString调用结果

                      示例代码:

                      wx.navigateToMiniProgram({  appId: '',  path: 'pages/index/index?id=123',  extraData: {    foo: 'bar'  },  envVersion: 'develop',  success(res) {    // 打开成功  }})

                      Bug & Tip

                      1. tip: 在开发者工具上调用此 API 并不会真实的跳转到另外的小程序,但是开发者工具会校验本次调用跳转是否成功详情
                      2. tip: 开发者工具上支持被跳转的小程序处理接收参数的调试详情
                      3. tip: 只有同一公众号下的关联的小程序之间才可相互跳转 详情

                      wx.navigateBackMiniProgram(OBJECT)


                      基础库 1.3.0 开始支持,低版本需做兼容处理

                      iOS 微信客户端 6.5.9 版本开始支持,Android 客户端即将在 6.5.10 版本开始支持,请先使用 iOS 客户端进行调试

                      返回到上一个小程序,只有在当前小程序是被其他小程序打开时可以调用成功

                      OBJECT参数说明:

                      参数名类型必填说明
                      extraDataObject需要返回给上一个小程序的数据,上一个小程序可在App.onShow()中获取到这份数据。详情
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      errMsgString调用结果

                      示例代码:

                      wx.navigateBackMiniProgram({  extraData: {    foo: 'bar'  },  success(res) {    // 返回成功  }})


                      Object wx.getAccountInfoSync()

                      基础库 2.2.2 开始支持,低版本需做兼容处理

                      获取当前帐号信息。线上小程序版本号仅支持在正式版小程序中获取,开发版和体验版中无法获取。

                      返回值

                      Object

                      帐号信息

                      属性类型说明
                      miniProgramObject小程序帐号信息
                      pluginObject插件帐号信息(仅在插件中调用时包含这一项)

                      miniProgram 的结构

                      属性类型说明最低版本
                      appIdstring小程序 appId
                      envVersionstring小程序版本2.10.0
                      versionstring线上小程序版本号2.10.2

                      miniProgram.envVersion 的合法值

                      说明最低版本
                      develop开发版
                      trial体验版
                      release正式版

                      plugin 的结构

                      属性类型说明
                      appIdstring插件 appId
                      versionstring插件版本号

                      示例代码

                      const accountInfo = wx.getAccountInfoSync();console.log(accountInfo.miniProgram.appId) // 小程序 appIdconsole.log(accountInfo.plugin.appId) // 插件 appIdconsole.log(accountInfo.plugin.version) // 插件版本号, 'a.b.c' 这样的形式


                      wx.getUserInfo(OBJECT)

                      ​获取用户信息,withCredentials 为 true 时需要先调用wx.login接口

                      OBJECT参数说明:

                      参数名类型必填说明最低版本
                      withCredentialsBoolean是否带上登录态信息1.1.0
                      langString指定返回用户信息的语言,zh_CN 简体中文,zh_TW 繁体中文,en 英文1.4.0
                      successFunction接口调用成功的回调函数 
                      failFunction接口调用失败的回调函数 
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行) 

                      注:当 withCredentials 为 true 时,要求此前有调用过 wx.login 且登录态尚未过期,此时返回的数据会包含 encryptedData, iv 等敏感信息;当 withCredentials 为 false 时,不要求有登录态,返回的数据不包含 encryptedData, iv 等敏感信息。

                      success返回参数说明:
                      参数类型说明
                      userInfoOBJECT用户信息对象,不包含 openid 等敏感信息
                      rawDataString不包括敏感信息的原始数据字符串,用于计算签名。
                      signatureString使用 sha1( rawData + sessionkey ) 得到字符串,用于校验用户信息,参考文档signature
                      encryptedDataString包括敏感数据在内的完整用户信息的加密数据,详细见加密数据解密算法
                      ivString加密算法的初始向量,详细见加密数据解密算法

                      示例代码:

                      wx.getUserInfo({  success: function(res) {    var userInfo = res.userInfo    var nickName = userInfo.nickName    var avatarUrl = userInfo.avatarUrl    var gender = userInfo.gender //性别 0:未知、1:男、2:女     var province = userInfo.province    var city = userInfo.city    var country = userInfo.country  }})

                      encryptedData 解密后为以下 json 结构,详见加密数据解密算法

                      {    "openId": "OPENID",    "nickName": "NICKNAME",    "gender": GENDER,    "city": "CITY",    "province": "PROVINCE",    "country": "COUNTRY",    "avatarUrl": "AVATARURL",    "unionId": "UNIONID",    "watermark":    {        "appid":"APPID",    "timestamp":TIMESTAMP    }}

                      Bug & Tip

                      1. tip:wx.getUserInfo接口需要用户授权,请兼容用户拒绝授权的场景。

                      UnionID机制说明:

                      如果开发者拥有多个移动应用、网站应用、和公众帐号(包括小程序),可通过unionid来区分用户的唯一性,因为只要是同一个微信开放平台帐号下的移动应用、网站应用和公众帐号(包括小程序),用户的unionid是唯一的。换句话说,同一用户,对同一个微信开放平台下的不同应用,unionid是相同的。

                      同一个微信开放平台下的相同主体的App、公众号、小程序,如果用户已经关注公众号,或者曾经登录过App或公众号,则用户打开小程序时,开发者可以直接通过wx.login获取到该用户UnionID,无须用户再次授权。

                      微信开放平台绑定小程序流程

                      前提:微信开放平台帐号必须已完成开发者资质认证

                      开发者资质认证流程:

                      登录微信开放平台(open.weixin.qq.com) – 帐号中心 – 开发者资质认证

                      绑定流程:

                      登录微信开放平台(open.weixin.qq.com)—管理中心—公众帐号—绑定公众帐号





                      wx.reportMonitor(string name, number value)

                      基础库 2.0.1 开始支持,低版本需做兼容处理

                      自定义业务数据监控上报接口。

                      参数

                      string name

                      监控ID,在「小程序管理后台」新建数据指标后获得

                      number value

                      上报数值,经处理后会在「小程序管理后台」上展示每分钟的上报总量

                      使用说明

                      使用前,需要在「小程序管理后台-运维中心-性能监控-业务数据监控」中新建监控事件,配置监控描述与告警类型。每一个监控事件对应唯一的监控ID,开发者最多可以创建128个监控事件。

                      示例代码

                      wx.reportMonitor('1', 1)


                      wx.reportAnalytics(string eventName, Object data)

                      自定义分析数据上报接口。使用前,需要在小程序管理后台自定义分析中新建事件,配置好事件名与字段。

                      参数

                      string eventName

                      事件名

                      Object data

                      上报的自定义数据,key 为配置中的字段名,value 为上报的数据。

                      示例代码

                      wx.reportAnalytics('purchase', {  price: 120,  color: 'red'})


                      wx.requestPayment(OBJECT)

                      发起微信支付。

                      Object参数说明:

                      参数类型必填说明
                      timeStampString时间戳从1970年1月1日00:00:00至今的秒数,即当前的时间
                      nonceStrString随机字符串,长度为32个字符以下。
                      packageString统一下单接口返回的 prepay_id 参数值,提交格式如:prepay_id=*
                      signTypeString签名算法,暂支持 MD5
                      paySignString签名,具体签名方案参见小程序支付接口文档;
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      了解更多信息,请查看微信支付接口文档

                      回调结果:

                      回调类型errMsg说明
                      successrequestPayment:ok调用支付成功
                      failrequestPayment:fail cancel用户取消支付
                      failrequestPayment:fail (detail message)调用支付失败,其中 detail message 为后台返回的详细失败原因


                      示例代码:

                      wx.requestPayment({   "timeStamp": "",   "nonceStr": "",   "package": "",   "signType": "MD5",   "paySign": "",   "success":function(res){   },   "fail":function(res){   }})


                      Bug & Tip

                      1. bug: 6.5.2 及之前版本中,用户取消支付不会触发 fail 回调,只会触发 complete 回调,回调 errMsg 为 'requestPayment:cancel'

                      wx.authorize(OBJECT)


                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      部分接口需要获得同意后才能调用。此类接口调用时,如果用户未授权过,会弹窗询问用户,用户点击同意后方可调用接口。如果用户点了拒绝,则短期内调用不会出现弹窗,而是直接进入 fail 回调。用户可以在小程序设置界面中修改对该小程序的授权信息。本接口用于提前向用户发起授权,调用后会立刻弹窗询问用户是否同意小程序使用某项功能或获取用户的某些数据,但不会实际调用接口。如果用户之前已经同意,则不会出现弹窗,直接返回成功。

                      OBJECT参数说明:

                      参数名类型必填说明
                      scopeString需要获取权限的scope,详见 scope 列表
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      errMsgString调用结果

                      示例代码:

                      // 可以通过 wx.getSetting 先查询一下用户是否授权了 "scope.record" 这个 scopewx.getSetting({    success(res) {        if (!res.authSetting['scope.record']) {            wx.authorize({                scope: 'scope.record',                success() {                    // 用户已经同意小程序使用录音功能,后续调用 wx.startRecord 接口不会弹窗询问                    wx.startRecord()                }            })        }    }})

                      scope 列表

                      scope对应接口描述
                      scope.userInfowx.getUserInfo用户信息
                      scope.userLocationwx.getLocation, wx.chooseLocation地理位置
                      scope.addresswx.chooseAddress通讯地址
                      scope.recordwx.startRecord录音功能
                      scope.writePhotosAlbumwx.saveImageToPhotosAlbum, wx.saveVideoToPhotosAlbum保存到相册

                      wx.openSetting(OBJECT)


                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      调起客户端小程序设置界面,返回用户设置的操作结果

                      Object 参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数,返回内容详见返回参数说明。
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数类型说明
                      authSettingObject用户授权结果,其中 key 为 scope 值,value 为 Bool 值,表示用户是否允许授权,详见 scope 列表

                      示例代码:

                      wx.openSetting({  success: (res) => {    /*     * res.authSetting = {     *   "scope.userInfo": true,     *   "scope.userLocation": true     * }     */  }})

                      OpenSettingButton wx.createOpenSettingButton(string type, string text, string image, Object style)


                      支持版本 >= 2.0.7

                      创建打开设置页面的按钮。

                      参数

                      string type

                      按钮的类型

                      type 的合法值:

                      说明
                      text可以设置背景色和文本的按钮
                      image只能设置背景贴图的按钮,背景贴图会直接拉伸到按钮的宽高

                      string text

                      按钮上的文本,仅当 type 为 text 时有效

                      string image

                      按钮的背景图片,仅当 type 为 image 时有效

                      Object style

                      按钮的样式

                      属性类型默认值是否必填说明支持版本
                      leftnumber左上角横坐标
                      topnumber左上角纵坐标
                      widthnumber宽度
                      heightnumber高度
                      backgroundColorstring背景颜色
                      borderColorstring边框颜色
                      borderWidthnumber边框宽度
                      borderRadiusnumber边框圆角
                      textAlignstring文本的水平居中方式
                      fontSizenumber字号
                      lineHeightnumber文本的行高

                      style.textAlign 的合法值:

                      说明
                      left居左
                      center居中
                      right居右

                      返回值

                      OpenSettingButton

                      示例代码

                      let button = wx.createOpenSettingButton({    type: 'text',    text: '打开设置页面',    style: {        left: 10,        top: 76,        width: 200,        height: 40,        lineHeight: 40,        backgroundColor: '#ff0000',        color: '#ffffff',        textAlign: 'center',        fontSize: 16,        borderRadius: 4    }})

                      wx.getSetting(OBJECT)


                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      获取用户的当前设置

                      Object 参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数,返回内容详见返回参数说明。
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数类型说明
                      authSettingObject用户授权结果,其中 key 为 scope 值,value 为 Bool 值,表示用户是否允许授权,详见 scope 列表

                      示例代码:

                      wx.getSetting({  success: (res) => {    /*     * res.authSetting = {     *   "scope.userInfo": true,     *   "scope.userLocation": true     * }     */  }})


                      wx.chooseAddress(OBJECT)


                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      调起用户编辑收货地址原生界面,并在编辑完成后返回用户选择的地址。

                      OBJECT参数说明:

                      参数类型必填返回
                      successFunction返回用户选择的收货地址信息
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数类型说明
                      errMsgString调用结果
                      userNameString收货人姓名
                      postalCodeString邮编
                      provinceNameString国标收货地址第一级地址
                      cityNameString国标收货地址第二级地址
                      countyNameString国标收货地址第三级地址
                      detailInfoString详细收货地址信息
                      nationalCodeString收货地址国家码
                      telNumberString收货人手机号码

                      示例代码:

                      wx.chooseAddress({  success: function (res) {    console.log(res.userName)    console.log(res.postalCode)    console.log(res.provinceName)    console.log(res.cityName)    console.log(res.countyName)    console.log(res.detailInfo)    console.log(res.nationalCode)    console.log(res.telNumber)  }})

                      Bug & Tip

                      1. tip:wx.chooseAddress接口需要用户授权,请兼容用户拒绝授权的场景。

                      wx.addCard(OBJECT)


                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      批量添加卡券。

                      Object参数说明:

                      参数类型必填说明
                      cardListObjectArray需要添加的卡券列表,列表内对象说明请参见请求对象说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      请求对象说明

                      参数类型说明
                      cardIdString卡券 Id
                      cardExtString卡券的扩展参数

                      cardExt 说明

                      参数类型必填是否参与签名说明
                      codeString用户领取的 code,仅自定义 code 模式的卡券须填写,非自定义 code 模式卡券不可填写,详情
                      openidString指定领取者的openid,只有该用户能领取。 bind_openid 字段为 true 的卡券必须填写,bind_openid 字段为 false 不可填写。
                      timestampNumber时间戳,东八区时间,UTC+8,单位为秒
                      nonce_strString随机字符串,由开发者设置传入,加强安全性(若不填写可能被重放请求)。随机字符串,不长于 32 位。推荐使用大小写字母和数字,不同添加请求的 nonce_str 须动态生成,若重复将会导致领取失败。
                      fixed_begintimestampNumber卡券在第三方系统的实际领取时间,为东八区时间戳(UTC+8,精确到秒)。当卡券的有效期类为 DATE_TYPE_FIX_TERM 时专用,标识卡券的实际生效时间,用于解决商户系统内起始时间和领取微信卡券时间不同步的问题。
                      outer_strString领取渠道参数,用于标识本次领取的渠道值。
                      signatureString-签名,商户将接口列表中的参数按照指定方式进行签名,签名方式使用 SHA1,具体签名方案参见:卡券签名

                      注:cardExt 需进行 JSON 序列化为字符串传入

                      回调结果:

                      回调类型errMsg说明
                      successaddCard:ok添加卡券成功
                      failaddCard:fail cancel用户取消添加卡券
                      failaddCard:fail (detail message)添加卡券失败,其中 detail message 为后台返回的详细失败原因

                      success返回参数:

                      参数类型说明
                      cardListObjectArray卡券添加结果列表,列表内对象说明请详见返回对象说明

                      返回对象说明

                      参数类型说明
                      codeString加密 code,为用户领取到卡券的code加密后的字符串,解密请参照:code 解码接口
                      cardIdString用户领取到卡券的Id
                      cardExtString用户领取到卡券的扩展参数,与调用时传入的参数相同
                      isSuccessBoolean是否成功

                      示例代码:

                      wx.addCard({  cardList: [    {      cardId: '',      cardExt: '{"code": "", "openid": "", "timestamp": "", "signature":""}'    }, {      cardId: '',      cardExt: '{"code": "", "openid": "", "timestamp": "", "signature":""}'    }  ],  success: function(res) {    console.log(res.cardList) // 卡券添加结果  }})

                      wx.openCard(OBJECT)


                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      查看微信卡包中的卡券。

                      Object参数说明:

                      参数类型必填说明
                      cardListObjectArray需要打开的卡券列表,列表内参数详见openCard 请求对象说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      openCard 请求对象说明

                      参数类型说明
                      cardIdString需要打开的卡券 Id
                      codeString由 addCard 的返回对象中的加密 code 通过解密后得到,解密请参照:code 解码接口

                      示例代码:

                      wx.openCard({  cardList: [    {      cardId: '',      code: ''    }, {      cardId: '',      code: ''    }  ],  success: function(res) {  }})

                      Tip

                      1. tip: 目前只有认证小程序才能使用卡券接口,可参考指引进行认证。
                      2. tip: 了解更多信息,请查看微信卡券接口文档

                      基于微信的通知渠道,我们为开发者提供了可以高效触达用户的模板消息能力,以便实现服务的闭环并提供更佳的体验。

                      模板推送位置:服务通知

                      模板下发条件:用户本人在微信体系内与页面有交互行为后触发,详见下发条件说明

                      模板跳转能力:点击查看详情仅能跳转下发模板的该帐号的各个页面

                      使用说明

                      步骤一:获取模板ID

                      有两个方法可以获取模版ID

                      1. 通过模版消息管理接口获取模版ID(详见模版消息管理
                      2. 在微信公众平台手动配置获取模版ID

                      ​登录https://mp.weixin.qq.com获取模板,如果没有合适的模板,可以申请添加新模板,审核通过后可使用,详见模板审核说明

                      小程序 模板消息

                      步骤二:页面的<form/>组件,属性report-submittrue时,可以声明为需发模板消息,此时点击按钮提交表单可以获取formId,用于发送模板消息。或者当用户完成支付行为,可以获取prepay_id用于发送模板消息。

                      步骤三:调用接口下发模板消息(详见发送模板消息


                      模版消息管理

                      1.获取小程序模板库标题列表

                      接口地址

                      https://api.weixin.qq.com/cgi-bin/wxopen/template/library/list?access_token=ACCESS_TOKEN

                      HTTP请求方式:

                      POST

                      POST参数说明:

                      参数必填说明
                      access_token接口调用凭证
                      offsetoffset和count用于分页,表示从offset开始,拉取count条记录,offset从0开始,count最大为20。
                      countoffset和count用于分页,表示从offset开始,拉取count条记录,offset从0开始,count最大为20。

                      示例:

                      {"offset":0,"count":5}

                      返回码说明:

                      在调用模板消息接口后,会返回JSON数据包。

                      正常时的返回JSON数据包示例:

                      {"errcode":0,"errmsg":"ok","list":[{"id":"AT0002","title":"购买成功通知"},{"id":"AT0003","title":"购买失败通知"},{"id":"AT0004","title":"交易提醒"},{"id":"AT0005","title":"付款成功通知"},{"id":"AT0006","title":"付款失败通知"}],"total_count":599}

                      返回参数说明:

                      参数说明
                      id模板标题id(获取模板标题下的关键词库时需要)
                      title模板标题内容
                      total_count模板库标题总数

                      2.获取模板库某个模板标题下关键词库

                      接口地址

                      https://api.weixin.qq.com/cgi-bin/wxopen/template/library/get?access_token=ACCESS_TOKEN

                      HTTP请求方式:

                      POST

                      POST参数说明:

                      参数必填说明
                      access_token接口调用凭证
                      id模板标题id,可通过接口获取,也可登录小程序后台查看获取

                      示例:

                      {"id":"AT0002"}

                      返回码说明:

                      在调用模板消息接口后,会返回JSON数据包。

                      正常时的返回JSON数据包示例:

                      {    "errcode": 0,    "errmsg": "ok",    "id": "AT0002",    "title": "购买成功通知",    "keyword_list": [        {            "keyword_id": 3,            "name": "购买地点",            "example": "TIT造舰厂"        },        {            "keyword_id": 4,            "name": "购买时间",            "example": "2016年6月6日"        },        {            "keyword_id": 5,            "name": "物品名称",            "example": "咖啡"        }    ]}

                      返回参数说明:

                      参数说明
                      keyword_id关键词id,添加模板时需要
                      name关键词内容
                      example关键词内容对应的示例

                      3.组合模板并添加至帐号下的个人模板库

                      接口地址

                      https://api.weixin.qq.com/cgi-bin/wxopen/template/add?access_token=ACCESS_TOKEN

                      HTTP请求方式:

                      POST

                      POST参数说明:

                      参数必填说明
                      access_token接口调用凭证
                      id模板标题id,可通过接口获取,也可登录小程序后台查看获取
                      keyword_id_list开发者自行组合好的模板关键词列表,关键词顺序可以自由搭配(例如[3,5,4]或[4,5,3]),最多支持10个关键词组合

                      示例:

                      {"id":"AT0002", "keyword_id_list":[3,4,5] }

                      返回码说明:

                      在调用模板消息接口后,会返回JSON数据包。

                      正常时的返回JSON数据包示例:

                      {"errcode": 0,"errmsg": "ok","template_id": "wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc"}

                      返回参数说明:

                      参数说明
                      template_id添加至帐号下的模板id,发送小程序模板消息时所需

                      4.获取帐号下已存在的模板列表

                      接口地址

                      https://api.weixin.qq.com/cgi-bin/wxopen/template/list?access_token=ACCESS_TOKEN

                      HTTP请求方式:

                      POST

                      POST参数说明:

                      参数必填说明
                      access_token接口调用凭证
                      offsetoffset和count用于分页,表示从offset开始,拉取count条记录,offset从0开始,count最大为20。最后一页的list长度可能小于请求的count
                      countoffset和count用于分页,表示从offset开始,拉取count条记录,offset从0开始,count最大为20。最后一页的list长度可能小于请求的count

                      示例:

                      {"offset":0,"count":1}

                      返回码说明:

                      在调用模板消息接口后,会返回JSON数据包。

                      正常时的返回JSON数据包示例:

                      {"errcode": 0,"errmsg": "ok","list": [        {            "template_id": "wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc",            "title": "购买成功通知",            "content": "购买地点{{keyword1.DATA}}
                      购买时间{{keyword2.DATA}}
                      物品名称{{keyword3.DATA}}
                      ",            "example": "购买地点:TIT造舰厂
                      购买时间:2016年6月6日
                      物品名称:咖啡
                      "        }    ]}

                      返回参数说明:

                      参数说明
                      list帐号下的模板列表
                      template_id添加至帐号下的模板id,发送小程序模板消息时所需
                      title模板标题
                      content模板内容
                      example模板内容示例

                      5.删除帐号下的某个模板

                      接口地址

                      https://api.weixin.qq.com/cgi-bin/wxopen/template/del?access_token=ACCESS_TOKEN

                      HTTP请求方式:

                      POST

                      POST参数说明:

                      参数必填说明
                      access_token接口调用凭证
                      template_id要删除的模板id

                      示例:

                      {"template_id":"wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc"}

                      返回码说明:

                      在调用模板消息接口后,会返回JSON数据包。

                      正常时的返回JSON数据包示例:

                      {"errcode": 0,"errmsg": "ok"}


                      发送模板消息


                      1. 获取access_token

                      access_token是全局唯一接口调用凭据,开发者调用各接口时都需使用access_token,请妥善保存。access_token的存储至少要保留512个字符空间。access_token的有效期目前为2个小时,需定时刷新,重复获取将导致上次获取的access_token失效。

                      公众平台的API调用所需的access_token的使用及生成方式说明:

                      1. 为了保密appsecrect,第三方需要一个access_token获取和刷新的中控服务器。而其他业务逻辑服务器所使用的access_token均来自于该中控服务器,不应该各自去刷新,否则会造成access_token覆盖而影响业务;
                      2. 目前access_token的有效期通过返回的expire_in来传达,目前是7200秒之内的值。中控服务器需要根据这个有效时间提前去刷新新access_token。在刷新过程中,中控服务器对外输出的依然是老access_token,此时公众平台后台会保证在刷新短时间内,新老access_token都可用,这保证了第三方业务的平滑过渡;
                      3. access_token的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新access_token的接口,这样便于业务服务器在API调用获知access_token已超时的情况下,可以触发access_token的刷新流程。

                      开发者可以使用AppID和AppSecret调用本接口来获取access_token。AppID和AppSecret可登录微信公众平台官网-设置-开发设置中获得(需要已经绑定成为开发者,且帐号没有异常状态)。AppSecret生成后请自行保存,因为在公众平台每次生成查看都会导致AppSecret被重置。注意调用所有微信接口时均需使用https协议。如果第三方不使用中控服务器,而是选择各个业务逻辑点各自去刷新access_token,那么就可能会产生冲突,导致服务不稳定。

                      接口地址:

                      https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

                      HTTP请求方式:

                      GET

                      参数说明 :

                      参数 必填 说明
                      grant_type 获取access_token填写client_credential
                      appid 第三方用户唯一凭证
                      secret 第三方用户唯一凭证密钥,即appsecret

                      返回参数说明:

                      正常情况下,微信会返回下述JSON数据包给开发者:

                      {"access_token":"ACCESS_TOKEN","expires_in":7200}
                      参数 说明
                      access_token 获取到的凭证
                      expires_in 凭证有效时间,单位:秒

                      错误时微信会返回错误码等信息,JSON数据包示例如下(该示例为AppID无效错误):

                      {"errcode":40013,"errmsg":"invalid appid"}

                      2. 发送模板消息

                      接口地址:(ACCESS_TOKEN需换成上文获取到的access_token)

                      https://api.weixin.qq.com/cgi-bin/message/wxopen/template/send?access_token=ACCESS_TOKEN

                      HTTP请求方式:

                      POST

                      POST参数说明:

                      参数 必填 说明
                      touser 接收者(用户)的openid
                      template_id 所需下发的模板消息的id
                      page 点击模板查看详情跳转页面,不填则模板无跳转
                      form_id 表单提交场景下,为submit事件带上的formId;支付场景下,为本次支付的prepay_id
                      value 模板内容,不填则下发空模板
                      color 模板内容字体的颜色,不填默认黑色
                      emphasis_keyword 模板需要放大的关键词,不填则默认无放大

                      示例:

                      {  "touser": "OPENID",    "template_id": "TEMPLATE_ID",   "page": "index",            "form_id": "FORMID",           "data": {      "keyword1": {          "value": "339208499",           "color": "#173177"      },       "keyword2": {          "value": "2015年01月05日 12:30",           "color": "#173177"      },       "keyword3": {          "value": "粤海喜来登酒店",           "color": "#173177"      } ,       "keyword4": {          "value": "广州市天河区天河路208号",           "color": "#173177"      }   },  "emphasis_keyword": "keyword1.DATA" }

                      返回码说明:

                      在调用模板消息接口后,会返回JSON数据包。

                      正常时的返回JSON数据包示例:

                      {  "errcode":0,  "errmsg":"ok",}

                      错误时会返回错误码信息,说明如下:

                      返回码说明
                      40037template_id不正确
                      41028form_id不正确,或者过期
                      41029form_id已被使用
                      41030page不正确
                      45009接口调用超过限额(目前默认每个帐号日调用限额为100万)

                      使用效果:

                      模板消息

                      下发条件说明

                      1. 支付

                        当用户在小程序内完成过支付行为,可允许开发者向用户在7天内推送有限条数的模板消息(1次支付可下发3条,多次支付下发条数独立,互相不影响)

                      2. 提交表单

                        当用户在小程序内发生过提交表单行为且该表单声明为要发模板消息的,开发者需要向用户提供服务时,可允许开发者向用户在7天内推送有限条数的模板消息(1次提交表单可下发1条,多次提交下发条数独立,相互不影响)


                      审核说明

                      1.标题

                      1.1标题不能存在相同

                      1.2标题意思不能存在过度相似

                      1.3标题必须以“提醒”或“通知”结尾

                      1.4标题不能带特殊符号、个性化字词等没有行业通用性的内容

                      1.5标题必须能体现具体服务场景

                      1.6标题不能涉及营销相关内容,包括不限于:

                      消费优惠类、购物返利类、商品更新类、优惠券类、代金券类、红包类、会员卡类、积分类、活动类等营销倾向通知

                      2.关键词

                      2.1同一标题下,关键词不能存在相同

                      2.2同一标题下,关键词不能存在过度相似

                      2.3关键词不能带特殊符号、个性化字词等没有行业通用性的内容

                      2.4关键词内容示例必须与关键词对应匹配

                      2.5关键词不能太过宽泛,需要具有限制性,例如:“内容”这个就太宽泛,不能审核通过

                      违规说明


                      除不能违反运营规范外,还不能违反以下规则,包括但不限于:

                      1. 不允许恶意诱导用户进行触发操作,以达到可向用户下发模板目的
                      2. 不允许恶意骚扰,下发对用户造成骚扰的模板
                      3. 不允许恶意营销,下发营销目的模板

                      处罚说明


                      根据违规情况给予相应梯度的处罚,一般处罚规则如下:

                      第一次违规,删除违规模板以示警告,

                      第二次违规,封禁接口7天,

                      第三次违规,封禁接口30天,

                      第四次违规,永久封禁接口

                      处罚结果及原因以站内信形式告知


                      Bug & Tip

                      1. tip: 微信6.5.2及以上版本支持模板功能。低于该版本将无法收到模板消息。

                      接收消息和事件


                      在页面中使用 <button open-type="contact" /> 可以显示进入客服会话按钮。

                      当用户在客服会话发送消息、或由某些特定的用户操作引发事件推送时,微信服务器会将消息或事件的数据包发送到开发者填写的 URL,如果使用的是云开发,则可以推送到指定的云函数(详情请参考消息推送)。开发者收到请求后可以使用 发送客服消息 接口进行异步回复。

                      各消息类型的推送JSON、XML数据包结构如下。

                      文本消息

                      用户在客服会话中发送文本消息时将产生如下数据包:

                      XML 格式

                      <xml>   <ToUserName><![CDATA[toUser]]></ToUserName>   <FromUserName><![CDATA[fromUser]]></FromUserName>   <CreateTime>1482048670</CreateTime>   <MsgType><![CDATA[text]]></MsgType>   <Content><![CDATA[this is a test]]></Content>   <MsgId>1234567890123456</MsgId></xml>

                      JSON 格式

                      {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "text",  "Content": "this is a test",  "MsgId": 1234567890123456}

                      参数说明

                      参数说明
                      ToUserName小程序的原始ID
                      FromUserName发送者的openid
                      CreateTime消息创建时间(整型)
                      MsgTypetext
                      Content文本消息内容
                      MsgId消息id,64位整型

                      图片消息

                      用户在客服会话中发送图片消息时将产生如下数据包:

                      XML 格式

                      <xml>      <ToUserName><![CDATA[toUser]]></ToUserName>      <FromUserName><![CDATA[fromUser]]></FromUserName>      <CreateTime>1482048670</CreateTime>      <MsgType><![CDATA[image]]></MsgType>      <PicUrl><![CDATA[this is a url]]></PicUrl>      <MediaId><![CDATA[media_id]]></MediaId>      <MsgId>1234567890123456</MsgId></xml>

                      JSON 格式

                      {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "image",  "PicUrl": "this is a url",  "MediaId": "media_id",  "MsgId": 1234567890123456}

                      参数说明

                      参数说明
                      ToUserName小程序的原始ID
                      FromUserName发送者的openid
                      CreateTime消息创建时间(整型)
                      MsgTypeimage
                      PicUrl图片链接(由系统生成)
                      MediaId图片消息媒体id,可以调用[获取临时素材]((getTempMedia)接口拉取数据。
                      MsgId消息id,64位整型

                      小程序卡片消息

                      用户在客服会话中发送小程序卡片消息时将产生如下数据包:

                      XML 格式

                      <xml>  <ToUserName><![CDATA[toUser]]></ToUserName>  <FromUserName><![CDATA[fromUser]]></FromUserName>  <CreateTime>1482048670</CreateTime>  <MsgType><![CDATA[miniprogrampage]]></MsgType>  <MsgId>1234567890123456</MsgId>  <Title><![CDATA[Title]]></Title>  <AppId><![CDATA[AppId]]></AppId>  <PagePath><![CDATA[PagePath]]></PagePath>  <ThumbUrl><![CDATA[ThumbUrl]]></ThumbUrl>  <ThumbMediaId><![CDATA[ThumbMediaId]]></ThumbMediaId></xml>

                      JSON 格式

                      {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "miniprogrampage",  "MsgId": 1234567890123456,  "Title":"title",  "AppId":"appid",  "PagePath":"path",  "ThumbUrl":"",  "ThumbMediaId":""}

                      参数说明

                      参数说明
                      ToUserName小程序的原始ID
                      FromUserName发送者的openid
                      CreateTime消息创建时间(整型)
                      MsgTypeminiprogrampage
                      MsgId消息id,64位整型
                      Title标题
                      AppId小程序appid
                      PagePath小程序页面路径
                      ThumbUrl封面图片的临时cdn链接
                      ThumbMediaId封面图片的临时素材id

                      进入会话事件

                      用户在小程序“客服会话按钮”进入客服会话时将产生如下数据包:

                      XML 格式

                      <xml>    <ToUserName><![CDATA[toUser]]></ToUserName>    <FromUserName><![CDATA[fromUser]]></FromUserName>    <CreateTime>1482048670</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[user_enter_tempsession]]></Event>    <SessionFrom><![CDATA[sessionFrom]]></SessionFrom></xml>

                      JSON 格式

                      {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1482048670,  "MsgType": "event",  "Event": "user_enter_tempsession",  "SessionFrom": "sessionFrom"}

                      参数说明

                      参数说明
                      ToUserName小程序的原始ID
                      FromUserName发送者的openid
                      CreateTime事件创建时间(整型)
                      MsgTypeevent
                      Event事件类型,user_enter_tempsession
                      SessionFrom开发者在客服会话按钮设置的 session-from 属性


                      发送客服消息


                      当用户和小程序客服产生特定动作的交互时(具体动作列表请见下方说明),微信将会把消息数据推送给开发者,开发者可以在一段时间内(目前修改为48小时)调用客服接口,通过POST一个JSON数据包来发送消息给普通用户。此接口主要用于客服等有人工消息处理环节的功能,方便开发者为用户提供更加优质的服务。

                      目前允许的动作列表如下,不同动作触发后,允许的客服接口下发消息条数和下发时限不同。下发条数达到上限后,会收到错误返回码,具体请见返回码说明页:

                      用户动作允许下发条数限制下发时限
                      用户通过客服消息按钮进入会话1条1分钟
                      用户发送信息5条48小时

                      客服接口-发消息

                      接口调用请求说明

                      http请求方式: POSThttps://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

                      各消息类型所需的JSON数据包如下:

                      发送文本消息

                      {    "touser":"OPENID",    "msgtype":"text",    "text":    {         "content":"Hello World"    }}

                      发送图片消息

                      {    "touser":"OPENID",    "msgtype":"image",    "image":    {      "media_id":"MEDIA_ID"    }

                      发送图文链接

                      每次可以发送一个图文链接

                      {    "touser": "OPENID",    "msgtype": "link",    "link": {          "title": "Happy Day",          "description": "Is Really A Happy Day",          "url": "URL",          "thumb_url": "THUMB_URL"    }}

                      参数说明

                      参数是否必须说明
                      access_token调用接口凭证
                      touser普通用户(openid)
                      msgtype消息类型,文本为text,图文链接为link
                      content文本消息内容
                      media_id发送的图片的媒体ID,通过新增素材接口上传图片文件获得。
                      title图文链接消息标题
                      description图文链接消息
                      url图文链接消息被点击后跳转的链接
                      picurl图文链接消息的图片链接,支持 JPG、PNG 格式,较好的效果为大图 640 X 320,小图 80 X 80

                      返回码说明

                      参数说明
                      -1系统繁忙,此时请开发者稍候再试
                      0请求成功
                      40001获取access_token时AppSecret错误,或者access_token无效。请开发者认真比对AppSecret的正确性,或查看是否正在为恰当的小程序调用接口
                      40002不合法的凭证类型
                      40003不合法的OpenID,请开发者确认OpenID否是其他小程序的OpenID
                      45015回复时间超过限制
                      45047客服接口下行条数超过上限
                      48001api功能未授权,请确认小程序已获得该接口

                      转发消息

                      如果小程序设置了消息推送,普通微信用户向小程序客服发消息时,微信服务器会先将消息 POST 到开发者填写的 url 上,如果希望将消息转发到网页版客服工具,则需要开发者在响应包中返回 MsgType 为 transfer_customer_service 的消息,微信服务器收到响应后会把当次发送的消息转发至客服系统。

                      用户被客服接入以后,客服关闭会话以前,处于会话过程中时,用户发送的消息均会被直接转发至客服系统。当会话超过 30 分钟客服没有关闭时,微信服务器会自动停止转发至客服,而将消息恢复发送至开发者填写的 url 上。

                      用户在等待队列中时,用户发送的消息仍然会被推送至开发者填写的 url 上。

                      这里特别要注意,只针对微信用户发来的消息才进行转发,而对于其他事件(比如用户从小程序唤起客服会话)都不应该转接,否则客服在客服系统上就会看到一些无意义的消息了。

                      消息转发到网页版客服工具

                      开发者只在响应包中返回 MsgType 为 transfer_customer_service 的消息,微信服务器收到响应后就会把当次发送的消息转发至客服系统。

                       <xml>     <ToUserName><![CDATA[touser]]></ToUserName>     <FromUserName><![CDATA[fromuser]]></FromUserName>     <CreateTime>1399197672</CreateTime>     <MsgType><![CDATA[transfer_customer_service]]></MsgType> </xml>

                      参数说明

                      参数是否必须描述
                      ToUserName接收方帐号(收到的OpenID)
                      FromUserName开发者微信号
                      CreateTime消息创建时间 (整型)
                      MsgTypetransfer_customer_service

                      临时素材接口


                      获取临时素材

                      小程序可以使用本接口获取客服消息内的临时素材(即下载临时的多媒体文件)。目前小程序仅支持下载图片文件。

                      接口调用请求说明

                      HTTP 请求方式: GET,HTTPS 调用

                      https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID

                      请求示例(示例为通过curl命令获取多媒体文件)

                      curl -I -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

                      参数说明

                      参数是否必须说明
                      access_token调用接口凭证
                      media_id媒体文件ID

                      返回说明

                      正确情况下的返回 HTTP 头如下:

                      HTTP/1.1 200 OKConnection: closeContent-Type: image/jpeg Content-disposition: attachment; filename="MEDIA_ID.jpg"Date: Sun, 06 Jan 2013 10:20:18 GMTCache-Control: no-cache, must-revalidateContent-Length: 339721curl -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

                      如果返回的是视频消息素材,则内容如下:

                      { "video_url":DOWN_URL}

                      错误情况下的返回JSON数据包示例如下(示例为无效媒体ID错误):

                      {  "errcode":40007,  "errmsg":"invalid media_id"}


                      新增临时素材

                      小程序可以使用本接口把媒体文件(目前仅支持图片)上传到微信服务器,用户发送客服消息或被动回复用户消息。

                      接口调用请求说明

                      HTTP 请求方式:POST/FORM,HTTPS 调用

                      https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE

                      调用示例(使用curl命令,用FORM表单方式上传一个多媒体文件):

                      curl -F media=@test.jpg "https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE"

                      参数说明

                      参数是否必须说明
                      access_token调用接口凭证
                      typeimage
                      mediaform-data中媒体文件标识,有filename、filelength、content-type等信息

                      返回说明

                      正确情况下的返回 JSON 数据包结果如下:

                      {  "type":"TYPE",  "media_id":"MEDIA_ID",  "created_at":123456789}


                      参数描述
                      typeimage
                      media_id媒体文件上传后,获取标识
                      created_at媒体文件上传时间戳

                      错误情况下的返回JSON数据包示例如下(示例为无效媒体类型错误):

                      {  "errcode":40004,  "errmsg":"invalid media type"}

                      接入概述


                      接入微信小程序消息服务,开发者需要按照如下步骤完成:

                      1、填写服务器配置

                      2、验证服务器地址的有效性

                      3、依据接口文档实现业务逻辑

                      下面详细介绍这3个步骤。

                      第一步:填写服务器配置

                      登录微信小程序官网后,在小程序官网的“设置-消息服务器”页面,管理员扫码启用消息服务,填写服务器地址(URL)、Token 和 EncodingAESKey。

                      URL是开发者用来接收微信消息和事件的接口URL。Token可由开发者可以任意填写,用作生成签名(该Token会和接口URL中包含的Token进行比对,从而验证安全性)。EncodingAESKey由开发者手动填写或随机生成,将用作消息体加解密密钥。

                      同时,开发者可选择消息加解密方式:明文模式、兼容模式和安全模式。可以选择消息数据格式:XML格式或JSON格式。加密方式的默认状态是明文格式,而数据格式的默认状态是XML格式。

                      模式的选择与服务器配置在提交后都会立即生效,请开发者谨慎填写及选择。切换加密方式和数据格式需要提前配置好相关代码,详情请参考消息加解密说明

                      填写服务器配置


                      第二步:验证消息的确来自微信服务器

                      开发者提交信息后,微信服务器将发送GET请求到填写的服务器地址URL上,GET请求携带参数如下表所示:

                      参数描述
                      signature微信加密签名,signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。
                      timestamp时间戳
                      nonce随机数
                      echostr随机字符串

                      开发者通过检验signature对请求进行校验(下面有校验方式)。若确认此次GET请求来自微信服务器,请原样返回echostr参数内容,则接入生效,成为开发者成功,否则接入失败。加密/校验流程如下:1、将token、timestamp、nonce三个参数进行字典序排序;2、将三个参数字符串拼接成一个字符串进行sha1加密;3、开发者获得加密后的字符串可与signature对比,标识该请求来源于微信

                      检验signature的PHP示例代码:

                      private function checkSignature(){    $signature = $_GET["signature"];    $timestamp = $_GET["timestamp"];    $nonce = $_GET["nonce"];    $token = TOKEN;    $tmpArr = array($token, $timestamp, $nonce);    sort($tmpArr, SORT_STRING);    $tmpStr = implode( $tmpArr );    $tmpStr = sha1( $tmpStr );    if( $tmpStr == $signature ){        return true;    }else{        return false;    }}

                      PHP示例代码下载:下载


                      第三步:依据接口文档实现业务逻辑

                      验证URL有效性成功后即接入生效,成为开发者。至此用户向小程序客服发送消息、或者进入会话等情况时,开发者填写的服务器配置URL将得到微信服务器推送过来的消息和事件,开发者可以依据自身业务逻辑进行响应。

                      另请注意,开发者所填写的URL必须以 http:// 或 https:// 开头,分别支持80端口和443端口。

                      onShareAppMessage(options)


                      在 Page 中定义 onShareAppMessage 函数,设置该页面的转发信息。

                      • 只有定义了此事件处理函数,右上角菜单才会显示“转发”按钮
                      • 用户点击转发按钮的时候会调用
                      • 此事件需要 return 一个 Object,用于自定义转发内容

                      options 参数说明

                      参数类型说明最低版本
                      fromString转发事件来源。button:页面内转发按钮;menu:右上角转发菜单1.2.4
                      targetObject如果 from 值是 button,则 target 是触发这次转发事件的 button,否则为 undefined1.2.4
                      自定义转发字段

                      字段说明默认值最低版本
                      title转发标题当前小程序名称 
                      path转发路径当前页面 path ,必须是以 / 开头的完整路径 
                      success转发成功的回调函数 1.1.0
                      fail转发失败的回调函数 1.1.0
                      complete转发结束的回调函数(转发成功、失败都会执行 1.1.0

                      回调结果:

                      回调类型errMsg说明
                      successshareAppMessage:ok转发成功
                      failshareAppMessage:fail cancel用户取消转发
                      failshareAppMessage:fail (detail message)转发失败,其中 detail message 为详细失败信息

                      success回调参数说明:

                      参数类型说明最低版本
                      shareTicketsStringArrayshareTicket 数组,每一项是一个 shareTicket ,对应一个转发对象1.1.0

                      示例代码:

                      Page({  onShareAppMessage: function (res) {    if (res.from === 'button') {      // 来自页面内转发按钮      console.log(res.target)    }    return {      title: '自定义转发标题',      path: '/page/user?id=123',      success: function(res) {        // 转发成功      },      fail: function(res) {        // 转发失败      }    }  }})

                      wx.showShareMenu(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      显示当前页面的转发按钮

                      OBJECT参数说明:

                      参数类型必填说明
                      withShareTicketBoolean是否使用带 shareTicket 的转发详情
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.showShareMenu({  withShareTicket: true})

                      wx.hideShareMenu(OBJECT)

                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      隐藏转发按钮

                      OBJECT参数说明:

                      参数类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.hideShareMenu()

                      wx.updateShareMenu(OBJECT)

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      更新转发属性

                      OBJECT参数说明:

                      参数类型必填说明
                      withShareTicketBoolean是否使用带 shareTicket 的转发详情
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码:

                      wx.updateShareMenu({  withShareTicket: true,  success() {  }})

                      wx.getShareInfo(OBJECT)

                      基础库 1.1.0 开始支持,低版本需做兼容处理

                      获取转发详细信息

                      OBJECT参数说明:

                      参数类型必填说明
                      shareTicketStringshareTicket
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      CALLBACK 参数说明:

                      参数类型说明
                      errMsgString错误信息
                      encryptedDataString包括敏感数据在内的完整转发信息的加密数据,详细见加密数据解密算法
                      ivString加密算法的初始向量,详细见加密数据解密算法

                      encryptedData 解密后为一个 JSON 结构,包含字段如下:

                      字段说明
                      openGId群对当前小程序的唯一 ID

                      Tip: 如需要展示群名称,可以使用开放数据组件

                      获取更多转发信息

                      通常开发者希望转发出去的小程序被二次打开的时候能够获取到一些信息,例如群的标识。现在通过调用 wx.showShareMenu 并且设置 withShareTicket 为 true ,当用户将小程序转发到任一群聊之后,可以获取到此次转发的 shareTicket,此转发卡片在群聊中被其他用户打开时,可以在 App.onLaunch() 或 App.onShow 获取到另一个 shareTicket。这两步获取到的 shareTicket 均可通过 wx.getShareInfo() 接口可以获取到相同的转发信息。

                      页面内发起转发

                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      通过给 button 组件设置属性 open-type="share",可以在用户点击按钮后触发 Page.onShareAppMessage() 事件,如果当前页面没有定义此事件,则点击后无效果。相关组件:button

                      使用指引

                      转发按钮,旨在帮助用户更流畅地与好友分享内容和服务。转发,应是用户自发的行为,且在需要时触手可及。开发者在使用时若遵从以下指引,会得到更佳的用户体验。

                      1. 含义清晰:明确、一目了然的图形按钮,将为用户减少理解的时间。在我们的资源下载中心,你可以找到这样的按钮素材并直接使用。或者你可以根据自己业务的设计风格,灵活设计含义清晰的按钮的样式。当然,你也可以直接使用带文案的按钮,“转发给好友”,它也足够明确。
                      2. 方便点击:按钮点击热区不宜过小,亦不宜过大。同时,转发按钮与其他按钮一样,热区也不宜过密,以免用户误操作。
                      3. 按需出现:并非所有页面都适合放置转发按钮,涉及用户隐私的非公开内容,或可能打断用户完成当前操作体验的场景,该功能并不推荐使用。同时,由于转发过程中,我们将截取用户屏幕图像作为配图,因此,需要注意帮助用户屏蔽个人信息。
                      4. 尊重意愿:理所当然,并非所有的用户,都喜欢与朋友分享你的小程序。因此,它不应该成为一个诱导或强制行为,如转发后才能解锁某项功能等。请注意,这类做法不仅不被推荐,还可能违反我们的《运营规范》,我们强烈建议你在使用前阅读这部分内容。

                      以上,我们陈列了最重要的几点,如果你有时间,可以完整浏览《设计指南》,相信会有更多的收获。

                      Bug & Tip

                      1. tip: 转发图片不能自定义;会取当前页面,从顶部开始,高度为 80% 屏幕宽度的图像作为转发图片。
                      2. tip: 转发的调试支持请查看 普通转发的调试支持 和 带 shareTicket 的转发
                      3. tip: 只有转发到群聊中打开才可以获取到 shareTickets 返回值,单聊没有 shareTickets
                      4. tipshareTicket 仅在当前小程序生命周期内有效
                      5. tip: 由于策略变动,小程序群相关能力进行调整,开发者可先使用wx.getShareInfo接口中的群ID进行功能开发。




                      获取二维码


                      通过后台接口可以获取小程序任意页面的二维码,扫描该二维码可以直接进入小程序对应的页面。目前微信支持两种二维码,小程序码(左),小程序二维码(右),如下所示:

                      小程序二维码

                      可以使用开发工具 1.02.1803130 及以后版本通过二维码编译功能调试所获得的二维码

                      qrcodecompile

                      获取小程序码

                      我们推荐生成并使用小程序码,它具有更好的辨识度。目前有两个接口可以生成小程序码,开发者可以根据自己的需要选择合适的接口。

                      接口A: 适用于需要的码数量较少的业务场景

                      接口地址:

                      https://api.weixin.qq.com/wxa/getwxacode?access_token=ACCESS_TOKEN

                      获取 access_token 详见文档

                      POST 参数说明

                      参数类型默认值说明
                      pathString 不能为空,最大长度 128 字节
                      widthInt430二维码的宽度
                      auto_colorBoolfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调
                      line_colorObject{"r":"0","g":"0","b":"0"}auth_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"}

                      注意:通过该接口生成的小程序码,永久有效,数量限制见文末说明,请谨慎使用。用户扫描该码进入小程序后,将直接进入 path 对应的页面。

                      接口B:适用于需要的码数量极多,或仅临时使用的业务场景

                      接口地址:

                      https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=ACCESS_TOKEN

                      获取 access_token 详见文档

                      POST 参数说明

                      参数类型默认值说明
                      sceneString 最大32个可见字符,只支持数字,大小写英文以及部分特殊字符:!#$&'()*+,/:;=?@-._~,其它字符请自行编码为合法字符(因不支持%,中文无法使用 urlencode 处理,请使用其他编码方式)
                      pageString 必须是已经发布的小程序页面,例如 "pages/index/index" ,如果不填写这个字段,默认跳主页面
                      widthInt430二维码的宽度
                      auto_colorBoolfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调
                      line_colorObject{"r":"0","g":"0","b":"0"}auto_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"}

                      注意:通过该接口生成的小程序码,永久有效,数量暂无限制。用户扫描该码进入小程序后,开发者需在对应页面获取的码中 scene 字段的值,再做处理逻辑。使用如下代码可以获取到二维码中的 scene 字段的值。调试阶段可以使用开发工具的条件编译自定义参数 scene=xxxx 进行模拟,开发工具模拟时的 scene 的参数值需要进行 urlencode

                      // 这是首页的 jsPage({  onLoad: function(options) {    // options 中的 scene 需要使用 decodeURIComponent 才能获取到生成二维码时传入的 scene    var scene = decodeURIComponent(options.scene)  }})

                      获取小程序二维码

                      接口C:适用于需要的码数量较少的业务场景

                      接口地址:

                      https://api.weixin.qq.com/cgi-bin/wxaapp/createwxaqrcode?access_token=ACCESS_TOKEN

                      获取 access_token 详见文档

                      POST 参数说明

                      参数类型默认值说明
                      pathString 不能为空,最大长度 128 字节
                      widthInt430二维码的宽度

                      注意:通过该接口生成的小程序二维码,永久有效,数量限制见文末说明,请谨慎使用。用户扫描该码进入小程序后,将直接进入 path 对应的页面。

                      示例:

                      {"path": "pages/index?query=1", "width": 430}

                      注:pages/index 需要在app.json的 pages 中定义

                      Bug & Tip

                      1. tip:通过该接口,仅能生成已发布的小程序的二维码。
                      2. tip:可以在开发者工具预览时生成开发版的带参二维码。
                      3. tip:接口A加上接口C,总共生成的码数量限制为100,000,请谨慎调用。
                      4. tip: POST 参数需要转成 json 字符串,不支持 form 表单提交。
                      5. tip: auto_color line_color 参数仅对小程序码生效。

                      错误码

                      45009:B接口调用分钟频率受限(目前5000次/分钟,会调整),如需大量小程序码,建议预生成。

                      45029:A接口和C接口生成码个数总和到达最大个数限制。 

                      41030:B接口所传page页面不存在,或者小程序没有发布,请注意B接口没有path参数,传path参数虽然可以生成小程序码,但是只能跳主页面。

                      wx.getWeRunData(OBJECT)


                      基础库 1.2.0 开始支持,低版本需做兼容处理

                      获取用户过去三十天微信运动步数,需要先调用 wx.login 接口。

                      OBJECT参数说明:

                      参数名类型必填说明
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      errMsgString调用结果
                      encryptedDataString包括敏感数据在内的完整用户信息的加密数据,详细见加密数据解密算法
                      ivString加密算法的初始向量,详细见加密数据解密算法

                      示例代码:

                      wx.getWeRunData({    success(res) {        const encryptedData = res.encryptedData    }})

                      encryptedData 解密后为以下 json 结构,详见加密数据解密算法

                      属性类型说明
                      stepInfoListObjectArray用户过去三十天的微信运动步数

                      stepInfo 结构如下

                      属性类型说明
                      timestampNumber时间戳,表示数据对应的时间
                      stepNumber微信运动步数

                      {    "stepInfoList": [        {            "timestamp": 1445866601,            "step": 100        },        {            "timestamp": 1445866602,            "step": 100        }    ]}

                      wx.chooseInvoiceTitle(OBJECT)


                      基础库 1.5.0 开始支持,低版本需做兼容处理

                      选择用户的发票抬头

                      Object参数说明:

                      参数 类型 必填 说明
                      success Function 接口调用成功的回调函数
                      fail Function 接口调用失败的回调函数
                      complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名 类型 说明
                      type String 抬头类型(0:单位,1:个人)
                      title String 抬头名称
                      taxNumber String 抬头税号
                      companyAddress String 单位地址
                      telephone String 手机号码
                      bankName String 银行名称
                      bankAccount String 银行账号
                      errMsg String 接口调用结果

                      示例代码:

                      wx.chooseInvoiceTitle({
                      success(res) {
                      }
                      })

                      wx.checkIsSupportSoterAuthentication(OBJECT)


                      基础库 1.5.0 开始支持,低版本需做兼容处理

                      获取本机支持的 SOTER 生物认证方式

                      Object参数说明:

                      参数 类型 必填 说明
                      success Function 接口调用成功的回调函数
                      fail Function 接口调用失败的回调函数
                      complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名 类型 说明
                      supportMode StringArray 该设备支持的可被SOTER识别的生物识别方式
                      errMsg String 接口调用结果

                      supportMode 有效值:

                      说明
                      fingerPrint 指纹识别
                      facial 人脸识别(暂未支持)
                      speech 声纹识别(暂未支持)

                      示例代码:

                      wx.checkIsSupportSoterAuthentication({
                      success(res) {
                      // res.supportMode = [] 不具备任何被SOTER支持的生物识别方式
                      // res.supportMode = ['fingerPrint'] 只支持指纹识别
                      // res.supportMode = ['fingerPrint', 'facial'] 支持指纹识别和人脸识别
                      }
                      })


                      wx.reportPerformance(Number id, Number value, String|Array dimensions)

                      基础库 2.9.2 开始支持,低版本需做兼容处理。

                      小程序测速上报。使用前,需要在小程序管理后台配置。 

                      参数

                      Number id

                      指标 id

                      Number value

                      需要上报的数值

                      String|Array dimensions

                      自定义维度 (选填)

                      示例代码

                      wx.reportPerformance(1101, 680)wx.reportPerformance(1101, 680, 'custom')


                      wx.getPerformance()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      获取当前小程序性能相关的信息。

                      目前支持获取以下几类性能指标:

                      类别名称 (entryType)指标
                      路由navigationroute, appLaunch
                      渲染renderfirstRender
                      脚本scriptevaluateScript
                      • route: 路由性能
                      • appLaunch: 小程序启动耗时
                      • firstRender: 页面首次渲染耗时
                      • evaluateScript: 注入脚本耗时

                      示例代码

                      const performance = wx.getPerformance()const observer = performance.createObserver((entryList) => {  console.log(entryList.getEntries())})observer.observe({ entryTypes: ['render', 'script'] })


                      EntryList

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      EntryList 对象


                      方法:

                      Array EntryList.getEntries()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      该方法返回当前列表中的所有性能数据

                      返回值

                      Array



                      Array EntryList.getEntriesByName(string name, string entryType)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      获取当前列表中所有名称为 [name] 且类型为 [entryType] 的性能数据

                      参数

                      string name

                      string entryType

                      返回值

                      Array



                      Array EntryList.getEntriesByType(string entryType)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      获取当前列表中所有类型为 [entryType] 的性能数据

                      参数

                      string entryType

                      返回值

                      Array


                      Performance

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      Performance 对象,用于获取性能数据及创建性能监听器


                      方法:

                      PerformanceObserver Performance.createObserver(function callback)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      创建全局性能事件监听器

                      参数

                      function callback

                      返回值

                      PerformanceObserver



                      Array Performance.getEntries()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      该方法返回当前缓冲区中的所有性能数据

                      返回值

                      Array



                      Array Performance.getEntriesByName(string name, string entryType)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      获取当前缓冲区中所有名称为 [name] 且类型为 [entryType] 的性能数据

                      参数

                      string name

                      string entryType

                      返回值

                      Array



                      Array Performance.getEntriesByType(string entryType)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      获取当前缓冲区中所有类型为 [entryType] 的性能数据

                      参数

                      string entryType

                      返回值

                      Array



                      Performance.setBufferSize(number size)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      设置缓冲区大小, 默认缓冲 30 条性能数据

                      参数

                      number size


                      PerformanceObserver

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      PerformanceObserver 对象, 用于监听性能相关事件

                      属性

                      Array supportedEntryTypes

                      获取当前支持的所有性能指标类型


                      方法:

                      PerformanceObserver.disconnect()

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      停止监听




                      PerformanceObserver.observe(Object options)

                      基础库 2.11.0 开始支持,低版本需做兼容处理

                      开始监听

                      参数

                      Object options

                      设置 type 监听单个类型的指标,设置 entryTypes 监听多个类型指标。


                      wx.requestSubscribeMessage(Object object)

                      基础库 2.4.4 开始支持,低版本需做兼容处理

                      调起客户端小程序订阅消息界面,返回用户订阅消息的操作结果。当用户勾选了订阅面板中的“总是保持以上选择,不再询问”时,模板消息会被添加到用户的小程序设置页,通过 wx.getSetting 接口可获取用户对相关模板消息的订阅状态。

                      注意事项

                      • 一次性模板 id 和永久模板 id 不可同时使用。
                      • 低版本基础库2.4.4~2.8.3 已支持订阅消息接口调用,仅支持传入一个一次性 tmplId / 永久 tmplId。
                      • 2.8.2 版本开始,用户发生点击行为或者发起支付回调后,才可以调起订阅消息界面。
                      • 2.10.0 版本开始,开发版和体验版小程序将禁止使用模板消息 formId。

                      参数

                      Object object

                      属性类型默认值必填说明
                      tmplIdsArray需要订阅的消息模板的id的集合,一次调用最多可订阅3条消息(注意:iOS客户端7.0.6版本、Android客户端7.0.7版本之后的一次性订阅/长期订阅才支持多个模板消息,iOS客户端7.0.5版本、Android客户端7.0.6版本之前的一次订阅只支持一个模板消息)消息模板id在[微信公众平台(mp.weixin.qq.com)-功能-订阅消息]中配置
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgString接口调用成功时errMsg值为'requestSubscribeMessage:ok'
                      TEMPLATE_IDString[TEMPLATE_ID]是动态的键,即模板id,值包括'accept'、'reject'、'ban'。'accept'表示用户同意订阅该条id对应的模板消息,'reject'表示用户拒绝订阅该条id对应的模板消息,'ban'表示已被后台封禁。例如 { errMsg: "requestSubscribeMessage:ok", zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: "accept"} 表示用户同意订阅zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE这条消息

                      object.fail 回调函数

                      参数
                      Object res
                      属性类型说明
                      errMsgString接口调用失败错误信息
                      errCodeNumber接口调用失败错误码

                      错误码

                      errCodeerrMsg说明
                      10001TmplIds can't be empty参数传空了
                      10002Request list fail网络问题,请求消息列表失败
                      10003Request subscribe fail网络问题,订阅请求发送失败
                      10004Invalid template id参数类型错误
                      10005Cannot show subscribe message UI无法展示 UI,一般是小程序这个时候退后台了导致的
                      20001No template data return, verify the template id exist没有模板数据,一般是模板 ID 不存在 或者和模板类型不对应 导致的
                      20002Templates type must be same模板消息类型 既有一次性的又有永久的
                      20003Templates count out of max bounds模板消息数量超过上限
                      20004The main switch is switched off用户关闭了主开关,无法进行订阅
                      20005This mini program was banned from subscribing messages小程序被禁封

                      示例代码

                      wx.requestSubscribeMessage({  tmplIds: [''],  success (res) { }})


                      数据分析接口

                      开发者通过数据分析接口,可获取到小程序的各项数据指标,便于进行数据存储和整理。数据分析详细功能介绍及指标解释参见数据分析文档

                      概况

                      用户访问小程序的详细数据可从访问分析中获取,概况中提供累计用户数等部分指标数据。

                      概况趋势

                      接口地址

                      https://api.weixin.qq.com/datacube/getweanalysisappiddailysummarytrend?access_token=ACCESS_TOKEN

                      获取 access_token 详见文档

                      POST 请求参数说明:

                      参数是否必填说明
                      begin_date开始日期
                      end_date结束日期,限定查询1天数据,end_date允许设置的最大值为昨日

                      POST 内容示例:

                      {  "begin_date" : "20170313",  "end_date" : "20170313"}

                      返回参数说明:

                      参数说明
                      visit_total累计用户数
                      share_pv转发次数
                      share_uv转发人数

                      返回数据示例:

                      {  "list": [    {      "ref_date": "20170313",      "visit_total": 391,      "share_pv": 572,      "share_uv": 383    }  ]}

                      访问分析

                      获取小程序访问分析数据,数据说明参见访问分析

                      访问趋势

                      日趋势

                      接口地址

                      https://api.weixin.qq.com/datacube/getweanalysisappiddailyvisittrend?access_token=ACCESS_TOKEN

                      POST 参数说明

                      参数是否必填说明
                      begin_date开始日期
                      end_date结束日期,限定查询1天数据,end_date允许设置的最大值为昨日

                      POST 内容示例:

                      {  "begin_date" : "20170313",  "end_date" : "20170313"}

                      返回参数说明:

                      参数说明
                      ref_date时间: 如: "20170313"
                      session_cnt打开次数
                      visit_pv访问次数
                      visit_uv访问人数
                      visit_uv_new新用户数
                      stay_time_uv人均停留时长 (浮点型,单位:秒)
                      stay_time_session次均停留时长 (浮点型,单位:秒)
                      visit_depth平均访问深度 (浮点型)

                      返回数据示例:

                      {  "list": [    {      "ref_date": "20170313",      "session_cnt": 142549,      "visit_pv": 472351,      "visit_uv": 55500,      "visit_uv_new": 5464,      "stay_time_session": 0,      "visit_depth": 1.9838    }  ]}

                      周趋势

                      接口地址

                      https://api.weixin.qq.com/datacube/getweanalysisappidweeklyvisittrend?access_token=ACCESS_TOKEN

                      POST 参数说明:

                      参数是否必填说明
                      begin_date开始日期,为周一日期
                      end_date结束日期,为周日日期,限定查询一周数据

                      注意:请求json和返回json与天的一致,这里限定查询一个自然周的数据,时间必须按照自然周的方式输入: 如:20170306(周一), 20170312(周日)

                      POST 内容示例:

                      {"begin_date":"20170306","end_date":"20170312"}

                      返回参数说明:

                      参数说明
                      ref_date时间,如:"20170306-20170312"
                      session_cnt打开次数(自然周内汇总)
                      visit_pv访问次数(自然周内汇总)
                      visit_uv访问人数(自然周内去重)
                      visit_uv_new新用户数(自然周内去重)
                      stay_time_uv人均停留时长 (浮点型,单位:秒)
                      stay_time_session次均停留时长 (浮点型,单位:秒)
                      visit_depth平均访问深度 (浮点型)

                      返回内容示例:

                      {  "list": [    {      "ref_date": "20170306-20170312",      "session_cnt": 986780,      "visit_pv": 3251840,      "visit_uv": 189405,      "visit_uv_new": 45592,      "stay_time_session": 54.5346,      "visit_depth": 1.9735    }  ]}

                      月趋势

                      接口地址

                      https://api.weixin.qq.com/datacube/getweanalysisappidmonthlyvisittrend?access_token=ACCESS_TOKEN

                      POST 参数说明:

                      参数是否必填说明
                      begin_date开始日期,为自然月第一天
                      end_date结束日期,为自然月最后一天,限定查询一个月数据

                      注意:请求json和返回json与天的一致,这里限定查询一个自然月的数据,时间必须按照自然月的方式输入: 如:20170201(月初), 20170228(月末)

                      POST 内容示例:

                      {"begin_date":"20170201","end_date":"20170228"}

                      返回参数说明:

                      参数说明
                      ref_date时间,如:"201702"
                      session_cnt打开次数(自然月内汇总)
                      visit_pv访问次数(自然月内汇总)
                      visit_uv访问人数(自然月内去重)
                      visit_uv_new新用户数(自然月内去重)
                      stay_time_uv人均停留时长 (浮点型,单位:秒)
                      stay_time_session次均停留时长 (浮点型,单位:秒)
                      visit_depth平均访问深度 (浮点型)

                      返回内容示例:

                      {  "list": [    {      "ref_date": "201702",      "session_cnt": 126513,      "visit_pv": 426113,      "visit_uv": 48659,      "visit_uv_new": 6726,      "stay_time_session": 56.4112,      "visit_depth": 2.0189    }  ]}

                      访问分布

                      接口地址

                      https://api.weixin.qq.com/datacube/getweanalysisappidvisitdistribution?access_token=ACCESS_TOKEN

                      POST 参数说明:

                      参数是否必填说明
                      begin_date开始日期
                      end_date结束日期,限定查询1天数据,end_date允许设置的最大值为昨日

                      POST 内容示例:

                      {"begin_date":"20170313","end_date":"20170313"}

                      返回参数说明:

                      参数说明
                      ref_date时间: 如: "20170313"
                      list存入所有类型的指标情况

                      list 的每一项包括:

                      参数说明
                      index分布类型
                      item_list分布数据列表

                      分布类型(index)的取值范围:

                      说明
                      access_source_session_cnt访问来源分布
                      access_staytime_info访问时长分布
                      access_depth_info访问深度的分布

                      每个数据项包括:

                      参数说明
                      key场景 id
                      value 场景下的值(均为整数型)

                      key对应关系如下:

                      访问来源:(index="access_source_session_cnt")

                      1:小程序历史列表

                      2:搜索

                      3:会话

                      4:二维码

                      5:公众号主页

                      6:聊天顶部

                      7:系统桌面

                      8:小程序主页

                      9:附近的小程序

                      10:其他

                      11:模板消息

                      12:客服消息

                      13: 公众号菜单

                      14: APP分享

                      15: 支付完成页

                      16: 长按识别二维码

                      17:相册选取二维码

                      18: 公众号文章

                      访问时长:(index="access_staytime_info")

                      1: 0-2s

                      2: 3-5s

                      3: 6-10s

                      4: 11-20s

                      5: 20-30s

                      6: 30-50s

                      7: 50-100s

                      8: > 100s

                      平均访问深度:(index="access_depth_info")

                      1: 1页

                      2: 2页

                      3: 3页

                      4: 4页

                      5: 5页

                      6: 6-10页

                      7: >10页

                      返回数据示例:

                      {  "ref_date": "20170313",  "list": [    {      "index": "access_source_session_cnt",      "item_list": [        {          "key": 10,          "value": 5        },        {          "key": 8,          "value": 687        },        {          "key": 7,          "value": 10740        },        {          "key": 6,          "value": 1961        },        {          "key": 5,          "value": 677        },        {          "key": 4,          "value": 653        },        {          "key": 3,          "value": 1120        },        {          "key": 2,          "value": 10243        },        {          "key": 1,          "value": 116578        }      ]    },    {      "index": "access_staytime_info",      "item_list": [        {          "key": 8,          "value": 16329        },        {          "key": 7,          "value": 19322        },        {          "key": 6,          "value": 21832        },        {          "key": 5,          "value": 19539        },        {          "key": 4,          "value": 29670        },        {          "key": 3,          "value": 19667        },        {          "key": 2,          "value": 11794        },        {          "key": 1,          "value": 4511        }      ]    },    {      "index": "access_depth_info",      "item_list": [        {          "key": 5,          "value": 217        },        {          "key": 4,          "value": 3259        },        {          "key": 3,          "value": 32445        },        {          "key": 2,          "value": 63542        },        {          "key": 1,          "value": 43201        }      ]    }  ]}

                      访问留存

                      日留存

                      接口地址

                      https://api.weixin.qq.com/datacube/getweanalysisappiddailyretaininfo?access_token=ACCESS_TOKEN

                      POST 参数说明:

                      参数是否必填说明
                      begin_date开始日期
                      end_date结束日期,限定查询1天数据,end_date允许设置的最大值为昨日

                      POST 内容示例:

                      {  "begin_date" : "20170313",  "end_date" : "20170313"}

                      返回参数说明:

                      参数说明
                      visit_uv_new新增用户留存
                      visit_uv活跃用户留存

                      visit_uv、visit_uv_new 的每一项包括:

                      参数说明
                      key标识,0开始,0表示当天,1表示1天后,依此类推,key取值分别是:0,1,2,3,4,5,6,7,14,30
                      valuekey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      返回数据示例:

                      {  "ref_date": "20170313",  "visit_uv_new": [    {      "key": 0,      "value": 5464    }  ],  "visit_uv": [    {      "key": 0,      "value": 55500    }  ]}

                      周留存

                      接口地址

                      https://api.weixin.qq.com/datacube/getweanalysisappidweeklyretaininfo?access_token=ACCESS_TOKEN

                      POST 参数说明:

                      参数是否必填说明
                      begin_date开始日期,为周一日期
                      end_date结束日期,为周日日期,限定查询一周数据

                      注意:请求json和返回json与天的一致,这里限定查询一个自然周的数据,时间必须按照自然周的方式输入: 如:20170306(周一), 20170312(周日)

                      POST 内容示例:

                      {  "begin_date" : "20170306",  "end_date" : "20170312"}

                      返回参数说明:

                      参数说明
                      ref_date时间,如:"20170306-20170312"
                      visit_uv_new新增用户留存
                      visit_uv活跃用户留存

                      visit_uv、visit_uv_new 的每一项包括:

                      参数说明
                      key标识,0开始,0表示当周,1表示1周后,依此类推,key取值分别是:0,1,2,3,4
                      valuekey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      返回内容示例:

                      {  "ref_date": "20170306-20170312",  "visit_uv_new": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 16853    }  ],  "visit_uv": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 99310    }  ]}

                      月留存

                      接口地址

                      https://api.weixin.qq.com/datacube/getweanalysisappidmonthlyretaininfo?access_token=ACCESS_TOKEN

                      POST 参数说明:

                      参数是否必填说明
                      begin_date开始日期,为自然月第一天
                      end_date结束日期,为自然月最后一天,限定查询一个月数据

                      注意:请求json和返回json与天的一致,这里限定查询一个自然月的数据,时间必须按照自然月的方式输入: 如:20170201(月初), 20170228(月末)

                      POST 内容示例:

                      {  "begin_date":"20170201",  "end_date":"20170228"}

                      返回参数说明:

                      参数说明
                      ref_date时间,如:"201702"
                      visit_uv_new新增用户留存
                      visit_uv活跃用户留存

                      visit_uv、visit_uv_new 的每一项包括:

                      参数说明
                      key标识,0开始,0表示当月,1表示1月后,key取值分别是:0,1
                      valuekey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      返回内容示例:

                      {  "ref_date": "201702",  "visit_uv_new": [    {      "key": 0,      "value": 346249    }  ],  "visit_uv": [    {      "key": 0,      "value": 346249    }  ]}

                      访问页面

                      访问页面

                      接口地址

                      https://api.weixin.qq.com/datacube/getweanalysisappidvisitpage?access_token=ACCESS_TOKEN

                      POST 参数说明:

                      参数是否必填说明
                      begin_date开始日期
                      end_date结束日期,限定查询1天数据,end_date允许设置的最大值为昨日

                      POST 内容示例:

                      {  "begin_date":"20170313",  "end_date":"20170313"}

                      返回参数说明:

                      参数说明
                      page_path页面路径
                      page_visit_pv访问次数
                      page_visit_uv访问人数
                      page_staytime_pv次均停留时长
                      entrypage_pv进入页次数
                      exitpage_pv退出页次数
                      page_share_pv转发次数
                      page_share_uv转发人数

                      返回内容示例:

                      {  "ref_date": "20170313",  "list": [    {      "page_path": "pages/main/main.html",      "page_visit_pv": 213429,      "page_visit_uv": 55423,      "page_staytime_pv": 8.139198,      "entrypage_pv": 117922,      "exitpage_pv": 61304,      "page_share_pv": 180,      "page_share_uv": 166    },    {      "page_path": "pages/linedetail/linedetail.html",      "page_visit_pv": 155030,      "page_visit_uv": 42195,      "page_staytime_pv": 35.462395,      "entrypage_pv": 21101,      "exitpage_pv": 47051,      "page_share_pv": 47,      "page_share_uv": 42    },    {      "page_path": "pages/search/search.html",      "page_visit_pv": 65011,      "page_visit_uv": 24716,      "page_staytime_pv": 6.889634,      "entrypage_pv": 1811,      "exitpage_pv": 3198,      "page_share_pv": 0,      "page_share_uv": 0    },    {      "page_path": "pages/stationdetail/stationdetail.html",      "page_visit_pv": 29953,      "page_visit_uv": 9695,      "page_staytime_pv": 7.558508,      "entrypage_pv": 1386,      "exitpage_pv": 2285,      "page_share_pv": 0,      "page_share_uv": 0    },    {      "page_path": "pages/switch-city/switch-city.html",      "page_visit_pv": 8928,      "page_visit_uv": 4017,      "page_staytime_pv": 9.22659,      "entrypage_pv": 748,      "exitpage_pv": 1613,      "page_share_pv": 0,      "page_share_uv": 0    }  ]}

                      返回参数说明:

                      参数说明
                      page_path页面路径
                      page_visit_pv访问次数
                      page_visit_uv访问人数
                      page_staytime_pv次均停留时长
                      entrypage_pv进入页次数
                      exitpage_pv退出页次数
                      page_share_pv转发次数
                      page_share_uv转发人数

                      注意:目前只提供按 page_visit_pv 排序的 top200

                      用户画像

                      获取小程序新增或活跃用户的画像分布数据。时间范围支持昨天、最近7天、最近30天。其中,新增用户数为时间范围内首次访问小程序的去重用户数,活跃用户数为时间范围内访问过小程序的去重用户数。画像属性包括用户年龄、性别、省份、城市、终端类型、机型。

                      接口地址: https://api.weixin.qq.com/datacube/getweanalysisappiduserportrait?access_token=ACCESS_TOKEN

                      POST 请求参数说明:

                      参数是否必填说明
                      begin_date开始日期
                      end_date结束日期,开始日期与结束日期相差的天数限定为0/6/29,分别表示查询最近1/7/30天数据,end_date允许设置的最大值为昨日

                      POST 内容示例:

                      {    "begin_date" : "2017-06-11",    "end_date" : "2017-06-17"}

                      返回参数说明:

                      每次请求返回选定的时间范围及以下指标项:

                      参数说明
                      ref_date时间范围,如: "20170611-20170617"
                      visit_uv_new新用户
                      visit_uv活跃用户

                      每个指标项下包括的属性:

                      参数说明
                      province省份,如北京、广东等
                      city城市,如北京、广州等
                      genders性别,包括男、女、未知
                      platfomrs终端类型,包括iPhone, android,其他
                      devices机型,如苹果iPhone6, OPPO R9等
                      ages年龄,包括17岁以下、18-24岁等区间

                      每个属性下包括的数据项:

                      参数说明
                      id属性值id
                      name属性值名称,与id一一对应。如属性为province时,返回的属性值名称包括“广东”等
                      value属性值对应的指标值,如指标为visit_uv,属性为province,属性值为"广东省”,value对应广东地区的活跃用户数

                      返回数据示例:

                      {  "ref_date": "20170611",  "visit_uv_new": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 215      }    ],    "city": [     {        "id": 3102,        "name": "广州",        "value": 78      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 2146      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 27642      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 61      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 151      }    ]  },  "visit_uv": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 1341      }    ],    "city": [     {        "id": 3102,        "name": "广州",        "value": 234      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 14534      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 21750      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 617      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 3156      }    ]  }}

                      注:

                      1. 由于部分用户属性数据缺失,属性值可能出现 “未知”。
                      2. 机型数据无 id 字段,暂只提供用户数最多的 top20。

                      wx.reportAnalytics(eventName, data)

                      自定义分析数据上报接口。使用前,需要在小程序管理后台自定义分析中新建事件,配置好事件名与字段。

                      参数说明:

                      参数类型必填说明
                      eventNameString事件名。
                      dataObject上报的自定义数据。key为配置中的字段名,value为上报的数据

                      示例代码:

                      wx.reportAnalytics('purchase', {  price: 120,  color: 'red'})

                      wx.getUpdateManager()


                      基础库 1.9.90 开始支持,低版本需做兼容处理

                      获取全局唯一的版本更新管理器,用于管理小程序更新。

                      关于小程序的更新机制,可以查看 运行机制 文档。

                      updateManager


                      updateManager 对象的方法列表:

                      方法参数说明
                      onCheckForUpdatecallback当向微信后台请求完新版本信息,会进行回调
                      onUpdateReadycallback当新版本下载完成,会进行回调
                      onUpdateFailedcallback当新版本下载失败,会进行回调
                      applyUpdate当新版本下载完成,调用该方法会强制当前小程序应用上新版本并重启

                      onCheckForUpdate(callback) 回调结果说明:

                      属性类型说明
                      hasUpdateBoolean是否有新的版本

                      注: 检查更新操作由微信在小程序冷启动时自动触发,不需由开发者主动触发,开发者只需监听检查结果即可。

                      onUpdateReady(callback) 回调结果说明:

                      当微信检查到小程序有新版本,会主动触发下载操作(无需开发者触发),当下载完成后,会通过 onUpdateReady 告知开发者。

                      onUpdateFailed(callback) 回调结果说明:

                      当微信检查到小程序有新版本,会主动触发下载操作(无需开发者触发),如果下载失败(可能是网络原因等),会通过 onUpdateFailed 告知开发者。

                      applyUpdate() 说明:

                      当小程序新版本已经下载时(即收到 onUpdateReady 回调),可以通过这个方法强制重启小程序并应用上最新版本。

                      示例代码:

                      const updateManager = wx.getUpdateManager()updateManager.onCheckForUpdate(function (res) {  // 请求完新版本信息的回调  console.log(res.hasUpdate)})updateManager.onUpdateReady(function () {  // 新的版本已经下载好,调用 applyUpdate 应用新版本并重启  updateManager.applyUpdate()})updateManager.onUpdateFailed(function () {  // 新的版本下载失败})

                      wx.updateWeChatApp()

                      基础库 2.12.0 开始支持,低版本需做兼容处理。

                      更新客户端版本。当判断用户小程序所在客户端版本过低时,可使用该接口跳转到更新微信页面。

                      参数

                      Object object

                      属性类型默认值必填说明
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)


                      wx.arrayBufferToBase64(arrayBuffer)


                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      将 ArrayBuffer 数据转成 Base64 字符串

                      示例代码

                      const arrayBuffer = new Uint8Array([11, 22, 33])const base64 = wx.arrayBufferToBase64(arrayBuffer)

                      wx.base64ToArrayBuffer(base64)


                      基础库版本 1.1.0 开始支持,低版本需做兼容处理

                      将 Base64 字符串转成 ArrayBuffer 数据

                      示例代码

                      const base64 = 'CxYh'const arrayBuffer = wx.base64ToArrayBuffer(base64)

                      wx.createWorker(scriptPath)


                      基础库 1.9.90 开始支持,低版本需做兼容处理

                      在使用 createWorker 前,请查阅 多线程 文档了解基础知识和配置方法。

                      创建一个 Worker 线程,并返回 Worker 实例,目前限制最多只能创建一个 Worker,创建下一个 Worker 前请调用 Worker.terminate。

                      scriptPath 为 worker 的入口文件路径,需填写绝对路径。

                      Worker

                      Worker 对象的方法列表:

                      方法参数说明
                      postMessageObject向 Worker 线程发送的消息。
                      onMessagecallback监听 Worker 线程向当前线程发送的消息
                      terminate结束当前 Worker 线程,仅限在主线程 Worker 实例上调用。

                      postMessage(message) 说明:

                      向 Worker 线程发送消息,message 参数为需要发送的消息,必须是一个可序列化的 JavaScript 对象。

                      onMessage(callback) 回调结果说明:

                      属性类型说明
                      messageObjectWorker 线程向当前线程发送的消息

                      terminate() 说明:

                      结束当前 worker 线程,仅限在主线程 Worker 对象上调用。

                      示例代码:

                      运行以下代码需先进行基础配置,详细请查阅 多线程 文档了解基础知识和配置方法。

                      const worker = wx.createWorker('workers/request/index.js') // 文件名指定 worker 的入口文件路径,绝对路径worker.onMessage(function (res) {  console.log(res)})worker.postMessage({  msg: 'hello worker'})worker.terminate()

                      wx.setEnableDebug(OBJECT)

                      基础库 1.4.0 开始支持,低版本需做兼容处理

                      设置是否打开调试开关,此开关对正式版也能生效。

                      OBJECT参数说明:

                      参数名类型必填说明
                      enableDebugBoolean是否打开调试
                      successFunction接口调用成功的回调函数
                      failFunction接口调用失败的回调函数
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success返回参数说明:

                      参数名类型说明
                      errMsgString调用结果

                      示例代码:

                      // 打开调试wx.setEnableDebug({    enableDebug: true})// 关闭调试wx.setEnableDebug({    enableDebug: false})


                      InterstitialAd wx.createInterstitialAd(Object object)

                      基础库 2.6.0 开始支持,低版本需做兼容处理

                      创建插屏广告组件。请通过 wx.getSystemInfoSync() 返回对象的 SDKVersion 判断基础库版本号后再使用该 API。每次调用该方法创建插屏广告都会返回一个全新的实例(小程序端的插屏广告实例不允许跨页面使用)。

                      参数

                      Object object

                      属性类型默认值必填说明
                      adUnitIdstring广告单元 id

                      返回值

                      InterstitialAd

                      插屏广告组件


                      InterstitialAd

                      插屏广告组件。插屏广告组件是一个原生组件,层级比普通组件高。插屏广告组件每次创建都会返回一个全新的实例(小程序端的插屏广告实例不允许跨页面使用),默认是隐藏的,需要调用 InterstitialAd.show() 将其显示。


                      方法:

                      InterstitialAd.destroy()

                      基础库 2.8.0 开始支持,低版本需做兼容处理

                      销毁插屏广告实例。


                      Promise InterstitialAd.load()

                      基础库 2.8.0 开始支持,低版本需做兼容处理

                      加载插屏广告。

                      返回值

                      Promise

                      插屏广告加载数据的结果


                      InterstitialAd.offClose(function callback)

                      取消监听插屏广告关闭事件

                      参数

                      function callback

                      插屏广告关闭事件的回调函数


                      InterstitialAd.offError(function callback)

                      取消监听插屏错误事件

                      参数

                      function callback

                      插屏错误事件的回调函数


                      InterstitialAd.offLoad(function callback)

                      取消监听插屏广告加载事件

                      参数

                      function callback

                      插屏广告加载事件的回调函数


                      InterstitialAd.onClose(function callback)

                      监听插屏广告关闭事件。

                      参数

                      function callback

                      插屏广告关闭事件的回调函数


                      InterstitialAd.onError(function callback)

                      监听插屏错误事件。

                      参数

                      function callback

                      插屏错误事件的回调函数

                      参数

                      Object res
                      属性类型说明
                      errMsgstring错误信息
                      errCodenumber错误码

                      errCode 的合法值

                      说明最低版本
                      1000后端接口调用失败
                      1001参数错误
                      1002广告单元无效
                      1003内部错误
                      1004无合适的广告
                      1005广告组件审核中
                      1006广告组件被驳回
                      1007广告组件被封禁
                      1008广告单元已关闭

                      错误码信息与解决方案表

                      错误码是通过onError获取到的错误信息。调试期间,可以通过异常返回来捕获信息。 在小程序发布上线之后,如果遇到异常问题,可以在“运维中心“里面搜寻错误日志,还可以针对异常返回加上适当的监控信息。

                      代码异常情况理由解决方案
                      1000后端错误调用失败该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
                      1001参数错误使用方法错误可以前往developers.weixin.qq.com确认具体教程(小程序和小游戏分别有各自的教程,可以在顶部选项中,“设计”一栏的右侧进行切换。
                      1002广告单元无效可能是拼写错误、或者误用了其他APP的广告ID请重新前往mp.weixin.qq.com确认广告位ID。
                      1003内部错误该项错误不是开发者的异常情况一般情况下忽略一段时间即可恢复。
                      1004无适合的广告广告不是每一次都会出现,这次没有出现可能是由于该用户不适合浏览广告属于正常情况,且开发者需要针对这种情况做形态上的兼容。
                      1005广告组件审核中你的广告正在被审核,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
                      1006广告组件被驳回你的广告审核失败,无法展现广告请前往mp.weixin.qq.com确认审核状态,且开发者需要针对这种情况做形态上的兼容。
                      1007广告组件被驳回你的广告能力已经被封禁,封禁期间无法展现广告请前往mp.weixin.qq.com确认小程序广告封禁状态。
                      1008广告单元已关闭该广告位的广告能力已经被关闭请前往mp.weixin.qq.com重新打开对应广告位的展现。


                      InterstitialAd.onLoad(function callback)

                      监听插屏广告加载事件。

                      参数

                      function callback

                      插屏广告加载事件的回调函数


                      Promise InterstitialAd.show()

                      显示插屏广告。

                      返回值

                      Promise

                      插屏广告显示操作的结果

                      错误码信息表

                      如果插屏广告显示失败,InterstitialAd.show() 方法会返回一个rejected Promise,开发者可以获取到错误码及对应的错误信息。

                      代码异常情况理由
                      2001触发频率限制小程序启动一定时间内不允许展示插屏广告
                      2002触发频率限制距离小程序插屏广告或者激励视频广告上次播放时间间隔不足,不允许展示插屏广告
                      2003触发频率限制当前正在播放激励视频广告或者插屏广告,不允许再次展示插屏广告
                      2004广告渲染失败该项错误不是开发者的异常情况,或因小程序页面切换导致广告渲染失败
                      2005广告调用异常插屏广告实例不允许跨页面调用


                      wx.switchTab(Object object)

                      跳转到 tabBar 页面,并关闭其他所有非 tabBar 页面

                      参数

                      Object object

                      属性类型默认值必填说明
                      urlstring需要跳转的 tabBar 页面的路径 (代码包路径)(需在 app.json 的 tabBar 字段定义的页面),路径后不能带参数。
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      {  "tabBar": {    "list": [{      "pagePath": "index",      "text": "首页"    },{      "pagePath": "other",      "text": "其他"    }]  }}
                      wx.switchTab({  url: '/index'})


                      wx.reLaunch(Object object)

                      基础库 1.1.0 开始支持,低版本需做兼容处理

                      关闭所有页面,打开到应用内的某个页面

                      参数

                      Object object

                      属性类型默认值必填说明
                      urlstring需要跳转的应用内页面路径 (代码包路径),路径后可以带参数。参数与路径之间使用?分隔,参数键与参数值用=相连,不同参数用&分隔;如 'path?key=value&key2=value2'
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.reLaunch({  url: 'test?id=1'})
                      // testPage({  onLoad (option) {    console.log(option.query)  }})


                      wx.redirectTo(Object object)

                      关闭当前页面,跳转到应用内的某个页面。但是不允许跳转到 tabbar 页面。

                      参数

                      Object object

                      属性类型默认值必填说明
                      urlstring需要跳转的应用内非 tabBar 的页面的路径 (代码包路径), 路径后可以带参数。参数与路径之间使用 ? 分隔,参数键与参数值用 = 相连,不同参数用 & 分隔;如 'path?key=value&key2=value2'
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      wx.redirectTo({  url: 'test?id=1'})


                      wx.navigateTo(Object object)

                      保留当前页面,跳转到应用内的某个页面。但是不能跳到 tabbar 页面。使用 wx.navigateBack 可以返回到原页面。小程序中页面栈最多十层。

                      参数

                      Object object

                      属性类型默认值必填说明
                      urlstring需要跳转的应用内非 tabBar 的页面的路径 (代码包路径), 路径后可以带参数。参数与路径之间使用 ? 分隔,参数键与参数值用 = 相连,不同参数用 & 分隔;如 'path?key=value&key2=value2'
                      eventsObject页面间通信接口,用于监听被打开页面发送到当前页面的数据。基础库 2.7.3 开始支持。
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.success 回调函数

                      参数
                      Object res
                      属性类型说明
                      eventChannelEventChannel和被打开页面进行通信

                      示例代码

                      wx.navigateTo({  url: 'test?id=1',  events: {    // 为指定事件添加一个监听器,获取被打开页面传送到当前页面的数据    acceptDataFromOpenedPage: function(data) {      console.log(data)    },    someEvent: function(data) {      console.log(data)    }    ...  },  success: function(res) {    // 通过eventChannel向被打开页面传送数据    res.eventChannel.emit('acceptDataFromOpenerPage', { data: 'test' })  }})
                      //test.jsPage({  onLoad: function(option){    console.log(option.query)    const eventChannel = this.getOpenerEventChannel()    eventChannel.emit('acceptDataFromOpenedPage', {data: 'test'});    eventChannel.emit('someEvent', {data: 'test'});    // 监听acceptDataFromOpenerPage事件,获取上一页面通过eventChannel传送到当前页面的数据    eventChannel.on('acceptDataFromOpenerPage', function(data) {      console.log(data)    })  }})


                      wx.navigateBack(Object object)

                      关闭当前页面,返回上一页面或多级页面。可通过 getCurrentPages 获取当前的页面栈,决定需要返回几层。

                      参数

                      Object object

                      属性类型默认值必填说明
                      deltanumber1返回的页面数,如果 delta 大于现有页面数,则返回到首页。
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      示例代码

                      // 注意:调用 navigateTo 跳转时,调用该方法的页面会被加入堆栈,而 redirectTo 方法则不会。见下方示例代码// 此处是A页面wx.navigateTo({  url: 'B?id=1'})// 此处是B页面wx.navigateTo({  url: 'C?id=1'})// 在C页面内 navigateBack,将返回A页面wx.navigateBack({  delta: 2})


                      EventChannel

                      基础库 2.7.3 开始支持,低版本需做兼容处理

                      页面间事件通信通道

                      方法:

                      EventChannel.emit(string eventName, any args)

                      基础库 2.7.3 开始支持,低版本需做兼容处理

                      触发一个事件

                      参数

                      string eventName

                      事件名称

                      any args

                      事件参数


                      EventChannel.off(string eventName, function fn)

                      基础库 2.7.3 开始支持,低版本需做兼容处理

                      取消监听一个事件。给出第二个参数时,只取消给出的监听函数,否则取消所有监听函数

                      参数

                      string eventName

                      事件名称

                      function fn

                      事件监听函数

                      参数

                      any args

                      触发事件参数


                      EventChannel.on(string eventName, function fn)

                      基础库 2.7.3 开始支持,低版本需做兼容处理

                      持续监听一个事件

                      参数

                      string eventName

                      事件名称

                      function fn

                      事件监听函数

                      参数

                      any args

                      触发事件参数


                      EventChannel.once(string eventName, function fn)

                      基础库 2.7.3 开始支持,低版本需做兼容处理

                      监听一个事件一次,触发后失效

                      参数

                      string eventName

                      事件名称

                      function fn

                      事件监听函数

                      参数

                      any args

                      触发事件参数


                      auth.code2Session


                      auth.code2Session

                      本接口应在服务器端调用,详细说明参见服务端API

                      登录凭证校验。通过 wx.login 接口获得临时登录凭证 code 后传到开发者服务器调用此接口完成登录流程。更多使用方法详见 小程序登录

                      请求地址

                      GET https://api.weixin.qq.com/sns/jscode2session?appid=APPID&secret=SECRET&js_code=JSCODE&grant_type=authorization_code

                      请求参数

                      属性类型默认值必填说明
                      appidstring小程序 appId
                      secretstring小程序 appSecret
                      js_codestring登录时获取的 code
                      grant_typestring授权类型,此处只需填写 authorization_code

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      openidstring用户唯一标识
                      session_keystring会话密钥
                      unionidstring用户在开放平台的唯一标识符,在满足 UnionID 下发条件的情况下会返回。
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      -1系统繁忙,此时请开发者稍候再试
                      0请求成功
                      40029code 无效
                      45011频率限制,每个用户每分钟100次


                      auth.getPaidUnionId

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      用户支付完成后,获取该用户的 UnionId,无需用户授权。本接口支持第三方平台代理查询。

                      • 注意:调用前需要用户完成支付,且在支付后的五分钟内有效。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/wxa/getpaidunionid?access_token=ACCESS_TOKEN&openid=OPENID

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      openidstring支付用户唯一标识
                      transaction_idstring微信支付订单号
                      mch_idstring微信支付分配的商户号,和商户订单号配合使用
                      out_trade_nostring微信支付商户订单号,和商户号配合使用

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      unionidstring用户唯一标识,调用成功后返回
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      -1系统繁忙,此时请开发者稍候再试
                      0请求成功
                      40003openid 错误
                      89002没有绑定开放平台帐号
                      89300订单无效

                      使用说明

                      以下两种方式任选其一。

                      1. 微信支付订单号(transaction_id):
                      https://api.weixin.qq.com/wxa/getpaidunionid?access_token=ACCESS_TOKEN&openid=OPENID&transaction_id=TRANSACTION_ID
                      1. 微信支付商户订单号和微信支付商户号(out_trade_no 及 mch_id):
                       https://api.weixin.qq.com/wxa/getpaidunionid?access_token=ACCESS_TOKEN&openid=OPENID&mch_id=MCH_ID&out_trade_no=OUT_TRADE_NO

                      返回数据示例

                      {  "unionid": "oTmHYjg-tElZ68xxxxxxxxhy1Rgk",  "errcode": 0,  "errmsg": "ok"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.auth.getPaidUnionId
                      需在 config.json 中配置 auth.getPaidUnionId API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      openidstring支付用户唯一标识
                      transactionIdstring微信支付订单号
                      mchIdstring微信支付分配的商户号,和商户订单号配合使用
                      outTradeNostring微信支付商户订单号,和商户号配合使用

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      unionidstring用户唯一标识,调用成功后返回
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      -1系统繁忙,此时请开发者稍候再试
                      40003openid 错误
                      89002没有绑定开放平台帐号
                      89300订单无效

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.auth.getPaidUnionId({        openid: '',        transactionId: '',        mchId: '',        outTradeNo: ''      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "unionid": "oTmHYjg-tElZ68xxxxxxxxhy1Rgk",  "errCode": 0,  "errMsg": "openapi.auth.getPaidUnionId:ok"}


                      auth.getAccessToken

                      本接口应在服务器端调用,详细说明参见服务端API

                      获取小程序全局唯一后台接口调用凭据(access_token)。调用绝大多数后台接口时都需使用 access_token,开发者需要进行妥善保存。

                      请求地址

                      GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

                      请求参数

                      属性类型默认值必填说明
                      grant_typestring填写 client_credential
                      appidstring小程序唯一凭证,即 AppID,可在「微信公众平台 - 设置 - 开发设置」页中获得。(需要已经成为开发者,且帐号没有异常状态)
                      secretstring小程序唯一凭证密钥,即 AppSecret,获取方式同 appid

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      access_tokenstring获取到的凭证
                      expires_innumber凭证有效时间,单位:秒。目前是7200秒之内的值。
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      -1系统繁忙,此时请开发者稍候再试
                      0请求成功
                      40001AppSecret 错误或者 AppSecret 不属于这个小程序,请开发者确认 AppSecret 的正确性
                      40002请确保 grant_type 字段值为 client_credential
                      40013不合法的 AppID,请开发者检查 AppID 的正确性,避免异常字符,注意大小写

                      返回数据示例

                      正常返回

                      {"access_token":"ACCESS_TOKEN","expires_in":7200}

                      错误时返回

                      {"errcode":40013,"errmsg":"invalid appid"}

                      access_token 的存储与更新

                      • access_token 的存储至少要保留 512 个字符空间;
                      • access_token 的有效期目前为 2 个小时,需定时刷新,重复获取将导致上次获取的 access_token 失效;
                      • 建议开发者使用中控服务器统一获取和刷新 access_token,其他业务逻辑服务器所使用的 access_token 均来自于该中控服务器,不应该各自去刷新,否则容易造成冲突,导致 access_token 覆盖而影响业务;
                      • access_token 的有效期通过返回的 expires_in 来传达,目前是7200秒之内的值,中控服务器需要根据这个有效时间提前去刷新。在刷新过程中,中控服务器可对外继续输出的老 access_token,此时公众平台后台会保证在5分钟内,新老 access_token 都可用,这保证了第三方业务的平滑过渡;
                      • access_token 的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新 access_token 的接口,这样便于业务服务器在API调用获知 access_token 已超时的情况下,可以触发 access_token 的刷新流程。


                      analysis.getDailyRetain

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取用户访问小程序日留存

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/datacube/getweanalysisappiddailyretaininfo?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      begin_datestring开始日期。格式为 yyyymmdd
                      end_datestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      ref_datestring日期
                      visit_uv_newObject新增用户留存
                      visit_uvObject活跃用户留存

                      visit_uv_new 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当天,1表示1天后。依此类推,key取值分别是:0,1,2,3,4,5,6,7,14,30
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      visit_uv 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当天,1表示1天后。依此类推,key取值分别是:0,1,2,3,4,5,6,7,14,30
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      请求数据示例

                      {  "begin_date" : "20170313",  "end_date" : "20170313"}

                      返回数据示例

                      {  "ref_date": "20170313",  "visit_uv_new": [    {      "key": 0,      "value": 5464    }  ],  "visit_uv": [    {      "key": 0,      "value": 55500    }  ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.analysis.getDailyRetain
                      需在 config.json 中配置 analysis.getDailyRetain API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      beginDatestring开始日期。格式为 yyyymmdd
                      endDatestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      refDatestring日期
                      visitUvNewObject新增用户留存
                      visitUvObject活跃用户留存

                      visitUvNew 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当天,1表示1天后。依此类推,key取值分别是:0,1,2,3,4,5,6,7,14,30
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      visitUv 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当天,1表示1天后。依此类推,key取值分别是:0,1,2,3,4,5,6,7,14,30
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getDailyRetain({        beginDate: '20170313',        endDate: '20170313'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "refDate": "20170313",  "visitUvNew": [    {      "key": 0,      "value": 5464    }  ],  "visitUv": [    {      "key": 0,      "value": 55500    }  ],  "errMsg": "openapi.analysis.getDailyRetain:ok"}

                      analysis.getMonthlyRetain

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取用户访问小程序月留存

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/datacube/getweanalysisappidmonthlyretaininfo?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      begin_datestring开始日期,为自然月第一天。格式为 yyyymmdd
                      end_datestring结束日期,为自然月最后一天,限定查询一个月数据。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      ref_datestring时间,如:"201702"
                      visit_uv_newObject新增用户留存
                      visit_uvObject活跃用户留存

                      visit_uv_new 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当月,1表示1月后。key取值分别是:0,1
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      visit_uv 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当月,1表示1月后。key取值分别是:0,1
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      注意

                      请求json和返回json与天的一致,这里限定查询一个自然月的数据,时间必须按照自然月的方式输入: 如:20170201(月初), 20170228(月末)

                      请求数据示例

                      {  "begin_date" : "20170201",  "end_date" : "20170228"}

                      返回数据示例

                      {  "ref_date": "201702",  "visit_uv_new": [    {      "key": 0,      "value": 346249    }  ],  "visit_uv": [    {      "key": 0,      "value": 346249    }  ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.analysis.getMonthlyRetain
                      需在 config.json 中配置 analysis.getMonthlyRetain API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      beginDatestring开始日期,为自然月第一天。格式为 yyyymmdd
                      endDatestring结束日期,为自然月最后一天,限定查询一个月数据。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      refDatestring时间,如:"201702"
                      visitUvNewObject新增用户留存
                      visitUvObject活跃用户留存

                      visitUvNew 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当月,1表示1月后。key取值分别是:0,1
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      visitUv 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当月,1表示1月后。key取值分别是:0,1
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getMonthlyRetain({        beginDate: '20170201',        endDate: '20170228'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "refDate": "201702",  "visitUvNew": [    {      "key": 0,      "value": 346249    }  ],  "visitUv": [    {      "key": 0,      "value": 346249    }  ],  "errMsg": "openapi.analysis.getMonthlyRetain:ok"}

                      analysis.getWeeklyRetain

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取用户访问小程序周留存

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/datacube/getweanalysisappidweeklyretaininfo?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      begin_datestring开始日期,为周一日期。格式为 yyyymmdd
                      end_datestring结束日期,为周日日期,限定查询一周数据。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      ref_datestring时间,如:"20170306-20170312"
                      visit_uv_newObject新增用户留存
                      visit_uvObject活跃用户留存

                      visit_uv_new 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当周,1表示1周后。依此类推,取值分别是:0,1,2,3,4
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      visit_uv 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当周,1表示1周后。依此类推,取值分别是:0,1,2,3,4
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      注意

                      请求json和返回json与天的一致,这里限定查询一个自然周的数据,时间必须按照自然周的方式输入: 如:20170306(周一), 20170312(周日)

                      请求数据示例

                      {  "begin_date" : "20170306",  "end_date" : "20170312"}

                      返回数据示例

                      {  "ref_date": "20170306-20170312",  "visit_uv_new": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 16853    }  ],  "visit_uv": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 99310    }  ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.analysis.getWeeklyRetain
                      需在 config.json 中配置 analysis.getWeeklyRetain API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      beginDatestring开始日期,为周一日期。格式为 yyyymmdd
                      endDatestring结束日期,为周日日期,限定查询一周数据。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      refDatestring时间,如:"20170306-20170312"
                      visitUvNewObject新增用户留存
                      visitUvObject活跃用户留存

                      visitUvNew 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当周,1表示1周后。依此类推,取值分别是:0,1,2,3,4
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      visitUv 的结构

                      属性类型说明
                      keynumber标识,0开始,表示当周,1表示1周后。依此类推,取值分别是:0,1,2,3,4
                      valuenumberkey对应日期的新增用户数/活跃用户数(key=0时)或留存用户数(k>0时)

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getWeeklyRetain({        beginDate: '20170306',        endDate: '20170312'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "refDate": "20170306-20170312",  "visitUvNew": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 16853    }  ],  "visitUv": [    {      "key": 0,      "value": 0    },    {      "key": 1,      "value": 99310    }  ],  "errMsg": "openapi.analysis.getWeeklyRetain:ok"}


                      analysis.getDailySummary

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取用户访问小程序数据概况

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/datacube/getweanalysisappiddailysummarytrend?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      begin_datestring开始日期。格式为 yyyymmdd
                      end_datestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      listArray.<Object>数据列表

                      list 的结构

                      属性类型说明
                      ref_datestring日期,格式为 yyyymmdd
                      visit_totalnumber累计用户数
                      share_pvnumber转发次数
                      share_uvnumber转发人数

                      请求数据示例

                      {  "begin_date" : "20170313",  "end_date" : "20170313"}

                      返回数据示例

                      {  "list": [    {      "ref_date": "20170313",      "visit_total": 391,      "share_pv": 572,      "share_uv": 383    }  ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.analysis.getDailySummary
                      需在 config.json 中配置 analysis.getDailySummary API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      beginDatestring开始日期。格式为 yyyymmdd
                      endDatestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      listArray.<Object>数据列表

                      list 的结构

                      属性类型说明
                      refDatestring日期,格式为 yyyymmdd
                      visitTotalnumber累计用户数
                      sharePvnumber转发次数
                      shareUvnumber转发人数

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getDailySummary({        beginDate: '20170313',        endDate: '20170313'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "list": [    {      "refDate": "20170313",      "visitTotal": 391,      "sharePv": 572,      "shareUv": 383    }  ],  "errMsg": "openapi.analysis.getDailySummary:ok"}


                      analysis.getDailyVisitTrend

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取用户访问小程序数据日趋势

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/datacube/getweanalysisappiddailyvisittrend?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      begin_datestring开始日期。格式为 yyyymmdd
                      end_datestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      listArray.<Object>数据列表

                      list 的结构

                      属性类型说明
                      ref_datestring日期,格式为 yyyymmdd
                      session_cntnumber打开次数
                      visit_pvnumber访问次数
                      visit_uvnumber访问人数
                      visit_uv_newnumber新用户数
                      stay_time_uvnumber人均停留时长 (浮点型,单位:秒)
                      stay_time_sessionnumber次均停留时长 (浮点型,单位:秒)
                      visit_depthnumber平均访问深度 (浮点型)

                      请求数据示例

                      {  "begin_date" : "20170313",  "end_date" : "20170313"}

                      返回数据示例

                      {  "list": [    {      "ref_date": "20170313",      "session_cnt": 142549,      "visit_pv": 472351,      "visit_uv": 55500,      "visit_uv_new": 5464,      "stay_time_session": 0,      "visit_depth": 1.9838    }  ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.analysis.getDailyVisitTrend
                      需在 config.json 中配置 analysis.getDailyVisitTrend API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      beginDatestring开始日期。格式为 yyyymmdd
                      endDatestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      listArray.<Object>数据列表

                      list 的结构

                      属性类型说明
                      refDatestring日期,格式为 yyyymmdd
                      sessionCntnumber打开次数
                      visitPvnumber访问次数
                      visitUvnumber访问人数
                      visitUvNewnumber新用户数
                      stayTimeUvnumber人均停留时长 (浮点型,单位:秒)
                      stayTimeSessionnumber次均停留时长 (浮点型,单位:秒)
                      visitDepthnumber平均访问深度 (浮点型)

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getDailyVisitTrend({        beginDate: '20170313',        endDate: '20170313'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "list": [    {      "refDate": "20170313",      "sessionCnt": 142549,      "visitPv": 472351,      "visitUv": 55500,      "visitUvNew": 5464,      "stayTimeSession": 0,      "visitDepth": 1.9838    }  ],  "errMsg": "openapi.analysis.getDailyVisitTrend:ok"}

                      analysis.getMonthlyVisitTrend

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取用户访问小程序数据月趋势(能查询到的最新数据为上一个自然月的数据)

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/datacube/getweanalysisappidmonthlyvisittrend?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      begin_datestring开始日期,为自然月第一天。格式为 yyyymmdd
                      end_datestring结束日期,为自然月最后一天,限定查询一个月的数据。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      listArray.<Object>数据列表

                      list 的结构

                      属性类型说明
                      ref_datestring时间,格式为 yyyymm,如:"201702"
                      session_cntnumber打开次数(自然月内汇总)
                      visit_pvnumber访问次数(自然月内汇总)
                      visit_uvnumber访问人数(自然月内去重)
                      visit_uv_newnumber新用户数(自然月内去重)
                      stay_time_uvnumber人均停留时长 (浮点型,单位:秒)
                      stay_time_sessionnumber次均停留时长 (浮点型,单位:秒)
                      visit_depthnumber平均访问深度 (浮点型)

                      访问周期说明

                      限定查询一个自然月的数据,时间必须按照自然月的方式输入: 如:20170301, 20170331

                      请求数据示例

                      {  "begin_date" : "20170301",  "end_date" : "20170331"}

                      返回数据示例

                      {  "list": [    {      "ref_date": "201703",      "session_cnt": 126513,      "visit_pv": 426113,      "visit_uv": 48659,      "visit_uv_new": 6726,      "stay_time_session": 56.4112,      "visit_depth": 2.0189    }  ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.analysis.getMonthlyVisitTrend
                      需在 config.json 中配置 analysis.getMonthlyVisitTrend API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      beginDatestring开始日期,为自然月第一天。格式为 yyyymmdd
                      endDatestring结束日期,为自然月最后一天,限定查询一个月的数据。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      listArray.<Object>数据列表

                      list 的结构

                      属性类型说明
                      refDatestring时间,格式为 yyyymm,如:"201702"
                      sessionCntnumber打开次数(自然月内汇总)
                      visitPvnumber访问次数(自然月内汇总)
                      visitUvnumber访问人数(自然月内去重)
                      visitUvNewnumber新用户数(自然月内去重)
                      stayTimeUvnumber人均停留时长 (浮点型,单位:秒)
                      stayTimeSessionnumber次均停留时长 (浮点型,单位:秒)
                      visitDepthnumber平均访问深度 (浮点型)

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getMonthlyVisitTrend({        beginDate: '20170301',        endDate: '20170331'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "list": [    {      "refDate": "201703",      "sessionCnt": 126513,      "visitPv": 426113,      "visitUv": 48659,      "visitUvNew": 6726,      "stayTimeSession": 56.4112,      "visitDepth": 2.0189    }  ],  "errMsg": "openapi.analysis.getMonthlyVisitTrend:ok"}

                      analysis.getWeeklyVisitTrend

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取用户访问小程序数据周趋势

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/datacube/getweanalysisappidweeklyvisittrend?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      begin_datestring开始日期,为周一日期。格式为 yyyymmdd
                      end_datestring结束日期,为周日日期,限定查询一周数据。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      listArray.<Object>数据列表

                      list 的结构

                      属性类型说明
                      ref_datestring时间,格式为 yyyymmdd-yyyymmdd,如:"20170306-20170312"
                      session_cntnumber打开次数(自然周内汇总)
                      visit_pvnumber访问次数(自然周内汇总)
                      visit_uvnumber访问人数(自然周内去重)
                      visit_uv_newnumber新用户数(自然周内去重)
                      stay_time_uvnumber人均停留时长 (浮点型,单位:秒)
                      stay_time_sessionnumber次均停留时长 (浮点型,单位:秒)
                      visit_depthnumber平均访问深度 (浮点型)

                      访问周期说明

                      限定查询一个自然周的数据,时间必须按照自然周的方式输入: 如:20170306(周一), 20170312(周日)

                      请求数据示例

                      {  "begin_date" : "20170306",  "end_date" : "20170312"}

                      返回数据示例

                      {  "list": [    {      "ref_date": "20170306-20170312",      "session_cnt": 986780,      "visit_pv": 3251840,      "visit_uv": 189405,      "visit_uv_new": 45592,      "stay_time_session": 54.5346,      "visit_depth": 1.9735    }  ]}

                      云调用

                          是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.analysis.getWeeklyVisitTrend
                      需在 config.json 中配置 analysis.getWeeklyVisitTrend API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      beginDatestring开始日期,为周一日期。格式为 yyyymmdd
                      endDatestring结束日期,为周日日期,限定查询一周数据。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      listArray.<Object>数据列表

                      list 的结构

                      属性类型说明
                      refDatestring时间,格式为 yyyymmdd-yyyymmdd,如:"20170306-20170312"
                      sessionCntnumber打开次数(自然周内汇总)
                      visitPvnumber访问次数(自然周内汇总)
                      visitUvnumber访问人数(自然周内去重)
                      visitUvNewnumber新用户数(自然周内去重)
                      stayTimeUvnumber人均停留时长 (浮点型,单位:秒)
                      stayTimeSessionnumber次均停留时长 (浮点型,单位:秒)
                      visitDepthnumber平均访问深度 (浮点型)

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getWeeklyVisitTrend({        beginDate: '20170306',        endDate: '20170312'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "list": [    {      "refDate": "20170306-20170312",      "sessionCnt": 986780,      "visitPv": 3251840,      "visitUv": 189405,      "visitUvNew": 45592,      "stayTimeSession": 54.5346,      "visitDepth": 1.9735    }  ],  "errMsg": "openapi.analysis.getWeeklyVisitTrend:ok"}


                      analysis.getUserPortrait

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取小程序新增或活跃用户的画像分布数据。时间范围支持昨天、最近7天、最近30天。其中,新增用户数为时间范围内首次访问小程序的去重用户数,活跃用户数为时间范围内访问过小程序的去重用户数。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/datacube/getweanalysisappiduserportrait?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      begin_datestring开始日期。格式为 yyyymmdd
                      end_datestring结束日期,开始日期与结束日期相差的天数限定为0/6/29,分别表示查询最近1/7/30天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      ref_datestring时间范围,如:"20170611-20170617"
                      visit_uv_newObject新用户画像
                      visit_uvObject活跃用户画像

                      visit_uv_new 的结构

                      属性类型说明
                      indexnumber分布类型
                      provinceObject省份,如北京、广东等
                      cityObject城市,如北京、广州等
                      gendersObject性别,包括男、女、未知
                      platformsObject终端类型,包括 iPhone,android,其他
                      devicesObject机型,如苹果 iPhone 6,OPPO R9 等
                      agesObject年龄,包括17岁以下、18-24岁等区间

                      province 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      city 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      genders 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      platforms 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      devices 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      ages 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      visit_uv 的结构

                      属性类型说明
                      indexnumber分布类型
                      provinceObject省份,如北京、广东等
                      cityObject城市,如北京、广州等
                      gendersObject性别,包括男、女、未知
                      platformsObject终端类型,包括 iPhone,android,其他
                      devicesObject机型,如苹果 iPhone 6,OPPO R9 等
                      agesObject年龄,包括17岁以下、18-24岁等区间

                      province 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      city 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      genders 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      platforms 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      devices 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      ages 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      access_source_visit_uvnumber该场景访问uv

                      请求数据示例

                      {  "begin_date" : "20170611",  "end_date" : "20170617"}

                      返回数据示例

                      {  "ref_date": "20170611",  "visit_uv_new": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 215      }    ],    "city": [     {        "id": 3102,        "name": "广州",        "value": 78      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 2146      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 27642      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 61      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 151      }    ]  },  "visit_uv": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 1341      }    ],    "city": [     {        "id": 3102,        "name": "广州",        "value": 234      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 14534      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 21750      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 617      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 3156      }    ]  }}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.analysis.getUserPortrait
                      需在 config.json 中配置 analysis.getUserPortrait API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      beginDatestring开始日期。格式为 yyyymmdd
                      endDatestring结束日期,开始日期与结束日期相差的天数限定为0/6/29,分别表示查询最近1/7/30天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      refDatestring时间范围,如:"20170611-20170617"
                      visitUvNewObject新用户画像
                      visitUvObject活跃用户画像

                      visitUvNew 的结构

                      属性类型说明
                      indexnumber分布类型
                      provinceObject省份,如北京、广东等
                      cityObject城市,如北京、广州等
                      gendersObject性别,包括男、女、未知
                      platformsObject终端类型,包括 iPhone,android,其他
                      devicesObject机型,如苹果 iPhone 6,OPPO R9 等
                      agesObject年龄,包括17岁以下、18-24岁等区间

                      province 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      city 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      genders 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      platforms 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      devices 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      ages 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      visitUv 的结构

                      属性类型说明
                      indexnumber分布类型
                      provinceObject省份,如北京、广东等
                      cityObject城市,如北京、广州等
                      gendersObject性别,包括男、女、未知
                      platformsObject终端类型,包括 iPhone,android,其他
                      devicesObject机型,如苹果 iPhone 6,OPPO R9 等
                      agesObject年龄,包括17岁以下、18-24岁等区间

                      province 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      city 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      genders 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      platforms 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      devices 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      ages 的结构

                      属性类型说明
                      idnumber属性值id
                      namestring属性值名称,与id对应。如属性为 province 时,返回的属性值名称包括「广东」等。
                      accessSourceVisitUvnumber该场景访问uv

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getUserPortrait({        beginDate: '20170611',        endDate: '20170617'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "refDate": "20170611",  "visitUvNew": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 215      }    ],    "city": [      {        "id": 3102,        "name": "广州",        "value": 78      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 2146      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 27642      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 61      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 151      }    ]  },  "visitUv": {    "province": [      {        "id": 31,        "name": "广东省",        "value": 1341      }    ],    "city": [      {        "id": 3102,        "name": "广州",        "value": 234      }    ],    "genders": [      {        "id": 1,        "name": "男",        "value": 14534      }    ],    "platforms": [      {        "id": 1,        "name": "iPhone",        "value": 21750      }    ],    "devices": [      {        "name": "OPPO R9",        "value": 617      }    ],    "ages": [      {        "id": 1,        "name": "17岁以下",        "value": 3156      }    ]  },  "errMsg": "openapi.analysis.getUserPortrait:ok"}


                      analysis.getVisitDistribution

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取用户小程序访问分布数据

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/datacube/getweanalysisappidvisitdistribution?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      begin_datestring开始日期。格式为 yyyymmdd
                      end_datestring结束日期,限定查询 1 天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      ref_datestring日期,格式为 yyyymmdd
                      listArray.<Object>数据列表

                      list 的结构

                      属性类型说明
                      indexnumber分布类型
                      item_listArray.<Object>分布数据列表

                      index 的合法值

                      说明最低版本
                      access_source_session_cnt访问来源分布
                      access_staytime_info访问时长分布
                      access_depth_info访问深度的分布

                      item_list 的结构

                      属性类型说明
                      keynumber场景 id,定义在各个 index 下不同,具体参见下方表格
                      valuenumber该场景 id 访问 pv
                      access_source_visit_uvnumber该场景 id 访问 uv

                      请求数据示例

                      {  "begin_date" : "20170313",  "end_date" : "20170313"}

                      返回数据示例

                      {  "ref_date": "20170313",  "list": [    {      "index": "access_source_session_cnt",      "item_list": [        {          "key": 10,          "value": 5        },        {          "key": 8,          "value": 687        },        {          "key": 7,          "value": 10740        },        {          "key": 6,          "value": 1961        },        {          "key": 5,          "value": 677        },        {          "key": 4,          "value": 653        },        {          "key": 3,          "value": 1120        },        {          "key": 2,          "value": 10243        },        {          "key": 1,          "value": 116578        }      ]    },    {      "index": "access_staytime_info",      "item_list": [        {          "key": 8,          "value": 16329        },        {          "key": 7,          "value": 19322        },        {          "key": 6,          "value": 21832        },        {          "key": 5,          "value": 19539        },        {          "key": 4,          "value": 29670        },        {          "key": 3,          "value": 19667        },        {          "key": 2,          "value": 11794        },        {          "key": 1,          "value": 4511        }      ]    },    {      "index": "access_depth_info",      "item_list": [        {          "key": 5,          "value": 217        },        {          "key": 4,          "value": 3259        },        {          "key": 3,          "value": 32445        },        {          "key": 2,          "value": 63542        },        {          "key": 1,          "value": 43201        }      ]    }  ]}

                      访问来源 key 对应关系(index="access_source_session_cnt"),场景值说明参见 场景值

                      key访问来源对应场景值
                      1小程序历史列表1001 1002 1004
                      2搜索1005 1006 1027 1042 1053 1106 1108 1132
                      3会话1007 1008 1044 1093 1094 1096
                      4扫一扫二维码1011 1025 1047 1105 1124 1150
                      5公众号主页1020
                      6聊天顶部1022
                      7系统桌面1023 1113 1114 1117
                      8小程序主页1024 1135
                      9附近的小程序1026 1033 1068
                      11模板消息1014 1043 1107 1162
                      12客服消息1021
                      13公众号菜单1035 1102 1130
                      14APP分享1036
                      15支付完成页1034 1060 1072 1097 1109 1137 1149
                      16长按识别二维码1012 1048 1050 1125
                      17相册选取二维码1013 1049 1126
                      18公众号文章1058 1091
                      19钱包1019 1057 1061 1066 1070 1071
                      20卡包1028 1128 1148
                      21小程序内卡券1029 1062
                      22其他小程序1037
                      23其他小程序返回1038
                      24卡券适用门店列表1052
                      25搜索框快捷入口1054
                      26小程序客服消息1073 1081
                      27公众号下发1074 1076 1082 1152
                      28系统会话菜单1080 1083 1088
                      29任务栏-最近使用1089
                      30长按小程序菜单圆点1085 1090 1147
                      31连wifi成功页1064 1078
                      32城市服务1092
                      33微信广告1045 1046 1067 1084 1095
                      34其他移动应用1065 1069 1111 1140
                      35发现入口-我的小程序1003 1103
                      36任务栏-我的小程序1104
                      37微信圈子1138 1163
                      38手机充值1098
                      39H51018 1055
                      40插件1040 1041 1099
                      41大家在用1118 1145
                      42发现页1112 1141 1142 1143
                      43浮窗1131
                      44附近的人1075 1134
                      45看一看1115
                      46朋友圈1009 1110 1154 1155
                      47企业微信1119 1120 1121 1122 1123 1156
                      48视频1136 1144
                      49收藏1010
                      50微信红包1100
                      51微信游戏中心1079 1127
                      52摇一摇1039 1077
                      53公众号导购消息1157
                      54识物1153
                      55小程序订单1151
                      56小程序直播1161
                      57群工具1158 1159 1160
                      10其他除上述外其余场景值

                      访问时长 key 对应关系(index="access_staytime_info")

                      key访问时长
                      10-2s
                      23-5s
                      36-10s
                      411-20s
                      520-30s
                      630-50s
                      750-100s
                      8>100s

                      平均访问深度 key 对应关系(index="access_depth_info")

                      key访问时长
                      11 页
                      22 页
                      33 页
                      44 页
                      55 页
                      66-10 页
                      7>10 页

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.analysis.getVisitDistribution
                      需在 config.json 中配置 analysis.getVisitDistribution API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      beginDatestring开始日期。格式为 yyyymmdd
                      endDatestring结束日期,限定查询 1 天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      refDatestring日期,格式为 yyyymmdd
                      listArray.<Object>数据列表

                      list 的结构

                      属性类型说明
                      indexnumber分布类型
                      itemListArray.<Object>分布数据列表

                      index 的合法值

                      说明最低版本
                      access_source_session_cnt访问来源分布
                      access_staytime_info访问时长分布
                      access_depth_info访问深度的分布

                      itemList 的结构

                      属性类型说明
                      keynumber场景 id,定义在各个 index 下不同,具体参见下方表格
                      valuenumber该场景 id 访问 pv
                      accessSourceVisitUvnumber该场景 id 访问 uv

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getVisitDistribution({        beginDate: '20170313',        endDate: '20170313'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "refDate": "20170313",  "list": [    {      "index": "access_source_session_cnt",      "itemList": [        {          "key": 10,          "value": 5        },        {          "key": 8,          "value": 687        },        {          "key": 7,          "value": 10740        },        {          "key": 6,          "value": 1961        },        {          "key": 5,          "value": 677        },        {          "key": 4,          "value": 653        },        {          "key": 3,          "value": 1120        },        {          "key": 2,          "value": 10243        },        {          "key": 1,          "value": 116578        }      ]    },    {      "index": "access_staytime_info",      "itemList": [        {          "key": 8,          "value": 16329        },        {          "key": 7,          "value": 19322        },        {          "key": 6,          "value": 21832        },        {          "key": 5,          "value": 19539        },        {          "key": 4,          "value": 29670        },        {          "key": 3,          "value": 19667        },        {          "key": 2,          "value": 11794        },        {          "key": 1,          "value": 4511        }      ]    },    {      "index": "access_depth_info",      "itemList": [        {          "key": 5,          "value": 217        },        {          "key": 4,          "value": 3259        },        {          "key": 3,          "value": 32445        },        {          "key": 2,          "value": 63542        },        {          "key": 1,          "value": 43201        }      ]    }  ],  "errMsg": "openapi.analysis.getVisitDistribution:ok"}


                      analysis.getVisitPage

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      访问页面。目前只提供按 page_visit_pv 排序的 top200。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/datacube/getweanalysisappidvisitpage?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      begin_datestring开始日期。格式为 yyyymmdd
                      end_datestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      page_pathstring页面路径
                      page_visit_pvnumber访问次数
                      page_visit_uvnumber访问人数
                      page_staytime_pvnumber次均停留时长
                      entrypage_pvnumber进入页次数
                      exitpage_pvnumber退出页次数
                      page_share_pvnumber转发次数
                      page_share_uvnumber转发人数

                      请求数据示例

                      {  "begin_date" : "20170313",  "end_date" : "20170313"}

                      返回数据示例

                      {  "ref_date": "20170313",  "list": [    {      "page_path": "pages/main/main.html",      "page_visit_pv": 213429,      "page_visit_uv": 55423,      "page_staytime_pv": 8.139198,      "entrypage_pv": 117922,      "exitpage_pv": 61304,      "page_share_pv": 180,      "page_share_uv": 166    },    {      "page_path": "pages/linedetail/linedetail.html",      "page_visit_pv": 155030,      "page_visit_uv": 42195,      "page_staytime_pv": 35.462395,      "entrypage_pv": 21101,      "exitpage_pv": 47051,      "page_share_pv": 47,      "page_share_uv": 42    },    {      "page_path": "pages/search/search.html",      "page_visit_pv": 65011,      "page_visit_uv": 24716,      "page_staytime_pv": 6.889634,      "entrypage_pv": 1811,      "exitpage_pv": 3198,      "page_share_pv": 0,      "page_share_uv": 0    },    {      "page_path": "pages/stationdetail/stationdetail.html",      "page_visit_pv": 29953,      "page_visit_uv": 9695,      "page_staytime_pv": 7.558508,      "entrypage_pv": 1386,      "exitpage_pv": 2285,      "page_share_pv": 0,      "page_share_uv": 0    },    {      "page_path": "pages/switch-city/switch-city.html",      "page_visit_pv": 8928,      "page_visit_uv": 4017,      "page_staytime_pv": 9.22659,      "entrypage_pv": 748,      "exitpage_pv": 1613,      "page_share_pv": 0,      "page_share_uv": 0    }  ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.analysis.getVisitPage
                      需在 config.json 中配置 analysis.getVisitPage API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      beginDatestring开始日期。格式为 yyyymmdd
                      endDatestring结束日期,限定查询1天数据,允许设置的最大值为昨日。格式为 yyyymmdd

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      pagePathstring页面路径
                      pageVisitPvnumber访问次数
                      pageVisitUvnumber访问人数
                      pageStaytimePvnumber次均停留时长
                      entrypagePvnumber进入页次数
                      exitpagePvnumber退出页次数
                      pageSharePvnumber转发次数
                      pageShareUvnumber转发人数

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.analysis.getVisitPage({        beginDate: '20170313',        endDate: '20170313'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "refDate": "20170313",  "list": [    {      "pagePath": "pages/main/main.html",      "pageVisitPv": 213429,      "pageVisitUv": 55423,      "pageStaytimePv": 8.139198,      "entrypagePv": 117922,      "exitpagePv": 61304,      "pageSharePv": 180,      "pageShareUv": 166    },    {      "pagePath": "pages/linedetail/linedetail.html",      "pageVisitPv": 155030,      "pageVisitUv": 42195,      "pageStaytimePv": 35.462395,      "entrypagePv": 21101,      "exitpagePv": 47051,      "pageSharePv": 47,      "pageShareUv": 42    },    {      "pagePath": "pages/search/search.html",      "pageVisitPv": 65011,      "pageVisitUv": 24716,      "pageStaytimePv": 6.889634,      "entrypagePv": 1811,      "exitpagePv": 3198,      "pageSharePv": 0,      "pageShareUv": 0    },    {      "pagePath": "pages/stationdetail/stationdetail.html",      "pageVisitPv": 29953,      "pageVisitUv": 9695,      "pageStaytimePv": 7.558508,      "entrypagePv": 1386,      "exitpagePv": 2285,      "pageSharePv": 0,      "pageShareUv": 0    },    {      "pagePath": "pages/switch-city/switch-city.html",      "pageVisitPv": 8928,      "pageVisitUv": 4017,      "pageStaytimePv": 9.22659,      "entrypagePv": 748,      "exitpagePv": 1613,      "pageSharePv": 0,      "pageShareUv": 0    }  ],  "errMsg": "openapi.analysis.getVisitPage:ok"}


                      customerServiceMessage.getTempMedia

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取客服消息内的临时素材。即下载临时的多媒体文件。目前小程序仅支持下载图片文件。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      media_idstring媒体文件 ID

                      返回值

                      Buffer

                      返回的图片 Buffer

                      异常返回

                      Object

                      JSON

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      40007无效媒体文件 ID

                      返回值说明

                      如果调用成功,会直接返回图片二进制内容,如果请求失败,会返回 JSON 格式的数据。

                      调用示例

                      使用 CURL 命令,用 FORM 表单方式上传一个多媒体文件

                      curl -I -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.customerServiceMessage.getTempMedia
                      需在 config.json 中配置 customerServiceMessage.getTempMedia API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      mediaIdstring媒体文件 ID

                      返回值

                      Object

                      包含二进制数据及其数据类型的对象

                      属性类型说明
                      contentTypeString数据类型 (MIME Type)
                      bufferBuffer数据 Buffer

                      异常

                      Object

                      JSON

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.getTempMedia({        mediaId: ''      })    return result  } catch (err) {    return err  }}

                      SDK 调用示例

                      // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.customerServiceMessage.getTempMedia({  mediaId: 'MEDIA_ID'})

                      SDK 调用返回示例

                      {  "errCode": 0,  "errMsg": "openapi.customerServiceMessage.getTempMedia:ok",   "contentType": "image/jpeg",   "buffer": Buffer}


                      customerServiceMessage.send

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      发送客服消息给用户。详细规则见 发送客服消息

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      touserstring用户的 OpenID
                      msgtypestring消息类型
                      textObject文本消息,msgtype="text" 时必填
                      imageObject图片消息,msgtype="image" 时必填
                      linkObject图文链接,msgtype="link" 时必填
                      miniprogrampageObject小程序卡片,msgtype="miniprogrampage" 时必填

                      msgtype 的合法值

                      说明最低版本
                      text文本消息
                      image图片消息
                      link图文链接
                      miniprogrampage小程序卡片

                      text 的结构

                      属性类型默认值必填说明
                      contentstring文本消息内容

                      image 的结构

                      属性类型默认值必填说明
                      media_idstring发送的图片的媒体ID,通过 新增素材接口 上传图片文件获得。

                      link 的结构

                      属性类型默认值必填说明
                      titlestring消息标题
                      descriptionstring图文链接消息
                      urlstring图文链接消息被点击后跳转的链接
                      thumb_urlstring图文链接消息的图片链接,支持 JPG、PNG 格式,较好的效果为大图 640 X 320,小图 80 X 80

                      miniprogrampage 的结构

                      属性类型默认值必填说明
                      titlestring消息标题
                      pagepathstring小程序的页面路径,跟app.json对齐,支持参数,比如pages/index/index?foo=bar
                      thumb_media_idstring小程序消息卡片的封面, image 类型的 media_id,通过 新增素材接口 上传图片文件获得,建议大小为 520*416

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统繁忙,此时请开发者稍候再试
                      40001获取 access_token 时 AppSecret 错误,或者 access_token 无效。请开发者认真比对 AppSecret 的正确性,或查看是否正在为恰当的小程序调用接口
                      40002不合法的凭证类型
                      40003不合法的 OpenID,请开发者确认 OpenID 是否是其他小程序的 OpenID
                      45015回复时间超过限制
                      45047客服接口下行条数超过上限
                      48001API 功能未授权,请确认小程序已获得该接口

                      下发消息示例

                      发送文本消息

                      {  "touser":"OPENID",  "msgtype":"text",  "text":  {    "content":"Hello World"  }}

                      发送文本消息时,支持添加可跳转小程序的文字连接

                      文本内容...<a href="http://www.qq.com" rel="external nofollow" target="_blank"  rel="external nofollow" target="_blank"  data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>
                      说明:
                      1. data-miniprogram-appid 项,填写小程序appid,则表示该链接跳转小程序;
                      2. data-miniprogram-path项,填写小程序路径,路径与app.json中保持一致,可带参数;
                      3. 对于不支持 data-miniprogram-appid 项的客户端版本(6.5.16 以下),如果有 herf 项,则仍然保持跳 href 中的链接;
                      4. 小程序发带小程序文字链的文本消息,data-miniprogram-appid必须是该小程序的appid。

                      发送图片消息

                      {  "touser":"OPENID",  "msgtype":"image",  "image": {    "media_id":"MEDIA_ID"  }}

                      发送图文链接

                      每次可以发送一个图文链接

                      {  "touser": "OPENID",  "msgtype": "link",  "link": {    "title": "Happy Day",    "description": "Is Really A Happy Day",    "url": "URL",    "thumb_url": "THUMB_URL"  }}

                      发送小程序卡片

                      { "touser":"OPENID", "msgtype":"miniprogrampage", "miniprogrampage": {   "title":"title",   "pagepath":"pagepath",   "thumb_media_id":"thumb_media_id" }}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.customerServiceMessage.send
                      需在 config.json 中配置 customerServiceMessage.send API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      touserstring用户的 OpenID
                      msgtypestring消息类型
                      textObject文本消息,msgtype="text" 时必填
                      imageObject图片消息,msgtype="image" 时必填
                      linkObject图文链接,msgtype="link" 时必填
                      miniprogrampageObject小程序卡片,msgtype="miniprogrampage" 时必填

                      msgtype 的合法值

                      说明最低版本
                      text文本消息
                      image图片消息
                      link图文链接
                      miniprogrampage小程序卡片

                      text 的结构

                      属性类型默认值必填说明
                      contentstring文本消息内容

                      image 的结构

                      属性类型默认值必填说明
                      mediaIdstring发送的图片的媒体ID,通过 新增素材接口 上传图片文件获得。

                      link 的结构

                      属性类型默认值必填说明
                      titlestring消息标题
                      descriptionstring图文链接消息
                      urlstring图文链接消息被点击后跳转的链接
                      thumbUrlstring图文链接消息的图片链接,支持 JPG、PNG 格式,较好的效果为大图 640 X 320,小图 80 X 80

                      miniprogrampage 的结构

                      属性类型默认值必填说明
                      titlestring消息标题
                      pagepathstring小程序的页面路径,跟app.json对齐,支持参数,比如pages/index/index?foo=bar
                      thumbMediaIdstring小程序消息卡片的封面, image 类型的 media_id,通过 新增素材接口 上传图片文件获得,建议大小为 520*416

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      -1系统繁忙,此时请开发者稍候再试
                      40001获取 access_token 时 AppSecret 错误,或者 access_token 无效。请开发者认真比对 AppSecret 的正确性,或查看是否正在为恰当的小程序调用接口
                      40002不合法的凭证类型
                      40003不合法的 OpenID,请开发者确认 OpenID 是否是其他小程序的 OpenID
                      45015回复时间超过限制
                      45047客服接口下行条数超过上限
                      48001API 功能未授权,请确认小程序已获得该接口

                      下发消息示例

                      发送文本消息

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.send({        touser: 'OPENID',        msgtype: 'text',        text: {          content: 'Hello World'        }      })    return result  } catch (err) {    return err  }}

                      发送文本消息时,支持添加可跳转小程序的文字连接

                      文本内容...<a href="http://www.qq.com" rel="external nofollow" target="_blank"  rel="external nofollow" target="_blank"  data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>
                      说明:
                      1. data-miniprogram-appid 项,填写小程序appid,则表示该链接跳转小程序;
                      2. data-miniprogram-path项,填写小程序路径,路径与app.json中保持一致,可带参数;
                      3. 对于不支持 data-miniprogram-appid 项的客户端版本(6.5.16 以下),如果有 herf 项,则仍然保持跳 href 中的链接;
                      4. 小程序发带小程序文字链的文本消息,data-miniprogram-appid必须是该小程序的appid。

                      发送图片消息

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.send({        touser: 'OPENID',        msgtype: 'image',        image: {          mediaId: 'MEDIA_ID'        }      })    return result  } catch (err) {    return err  }}

                      发送图文链接

                      每次可以发送一个图文链接

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.send({        touser: 'OPENID',        msgtype: 'link',        link: {          title: 'Happy Day',          description: 'Is Really A Happy Day',          url: 'URL',          thumbUrl: 'THUMB_URL'        }      })    return result  } catch (err) {    return err  }}

                      发送小程序卡片

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.send({        touser: 'OPENID',        msgtype: 'miniprogrampage',        miniprogrampage: {          title: 'title',          pagepath: 'pagepath',          thumbMediaId: 'thumb_media_id'        }      })    return result  } catch (err) {    return err  }}


                      customerServiceMessage.setTyping

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      下发客服当前输入状态给用户。详见 客服消息输入状态

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/message/custom/typing?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      touserstring用户的 OpenID
                      commandStrign命令

                      command 的合法值

                      说明最低版本
                      Typing对用户下发"正在输入"状态
                      CancelTyping取消对用户的"正在输入"状态

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      45072command字段取值不对
                      45080下发输入状态,需要之前30秒内跟用户有过消息交互
                      45081已经在输入状态,不可重复下发

                      请求示例

                      {  "touser": "OPENID",  "command": "Typing"   }

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.customerServiceMessage.setTyping
                      需在 config.json 中配置 customerServiceMessage.setTyping API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      touserstring用户的 OpenID
                      commandStrign命令

                      command 的合法值

                      说明最低版本
                      Typing对用户下发"正在输入"状态
                      CancelTyping取消对用户的"正在输入"状态

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      45072command字段取值不对
                      45080下发输入状态,需要之前30秒内跟用户有过消息交互
                      45081已经在输入状态,不可重复下发

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.customerServiceMessage.setTyping({        touser: 'OPENID',        command: 'Typing'      })    return result  } catch (err) {    return err  }}


                      customerServiceMessage.uploadTempMedia

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      把媒体文件上传到微信服务器。目前仅支持图片。用于发送客服消息或被动回复用户消息。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      typestring文件类型
                      mediaFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息

                      type 的合法值

                      说明最低版本
                      image图片

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      typestring文件类型
                      media_idstring媒体文件上传后,获取标识,3天内有效。
                      created_atnumber媒体文件上传时间戳

                      errcode 的合法值

                      说明最低版本
                      40004无效媒体文件类型

                      type 的合法值

                      说明最低版本
                      image图片

                      调用示例

                      使用 CURL 命令,用 FORM 表单方式上传一个多媒体文件

                      curl -F media=@test.jpg "https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE"

                      返回示例

                      {  "errcode": 0,  "errmsg": "ok",  "type": "image",  "media_id": "MEDIA_ID",  "created_at": "xxx"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.customerServiceMessage.uploadTempMedia
                      需在 config.json 中配置 customerServiceMessage.uploadTempMedia API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      typestring文件类型
                      mediaFormData媒体文件数据

                      type 的合法值

                      说明最低版本
                      image图片

                      media 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息
                      typestring文件类型
                      mediaIdstring媒体文件上传后,获取标识,3天内有效。
                      createdAtnumber媒体文件上传时间戳

                      errCode 的合法值

                      说明最低版本
                      0成功

                      type 的合法值

                      说明最低版本
                      image图片

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      40004无效媒体文件类型

                      返回示例

                      {  "errCode": 0,  "errMsg": "openapi.customerServiceMessage.uploadTempMedia:ok",  "type": "image",  "mediaId": "MEDIA_ID",  "createdAt": "xxx"}

                      SDK 调用示例

                      // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.customerServiceMessage.uploadTempMedia({  type: 'image',  media: {    contentType: 'image/png',    value: Buffer  }})


                      uniformMessage.send

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      下发小程序和公众号统一的服务消息

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/message/wxopen/template/uniform_send?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      touserstring用户openid,可以是小程序的openid,也可以是mp_template_msg.appid对应的公众号的openid
                      weapp_template_msgObject小程序模板消息相关的信息,可以参考小程序模板消息接口; 有此节点则优先发送小程序模板消息
                      mp_template_msgObject公众号模板消息相关的信息,可以参考公众号模板消息接口;有此节点并且没有weapp_template_msg节点时,发送公众号模板消息

                      weapp_template_msg 的结构

                      属性类型默认值必填说明
                      template_idstring小程序模板ID
                      pagestring小程序页面路径
                      form_idstring小程序模板消息formid
                      datastring小程序模板数据
                      emphasis_keywordstring小程序模板放大关键词

                      mp_template_msg 的结构

                      属性类型默认值必填说明
                      appidstring公众号appid,要求与小程序有绑定且同主体
                      template_idstring公众号模板id
                      urlstring公众号模板消息所要跳转的url
                      miniprogramstring公众号模板消息所要跳转的小程序,小程序的必须与公众号具有绑定关系
                      datastring公众号模板消息的数据

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      错误

                      错误码错误信息说明
                      40037模板id不正确,weapp_template_msg.template_id或者mp_template_msg.template_id
                      41028weapp_template_msg.form_id过期或者不正确
                      41029weapp_template_msg.form_id已被使用
                      41030weapp_template_msg.page不正确
                      45009接口调用超过限额
                      40003touser不是正确的openid
                      40013appid不正确,或者不符合绑定关系要求

                      请求数据示例

                      {    "touser":"OPENID",    "weapp_template_msg":{        "template_id":"TEMPLATE_ID",        "page":"page/page/index",        "form_id":"FORMID",        "data":{            "keyword1":{                "value":"339208499"            },            "keyword2":{                "value":"2015年01月05日 12:30"            },            "keyword3":{                "value":"腾讯微信总部"            },            "keyword4":{                "value":"广州市海珠区新港中路397号"            }        },        "emphasis_keyword":"keyword1.DATA"    },    "mp_template_msg":{        "appid":"APPID ",        "template_id":"TEMPLATE_ID",        "url":"http://weixin.qq.com/download",        "miniprogram":{            "appid":"xiaochengxuappid12345",            "pagepath":"index?foo=bar"        },        "data":{            "first":{                "value":"恭喜你购买成功!",                "color":"#173177"            },            "keyword1":{                "value":"巧克力",                "color":"#173177"            },            "keyword2":{                "value":"39.8元",                "color":"#173177"            },            "keyword3":{                "value":"2014年9月22日",                "color":"#173177"            },            "remark":{                "value":"欢迎再次购买!",                "color":"#173177"            }        }    }}

                      返回数据示例

                      { "errcode": 0, "errmsg": "ok"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.uniformMessage.send
                      需在 config.json 中配置 uniformMessage.send API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      touserstring用户openid,可以是小程序的openid,也可以是mp_template_msg.appid对应的公众号的openid
                      weappTemplateMsgObject小程序模板消息相关的信息,可以参考小程序模板消息接口; 有此节点则优先发送小程序模板消息
                      mpTemplateMsgObject公众号模板消息相关的信息,可以参考公众号模板消息接口;有此节点并且没有weapp_template_msg节点时,发送公众号模板消息

                      weappTemplateMsg 的结构

                      属性类型默认值必填说明
                      templateIdstring小程序模板ID
                      pagestring小程序页面路径
                      formIdstring小程序模板消息formid
                      datastring小程序模板数据
                      emphasisKeywordstring小程序模板放大关键词

                      mpTemplateMsg 的结构

                      属性类型默认值必填说明
                      appidstring公众号appid,要求与小程序有绑定且同主体
                      templateIdstring公众号模板id
                      urlstring公众号模板消息所要跳转的url
                      miniprogramstring公众号模板消息所要跳转的小程序,小程序的必须与公众号具有绑定关系
                      datastring公众号模板消息的数据

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      错误

                      错误码错误信息说明
                      40037模板id不正确,weapp_template_msg.template_id或者mp_template_msg.template_id
                      41028weapp_template_msg.form_id过期或者不正确
                      41029weapp_template_msg.form_id已被使用
                      41030weapp_template_msg.page不正确
                      45009接口调用超过限额
                      40003touser不是正确的openid
                      40013appid不正确,或者不符合绑定关系要求

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.uniformMessage.send({        touser: 'OPENID',        weappTemplateMsg: {          page: 'page/page/index',          data: {            keyword1: {              value: '339208499'            },            keyword2: {              value: '2015年01月05日 12:30'            },            keyword3: {              value: '腾讯微信总部'            },            keyword4: {              value: '广州市海珠区新港中路397号'            }          },          templateId: 'TEMPLATE_ID',          formId: 'FORMID',          emphasisKeyword: 'keyword1.DATA'        },        mpTemplateMsg: {          appid: 'APPID ',          url: 'http://weixin.qq.com/download',          miniprogram: {            appid: 'xiaochengxuappid12345',            pagepath: 'index?foo=bar'          },          data: {            first: {              value: '恭喜你购买成功!',              color: '#173177'            },            keyword1: {              value: '巧克力',              color: '#173177'            },            keyword2: {              value: '39.8元',              color: '#173177'            },            keyword3: {              value: '2014年9月22日',              color: '#173177'            },            remark: {              value: '欢迎再次购买!',              color: '#173177'            }          },          templateId: 'TEMPLATE_ID'        }      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "errCode": 0,  "errMsg": "openapi.uniformMessage.send:ok"}


                      updatableMessage.createActivityId

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      创建被分享动态消息的 activity_id。详见动态消息

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/cgi-bin/message/wxopen/activityid/create?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      activity_idstring动态消息的 ID
                      expiration_timenumberactivity_id 的过期时间戳。默认24小时后过期。
                      errcodenumber错误码

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统繁忙。此时请开发者稍候再试
                      42001access_token 过期

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.updatableMessage.createActivityId
                      需在 config.json 中配置 updatableMessage.createActivityId API 的权限,详情

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      activityIdstring动态消息的 ID
                      expirationTimenumberactivity_id 的过期时间戳。默认24小时后过期。
                      errCodenumber错误码

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码

                      errCode 的合法值

                      说明最低版本
                      -1系统繁忙。此时请开发者稍候再试
                      42001access_token 过期


                      updatableMessage.setUpdatableMsg

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      修改被分享的动态消息。详见动态消息

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/message/wxopen/updatablemsg/send?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      activity_idstring动态消息的 ID,通过 updatableMessage.createActivityId 接口获取
                      target_statenumber动态消息修改后的状态(具体含义见后文)
                      template_infoObject动态消息对应的模板信息

                      target_state 的合法值

                      说明最低版本
                      0未开始
                      1已开始

                      template_info 的结构

                      属性类型默认值必填说明
                      parameter_listArray.<Object>模板中需要修改的参数

                      parameter_list 的结构

                      属性类型默认值必填说明
                      namestring要修改的参数名
                      valuestring修改后的参数值

                      name 的合法值

                      说明最低版本
                      member_counttarget_state = 0 时必填,文字内容模板中 member_count 的值
                      room_limittarget_state = 0 时必填,文字内容模板中 room_limit 的值
                      pathtarget_state = 1 时必填,点击「进入」启动小程序时使用的路径。
                      对于小游戏,没有页面的概念,可以用于传递查询字符串(query),如 "?foo=bar"
                      version_typetarget_state = 1 时必填,点击「进入」启动小程序时使用的版本。
                      有效参数值为:develop(开发版),trial(体验版),release(正式版)

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgnumber错误信息

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统繁忙。此时请开发者稍候再试
                      42001access_token 过期
                      44002post 数据为空
                      47001post 数据中参数缺失
                      47501参数 activity_id 错误
                      47502参数 target_state 错误
                      47503参数 version_type 错误
                      47504activity_id 过期

                      消息状态

                      消息有两个状态(target_state),分别有其对应的文字内容和颜色。文字内容模板和颜色不支持变更。

                      状态文字内容颜色允许转移的状态
                      0"成员正在加入,当前 {member_count}/{room_limit} 人"#FA9D390, 1
                      1"已开始"#CCCCCC

                      活动的默认有效期是 24 小时。活动结束后,消息内容会变成统一的样式:

                      • 文字内容:“已结束”
                      • 文字颜色:#00ff00

                      curl 调用示例

                      curl -d '{"activity_id": "966_NGiqxxxxxxxxx...xxxxxxxxE33BlwX", "target_state": 0, "template_info": {"parameter_list": [{"name": "member_count", "value": "2"}, {"name":"room_limit", "value": "5"} ] } }' 'https://api.weixin.qq.com/cgi-bin/message/wxopen/updatablemsg/send?access_token=ACCESS_TOKEN'

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.updatableMessage.setUpdatableMsg
                      需在 config.json 中配置 updatableMessage.setUpdatableMsg API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      activityIdstring动态消息的 ID,通过 updatableMessage.createActivityId 接口获取
                      targetStatenumber动态消息修改后的状态(具体含义见后文)
                      templateInfoObject动态消息对应的模板信息

                      targetState 的合法值

                      说明最低版本
                      0未开始
                      1已开始

                      templateInfo 的结构

                      属性类型默认值必填说明
                      parameterListArray.<Object>模板中需要修改的参数

                      parameterList 的结构

                      属性类型默认值必填说明
                      namestring要修改的参数名
                      valuestring修改后的参数值

                      name 的合法值

                      说明最低版本
                      member_counttarget_state = 0 时必填,文字内容模板中 member_count 的值
                      room_limittarget_state = 0 时必填,文字内容模板中 room_limit 的值
                      pathtarget_state = 1 时必填,点击「进入」启动小程序时使用的路径。
                      对于小游戏,没有页面的概念,可以用于传递查询字符串(query),如 "?foo=bar"
                      version_typetarget_state = 1 时必填,点击「进入」启动小程序时使用的版本。
                      有效参数值为:develop(开发版),trial(体验版),release(正式版)

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgnumber错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgnumber错误信息

                      errCode 的合法值

                      说明最低版本
                      -1系统繁忙。此时请开发者稍候再试
                      42001access_token 过期
                      44002post 数据为空
                      47001post 数据中参数缺失
                      47501参数 activity_id 错误
                      47502参数 target_state 错误
                      47503参数 version_type 错误
                      47504activity_id 过期


                      pluginManager.applyPlugin

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      向插件开发者发起使用插件的申请

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/plugin?access_token=TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      actionstring此接口下填写 "apply"
                      plugin_appidstring插件 appId
                      reasonstring申请使用理由

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      错误

                      错误码错误信息说明
                      0ok正常
                      -1系统错误
                      89236该插件不能申请
                      89237已经添加该插件
                      89238申请或使用的插件已经达到上限
                      89239该插件不存在
                      89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
                      89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
                      89242该appid不在申请列表内
                      89243“待确认”的申请不可删除
                      89044不存在该插件appid

                      请求数据示例

                      {  "action": "apply",  "plugin_appid": "aaaa",  "reason": "hello"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.pluginManager.applyPlugin
                      需在 config.json 中配置 pluginManager.applyPlugin API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      actionstring此接口下填写 "apply"
                      pluginAppidstring插件 appId
                      reasonstring申请使用理由

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      错误

                      错误码错误信息说明
                      0ok正常
                      -1系统错误
                      89236该插件不能申请
                      89237已经添加该插件
                      89238申请或使用的插件已经达到上限
                      89239该插件不存在
                      89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
                      89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
                      89242该appid不在申请列表内
                      89243“待确认”的申请不可删除
                      89044不存在该插件appid

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.applyPlugin({        action: 'apply',        reason: 'hello',        pluginAppid: 'aaaa'      })    return result  } catch (err) {    return err  }}


                      pluginManager.getPluginDevApplyList

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取当前所有插件使用方(供插件开发者调用)

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/devplugin?access_token=TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      actionstring此接口下填写 "dev_apply_list"
                      pagenumber要拉取第几页的数据
                      numnumber每页的记录数

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      apply_listArray.<Object>插件使用方列表

                      apply_list 的结构

                      属性类型说明
                      appidstring使用者的appid
                      statusnumber插件状态
                      nicknamestring使用者的昵称
                      headimgurlstring使用者的头像
                      categoriesArray.<Object>使用者的类目
                      create_timestring使用者的申请时间
                      apply_urlstring使用者的小程序码
                      reasonstring使用者的申请说明

                      status 的合法值

                      说明最低版本
                      1申请中
                      2申请通过
                      3已拒绝
                      4已超时

                      错误

                      错误码错误信息说明
                      0ok正常
                      -1系统错误
                      89236该插件不能申请
                      89237已经添加该插件
                      89238申请或使用的插件已经达到上限
                      89239该插件不存在
                      89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
                      89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
                      89242该appid不在申请列表内
                      89243“待确认”的申请不可删除
                      89044不存在该插件appid

                      请求数据示例

                      {  "action":"dev_apply_list",  "page": 1,  "num": 10}

                      返回数据示例

                      {  "errcode": 0,  "errmsg": "ok",  "apply_list": [{    "appid": "xxxxxxxxxxxxx",    "status": 1,    "nickname": "名称",    "headimgurl": "**********",    "reason": "polo has gone",    "apply_url": "*******",    "create_time": "1536305096",    "categories": [{      "first": "IT科技",      "second": "硬件与设备"    }]  }]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.pluginManager.getPluginDevApplyList
                      需在 config.json 中配置 pluginManager.getPluginDevApplyList API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      actionstring此接口下填写 "dev_apply_list"
                      pagenumber要拉取第几页的数据
                      numnumber每页的记录数

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息
                      applyListArray.<Object>插件使用方列表

                      applyList 的结构

                      属性类型说明
                      appidstring使用者的appid
                      statusnumber插件状态
                      nicknamestring使用者的昵称
                      headimgurlstring使用者的头像
                      categoriesArray.<Object>使用者的类目
                      createTimestring使用者的申请时间
                      applyUrlstring使用者的小程序码
                      reasonstring使用者的申请说明

                      status 的合法值

                      说明最低版本
                      1申请中
                      2申请通过
                      3已拒绝
                      4已超时

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      错误

                      错误码错误信息说明
                      0ok正常
                      -1系统错误
                      89236该插件不能申请
                      89237已经添加该插件
                      89238申请或使用的插件已经达到上限
                      89239该插件不存在
                      89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
                      89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
                      89242该appid不在申请列表内
                      89243“待确认”的申请不可删除
                      89044不存在该插件appid

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.getPluginDevApplyList({        action: 'dev_apply_list',        page: 1,        num: 10      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "errCode": 0,  "errMsg": "openapi.pluginManager.getPluginDevApplyList:ok",  "applyList": [    {      "appid": "xxxxxxxxxxxxx",      "status": 1,      "nickname": "名称",      "headimgurl": "**********",      "reason": "polo has gone",      "categories": [        {          "first": "IT科技",          "second": "硬件与设备"        }      ],      "applyUrl": "*******",      "createTime": "1536305096"    }  ]}


                      pluginManager.getPluginList

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      查询已添加的插件

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/plugin?access_token=TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      actionstring此接口下填写 "list"

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      plugin_listArray.<Object>申请或使用中的插件列表

                      plugin_list 的结构

                      属性类型说明
                      appidstring插件 appId
                      statusnumber插件状态
                      nicknamestring插件昵称
                      headimgurlstring插件头像

                      status 的合法值

                      说明最低版本
                      1申请中
                      2申请通过
                      3已拒绝
                      4已超时

                      错误

                      错误码错误信息说明
                      0ok正常
                      -1系统错误
                      89236该插件不能申请
                      89237已经添加该插件
                      89238申请或使用的插件已经达到上限
                      89239该插件不存在
                      89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
                      89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
                      89242该appid不在申请列表内
                      89243“待确认”的申请不可删除
                      89044不存在该插件appid

                      请求数据示例

                      {  "action":"list"}

                      返回数据示例

                      {  "errcode": 0,  "errmsg": "ok",  "plugin_list": [{    "appid": "aaaa",    "status": 1,    "nickname": "插件昵称",    "headimgurl": "http://plugin.qq.com"  }]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.pluginManager.getPluginList
                      需在 config.json 中配置 pluginManager.getPluginList API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      actionstring此接口下填写 "list"

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息
                      pluginListArray.<Object>申请或使用中的插件列表

                      pluginList 的结构

                      属性类型说明
                      appidstring插件 appId
                      statusnumber插件状态
                      nicknamestring插件昵称
                      headimgurlstring插件头像

                      status 的合法值

                      说明最低版本
                      1申请中
                      2申请通过
                      3已拒绝
                      4已超时

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      错误

                      错误码错误信息说明
                      0ok正常
                      -1系统错误
                      89236该插件不能申请
                      89237已经添加该插件
                      89238申请或使用的插件已经达到上限
                      89239该插件不存在
                      89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
                      89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
                      89242该appid不在申请列表内
                      89243“待确认”的申请不可删除
                      89044不存在该插件appid

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.getPluginList({        action: 'list'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "errCode": 0,  "errMsg": "openapi.pluginManager.getPluginList:ok",  "pluginList": [    {      "appid": "aaaa",      "status": 1,      "nickname": "插件昵称",      "headimgurl": "http://plugin.qq.com"    }  ]}


                      pluginManager.setDevPluginApplyStatus

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      修改插件使用申请的状态(供插件开发者调用)

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/devplugin?access_token=TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      actionstring修改操作
                      appidstring使用者的 appid。同意申请时填写。
                      reasonstring拒绝理由。拒绝申请时填写。

                      action 的合法值

                      说明最低版本
                      dev_agree同意申请
                      dev_refuse拒绝申请
                      dev_delete删除已拒绝的申请者

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      错误

                      错误码错误信息说明
                      0ok正常
                      -1系统错误
                      89236该插件不能申请
                      89237已经添加该插件
                      89238申请或使用的插件已经达到上限
                      89239该插件不存在
                      89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
                      89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
                      89242该appid不在申请列表内
                      89243“待确认”的申请不可删除
                      89044不存在该插件appid

                      请求数据示例

                      {  "action": "dev_agree",  "appid": "aaaa"}

                      {  "action": "dev_refuse",  "reason": "refuse reason"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.pluginManager.setDevPluginApplyStatus
                      需在 config.json 中配置 pluginManager.setDevPluginApplyStatus API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      actionstring修改操作
                      appidstring使用者的 appid。同意申请时填写。
                      reasonstring拒绝理由。拒绝申请时填写。

                      action 的合法值

                      说明最低版本
                      dev_agree同意申请
                      dev_refuse拒绝申请
                      dev_delete删除已拒绝的申请者

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      错误

                      错误码错误信息说明
                      0ok正常
                      -1系统错误
                      89236该插件不能申请
                      89237已经添加该插件
                      89238申请或使用的插件已经达到上限
                      89239该插件不存在
                      89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
                      89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
                      89242该appid不在申请列表内
                      89243“待确认”的申请不可删除
                      89044不存在该插件appid

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.setDevPluginApplyStatus({        action: 'dev_agree',        appid: 'aaaa'      })    return result  } catch (err) {    return err  }}

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.setDevPluginApplyStatus({        action: 'dev_refuse',        reason: 'refuse reason'      })    return result  } catch (err) {    return err  }}


                      pluginManager.unbindPlugin

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      删除已添加的插件

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/plugin?access_token=TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      actionstring此接口下填写 "unbind"
                      plugin_appidstring插件 appId

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      错误

                      错误码错误信息说明
                      0ok正常
                      -1系统错误
                      89236该插件不能申请
                      89237已经添加该插件
                      89238申请或使用的插件已经达到上限
                      89239该插件不存在
                      89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
                      89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
                      89242该appid不在申请列表内
                      89243“待确认”的申请不可删除
                      89044不存在该插件appid

                      请求数据示例

                      {  "action":"unbind",  "plugin_appid":"aaaa"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.pluginManager.unbindPlugin
                      需在 config.json 中配置 pluginManager.unbindPlugin API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      actionstring此接口下填写 "unbind"
                      pluginAppidstring插件 appId

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      错误

                      错误码错误信息说明
                      0ok正常
                      -1系统错误
                      89236该插件不能申请
                      89237已经添加该插件
                      89238申请或使用的插件已经达到上限
                      89239该插件不存在
                      89240无法进行此操作,只有“待确认”的申请可操作通过/拒绝
                      89241无法进行此操作,只有“已拒绝/已超时”的申请可操作删除
                      89242该appid不在申请列表内
                      89243“待确认”的申请不可删除
                      89044不存在该插件appid

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.pluginManager.unbindPlugin({        action: 'unbind',        pluginAppid: 'aaaa'      })    return result  } catch (err) {    return err  }}


                      nearbyPoi.add

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      添加地点

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/addnearbypoi?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      is_comm_nearbystring必填,写死为"1"
                      pic_liststring门店图片,最多9张,最少1张,上传门店图片如门店外景、环境设施、商品服务等,图片将展示在微信客户端的门店页。图片链接通过文档https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1444738729中的《上传图文消息内的图片获取URL》接口获取。必填,文件格式为bmp、png、jpeg、jpg或gif,大小不超过5M pic_list是字符串,内容是一个json
                      service_infosstring必服务标签列表 必填,需要填写
                      1、 服务标签ID
                      2、 服务类型tpye
                      3、 服务名称name
                      详细字段格式见下方《服务标签id编号、类型与服务名称表》
                      4、 APPID
                      5、 对应服务落地页的path路径:path路径页面要与对应的服务标签一致,例如选取外卖服务,path路径应该是小程序的外卖对应的那个页面,path路径获取咨询开发或者到小程序管理后台-工具-生成小程序码页面获取
                      6、新增服务描述desc:描述服务内容,例如满减、折扣等优惠信息或新品、爆品等商品信息,仅标准服务都可添加,10个字符以内。
                      service_infos是字符串,内容是一个json
                      kf_infostring客服信息 选填,可自定义服务头像与昵称,具体填写字段见下方示例kf_info pic_list是字符串,内容是一个json
                      store_namestring门店名字 必填,门店名称需按照所选地理位置自动拉取腾讯地图门店名称,不可修改,如需修改请重现选择地图地点或重新创建地点。
                      hourstring营业时间,格式11:11-12:12 必填
                      addressstring地址 必填
                      poi_idstring如果创建新的门店,poi_id字段为空 如果更新门店,poi_id参数则填对应门店的poi_id 选填
                      company_namestring主体名字 必填
                      contract_phonestring门店电话 必填
                      credentialstring资质号 必填, 15位营业执照注册号或9位组织机构代码
                      qualification_liststring证明材料 必填 如果company_name和该小程序主体不一致,需要填qualification_list,详细规则见附近的小程序使用指南-如何证明门店的经营主体跟公众号或小程序帐号主体相关http://kf.qq.com/faq/170401MbUnim17040122m2qY.html
                      map_poi_idstring对应《在腾讯地图中搜索门店》中的sosomap_poi_uid字段 腾讯地图那边有些数据不一致,如果不填map_poi_id的话,小概率会提交失败!
                      注:
                      poi_id与map_poi_id关系:
                      map_poi_id是腾讯地图对于poi的唯一标识
                      poi_id是门店进驻附近后的门店唯一标识
                      NearbyPoiError@error

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errmsgstring错误信息
                      errcodenumber错误码
                      dataobject返回数据

                      data 的结构

                      属性类型说明
                      audit_idstring审核单 ID
                      poi_idstring附近地点 ID
                      related_credentialstring经营资质证件号

                      注:添加门店需要审核,需要1到2个工作日

                      服务标签id编号、类型与服务名称表

                      IDtypename(服务名称)
                      02自定义服务,可自定义名称(10个以内)
                      11外送
                      21快递
                      31充电
                      41预约
                      51挂号
                      61点餐
                      71优惠
                      81乘车
                      91会员
                      101买单
                      111排队
                      121缴费
                      131购票
                      141到店自提
                      151预定

                      频率限制说明

                      添加请求暂不支持并发调用,建议使用时间隔1s进行串行调用

                      请求示例

                      {"is_comm_nearby": "1", //值固定"kf_info": "{"open_kf":true,"kf_headimg":"http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITqmP914zSwhajIEJzUPpx40P7R8fRe1QmicneQMhFzpZNhSLjrvU1pIA/0?wx_fmt=jpeg","kf_name":"Harden"}","pic_list": "{"list":["http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITqmP914zSwhajIEJzUPpx40P7R8fRe1QmicneQMhFzpZNhSLjrvU1pIA/0?wx_fmt=jpeg","http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITRneE5FS9uYruXGMmrtmhsBySwddEWUGOibG8Ze2NT5E3Dyt79I0htNg/0?wx_fmt=jpeg"]}","service_infos": "{"service_infos":[{"id":2,"type":1,"name":"快递","appid":"wx1373169e494e0c39","path":"index"},{"id":0,"type":2,"name":"自定义","appid":"wx1373169e494e0c39","path":"index"}]}","store_name": "羊村小马烧烤","contract_phone": "111111111","hour": "00:00-11:11","company_name": "深圳市腾讯计算机系统有限公司","credential": "156718193518281","address": "新疆维吾尔自治区克拉玛依市克拉玛依区碧水路15-1-8号(碧水云天广场)","qualification_list": "3LaLzqiTrQcD20DlX_o-OV1-nlYMu7sdVAL7SV2PrxVyjZFZZmB3O6LPGaYXlZWq","poi_id": ""}

                      返回json示例: { "errcode":0, "errmsg":"ok", "data":{ "audit_id":416620525, "poi_id": 112333 } }

                      审核状态通知

                      审核状态通过事件推送通知,推送数据格式为 XML

                      示例数据

                      <xml>  <ToUserName><![CDATA[gh_4346ac1514d8]]></ToUserName>  <FromUserName><![CDATA[od1P50M-fNQI5Gcq-trm4a7apsU8]]></FromUserName>  <CreateTime>1488856741</CreateTime>  <MsgType><![CDATA[event]]></MsgType>  <Event><![CDATA[add_nearby_poi_audit_info]]></Event>  <audit_id>11111</audit_id>  <status>3</status>                // 2: 审核失败 3: 审核通过  <reason><![CDATA[xxx]]></reason>  //审核失败的理由  <poi_id>111111</poi_id></xml>

                      参数说明

                      参数说明
                      audit_id审核单id
                      status审核状态(3:审核通过,2:审核失败)
                      reason如果status为2,会返回审核失败的原因
                      poi_idpoi_id

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.nearbyPoi.add
                      需在 config.json 中配置 nearbyPoi.add API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      isCommNearbystring必填,写死为"1"
                      picListstring门店图片,最多9张,最少1张,上传门店图片如门店外景、环境设施、商品服务等,图片将展示在微信客户端的门店页。图片链接通过文档https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1444738729中的《上传图文消息内的图片获取URL》接口获取。必填,文件格式为bmp、png、jpeg、jpg或gif,大小不超过5M pic_list是字符串,内容是一个json
                      serviceInfosstring必服务标签列表 必填,需要填写
                      1、 服务标签ID
                      2、 服务类型tpye
                      3、 服务名称name
                      详细字段格式见下方《服务标签id编号、类型与服务名称表》
                      4、 APPID
                      5、 对应服务落地页的path路径:path路径页面要与对应的服务标签一致,例如选取外卖服务,path路径应该是小程序的外卖对应的那个页面,path路径获取咨询开发或者到小程序管理后台-工具-生成小程序码页面获取
                      6、新增服务描述desc:描述服务内容,例如满减、折扣等优惠信息或新品、爆品等商品信息,仅标准服务都可添加,10个字符以内。
                      service_infos是字符串,内容是一个json
                      kfInfostring客服信息 选填,可自定义服务头像与昵称,具体填写字段见下方示例kf_info pic_list是字符串,内容是一个json
                      storeNamestring门店名字 必填,门店名称需按照所选地理位置自动拉取腾讯地图门店名称,不可修改,如需修改请重现选择地图地点或重新创建地点。
                      hourstring营业时间,格式11:11-12:12 必填
                      addressstring地址 必填
                      poiIdstring如果创建新的门店,poi_id字段为空 如果更新门店,poi_id参数则填对应门店的poi_id 选填
                      companyNamestring主体名字 必填
                      contractPhonestring门店电话 必填
                      credentialstring资质号 必填, 15位营业执照注册号或9位组织机构代码
                      qualificationListstring证明材料 必填 如果company_name和该小程序主体不一致,需要填qualification_list,详细规则见附近的小程序使用指南-如何证明门店的经营主体跟公众号或小程序帐号主体相关http://kf.qq.com/faq/170401MbUnim17040122m2qY.html
                      mapPoiIdstring对应《在腾讯地图中搜索门店》中的sosomap_poi_uid字段 腾讯地图那边有些数据不一致,如果不填map_poi_id的话,小概率会提交失败!
                      注:
                      poi_id与map_poi_id关系:
                      map_poi_id是腾讯地图对于poi的唯一标识
                      poi_id是门店进驻附近后的门店唯一标识
                      NearbyPoiError@error

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errMsgstring错误信息
                      errCodenumber错误码
                      dataobject返回数据

                      data 的结构

                      属性类型说明
                      auditIdstring审核单 ID
                      poiIdstring附近地点 ID
                      relatedCredentialstring经营资质证件号

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errMsgstring错误信息
                      errCodenumber错误码

                      errCode 的合法值

                      说明最低版本

                      请求示例

                      {"is_comm_nearby": "1", //值固定"kf_info": "{"open_kf":true,"kf_headimg":"http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITqmP914zSwhajIEJzUPpx40P7R8fRe1QmicneQMhFzpZNhSLjrvU1pIA/0?wx_fmt=jpeg","kf_name":"Harden"}","pic_list": "{"list":["http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITqmP914zSwhajIEJzUPpx40P7R8fRe1QmicneQMhFzpZNhSLjrvU1pIA/0?wx_fmt=jpeg","http://mmbiz.qpic.cn/mmbiz_jpg/kKMgNtnEfQzDKpLXYhgo3W3Gndl34gITRneE5FS9uYruXGMmrtmhsBySwddEWUGOibG8Ze2NT5E3Dyt79I0htNg/0?wx_fmt=jpeg"]}","service_infos": "{"service_infos":[{"id":2,"type":1,"name":"快递","appid":"wx1373169e494e0c39","path":"index"},{"id":0,"type":2,"name":"自定义","appid":"wx1373169e494e0c39","path":"index"}]}","store_name": "羊村小马烧烤","contract_phone": "111111111","hour": "00:00-11:11","company_name": "深圳市腾讯计算机系统有限公司","credential": "156718193518281","address": "新疆维吾尔自治区克拉玛依市克拉玛依区碧水路15-1-8号(碧水云天广场)","qualification_list": "3LaLzqiTrQcD20DlX_o-OV1-nlYMu7sdVAL7SV2PrxVyjZFZZmB3O6LPGaYXlZWq","poi_id": ""}

                      返回json示例: { "errcode":0, "errmsg":"ok", "data":{ "audit_id":416620525, "poi_id": 112333 } }


                      nearbyPoi.delete

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      删除地点

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/delnearbypoi?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      poi_idstring附近地点 ID

                      返回值

                      deleteNearbyPoiResponse

                      返回的 JSON 数据包

                      错误

                      错误码错误信息说明
                      0ok正常
                      47001POST数据json格式错误
                      20002POST参数非法
                      44002POST数据为空
                      92000该经营资质已添加,请勿重复添加
                      92002附近地点添加数量达到上线,无法继续添加
                      92003地点已被其它小程序占用
                      92004附近功能被封禁
                      92005地点正在审核中
                      92006地点正在展示小程序
                      92007地点审核失败
                      92008程序未展示在该地点
                      93009小程序未上架或不可见
                      93010地点不存在
                      93011个人类型小程序不可用
                      93011个人类型小程序不可用
                      93012非普通类型小程序(门店小程序、小店小程序等)不可用
                      93013从腾讯地图获取地址详细信息失败
                      93014同一资质证件号重复添加

                      POST数据示例:

                      { "poi_id":"469382092"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.nearbyPoi.delete
                      需在 config.json 中配置 nearbyPoi.delete API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      poiIdstring附近地点 ID

                      返回值

                      deleteNearbyPoiResponse

                      返回的 JSON 数据包

                      错误

                      错误码错误信息说明
                      0ok正常
                      47001POST数据json格式错误
                      20002POST参数非法
                      44002POST数据为空
                      92000该经营资质已添加,请勿重复添加
                      92002附近地点添加数量达到上线,无法继续添加
                      92003地点已被其它小程序占用
                      92004附近功能被封禁
                      92005地点正在审核中
                      92006地点正在展示小程序
                      92007地点审核失败
                      92008程序未展示在该地点
                      93009小程序未上架或不可见
                      93010地点不存在
                      93011个人类型小程序不可用
                      93011个人类型小程序不可用
                      93012非普通类型小程序(门店小程序、小店小程序等)不可用
                      93013从腾讯地图获取地址详细信息失败
                      93014同一资质证件号重复添加


                      nearbyPoi.getList

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      查看地点列表

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/wxa/getnearbypoilist?page=1&page_rows=20&access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      pagenumber起始页id(从1开始计数)
                      page_rowsnumber每页展示个数(最多1000个)

                      返回值

                      Object

                      属性类型说明
                      errmsgstring错误信息
                      errcodenumber错误码
                      dataobject返回数据

                      data 的结构

                      属性类型说明
                      left_apply_numnumber剩余可添加地点个数
                      max_apply_numnumber最大可添加地点个数
                      datastring地址列表的 JSON 格式字符串

                      data.data 的结构

                      属性类型说明
                      poi_listArray.<Object>地址列表

                      data.data.poi_list 的结构

                      属性类型说明
                      poi_idstring附近地点 ID
                      qualification_addressstring资质证件地址
                      qualification_numstring资质证件证件号
                      audit_statusnumber地点审核状态
                      display_statusnumber地点展示在附近状态
                      refuse_reasonstring审核失败原因,audit_status=4 时返回

                      audit_status 的合法值

                      说明最低版本
                      3审核中
                      4审核失败
                      5审核通过

                      display_status 的合法值

                      说明最低版本
                      0未展示
                      1展示中

                      错误

                      错误码错误信息说明
                      0ok正常
                      47001POST数据json格式错误
                      20002POST参数非法
                      44002POST数据为空
                      92000该经营资质已添加,请勿重复添加
                      92002附近地点添加数量达到上线,无法继续添加
                      92003地点已被其它小程序占用
                      92004附近功能被封禁
                      92005地点正在审核中
                      92006地点正在展示小程序
                      92007地点审核失败
                      92008程序未展示在该地点
                      93009小程序未上架或不可见
                      93010地点不存在
                      93011个人类型小程序不可用
                      93011个人类型小程序不可用
                      93012非普通类型小程序(门店小程序、小店小程序等)不可用
                      93013从腾讯地图获取地址详细信息失败
                      93014同一资质证件号重复添加

                      返回数据示例

                      {   "errcode": 0,   "errmsg": "",   "data": {      "left_apply_num": 9,      "max_apply_num": 10,      "data": "{"poi_list": [{"poi_id": "123456","qualification_address": "广东省广州市海珠区新港中路123号","qualification_num": "123456789-1","audit_status": 3,"display_status": 0,"refuse_reason": ""}]}"   }}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.nearbyPoi.getList
                      需在 config.json 中配置 nearbyPoi.getList API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      pagenumber起始页id(从1开始计数)
                      pageRowsnumber每页展示个数(最多1000个)

                      返回值

                      Object

                      属性类型说明
                      errMsgstring错误信息
                      errCodenumber错误码
                      dataobject返回数据

                      data 的结构

                      属性类型说明
                      leftApplyNumnumber剩余可添加地点个数
                      maxApplyNumnumber最大可添加地点个数
                      datastring地址列表的 JSON 格式字符串

                      data.data 的结构

                      属性类型说明
                      poiListArray.<Object>地址列表

                      data.data.poiList 的结构

                      属性类型说明
                      poiIdstring附近地点 ID
                      qualificationAddressstring资质证件地址
                      qualificationNumstring资质证件证件号
                      auditStatusnumber地点审核状态
                      displayStatusnumber地点展示在附近状态
                      refuseReasonstring审核失败原因,audit_status=4 时返回

                      auditStatus 的合法值

                      说明最低版本
                      3审核中
                      4审核失败
                      5审核通过

                      displayStatus 的合法值

                      说明最低版本
                      0未展示
                      1展示中

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errMsgstring错误信息
                      errCodenumber错误码

                      errCode 的合法值

                      说明最低版本

                      错误

                      错误码错误信息说明
                      0ok正常
                      47001POST数据json格式错误
                      20002POST参数非法
                      44002POST数据为空
                      92000该经营资质已添加,请勿重复添加
                      92002附近地点添加数量达到上线,无法继续添加
                      92003地点已被其它小程序占用
                      92004附近功能被封禁
                      92005地点正在审核中
                      92006地点正在展示小程序
                      92007地点审核失败
                      92008程序未展示在该地点
                      93009小程序未上架或不可见
                      93010地点不存在
                      93011个人类型小程序不可用
                      93011个人类型小程序不可用
                      93012非普通类型小程序(门店小程序、小店小程序等)不可用
                      93013从腾讯地图获取地址详细信息失败
                      93014同一资质证件号重复添加

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.nearbyPoi.getList({        page: '',        pageRows: ''      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "errCode": 0,  "errMsg": "openapi.nearbyPoi.getList:ok",  "data": {    "data": "{"poi_list": [{"poi_id": "123456","qualification_address": "广东省广州市海珠区新港中路123号","qualification_num": "123456789-1","audit_status": 3,"display_status": 0,"refuse_reason": ""}]}",    "leftApplyNum": 9,    "maxApplyNum": 10  }}


                      nearbyPoi.setShowStatus

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      展示/取消展示附近小程序

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/setnearbypoishowstatus?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      poi_idstring附近地点 ID
                      statusnumber是否展示

                      status 的合法值

                      说明最低版本
                      0不展示
                      1展示

                      返回值

                      Object

                      返回的 JSON 数据

                      属性类型说明
                      errmsgstring错误信息
                      errcodenumber错误码

                      错误

                      错误码错误信息说明
                      0ok正常
                      47001POST数据json格式错误
                      20002POST参数非法
                      44002POST数据为空
                      92000该经营资质已添加,请勿重复添加
                      92002附近地点添加数量达到上线,无法继续添加
                      92003地点已被其它小程序占用
                      92004附近功能被封禁
                      92005地点正在审核中
                      92006地点正在展示小程序
                      92007地点审核失败
                      92008程序未展示在该地点
                      93009小程序未上架或不可见
                      93010地点不存在
                      93011个人类型小程序不可用
                      93011个人类型小程序不可用
                      93012非普通类型小程序(门店小程序、小店小程序等)不可用
                      93013从腾讯地图获取地址详细信息失败
                      93014同一资质证件号重复添加

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.nearbyPoi.setShowStatus
                      需在 config.json 中配置 nearbyPoi.setShowStatus API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      poiIdstring附近地点 ID
                      statusnumber是否展示

                      status 的合法值

                      说明最低版本
                      0不展示
                      1展示

                      返回值

                      Object

                      返回的 JSON 数据

                      属性类型说明
                      errMsgstring错误信息
                      errCodenumber错误码

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errMsgstring错误信息
                      errCodenumber错误码

                      errCode 的合法值

                      说明最低版本

                      错误

                      错误码错误信息说明
                      0ok正常
                      47001POST数据json格式错误
                      20002POST参数非法
                      44002POST数据为空
                      92000该经营资质已添加,请勿重复添加
                      92002附近地点添加数量达到上线,无法继续添加
                      92003地点已被其它小程序占用
                      92004附近功能被封禁
                      92005地点正在审核中
                      92006地点正在展示小程序
                      92007地点审核失败
                      92008程序未展示在该地点
                      93009小程序未上架或不可见
                      93010地点不存在
                      93011个人类型小程序不可用
                      93011个人类型小程序不可用
                      93012非普通类型小程序(门店小程序、小店小程序等)不可用
                      93013从腾讯地图获取地址详细信息失败
                      93014同一资质证件号重复添加


                      wxacode.createQRCode

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取小程序二维码,适用于需要的码数量较少的业务场景。通过该接口生成的小程序码,永久有效,有数量限制,详见获取二维码

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/wxaapp/createwxaqrcode?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      pathstring扫码进入的小程序页面路径,最大长度 128 字节,不能为空;对于小游戏,可以只传入 query 部分,来实现传参效果,如:传入 "?foo=bar",即可在 wx.getLaunchOptionsSync 接口中的 query 参数获取到 {foo:"bar"}
                      widthnumber430二维码的宽度,单位 px。最小 280px,最大 1280px

                      返回值

                      Buffer

                      返回的图片 Buffer

                      异常返回

                      Object

                      JSON

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      45029生成码个数总和到达最大个数限制

                      返回值说明

                      如果调用成功,会直接返回图片二进制内容,如果请求失败,会返回 JSON 格式的数据。

                      注意

                      • POST 参数需要转成 JSON 字符串,不支持 form 表单提交。
                      • 接口只能生成已发布的小程序的二维码。开发版的带参二维码可以在开发者工具预览时生成。
                      • 与 wxacode.get 总共生成的码数量限制为 100,000,请谨慎调用。

                      示例

                      请求

                      { "path":"page/index/index", "width":430}

                      返回

                      { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.wxacode.createQRCode
                      需在 config.json 中配置 wxacode.createQRCode API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      pathstring扫码进入的小程序页面路径,最大长度 128 字节,不能为空;对于小游戏,可以只传入 query 部分,来实现传参效果,如:传入 "?foo=bar",即可在 wx.getLaunchOptionsSync 接口中的 query 参数获取到 {foo:"bar"}
                      widthnumber430二维码的宽度,单位 px。最小 280px,最大 1280px

                      返回值

                      Object

                      包含二进制数据及其数据类型的对象

                      属性类型说明
                      contentTypeString数据类型 (MIME Type)
                      bufferBuffer数据 Buffer

                      异常

                      Object

                      JSON

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      示例

                      请求

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.wxacode.createQRCode({        path: 'page/index/index',        width: 430      })    return result  } catch (err) {    return err  }}

                      返回

                      { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}


                      wxacode.get

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取小程序码,适用于需要的码数量较少的业务场景。通过该接口生成的小程序码,永久有效,有数量限制,详见获取二维码

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/getwxacode?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      pathstring扫码进入的小程序页面路径,最大长度 128 字节,不能为空;对于小游戏,可以只传入 query 部分,来实现传参效果,如:传入 "?foo=bar",即可在 wx.getLaunchOptionsSync 接口中的 query 参数获取到 {foo:"bar"}
                      widthnumber430二维码的宽度,单位 px。最小 280px,最大 1280px
                      auto_colorbooleanfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调
                      line_colorObject{"r":0,"g":0,"b":0}auto_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"} 十进制表示
                      is_hyalinebooleanfalse是否需要透明底色,为 true 时,生成透明底色的小程序码

                      返回值

                      Buffer

                      返回的图片 Buffer

                      异常返回

                      Object

                      JSON

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      45029生成码个数总和到达最大个数限制

                      返回值说明

                      如果调用成功,会直接返回图片二进制内容,如果请求失败,会返回 JSON 格式的数据。

                      注意

                      • POST 参数需要转成 JSON 字符串,不支持 form 表单提交。
                      • 接口只能生成已发布的小程序的二维码
                      • 与 wxacode.createQRCode 总共生成的码数量限制为 100,000,请谨慎调用。

                      示例

                      请求

                      { "path":"page/index/index", "width":430}

                      返回

                      { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.wxacode.get
                      需在 config.json 中配置 wxacode.get API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      pathstring扫码进入的小程序页面路径,最大长度 128 字节,不能为空;对于小游戏,可以只传入 query 部分,来实现传参效果,如:传入 "?foo=bar",即可在 wx.getLaunchOptionsSync 接口中的 query 参数获取到 {foo:"bar"}
                      widthnumber430二维码的宽度,单位 px。最小 280px,最大 1280px
                      autoColorbooleanfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调
                      lineColorObject{"r":0,"g":0,"b":0}auto_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"} 十进制表示
                      isHyalinebooleanfalse是否需要透明底色,为 true 时,生成透明底色的小程序码

                      返回值

                      Object

                      包含二进制数据及其数据类型的对象

                      属性类型说明
                      contentTypeString数据类型 (MIME Type)
                      bufferBuffer数据 Buffer

                      异常

                      Object

                      JSON

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      示例

                      请求

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.wxacode.get({        path: 'page/index/index',        width: 430      })    return result  } catch (err) {    return err  }}

                      返回

                      { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}


                      wxacode.getUnlimited

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取小程序码,适用于需要的码数量极多的业务场景。通过该接口生成的小程序码,永久有效,数量暂无限制。 更多用法详见 获取二维码

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址 

                      POST https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      scenestring最大32个可见字符,只支持数字,大小写英文以及部分特殊字符:!#$&'()*+,/:;=?@-._~,其它字符请自行编码为合法字符(因不支持%,中文无法使用 urlencode 处理,请使用其他编码方式)
                      pagestring主页必须是已经发布的小程序存在的页面(否则报错),例如 pages/index/index, 根路径前不要填加 /,不能携带参数(参数请放在scene字段里),如果不填写这个字段,默认跳主页面
                      widthnumber430二维码的宽度,单位 px,最小 280px,最大 1280px
                      auto_colorbooleanfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调,默认 false
                      line_colorObject{"r":0,"g":0,"b":0}auto_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"} 十进制表示
                      is_hyalinebooleanfalse是否需要透明底色,为 true 时,生成透明底色的小程序

                      返回值

                      Buffer

                      返回的图片 Buffer

                      异常返回

                      Object

                      JSON

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      45009调用分钟频率受限(目前5000次/分钟,会调整),如需大量小程序码,建议预生成。
                      41030所传page页面不存在,或者小程序没有发布

                      返回值说明

                      如果调用成功,会直接返回图片二进制内容,如果请求失败,会返回 JSON 格式的数据。

                      注意

                      • POST 参数需要转成 JSON 字符串,不支持 form 表单提交。
                      • 接口只能生成已发布的小程序的二维码
                      • 调用分钟频率受限(5000次/分钟),如需大量小程序码,建议预生成

                      获取 scene 值

                      scene 字段的值会作为 query 参数传递给小程序/小游戏。用户扫描该码进入小程序/小游戏后,开发者可以获取到二维码中的 scene 值,再做处理逻辑。

                      调试阶段可以使用开发工具的条件编译自定义参数 scene=xxxx 进行模拟,开发工具模拟时的 scene 的参数值需要进行 encodeURIComponent

                      小程序

                      Page({  onLoad (query) {    // scene 需要使用 decodeURIComponent 才能获取到生成二维码时传入的 scene    const scene = decodeURIComponent(query.scene)  }})

                      小游戏

                      // 在首次启动时通过 wx.getLaunchOptionsSync 接口获取const {query} = wx.getLaunchOptionsSync()const scene = decodeURIComponent(query.scene)// 或者在 wx.onShow 事件中获取wx.onShow(function ({query}) {  // scene 需要使用 decodeURIComponent 才能获取到生成二维码时传入的 scene  const scene = decodeURIComponent(query.scene)})

                      示例

                      请求

                      { "scene": "a=1"}

                      返回

                      { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.wxacode.getUnlimited
                      需在 config.json 中配置 wxacode.getUnlimited API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      scenestring最大32个可见字符,只支持数字,大小写英文以及部分特殊字符:!#$&'()*+,/:;=?@-._~,其它字符请自行编码为合法字符(因不支持%,中文无法使用 urlencode 处理,请使用其他编码方式)
                      pagestring主页必须是已经发布的小程序存在的页面(否则报错),例如 pages/index/index, 根路径前不要填加 /,不能携带参数(参数请放在scene字段里),如果不填写这个字段,默认跳主页面
                      widthnumber430二维码的宽度,单位 px,最小 280px,最大 1280px
                      autoColorbooleanfalse自动配置线条颜色,如果颜色依然是黑色,则说明不建议配置主色调,默认 false
                      lineColorObject{"r":0,"g":0,"b":0}auto_color 为 false 时生效,使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"} 十进制表示
                      isHyalinebooleanfalse是否需要透明底色,为 true 时,生成透明底色的小程序

                      返回值

                      Object

                      包含二进制数据及其数据类型的对象

                      属性类型说明
                      contentTypeString数据类型 (MIME Type)
                      bufferBuffer数据 Buffer

                      异常

                      Object

                      JSON

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      示例

                      请求

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.wxacode.getUnlimited({        scene: 'a=1'      })    return result  } catch (err) {    return err  }}

                      返回

                      { "errcode": 0, "errmsg": "ok", "contentType": "image/jpeg", "buffer": Buffer}


                      security.imgSecCheck

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      校验一张图片是否含有违法违规内容。

                      应用场景举例:

                      1. 图片智能鉴黄:涉及拍照的工具类应用(如美拍,识图类应用)用户拍照上传检测;电商类商品上架图片检测;媒体类用户文章里的图片检测等;
                      2. 敏感人脸识别:用户头像;媒体类用户文章里的图片检测;社交类用户上传的图片检测等。 频率限制:单个 appId 调用上限为 2000 次/分钟,200,000 次/天*(图片大小限制:1M) *服务市场:**通过服务市场使用可以有更多的能力,文档详情。

                      调用方式:

                      • HTTPS 调用
                      • 云调用
                      • 增量调用(加强版)

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/img_sec_check?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      mediaFormData要检测的图片文件,格式支持PNG、JPEG、JPG、GIF,图片尺寸不超过 750px x 1334px

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errMsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0内容正常
                      87014内容含有违法违规内容

                      errMsg 的合法值

                      说明最低版本
                      "ok"内容正常
                      "risky content"内容含有违法违规内容

                      调用示例

                      curl -F media=@test.jpg 'https://api.weixin.qq.com/wxa/img_sec_check?access_token=ACCESS_TOKEN'

                      调用过程中如遇到问题,可在珊瑚安全社区发帖交流。

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.security.imgSecCheck
                      需在 config.json 中配置 security.imgSecCheck API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      mediaFormData媒体文件数据

                      media 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      87014内容含有违法违规内容

                      errMsg 的合法值

                      说明最低版本
                      "ok"内容正常
                      "risky content"内容含有违法违规内容

                      SDK 调用示例

                      // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.security.imgSecCheck({  media: {    contentType: 'image/png',    value: Buffer  }})


                      security.mediaCheckAsync

                      本接口应在服务器端调用,详细说明参见服务端API

                      异步校验图片/音频是否含有违法违规内容。

                      应用场景举例:

                      1. 语音风险识别:社交类用户发表的语音内容检测;
                      2. 图片智能鉴黄:涉及拍照的工具类应用(如美拍,识图类应用)用户拍照上传检测;电商类商品上架图片检测;媒体类用户文章里的图片检测等;
                      3. 敏感人脸识别:用户头像;媒体类用户文章里的图片检测;社交类用户上传的图片检测等。 频率限制:单个 appId 调用上限为 2000 次/分钟,200,000 次/天;文件大小限制:单个文件大小不超过10M

                      请求地址

                      POST https://api.weixin.qq.com/wxa/media_check_async?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      media_urlstring要检测的多媒体url
                      media_typenumber1:音频;2:图片

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      trace_idstring任务id,用于匹配异步推送结果
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0检测请求已接收

                      Object

                      异步检测结果在 30 分钟内会推送到你的消息接收服务器。返回的 JSON 数据包

                      属性类型说明
                      ToUserNamestring小程序的username
                      FromUserNamestring平台推送服务UserName
                      CreateTimenumber发送时间
                      MsgTypestring默认为:Event
                      Eventstring默认为:wxa_media_check
                      isriskynumber检测结果,0:暂未检测到风险,1:风险
                      extra_info_jsonstring附加信息,默认为空
                      appidstring小程序的appid
                      trace_idstring任务id
                      status_codenumber默认为:0,4294966288(-1008)为链接无法下载

                      调用示例

                      curl -d '{ "media_url":"https://developers.weixin.qq.com/miniprogram/assets/images/head_global_z_@all.png","media_type":2 }' 'https://api.weixin.qq.com/wxa/media_check_async?access_token=ACCESS_TOKEN'

                      注意

                      media_type 需要准确填写 url 对应的多媒体类型,media_url 需要保证可以被检测服务器下载

                      接口返回示例

                      {   "errcode"  : 0,   "errmsg"   : "ok",   "trace_id" : "967e945cd8a3e458f3c74dcb886068e9"}

                      异步检测结果推送示例

                      {   "ToUserName"      : "gh_38cc49f9733b",   "FromUserName"    : "oH1fu0FdHqpToe2T6gBj0WyB8iS1",   "CreateTime"      : 1552465698,   "MsgType"         : "event",   "Event"           : "wxa_media_check",   "isrisky"         : 0,   "extra_info_json" : "",   "appid"           : "wxd8c59133dfcbfc71",   "trace_id"        : "967e945cd8a3e458f3c74dcb886068e9",   "status_code"     : 0}

                      调用过程中如遇到问题,可在珊瑚安全社区发帖交流。


                      security.msgSecCheck

                      本接口应在服务器端调用,详细说明参见服务端API。
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载),wx-server-sdk >= 0.4.0

                      检查一段文本是否含有违法违规内容。

                      应用场景举例:

                      1. 用户个人资料违规文字检测;
                      2. 媒体新闻类用户发表文章,评论内容检测;
                      3. 游戏类用户编辑上传的素材(如答题类小游戏用户上传的问题及答案)检测等。 频率限制:单个 appId 调用上限为 4000 次/分钟,2,000,000 次/天* *服务市场:**通过服务市场使用可以有更多的能力,文档详情。

                      调用方式:

                      • HTTPS 调用
                      • 云调用
                      • 增量调用(加强版)

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/msg_sec_check?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      contentstring要检测的文本内容,长度不超过 500KB

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errMsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0内容正常
                      87014内容含有违法违规内容

                      errMsg 的合法值

                      说明最低版本
                      "ok"内容正常
                      "riskycontent" 内容含有违法违规内容

                      调用示例

                      curl -d '{ "content":"hello world!" }' 'https://api.weixin.qq.com/wxa/msg_sec_check?access_token=ACCESS_TOKEN'

                      测试用例

                      特3456书yuuo莞6543李zxcz蒜7782法fgnv级完2347全dfji试3726测asad感3847知qwez到

                      开发者可使用以上两段文本进行测试,若接口errcode返回87014(内容含有违法违规内容),则对接成功。

                      调用过程中如遇到问题,可在珊瑚安全社区发帖交流。

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.security.msgSecCheck
                      需在 config.json 中配置 security.msgSecCheck API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      contentstring要检测的文本内容,长度不超过 500KB

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      87014内容含有违法违规内容

                      errMsg 的合法值

                      说明最低版本
                      "ok"内容正常
                      "riskycontent" 内容含有违法违规内容


                      logistics.batchGetOrder

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      批量获取运单数据

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/business/order/batchget?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      order_listArray.<Object>订单列表, 最多不能超过100个

                      order_list 的结构

                      属性类型默认值必填说明
                      order_idstring订单ID
                      delivery_idstring快递公司ID,参见getAllDelivery
                      waybill_idstring运单ID

                      返回值

                      Object

                      属性类型说明
                      order_listArray.<Object>运单列表
                      order_statusnumber运单状态, 0正常,1取消

                      order_list 的结构

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      order_idstring订单ID
                      delivery_idstring快递公司ID,参见getAllDelivery
                      waybill_idstring运单ID
                      print_htmlstring运单 html 的 BASE64 结果
                      waybill_dataArray.<Object>运单信息

                      order_list.waybill_data 的结构

                      属性类型说明
                      keystring运单信息 key
                      valuestring运单信息 value

                      请求数据示例

                      {   "order_list": [       {          "order_id": "01234567890123456789",          "delivery_id": "SF",          "waybill_id": "123456789"       },       {          "order_id": "01234567890123456789",          "delivery_id": "SF",          "waybill_id": "123456789"       }   ]}

                      返回数据示例

                      {   "order_list": [       {          "errcode": 0,          "errmsg": "ok",          "order_id": "01234567890123456789",          "delivery_id": "SF",          "waybill_id": "123456789",          "print_html": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",          "waybill_data": [               {                   "key": "SF_bagAddr",                   "value": "广州"               },               {                  "key": "SF_mark",                  "value": "101- 07-03 509"               }           ],           "order_status": 0       },       {          "errcode": 0,          "errmsg": "ok",          "order_id": "01234567890123456789_2",          "delivery_id": "SF",          "waybill_id": "123456789_2",          "print_html": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",          "waybill_data": [               {                   "key": "SF_bagAddr",                   "value": "广州"               },               {                  "key": "SF_mark",                  "value": "101- 07-03 509"               }           ],           "order_status": 0       }   ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.batchGetOrder
                      需在 config.json 中配置 logistics.batchGetOrder API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      orderListArray.<Object>订单列表, 最多不能超过100个

                      orderList 的结构

                      属性类型默认值必填说明
                      orderIdstring订单ID
                      deliveryIdstring快递公司ID,参见getAllDelivery
                      waybillIdstring运单ID

                      返回值

                      Object

                      属性类型说明
                      orderListArray.<Object>运单列表
                      orderStatusnumber运单状态, 0正常,1取消

                      orderList 的结构

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      orderIdstring订单ID
                      deliveryIdstring快递公司ID,参见getAllDelivery
                      waybillIdstring运单ID
                      printHtmlstring运单 html 的 BASE64 结果
                      waybillDataArray.<Object>运单信息

                      orderList.waybillData 的结构

                      属性类型说明
                      keystring运单信息 key
                      valuestring运单信息 value

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.batchGetOrder({        orderList: [          {            orderId: '01234567890123456789',            deliveryId: 'SF',            waybillId: '123456789'          },          {            orderId: '01234567890123456789',            deliveryId: 'SF',            waybillId: '123456789'          }        ]      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "orderList": [    {      "errcode": 0,      "errmsg": "ok",      "orderId": "01234567890123456789",      "deliveryId": "SF",      "waybillId": "123456789",      "printHtml": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",      "waybillData": [        {          "key": "SF_bagAddr",          "value": "广州"        },        {          "key": "SF_mark",          "value": "101- 07-03 509"        }      ],      "orderStatus": 0    },    {      "errcode": 0,      "errmsg": "ok",      "orderId": "01234567890123456789_2",      "deliveryId": "SF",      "waybillId": "123456789_2",      "printHtml": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",      "waybillData": [        {          "key": "SF_bagAddr",          "value": "广州"        },        {          "key": "SF_mark",          "value": "101- 07-03 509"        }      ],      "orderStatus": 0    }  ],  "errMsg": "openapi.logistics.batchGetOrder:ok"}


                      logistics.addOrder

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      生成运单

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/business/order/add?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      add_sourcenumber订单来源,0为小程序订单,2为App或H5订单,填2则不发送物流服务通知
                      wx_appidstringApp或H5的appid,add_source=2时必填,需和开通了物流助手的小程序绑定同一open帐号
                      order_idstring订单ID,须保证全局唯一,不超过512字节
                      openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
                      delivery_idstring快递公司ID,参见getAllDelivery
                      biz_idstring快递客户编码或者现付编码
                      custom_remarkstring快递备注信息,比如"易碎物品",不超过1024字节
                      tagidnumber订单标签id,用于平台型小程序区分平台上的入驻方,tagid须与入驻方账号一一对应,非平台型小程序无需填写该字段
                      senderObject发件人信息
                      receiverObject收件人信息
                      cargoObject包裹信息,将传递给快递公司
                      shopObject商品信息,会展示到物流服务通知和电子面单中
                      insuredObject保价信息
                      serviceObject服务类型
                      expect_timenumberUnix 时间戳, 单位秒,顺丰必须传。 预期的上门揽件时间,0表示已事先约定取件时间;否则请传预期揽件时间戳,需大于当前时间,收件员会在预期时间附近上门。例如expect_time为“1557989929”,表示希望收件员将在2019年05月16日14:58:49-15:58:49内上门取货。说明:若选择 了预期揽件时间,请不要自己打单,由上门揽件的时候打印。如果是下顺丰散单,则必传此字段,否则不会有收件员上门揽件。

                      sender 的结构

                      属性类型默认值必填说明
                      namestring发件人姓名,不超过64字节
                      telstring发件人座机号码,若不填写则必须填写 mobile,不超过32字节
                      mobilestring发件人手机号码,若不填写则必须填写 tel,不超过32字节
                      companystring发件人公司名称,不超过64字节
                      post_codestring发件人邮编,不超过10字节
                      countrystring发件人国家,不超过64字节
                      provincestring发件人省份,比如:"广东省",不超过64字节
                      citystring发件人市/地区,比如:"广州市",不超过64字节
                      areastring发件人区/县,比如:"海珠区",不超过64字节
                      addressstring发件人详细地址,比如:"XX路XX号XX大厦XX",不超过512字节

                      receiver 的结构

                      属性类型默认值必填说明
                      namestring收件人姓名,不超过64字节
                      telstring收件人座机号码,若不填写则必须填写 mobile,不超过32字节
                      mobilestring收件人手机号码,若不填写则必须填写 tel,不超过32字节
                      companystring收件人公司名,不超过64字节
                      post_codestring收件人邮编,不超过10字节
                      countrystring收件人所在国家,不超过64字节
                      provincestring收件人省份,比如:"广东省",不超过64字节
                      citystring收件人地区/市,比如:"广州市",不超过64字节
                      areastring收件人区/县,比如:"天河区",不超过64字节
                      addressstring收件人详细地址,比如:"XX路XX号XX大厦XX",不超过512字节

                      cargo 的结构

                      属性类型默认值必填说明
                      countnumber包裹数量, 需要和detail_list size保持一致
                      weightnumber包裹总重量,单位是千克(kg)
                      space_xnumber包裹长度,单位厘米(cm)
                      space_ynumber包裹宽度,单位厘米(cm)
                      space_znumber包裹高度,单位厘米(cm)
                      detail_listArray.<Object>包裹中商品详情列表

                      cargo.detail_list 的结构

                      属性类型默认值必填说明
                      namestring商品名,不超过128字节
                      countnumber商品数量

                      shop 的结构

                      属性类型默认值必填说明
                      wxa_pathstring商家小程序的路径,建议为订单页面
                      img_urlstring商品缩略图 url
                      goods_namestring商品名称, 不超过128字节
                      goods_countnumber商品数量

                      insured 的结构

                      属性类型默认值必填说明
                      use_insurednumber是否保价,0 表示不保价,1 表示保价
                      insured_valuenumber保价金额,单位是分,比如: 10000 表示 100 元

                      service 的结构

                      属性类型默认值必填说明
                      service_typenumber服务类型ID,详见已经支持的快递公司基本信息
                      service_namestring服务名称,详见已经支持的快递公司基本信息

                      返回值

                      Object

                      属性类型说明
                      order_idstring订单ID,下单成功时返回
                      waybill_idstring运单ID,下单成功时返回
                      waybill_dataArray.<Object>运单信息,下单成功时返回
                      errcodenumber微信侧错误码,下单失败时返回
                      errmsgstring微信侧错误信息,下单失败时返回
                      delivery_resultcodenumber快递侧错误码,下单失败时返回
                      delivery_resultmsgstring快递侧错误信息,下单失败时返回

                      waybill_data 的结构

                      属性类型说明
                      keystring运单信息 key
                      valuestring运单信息 value

                      errcode 的合法值

                      说明最低版本
                      -1系统失败
                      47001格式错误
                      40003openid无效
                      9300502快递公司系统错误
                      9300501快递侧逻辑错误,详细原因需要看 delivery_resultcode, 请先确认一下编码方式,python建议 json.dumps(b, ensure_ascii=False),php建议 json_encode($arr, JSON_UNESCAPED_UNICODE)
                      9300503delivery_id 不存在
                      9300510service_type 不存在
                      9300526字段长度不正确
                      930561参数错误
                      9300525bizid未绑定
                      9300534add_source=2时,wx_appid和当前小程序不同主体
                      9300535shop字段商品缩略图 url、商品名称为空或者非法,或者商品数量为0
                      9300536add_source=2时,wx_appid无效
                      9300531bizid无效
                      930564沙盒环境调用无配额
                      930559沙盒环境openid无效

                      请求示例

                      {  "add_source": 0,  "order_id": "01234567890123456789",  "openid": "oABC123456",  "delivery_id": "SF",  "biz_id": "xyz",  "custom_remark": "易碎物品",  "sender": {    "name": "张三",    "tel": "020-88888888",    "mobile": "18666666666",    "company": "公司名",    "post_code": "123456",    "country": "中国",    "province": "广东省",    "city": "广州市",    "area": "海珠区",    "address": "XX路XX号XX大厦XX栋XX"  },  "receiver": {    "name": "王小蒙",    "tel": "020-77777777",    "mobile": "18610000000",    "company": "公司名",    "post_code": "654321",    "country": "中国",    "province": "广东省",    "city": "广州市",    "area": "天河区",    "address": "XX路XX号XX大厦XX栋XX"  },  "shop": {    "wxa_path": "/index/index?from=waybill&id=01234567890123456789",    "img_url": "https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640",    "goods_name": "微信气泡狗抱枕&微信气泡狗钥匙扣",    "goods_count": 2  },  "cargo": {    "count": 2,    "weight": 5.5,    "space_x": 30.5,    "space_y": 20,    "space_z": 20,    "detail_list": [      {        "name": "微信气泡狗抱枕",        "count": 1      },      {        "name": "微信气泡狗钥匙扣",        "count": 1      }    ]  },  "insured": {    "use_insured": 1,    "insured_value": 10000  },  "service": {    "service_type": 0,    "service_name": "标准快递"  }}

                      返回示例

                      下单成功

                      {  "order_id": "01234567890123456789",  "waybill_id": "123456789",  "waybill_data": [    {      "key": "SF_bagAddr",      "value": "广州"    },    {      "key": "SF_mark",      "value": "101- 07-03 509"    }  ]}

                      下单失败

                      {  "errcode": 9300501,  "errmsg": "delivery logic fail",  "delivery_resultcode": 10002,  "delivery_resultmsg": "客户密码不正确"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.addOrder
                      需在 config.json 中配置 logistics.addOrder API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      addSourcenumber订单来源,0为小程序订单,2为App或H5订单,填2则不发送物流服务通知
                      wxAppidstringApp或H5的appid,add_source=2时必填,需和开通了物流助手的小程序绑定同一open帐号
                      orderIdstring订单ID,须保证全局唯一,不超过512字节
                      openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
                      deliveryIdstring快递公司ID,参见getAllDelivery
                      bizIdstring快递客户编码或者现付编码
                      customRemarkstring快递备注信息,比如"易碎物品",不超过1024字节
                      tagidnumber订单标签id,用于平台型小程序区分平台上的入驻方,tagid须与入驻方账号一一对应,非平台型小程序无需填写该字段
                      senderObject发件人信息
                      receiverObject收件人信息
                      cargoObject包裹信息,将传递给快递公司
                      shopObject商品信息,会展示到物流服务通知和电子面单中
                      insuredObject保价信息
                      serviceObject服务类型
                      expectTimenumberUnix 时间戳, 单位秒,顺丰必须传。 预期的上门揽件时间,0表示已事先约定取件时间;否则请传预期揽件时间戳,需大于当前时间,收件员会在预期时间附近上门。例如expect_time为“1557989929”,表示希望收件员将在2019年05月16日14:58:49-15:58:49内上门取货。说明:若选择 了预期揽件时间,请不要自己打单,由上门揽件的时候打印。如果是下顺丰散单,则必传此字段,否则不会有收件员上门揽件。

                      sender 的结构

                      属性类型默认值必填说明
                      namestring发件人姓名,不超过64字节
                      telstring发件人座机号码,若不填写则必须填写 mobile,不超过32字节
                      mobilestring发件人手机号码,若不填写则必须填写 tel,不超过32字节
                      companystring发件人公司名称,不超过64字节
                      postCodestring发件人邮编,不超过10字节
                      countrystring发件人国家,不超过64字节
                      provincestring发件人省份,比如:"广东省",不超过64字节
                      citystring发件人市/地区,比如:"广州市",不超过64字节
                      areastring发件人区/县,比如:"海珠区",不超过64字节
                      addressstring发件人详细地址,比如:"XX路XX号XX大厦XX",不超过512字节

                      receiver 的结构

                      属性类型默认值必填说明
                      namestring收件人姓名,不超过64字节
                      telstring收件人座机号码,若不填写则必须填写 mobile,不超过32字节
                      mobilestring收件人手机号码,若不填写则必须填写 tel,不超过32字节
                      companystring收件人公司名,不超过64字节
                      postCodestring收件人邮编,不超过10字节
                      countrystring收件人所在国家,不超过64字节
                      provincestring收件人省份,比如:"广东省",不超过64字节
                      citystring收件人地区/市,比如:"广州市",不超过64字节
                      areastring收件人区/县,比如:"天河区",不超过64字节
                      addressstring收件人详细地址,比如:"XX路XX号XX大厦XX",不超过512字节

                      cargo 的结构

                      属性类型默认值必填说明
                      countnumber包裹数量, 需要和detail_list size保持一致
                      weightnumber包裹总重量,单位是千克(kg)
                      spaceXnumber包裹长度,单位厘米(cm)
                      spaceYnumber包裹宽度,单位厘米(cm)
                      spaceZnumber包裹高度,单位厘米(cm)
                      detailListArray.<Object>包裹中商品详情列表

                      cargo.detailList 的结构

                      属性类型默认值必填说明
                      namestring商品名,不超过128字节
                      countnumber商品数量

                      shop 的结构

                      属性类型默认值必填说明
                      wxaPathstring商家小程序的路径,建议为订单页面
                      imgUrlstring商品缩略图 url
                      goodsNamestring商品名称, 不超过128字节
                      goodsCountnumber商品数量

                      insured 的结构

                      属性类型默认值必填说明
                      useInsurednumber是否保价,0 表示不保价,1 表示保价
                      insuredValuenumber保价金额,单位是分,比如: 10000 表示 100 元

                      service 的结构

                      属性类型默认值必填说明
                      serviceTypenumber服务类型ID,详见已经支持的快递公司基本信息
                      serviceNamestring服务名称,详见已经支持的快递公司基本信息

                      返回值

                      Object

                      属性类型说明
                      orderIdstring订单ID,下单成功时返回
                      waybillIdstring运单ID,下单成功时返回
                      waybillDataArray.<Object>运单信息,下单成功时返回
                      errCodenumber微信侧错误码,下单失败时返回
                      errMsgstring微信侧错误信息,下单失败时返回
                      deliveryResultcodenumber快递侧错误码,下单失败时返回
                      deliveryResultmsgstring快递侧错误信息,下单失败时返回

                      waybillData 的结构

                      属性类型说明
                      keystring运单信息 key
                      valuestring运单信息 value

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber微信侧错误码,下单失败时返回
                      errMsgstring微信侧错误信息,下单失败时返回

                      errCode 的合法值

                      说明最低版本
                      -1系统失败
                      47001格式错误
                      40003openid无效
                      9300502快递公司系统错误
                      9300501快递侧逻辑错误,详细原因需要看 delivery_resultcode, 请先确认一下编码方式,python建议 json.dumps(b, ensure_ascii=False),php建议 json_encode($arr, JSON_UNESCAPED_UNICODE)
                      9300503delivery_id 不存在
                      9300510service_type 不存在
                      9300526字段长度不正确
                      930561参数错误
                      9300525bizid未绑定
                      9300534add_source=2时,wx_appid和当前小程序不同主体
                      9300535shop字段商品缩略图 url、商品名称为空或者非法,或者商品数量为0
                      9300536add_source=2时,wx_appid无效
                      9300531bizid无效
                      930564沙盒环境调用无配额
                      930559沙盒环境openid无效

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.addOrder({        openid: 'oABC123456',        sender: {          name: '张三',          tel: '020-88888888',          mobile: '18666666666',          company: '公司名',          country: '中国',          province: '广东省',          city: '广州市',          area: '海珠区',          address: 'XX路XX号XX大厦XX栋XX',          postCode: '123456'        },        receiver: {          name: '王小蒙',          tel: '020-77777777',          mobile: '18610000000',          company: '公司名',          country: '中国',          province: '广东省',          city: '广州市',          area: '天河区',          address: 'XX路XX号XX大厦XX栋XX',          postCode: '654321'        },        shop: {          wxaPath: '/index/index?from=waybill&id=01234567890123456789',          imgUrl: 'https://mmbiz.qpic.cn/mmbiz_png/OiaFLUqewuIDNQnTiaCInIG8ibdosYHhQHPbXJUrqYSNIcBL60vo4LIjlcoNG1QPkeH5GWWEB41Ny895CokeAah8A/640',          goodsName: '微信气泡狗抱枕&微信气泡狗钥匙扣',          goodsCount: 2        },        cargo: {          count: 2,          weight: 5.5,          spaceX: 30.5,          spaceY: 20,          spaceZ: 20,          detailList: [            {              name: '微信气泡狗抱枕',              count: 1            },            {              name: '微信气泡狗钥匙扣',              count: 1            }          ]        },        insured: {          useInsured: 1,          insuredValue: 10000        },        service: {          serviceType: 0,          serviceName: '标准快递'        },        addSource: 0,        orderId: '01234567890123456789',        deliveryId: 'SF',        bizId: 'xyz',        customRemark: '易碎物品'      })    return result  } catch (err) {    return err  }}

                      返回示例

                      下单成功

                      {  "orderId": "01234567890123456789",  "waybillId": "123456789",  "waybillData": [    {      "key": "SF_bagAddr",      "value": "广州"    },    {      "key": "SF_mark",      "value": "101- 07-03 509"    }  ],  "errMsg": "openapi.logistics.addOrder:ok"}

                      下单失败

                      {  "errCode": 9300501,  "errMsg": "openapi.logistics.addOrder:fail delivery logic fail",  "deliveryResultcode": 10002,  "deliveryResultmsg": "客户密码不正确"}


                      logistics.bindAccount

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      绑定、解绑物流账号

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/business/account/bind?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      typestringbind表示绑定,unbind表示解除绑定
                      biz_idstring快递公司客户编码
                      delivery_idstring快递公司ID
                      passwordstring快递公司客户密码, ems,顺丰,京东非必填
                      remark_contentstring备注内容(提交EMS审核需要)

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0成功
                      -1系统失败
                      9300529账号已绑定过
                      9300530解绑的biz_id不存在
                      9300531账号或密码错误
                      9300532绑定已提交,审核中

                      请求数据示例

                      {  "type": "bind",  "biz_id": "123456",  "delivery_id": "YUNDA",  "password": "123456789123456789"}

                      返回数据示例

                      {  "errcode": 0,  "errmsg": "ok"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.bindAccount
                      需在 config.json 中配置 logistics.bindAccount API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      typestringbind表示绑定,unbind表示解除绑定
                      bizIdstring快递公司客户编码
                      deliveryIdstring快递公司ID
                      passwordstring快递公司客户密码, ems,顺丰,京东非必填
                      remarkContentstring备注内容(提交EMS审核需要)

                      返回值

                      Object

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      -1系统失败
                      9300529账号已绑定过
                      9300530解绑的biz_id不存在
                      9300531账号或密码错误
                      9300532绑定已提交,审核中

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.bindAccount({        type: 'bind',        password: '123456789123456789',        bizId: '123456',        deliveryId: 'YUNDA'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "errCode": 0,  "errMsg": "openapi.logistics.bindAccount:ok"}


                      logistics.cancelOrder

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载)
                      wx-server-sdk >= 0.4.0

                      取消运单

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/business/order/cancel?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      order_idstring订单 ID,需保证全局唯一
                      openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
                      delivery_idstring快递公司ID,参见getAllDelivery
                      waybill_idstring运单ID

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      delivery_resultcodenumber运力返回的错误码
                      delivery_resultmsgstring运力返回的错误信息

                      errcode 的合法值

                      说明最低版本
                      0成功
                      -1系统失败
                      40199运单 ID 不存在
                      9300503delivery_id不存在
                      930563订单不存在
                      930561参数错误
                      9300506运单 ID 已经存在轨迹,不可取消
                      9300524取消订单失败(一般为重复取消订单)
                      9300501快递公司逻辑错误,具体错误码见delivery_resultcode

                      请求示例

                      {  "order_id": "01234567890123456789",  "openid": "oABC123456",  "delivery_id": "SF",  "waybill_id": "123456789"}

                      返回示例

                      {  "errcode": 0,  "errmsg": "ok",  "delivery_resultcode": 0,  "delivery_resultmsg": ""}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.cancelOrder
                      需在 config.json 中配置 logistics.cancelOrder API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      orderIdstring订单 ID,需保证全局唯一
                      openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
                      deliveryIdstring快递公司ID,参见getAllDelivery
                      waybillIdstring运单ID

                      返回值

                      Object

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息
                      deliveryResultcodenumber运力返回的错误码
                      deliveryResultmsgstring运力返回的错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      -1系统失败
                      40199运单 ID 不存在
                      9300503delivery_id不存在
                      930563订单不存在
                      930561参数错误
                      9300506运单 ID 已经存在轨迹,不可取消
                      9300524取消订单失败(一般为重复取消订单)
                      9300501快递公司逻辑错误,具体错误码见delivery_resultcode

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.cancelOrder({        openid: 'oABC123456',        orderId: '01234567890123456789',        deliveryId: 'SF',        waybillId: '123456789'      })    return result  } catch (err) {    return err  }}

                      返回示例

                      {  "errCode": 0,  "errMsg": "openapi.logistics.cancelOrder:ok",  "deliveryResultcode": 0,  "deliveryResultmsg": ""}


                      logistics.getAllAccount

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取所有绑定的物流账号

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/cgi-bin/express/business/account/getall?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码
                      errmsgnumber错误信息
                      countnumber账号数量
                      listArray.<Object>账号列表

                      errcode 的合法值

                      说明最低版本
                      0成功
                      -1系统失败

                      list 的结构

                      属性类型说明
                      biz_idstring快递公司客户编码
                      delivery_idstring快递公司ID
                      create_timenumber账号绑定时间
                      update_timenumber账号更新时间
                      status_codenumber绑定状态
                      aliasstring账号别名
                      remark_wrong_msgstring账号绑定失败的错误信息(EMS审核结果)
                      remark_contentstring账号绑定时的备注内容(提交EMS审核需要)
                      quota_numnumber电子面单余额
                      quota_update_timenumber电子面单余额更新时间
                      service_typeArray.<Object>该绑定帐号支持的服务类型

                      list.status_code 的合法值

                      说明最低版本
                      0绑定成功
                      1审核中
                      2绑定失败
                      3已解绑

                      list.service_type 的结构

                      属性类型说明
                      service_typenumber服务类型ID
                      service_namestring服务类型名称

                      返回数据示例

                      {       "count": 1,       "list": [           {               "biz_id": "123456789",               "delivery_id": "YUNDA",               "create_time": 1555482786,               "update_time": 1556594799,               "status_code": 0,               "alias": "",               "remark_wrong_msg": "",               "remark_content": "",               "quota_num": 55,               "quota_update_time": 1556594799           }       ]   }

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.getAllAccount
                      需在 config.json 中配置 logistics.getAllAccount API 的权限,详情

                      返回值

                      Object

                      属性类型说明
                      errCodenumber错误码
                      errMsgnumber错误信息
                      countnumber账号数量
                      listArray.<Object>账号列表

                      errCode 的合法值

                      说明最低版本
                      0成功

                      list 的结构

                      属性类型说明
                      bizIdstring快递公司客户编码
                      deliveryIdstring快递公司ID
                      createTimenumber账号绑定时间
                      updateTimenumber账号更新时间
                      statusCodenumber绑定状态
                      aliasstring账号别名
                      remarkWrongMsgstring账号绑定失败的错误信息(EMS审核结果)
                      remarkContentstring账号绑定时的备注内容(提交EMS审核需要)
                      quotaNumnumber电子面单余额
                      quotaUpdateTimenumber电子面单余额更新时间
                      serviceTypeArray.<Object>该绑定帐号支持的服务类型

                      list.statusCode 的合法值

                      说明最低版本
                      0绑定成功
                      1审核中
                      2绑定失败
                      3已解绑

                      list.serviceType 的结构

                      属性类型说明
                      serviceTypenumber服务类型ID
                      serviceNamestring服务类型名称

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgnumber错误信息

                      errCode 的合法值

                      说明最低版本
                      -1系统失败

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getAllAccount({})    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "count": 1,  "list": [    {      "alias": "",      "bizId": "123456789",      "deliveryId": "YUNDA",      "createTime": 1555482786,      "updateTime": 1556594799,      "statusCode": 0,      "remarkWrongMsg": "",      "remarkContent": "",      "quotaNum": 55,      "quotaUpdateTime": 1556594799    }  ],  "errMsg": "openapi.logistics.getAllAccount:ok"}


                      logistics.getAllDelivery

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取支持的快递公司列表

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/cgi-bin/express/business/delivery/getall?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回值

                      Object

                      属性类型说明
                      countnumber快递公司数量
                      dataArray.<Object>快递公司信息列表

                      data 的结构

                      属性类型说明
                      delivery_idstring快递公司 ID
                      delivery_namestring快递公司名称
                      can_use_cashnumber是否支持散单, 1表示支持
                      can_get_quotanumber是否支持查询面单余额, 1表示支持
                      cash_biz_idstring散单对应的bizid,当can_use_cash=1时有效
                      service_typeArray.<Object>支持的服务类型

                      data.service_type 的结构

                      属性类型说明
                      service_typenumber服务类型ID
                      service_namestring服务类型名称

                      返回数据示例

                      {  "count": 7,  "data": [    {      "delivery_id": "BEST",      "delivery_name": "百世快递"    },    {      "delivery_id": "EMS",      "delivery_name": "中国邮政速递物流"    },    {      "delivery_id": "PJ",      "delivery_name": "品骏物流"    },    {      "delivery_id": "SF",      "delivery_name": "顺丰速运"    },    {      "delivery_id": "YTO",      "delivery_name": "圆通速递"    },    {      "delivery_id": "YUNDA",      "delivery_name": "韵达快递"    },    {      "delivery_id": "ZTO",      "delivery_name": "中通快递"    }  ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.getAllDelivery
                      需在 config.json 中配置 logistics.getAllDelivery API 的权限,详情

                      返回值

                      Object

                      属性类型说明
                      countnumber快递公司数量
                      dataArray.<Object>快递公司信息列表

                      data 的结构

                      属性类型说明
                      deliveryIdstring快递公司 ID
                      deliveryNamestring快递公司名称
                      canUseCashnumber是否支持散单, 1表示支持
                      canGetQuotanumber是否支持查询面单余额, 1表示支持
                      cashBizIdstring散单对应的bizid,当can_use_cash=1时有效
                      serviceTypeArray.<Object>支持的服务类型

                      data.serviceType 的结构

                      属性类型说明
                      serviceTypenumber服务类型ID
                      serviceNamestring服务类型名称

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getAllDelivery({})    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "count": 7,  "data": [    {      "deliveryId": "BEST",      "deliveryName": "百世快递"    },    {      "deliveryId": "EMS",      "deliveryName": "中国邮政速递物流"    },    {      "deliveryId": "PJ",      "deliveryName": "品骏物流"    },    {      "deliveryId": "SF",      "deliveryName": "顺丰速运"    },    {      "deliveryId": "YTO",      "deliveryName": "圆通速递"    },    {      "deliveryId": "YUNDA",      "deliveryName": "韵达快递"    },    {      "deliveryId": "ZTO",      "deliveryName": "中通快递"    }  ],  "errMsg": "openapi.logistics.getAllDelivery:ok"}


                      logistics.getOrder

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取运单数据

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/business/order/get?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      order_idstring订单 ID,需保证全局唯一
                      openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
                      delivery_idstring快递公司ID,参见getAllDelivery, 必须和waybill_id对应
                      waybill_idstring运单ID

                      返回值

                      Object

                      属性类型说明
                      print_htmlstring运单 html 的 BASE64 结果
                      waybill_dataArray.<Object>运单信息
                      delivery_idstring快递公司ID
                      order_idstring订单ID
                      waybill_idstring运单号
                      order_statusnumber运单状态, 0正常,1取消

                      waybill_data 的结构

                      属性类型说明
                      keystring运单信息 key
                      valuestring运单信息 value

                      请求数据示例

                      {  "order_id": "01234567890123456789",  "openid": "oABC123456",  "delivery_id": "SF",  "waybill_id": "123456789"}

                      返回数据示例

                      {  "print_html": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",  "waybill_data": [    {      "key": "SF_bagAddr",      "value": "广州"    },    {      "key": "SF_mark",      "value": "101- 07-03 509"    }  ],  "delivery_id": "SF",  "waybill_id": "123456",  "order_id": "123456",  "order_status": 0}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.getOrder
                      需在 config.json 中配置 logistics.getOrder API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      orderIdstring订单 ID,需保证全局唯一
                      openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
                      deliveryIdstring快递公司ID,参见getAllDelivery, 必须和waybill_id对应
                      waybillIdstring运单ID

                      返回值

                      Object

                      属性类型说明
                      printHtmlstring运单 html 的 BASE64 结果
                      waybillDataArray.<Object>运单信息
                      deliveryIdstring快递公司ID
                      orderIdstring订单ID
                      waybillIdstring运单号
                      orderStatusnumber运单状态, 0正常,1取消

                      waybillData 的结构

                      属性类型说明
                      keystring运单信息 key
                      valuestring运单信息 value

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getOrder({        openid: 'oABC123456',        orderId: '01234567890123456789',        deliveryId: 'SF',        waybillId: '123456789'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "printHtml": "jh7DjipP4ul4CQYUh69cniskrQZuOPwa1inAbXIqKbU0t71c0s65Au54cdWBZW0QJY4LYeofdM",  "waybillData": [    {      "key": "SF_bagAddr",      "value": "广州"    },    {      "key": "SF_mark",      "value": "101- 07-03 509"    }  ],  "deliveryId": "SF",  "waybillId": "123456",  "orderId": "123456",  "orderStatus": 0,  "errMsg": "openapi.logistics.getOrder:ok"}


                      logistics.getPath

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      查询运单轨迹

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/business/path/get?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      order_idstring订单 ID,需保证全局唯一
                      openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
                      delivery_idstring快递公司ID,参见getAllDelivery
                      waybill_idstring运单ID

                      返回值

                      Object

                      属性类型说明
                      openidstring用户openid
                      delivery_idstring快递公司 ID
                      waybill_idstring运单 ID
                      path_item_numnumber轨迹节点数量
                      path_item_listArray.<Object>轨迹节点列表

                      path_item_list 的结构

                      属性类型说明
                      action_timenumber轨迹节点 Unix 时间戳
                      action_typenumber轨迹节点类型
                      action_msgstring轨迹节点详情

                      action_type 的合法值

                      说明最低版本
                      100001揽件阶段-揽件成功
                      100002揽件阶段-揽件失败
                      100003揽件阶段-分配业务员
                      200001运输阶段-更新运输轨迹
                      300002派送阶段-开始派送
                      300003派送阶段-签收成功
                      300004派送阶段-签收失败
                      400001异常阶段-订单取消
                      400002异常阶段-订单滞留

                      请求数据示例

                      {  "order_id": "01234567890123456789",  "openid": "oABC123456",  "delivery_id": "SF",  "waybill_id": "123456789"}

                      返回数据示例

                      {  "openid": "OPENID",  "delivery_id": "SF",  "waybill_id": "12345678901234567890",  "path_item_num": 3,  "path_item_list": [    {      "action_time": 1533052800,      "action_type": 100001,      "action_msg": "快递员已成功取件"    },    {      "action_time": 1533062800,      "action_type": 200001,      "action_msg": "快件已到达xxx集散中心,准备发往xxx"    },    {      "action_time": 1533072800,      "action_type": 300001,      "action_msg": "快递员已出发,联系电话xxxxxx"    }  ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.getPath
                      需在 config.json 中配置 logistics.getPath API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      orderIdstring订单 ID,需保证全局唯一
                      openidstring用户openid,当add_source=2时无需填写(不发送物流服务通知)
                      deliveryIdstring快递公司ID,参见getAllDelivery
                      waybillIdstring运单ID

                      返回值

                      Object

                      属性类型说明
                      openidstring用户openid
                      deliveryIdstring快递公司 ID
                      waybillIdstring运单 ID
                      pathItemNumnumber轨迹节点数量
                      pathItemListArray.<Object>轨迹节点列表

                      pathItemList 的结构

                      属性类型说明
                      actionTimenumber轨迹节点 Unix 时间戳
                      actionTypenumber轨迹节点类型
                      actionMsgstring轨迹节点详情

                      actionType 的合法值

                      说明最低版本
                      100001揽件阶段-揽件成功
                      100002揽件阶段-揽件失败
                      100003揽件阶段-分配业务员
                      200001运输阶段-更新运输轨迹
                      300002派送阶段-开始派送
                      300003派送阶段-签收成功
                      300004派送阶段-签收失败
                      400001异常阶段-订单取消
                      400002异常阶段-订单滞留

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getPath({        openid: 'oABC123456',        orderId: '01234567890123456789',        deliveryId: 'SF',        waybillId: '123456789'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "openid": "OPENID",  "deliveryId": "SF",  "waybillId": "12345678901234567890",  "pathItemNum": 3,  "pathItemList": [    {      "actionTime": 1533052800,      "actionType": 100001,      "actionMsg": "快递员已成功取件"    },    {      "actionTime": 1533062800,      "actionType": 200001,      "actionMsg": "快件已到达xxx集散中心,准备发往xxx"    },    {      "actionTime": 1533072800,      "actionType": 300001,      "actionMsg": "快递员已出发,联系电话xxxxxx"    }  ],  "errMsg": "openapi.logistics.getPath:ok"}


                      logistics.getPrinter

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取打印员。若需要使用微信打单 PC 软件,才需要调用。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/cgi-bin/express/business/printer/getall?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回值

                      Object

                      返回数据示例

                      { "count": 2, "openid": [   "oABC",   "oXYZ" ], "tagid_list": [   "123",   "456" ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.getPrinter
                      需在 config.json 中配置 logistics.getPrinter API 的权限,详情

                      返回值

                      Object

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getPrinter({})    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "count": 2,  "openid": [    "oABC",    "oXYZ"  ],  "tagidList": [    "123",    "456"  ],  "errMsg": "openapi.logistics.getPrinter:ok"}


                      logistics.getQuota

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取电子面单余额。仅在使用加盟类快递公司时,才可以调用。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/business/quota/get?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      delivery_idstring快递公司ID,参见getAllDelivery
                      biz_idstring快递公司客户编码

                      返回值

                      Object

                      属性类型说明
                      quota_numnumber电子面单余额

                      请求数据示例

                      {  "delivery_id": "YTO",  "biz_id": "xyz"}

                      返回数据示例

                      {  "quota_num": 210}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.getQuota
                      需在 config.json 中配置 logistics.getQuota API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      deliveryIdstring快递公司ID,参见getAllDelivery
                      bizIdstring快递公司客户编码

                      返回值

                      Object

                      属性类型说明
                      quotaNumnumber电子面单余额

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getQuota({        deliveryId: 'YTO',        bizId: 'xyz'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "quotaNum": 210,  "errMsg": "openapi.logistics.getQuota:ok"}


                      logistics.onBindResultUpdate

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      绑定商户审核结果更新事件。收到事件之后,回复success或者空串即可。

                      消息参数

                      OnBindResultUpdateData

                      消息数据包示例

                      XML 格式

                      <xml>  <ToUserName><![CDATA[toUser]]></ToUserName>  <FromUserName><![CDATA[fromUser]]></FromUserName>  <CreateTime>1546924844</CreateTime>  <MsgType><![CDATA[event]]></MsgType>  <Event><![CDATA[update_business_bind_result]]></Event>  <errcode>0</errcode>  <errmsg><![CDATA[ok]]></errmsg>  <delivery_id><![CDATA[EMS]]></delivery_id>  <biz_id><![CDATA[1234567]]></biz_id></xml>

                      JSON 格式

                      {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1546924844,  "MsgType": "event",  "Event": "update_business_bind_result",  "errcode": 0,  "errmsg": "ok",  "delivery_id": "EMS",  "biz_id": "1234567",}


                      logistics.onPathUpdate

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      运单轨迹更新事件。当运单轨迹有更新时,会产生如下数据包。收到事件之后,回复success或者空串即可。

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring小程序的原始ID
                      FromUserNamestring发送者的openid
                      CreateTimenumber消息创建时间(整型)
                      MsgTypestring固定 event
                      Eventstring固定 add_express_path
                      DeliveryIDstring快递公司ID
                      WayBillIdstring运单ID
                      OrderIdstring订单ID
                      Versionnumber轨迹版本号(整型)
                      Countnumber轨迹节点数(整型)
                      ActionsArray.<Object>轨迹列表

                      Actions 的结构

                      属性类型说明
                      ActionTimenumber轨迹节点 Unix 时间戳
                      ActionTypenumber轨迹节点类型
                      ActionMsgstring轨迹节点详情

                      ActionType 的合法值

                      说明最低版本
                      100001揽件阶段-揽件成功
                      100002揽件阶段-揽件失败
                      100003揽件阶段-分配业务员
                      200001运输阶段-更新运输轨迹
                      300002派送阶段-开始派送
                      300003派送阶段-签收成功
                      300004派送阶段-签收失败
                      400001异常阶段-订单取消
                      400002异常阶段-订单滞留

                      消息数据包示例

                      XML 格式

                      <xml>  <ToUserName><![CDATA[toUser]]></ToUserName>  <FromUserName><![CDATA[fromUser]]></FromUserName>  <CreateTime>1546924844</CreateTime>  <MsgType><![CDATA[event]]></MsgType>  <Event><![CDATA[add_express_path]]></Event>  <DeliveryID><![CDATA[SF]]></DeliveryID>  <WayBillId><![CDATA[123456789]]></WayBillId>  <OrderId><![CDATA[123456]]></OrderId>  <Version>3</Version>  <Count>3</Count>  <Actions>    <ActionTime>1546924840</ActionTime>    <ActionType>100001</ActionType>    <ActionMsg><![CDATA[小哥A揽件成功]]></ActionMsg>  </Actions>  <Actions>    <ActionTime>1546924841</ActionTime>    <ActionType>200001</ActionType>    <ActionMsg><![CDATA[到达广州集包地]]></ActionMsg>  </Actions>  <Actions>    <ActionTime>1546924842</ActionTime>    <ActionType>200001</ActionType>    <ActionMsg><![CDATA[运往目的地]]></ActionMsg>  </Actions></xml>

                      JSON 格式

                      {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1546924844,  "MsgType": "event",  "Event": "add_express_path",  "DeliveryID": "SF",  "WayBillId": "123456789",  "OrderId": "123456789",  "Version": 2,  "Count": 3,  "Actions": [    {      "ActionTime": 1546924840,      "ActionType": 100001,      "ActionMsg": "小哥A揽件成功"    },    {      "ActionTime": 1546924841,      "ActionType": 200001,      "ActionMsg": "到达广州集包地"    },    {      "ActionTime": 1546924842,      "ActionType": 200001,      "ActionMsg": "运往目的地"    }  ]}


                      logistics.testUpdateOrder

                      本接口应在服务器端调用,详细说明参见服务端API

                      模拟快递公司更新订单状态, 该接口只能用户测试

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/business/test_update_order?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      biz_idstring商户id,需填test_biz_id
                      order_idstring订单号
                      delivery_idstring快递公司id,需填TEST
                      waybill_idstring运单号
                      action_timenumber轨迹变化 Unix 时间戳
                      action_typenumber轨迹变化类型
                      action_msgstring轨迹变化具体信息说明,使用UTF-8编码

                      action_type 的合法值

                      说明最低版本
                      100001揽件阶段-揽件成功
                      100002揽件阶段-揽件失败
                      100003揽件阶段-分配业务员
                      200001运输阶段-更新运输轨迹
                      300002派送阶段-开始派送
                      300003派送阶段-签收成功
                      300004派送阶段-签收失败
                      400001异常阶段-订单取消
                      400002异常阶段-订单滞留

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0成功
                      -1系统失败

                      请求数据示例

                      {  "biz_id": "test_biz_id",  "order_id": "xxxxxxxxxxxx",  "delivery_id": "TEST",  "waybill_id": "xxxxxxxxxx",  "action_time": 123456789,  "action_type": 100001,  "action_msg": "揽件阶段"}

                      返回数据示例

                      {  "errcode": 0,  "errmsg": "ok"}


                      logistics.updatePrinter

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      配置面单打印员,可以设置多个,若需要使用微信打单 PC 软件,才需要调用。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/business/printer/update?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      openidstring打印员 openid
                      update_typestring更新类型
                      tagid_liststring用于平台型小程序设置入驻方的打印员面单打印权限,同一打印员最多支持10个tagid,使用半角逗号分隔,中间不加空格,如填写123,456,表示该打印员可以拉取到tagid为123和456的下的单,非平台型小程序无需填写该字段

                      update_type 的合法值

                      说明最低版本
                      bind绑定
                      unbind解除绑定

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0成功
                      -1系统失败
                      9300517update_type 不正确

                      请求数据示例

                      {  "openid": "oJ4v0wRAfiXcnIbM3SgGEUkTw3Qw",  "update_type": "bind",  "tagid_list": "123,456"}

                      返回数据示例

                      {  "errcode": 0,  "errmsg": "ok"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.updatePrinter
                      需在 config.json 中配置 logistics.updatePrinter API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      openidstring打印员 openid
                      updateTypestring更新类型
                      tagidListstring用于平台型小程序设置入驻方的打印员面单打印权限,同一打印员最多支持10个tagid,使用半角逗号分隔,中间不加空格,如填写123,456,表示该打印员可以拉取到tagid为123和456的下的单,非平台型小程序无需填写该字段

                      updateType 的合法值

                      说明最低版本
                      bind绑定
                      unbind解除绑定

                      返回值

                      Object

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      -1系统失败
                      9300517update_type 不正确

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.updatePrinter({        openid: 'oJ4v0wRAfiXcnIbM3SgGEUkTw3Qw',        updateType: 'bind',        tagidList: '123,456'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "errCode": 0,  "errMsg": "openapi.logistics.updatePrinter:ok"}


                      logistics.getContact

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取面单联系人信息

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/delivery/contact/get?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      tokenstring商户侧下单事件中推送的 Token 字段
                      waybill_idstring运单 ID

                      返回值

                      Object

                      属性类型说明
                      waybill_idstring运单 ID
                      senderArray.<Object>发件人信息
                      receiverArray.<Object>收件人信息
                      errcodenumber错误码
                      errmsgstring错误信息

                      sender 的结构

                      属性类型说明
                      addressstring地址,已经将省市区信息合并
                      namestring用户姓名
                      telstring座机号码
                      mobilestring手机号码

                      receiver 的结构

                      属性类型说明
                      addressstring地址,已经将省市区信息合并
                      namestring用户姓名
                      telstring座机号码
                      mobilestring手机号码

                      errcode 的合法值

                      说明最低版本
                      0成功
                      -1其他错误
                      40199运单 ID 错误,未查到运单
                      9300507Token 不正确

                      请求数据示例

                      {  "token": "TOKEN",  "waybill_id": "12345678901234567890"}

                      返回数据示例

                      {  "waybill_id": "12345678901234567890",  "sender": {    "address": "广东省广州市海珠区XX路XX号XX大厦XX栋XX",    "name": "张三",    "tel": "020-88888888",    "mobile": "18666666666"  },  "receiver": {    "address": "广东省广州市天河区XX路XX号XX大厦XX栋XX",    "name": "王小蒙",    "tel": "029-77777777",    "mobile": "18610000000"  }}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.getContact
                      需在 config.json 中配置 logistics.getContact API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      tokenstring商户侧下单事件中推送的 Token 字段
                      waybillIdstring运单 ID

                      返回值

                      Object

                      属性类型说明
                      waybillIdstring运单 ID
                      senderArray.<Object>发件人信息
                      receiverArray.<Object>收件人信息
                      errCodenumber错误码
                      errMsgstring错误信息

                      sender 的结构

                      属性类型说明
                      addressstring地址,已经将省市区信息合并
                      namestring用户姓名
                      telstring座机号码
                      mobilestring手机号码

                      receiver 的结构

                      属性类型说明
                      addressstring地址,已经将省市区信息合并
                      namestring用户姓名
                      telstring座机号码
                      mobilestring手机号码

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      -1其他错误
                      40199运单 ID 错误,未查到运单
                      9300507Token 不正确

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.getContact({        token: 'TOKEN',        waybillId: '12345678901234567890'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "waybillId": "12345678901234567890",  "sender": {    "address": "广东省广州市海珠区XX路XX号XX大厦XX栋XX",    "name": "张三",    "tel": "020-88888888",    "mobile": "18666666666"  },  "receiver": {    "address": "广东省广州市天河区XX路XX号XX大厦XX栋XX",    "name": "王小蒙",    "tel": "029-77777777",    "mobile": "18610000000"  },  "errMsg": "openapi.logistics.getContact:ok"}


                      logistics.onAddOrder

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      请求下单事件。

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 add_waybill,不区分大小写
                      Tokenstring订单 Token。请保存该 Token,调用logistics.updatePath时需要传入
                      OrderIDstring唯一标识订单的 ID,由商户生成。快递需要保证相同的 OrderID 生成相同的运单ID。
                      BizIDstring商户 ID,即商户在快递注册的客户编码或月结账户名
                      BizPwdstringBizID 对应的密码
                      ShopAppIDstring商户的小程序 AppID
                      WayBillIDstring运单 ID,从微信号段中生成。若为 0,则表示需要快递来生成运单 ID。
                      Remarkstring快递备注,会打印到面单上,比如"易碎物品"
                      SenderArray.<Object>发件人信息
                      ReceiverArray.<Object>收件人信息
                      CargoArray.<Object>包裹信息
                      InsuredArray.<Object>保价信息
                      ServiceArray.<Object>服务类型

                      Sender 的结构

                      属性类型说明
                      Namestring发件人姓名
                      Telstring发件人座机号码
                      Mobilestring发件人手机号码
                      Companystring发件人公司名
                      PostCodestring发件人邮编
                      Countrystring发件人所在国家,默认为"中国"
                      Provincestring发件人省份,比如"广东省"
                      Citystring发件人地区/市,比如"广州市"
                      Areastring发件人区/县,比如"海珠区"
                      Addressstring发件人详细地址,比如"XX路XX号XX大厦XX"

                      Receiver 的结构

                      属性类型说明
                      Namestring收件人姓名
                      Telstring收件人座机号码
                      Mobilestring收件人手机号码
                      Companystring收件人公司名
                      PostCodestring收件人邮编
                      Countrystring收件人所在国家,默认为"中国"
                      Provincestring收件人省份,比如"广东省"
                      Citystring收件人地区/市,比如"广州市"
                      Areastring收件人区/县,比如"海珠区"
                      Addressstring收件人详细地址,比如"XX路XX号XX大厦XX"

                      Cargo 的结构

                      属性类型说明
                      Weightnumber货物总重量,比如1.2,单位是千克(kg)
                      Space_Xnumber货物长度,比如20.5,单位是厘米(cm)
                      Space_Ynumber货物宽度,比如15.0,单位是厘米(cm)
                      Space_Znumber货物高度,比如10.0,单位是厘米(cm)
                      Countnumber货物数量,一般为1

                      Insured 的结构

                      属性类型说明
                      UseInsurednumber是否保价,0 表示不保价,1 表示保价
                      InsuredValuenumber保价金额,单位是分,比如: 10000 表示 100 元

                      Service 的结构

                      属性类型说明
                      ServiceTypenumber服务类型ID,详见已经支持的快递公司基本信息
                      ServiceNamestring服务名称,详见已经支持的快递公司基本信息

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix 时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 add_waybill
                      Tokenstring传入的 Token,原样返回
                      OrderIDstring传入的唯一标识订单的 ID,由商户生成,原样返回
                      BizIDstring商户 ID,原样返回
                      WayBillIDstring运单 ID
                      ResultCodenumber处理结果错误码
                      ResultMsgstring处理结果的详细信息
                      WaybillDatastring集包地、三段码、大头笔等信息,用于生成面单信息。详见后文返回值说明

                      ResultCode 的合法值

                      说明最低版本
                      0下单成功
                      -1其他错误
                      10001客户编码或者月结账户不存在
                      10002客户密码不正确
                      20001运单 ID 不正确(仅适用于微信生成运单 ID 的情况)
                      20002发件人信息不完整(包括姓名、电话、地址等不完整)
                      20003发件人地址不可达或者发货地址不在服务范围
                      20004收件人信息不完整(包括姓名、电话、地址等不完整)
                      20005收件人地址不可达或者收货地址不在服务范围
                      20006货物数量、重量、尺寸不正确或者不合理
                      20007商户余额不足,需要充值后再进行下单
                      20008保价信息不正确(金额不合理或者快递不支持)
                      20009服务信息不正确

                      消息参数说明

                      • 各字段均为商家提供,不保证完整,不保证正确,需要快递侧做好参数合法性和正确性检查。
                      • 当网络环境不稳定时,下单事件可能会重复推送。对于相同的 BizID+OrderID,要返回相同的运单 ID。
                      • 不支持子母单、代收货款。

                      返回值说明

                      WaybillData 字段用于生成面单,结构为##(key##value##)*。key可以写到面单模板中,value是实际值。

                      比如样例##ZTO_bagAddr##广州##ZTO_mark##888-666-666##中,"ZTO_markAddr"表示中通的集包地代号,"广州"是实际的集包地值;"ZTO_mark"表示中通三段码代号,"888-666-666"是实际的三段码值。

                      消息数据包示例

                      XML 格式

                      <xml>  <ToUserName><![CDATA[gh_abcdefg]]></ToUserName>  <FromUserName><![CDATA[oABCD]]></FromUserName>  <CreateTime>1533042556</CreateTime>  <MsgType><![CDATA[event]]></MsgType>  <Event><![CDATA[add_waybill]]></Event>  <Token>1234ABC234523451</Token>  <OrderID><![CDATA[012345678901234567890123456789]]></OrderID>  <BizID><![CDATA[xyz]]></BizID>  <BizPwd><![CDATA[xyz123]]></BizPwd>  <ShopAppID><![CDATA[wxABCD]]></ShopAppID>  <WayBillID><![CDATA[123456789]]></WayBillID>  <Remark><![CDATA[易碎物品]]></Remark>  <Sender>      <Name><![CDATA[张三]]></Name>      <Tel><![CDATA[020-88888888]]></Tel>      <Mobile><![CDATA[18666666666]]></Mobile>      <Company><![CDATA[公司名]]></Company>      <PostCode><![CDATA[123456]]></PostCode>      <Country><![CDATA[中国]]></Country>      <Province><![CDATA[广东省]]></Province>      <City><![CDATA[广州市]]></City>      <Area><![CDATA[海珠区]]></Area>      <Address><![CDATA[XX路XX号XX大厦XX栋XX]]></Address>  </Sender>  <Receiver>      <Name><![CDATA[王小蒙]]></Name>      <Tel><![CDATA[029-77777777]]></Tel>      <Mobile><![CDATA[18610000000]]></Mobile>      <Company><![CDATA[公司名]]></Company>      <PostCode><![CDATA[654321]]></PostCode>      <Country><![CDATA[中国]]></Country>      <Province><![CDATA[广东省]]></Province>      <City><![CDATA[广州市]]></City>      <Area><![CDATA[天河区]]></Area>      <Address><![CDATA[XX路XX号XX大厦XX栋XX]]></Address>  </Receiver>  <Cargo>      <Weight>1.2</Weight>      <Space_X>20.5</Space_X>      <Space_Y>15.0</Space_Y>      <Space_Z>10.0</Space_Z>      <Count>2</Count>      <DetailList>          <Name><![CDATA[一千零一夜钻石包]]></Name>          <Count>1</Count>      </DetailList>      <DetailList>          <Name><![CDATA[爱马仕柏金钻石包]]></Name>          <Count>1</Count>      </DetailList>  </Cargo>  <Insured>      <UseInsured>1</UseInsured>      <InsuredValue>10000</InsuredValue>  </Insured>  <Service>      <ServiceType>0</ServiceType>      <ServiceName><![CDATA[标准快递]]></ServiceName>  </Service></xml>

                      JSON 格式

                      {  "ToUserName": "gh_abcdefg",  "FromUserName": "oABCD",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "add_waybill",  "Token": "1234ABC234523451",  "OrderID": "012345678901234567890123456789",  "BizID": "xyz",  "BizPwd": "xyz123",  "ShopAppID": "wxABCD",  "WayBillID": "123456789",  "Remark": "易碎物品",  "Sender": {    "Name": "张三",    "Tel": "020-88888888",    "Mobile": "18666666666",    "Company": "公司名",    "PostCode": "123456",    "Country": "中国",    "Province": "广东省",    "City": "广州市",    "Area": "海珠区",    "Address": "XX路XX号XX大厦XX栋XX"  },  "Receiver": {    "Name": "王小蒙",    "Tel": "029-77777777",    "Mobile": "18610000000",    "Company": "公司名",    "PostCode": "654321",    "Country": "中国",    "Province": "广东省",    "City": "广州市",    "Area": "天河区",    "Address": "XX路XX号XX大厦XX栋XX"  },  "Cargo": {    "Weight": 1.2,    "Space_X": 20.5,    "Space_Y": 15,    "Space_Z": 10,    "Count": 2,    "DetailList": [      {        "Name": "一千零一夜钻石包",        "Count": 1      },      {        "Name": "爱马仕柏金钻石包",        "Count": 1      }    ]  },  "Insured": {    "UseInsured": 1,    "InsuredValue": 10000  },  "Service": {    "ServiceType": 0,    "ServiceName": "标准快递"  }}

                      返回数据包示例

                      XML 格式

                      <xml>    <ToUserName><![CDATA[oABCD]]></ToUserName>    <FromUserName><![CDATA[gh_abcdefg]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[add_waybill]]></Event>    <Token>1234ABC234523451</Token>    <OrderID><![CDATA[012345678901234567890123456789]]></OrderID>    <BizID><![CDATA[xyz]]></BizID>    <WayBillID><![CDATA[123456789]]></WayBillID>    <ResultCode>0</ResultCode>    <ResultMsg><![CDATA[success]]></ResultMsg>    <WaybillData><![CDATA[##ZTO_bagAddr##广州##ZTO_mark##888-666-666##]]></WaybillData></xml>

                      JSON 格式

                      {  "ToUserName": "oABCD",  "FromUserName": "gh_abcdefg",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "add_waybill",  "Token": "1234ABC234523451",  "OrderID": "012345678901234567890123456789",  "BizID": "xyz",  "WayBillID": "123456789",  "ResultCode": 0,  "ResultMsg": "success",  "WaybillData": "##ZTO_bagAddr##广州##ZTO_mark##888-666-666##"}


                      logistics.onCancelOrder

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      取消订单事件。

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring下单用户的 OpenID
                      CreateTimenumber事件时间,Unix 时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 cancel_waybill
                      OrderIDstring唯一标识订单的 ID,由商户生成
                      BizIDstring商户 ID
                      BizPwdstring商户密码
                      ShopAppIDstring商户的小程序 AppID
                      WayBillIDstring运单 ID,从微信号段中生成

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix 时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 cancel_waybill,不区分大小写
                      BizIDstring商户ID,请原样返回
                      OrderIDstring唯一标识订单的ID,由商户生成。请原样返回
                      WayBillIDstring运单ID,请原样返回
                      ResultCodenumber处理结果错误码
                      ResultMsgstring处理结果详情

                      ResultCode 的合法值

                      说明最低版本
                      0取消成功
                      -1其他错误
                      30001参数错误(BizID、OrderID、WayBillID不存在)
                      30002已经揽收,不可取消
                      30003无效单(如已经取消过、或签收超过一定时间),不可取消
                      30004快递不支持取消运单

                      消息数据包示例

                      XML 格式

                      <xml>    <ToUserName><![CDATA[gh_abcdefg]]></ToUserName>    <FromUserName><![CDATA[oABCD]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[cancel_waybill]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <BizPwd><![CDATA[xyz123]]></BizPwd>    <ShopAppID><![CDATA[wxABCD]]></ShopAppID>    <OrderID><![CDATA[012345678901234567890123456789]]></OrderID>    <WayBillID><![CDATA[123456789]]></WayBillID></xml>

                      JSON 格式

                      {  "ToUserName": "gh_abcdefg",  "FromUserName": "oABCD",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "cancel_waybill",  "BizID": "xyz",  "BizPwd": "xyz123",  "ShopAppID": "wxABCD",  "OrderID": "012345678901234567890123456789",  "WayBillID": "123456789"}

                      返回数据包示例

                      XML 格式

                      <xml>    <ToUserName><![CDATA[oABCD]]></ToUserName>    <FromUserName><![CDATA[gh_abcdefg]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[cancel_waybill]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <OrderID><![CDATA[012345678901234567890123456789]]></OrderID>    <WayBillID><![CDATA[123456789]]></WayBillID>    <ResultCode>0</ResultCode>    <ResultMsg><![CDATA[success]]></ResultMsg></xml>

                      JSON 格式

                      {  "ToUserName": "oABCD",  "FromUserName": "gh_abcdefg",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "cancel_waybill",  "BizID": "xyz",  "OrderID": "012345678901234567890123456789",  "WayBillID": "123456789",  "ResultCode": 0,  "ResultMsg": "success"}


                      logistics.onCheckBusiness

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      审核商户事件。

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix 时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 check_biz,不区分大小写
                      BizIDstring商户ID,即商户在快递注册的客户编码或月结账户名
                      BizPwdstringBizID 对应的密码
                      ShopAppIDstring商户的小程序 AppID
                      ShopNamestring商户名称,即小程序昵称(仅EMS可用)
                      ShopTelphonestring商户联系电话(仅EMS可用)
                      ShopContactstring商户联系人姓名(仅EMS可用)
                      ServiceNamestring预开通的服务类型名称(仅EMS可用)
                      SenderAddressstring商户发货地址(仅EMS可用)
                      SenderProvincestring商户发货省份(仅EMS可用)
                      SenderCitystring商户发货城市(仅EMS可用)
                      SenderAreastring商户发货区域(仅EMS可用)

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为event
                      Eventstring事件类型,固定为check_biz,不区分大小写
                      BizIDstring商户ID
                      ResultCodenumber处理结果错误码
                      ResultMsgstring处理结果详情
                      Quotanumber商户可用余额,0 表示无可用余额

                      ResultCode 的合法值

                      说明最低版本
                      0审核通过
                      -1其他错误
                      10001客户编码或者月结账户不存在
                      10002客户密码不正确

                      消息数据包示例

                      XML 格式

                      <xml>    <ToUserName><![CDATA[gh_abcdefg]]></ToUserName>    <FromUserName><![CDATA[oABCD]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[check_biz]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <BizPwd><![CDATA[xyz123]]></BizPwd>    <ShopAppID><![CDATA[wxABCD]]></ShopAppID>    <ShopName><![CDATA[商户名称]]></ShopName>    <ShopTelphone><![CDATA[18677778888]]></ShopTelphone>    <ShopContact><![CDATA[村正]]></ShopContact>    <ServiceName><![CDATA[标准快递]]></ServiceName>    <SenderProvince><![CDATA[广东省]]></SenderProvince>    <SenderCity><![CDATA[广州市]]></SenderCity>    <SenderArea><![CDATA[海珠区]]></SenderArea>    <SenderAddress><![CDATA[新港中路397号]]></SenderAddress></xml>

                      JSON 格式

                      {  "ToUserName": "gh_abcdefg",  "FromUserName": "oABCD",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "check_biz",  "BizID": "xyz",  "BizPwd": "xyz123",  "ShopAppID": "wxABCD",  "ShopName": "商户名称",  "ShopTelphone": "18677778888",  "ShopContact": "村正",  "ServiceName": "标准快递",  "SenderProvince": "广东省"  "SenderCity": "广州市"  "SenderArea": "海珠区"  "SenderAddress": "新港中路397号"}

                      返回数据包示例

                      XML 格式

                      <xml>    <ToUserName><![CDATA[oABCD]]></ToUserName>    <FromUserName><![CDATA[gh_abcdefg]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[check_biz]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <ResultCode>0</ResultCode>    <ResultMsg><![CDATA[success]]></ResultMsg></xml>

                      JSON 格式

                      {  "ToUserName": "oABCD",  "FromUserName": "gh_abcdefg",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "check_biz",  "BizID": "xyz",  "ResultCode": 0,  "ResultMsg": "success"}


                      logistics.onGetQuota

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      查询商户余额事件。

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 get_quota,不区分大小写
                      BizIDstring商户ID,即商户在快递注册的客户编码或月结账户名
                      BizPwdstringBizID 对应的密码
                      ShopAppIDstring商户小程序的 AppID

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为event
                      Eventstring事件类型,固定为get_quota,不区分大小写
                      BizIDstring商户ID
                      ResultCodenumber处理结果错误码
                      ResultMsgstring处理结果详情
                      Quotanumber商户可用余额,0 表示无可用余额

                      ResultCode 的合法值

                      说明最低版本
                      0查询成功
                      -1其他错误
                      10001客户编码或者月结账户不存在
                      10002客户密码不正确

                      消息数据包示例

                      XML 格式

                      <xml>    <ToUserName><![CDATA[gh_abcdefg]]></ToUserName>    <FromUserName><![CDATA[oABCD]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[get_quota]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <BizPwd><![CDATA[xyz123]]></BizPwd>    <ShopAppID><![CDATA[wxABCD]]></ShopAppID></xml>

                      JSON 格式

                      {  "ToUserName": "gh_abcdefg",  "FromUserName": "oABCD",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "get_quota",  "BizID": "xyz",  "BizPwd": "xyz123",  "ShopAppID": "wxABCD"}

                      返回数据包示例

                      XML 格式

                      <xml>    <ToUserName><![CDATA[oABCD]]></ToUserName>    <FromUserName><![CDATA[gh_abcdefg]]></FromUserName>    <CreateTime>1533042556</CreateTime>    <MsgType><![CDATA[event]]></MsgType>    <Event><![CDATA[get_quota]]></Event>    <BizID><![CDATA[xyz]]></BizID>    <ResultCode>0</ResultCode>    <ResultMsg><![CDATA[success]]></ResultMsg>    <Quota>0</Quota></xml>

                      JSON 格式

                      {  "ToUserName": "oABCD",  "FromUserName": "gh_abcdefg",  "CreateTime": 1533042556,  "MsgType": "event",  "Event": "get_quota",  "BizID": "xyz",  "ResultCode": 0,  "ResultMsg": "success",  "Quota": 0}


                      logistics.previewTemplate

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      预览面单模板。用于调试面单模板使用。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/delivery/template/preview?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      waybill_idstring运单 ID
                      waybill_templatestring面单 HTML 模板内容(需经 Base64 编码)
                      waybill_datastring面单数据。详情参考下单事件返回值中的 WaybillData
                      customObject商户下单数据,格式是商户侧下单 API 中的请求体

                      返回值

                      Object

                      属性类型说明
                      waybill_idstring运单 ID
                      rendered_waybill_templatestring渲染后的面单 HTML 文件(已经过 Base64 编码)
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0成功
                      -1其他错误
                      40199运单 ID 错误,未查到运单
                      9300507Token 不正确
                      9300502预览模板中出现该错误,一般是waybill_data数据错误
                      9300512模板格式错误,渲染失败

                      请求数据示例

                      {  "waybill_id": "1234567890123",  "waybill_data": "##ZTO_mark##11-22-33##ZTO_bagAddr##广州##",  "waybill_template": "PGh0bWw+dGVzdDwvaHRtbD4=",  "custom": {    "order_id": "012345678901234567890123456789",    "openid": "oABC123456",    "delivery_id": "ZTO",    "biz_id": "xyz",    "custom_remark": "易碎物品",    "sender": {      "name": "张三",      "tel": "18666666666",      "mobile": "020-88888888",      "company": "公司名",      "post_code": "123456",      "country": "中国",      "province": "广东省",      "city": "广州市",      "area": "海珠区",      "address": "XX路XX号XX大厦XX栋XX"    },    "receiver": {      "name": "王小蒙",      "tel": "18610000000",      "mobile": "020-77777777",      "company": "公司名",      "post_code": "654321",      "country": "中国",      "province": "广东省",      "city": "广州市",      "area": "天河区",      "address": "XX路XX号XX大厦XX栋XX"    },    "shop": {      "wxa_path": "/index/index?from=waybill",      "img_url": "https://mmbiz.qpic.cn/mmbiz_png/KfrZwACMrmwbPGicysN6kibW0ibXwzmA3mtTwgSsdw4Uicabduu2pfbfwdKicQ8n0v91kRAUX6SDESQypl5tlRwHUPA/640",      "goods_name": "一千零一夜钻石包&爱马仕柏金钻石包",      "goods_count": 2    },    "cargo": {      "count": 2,      "weight": 5.5,      "space_x": 30.5,      "space_y": 20,      "space_z": 20,      "detail_list": [        {          "name": "一千零一夜钻石包",          "count": 1        },        {          "name": "爱马仕柏金钻石包",          "count": 1        }      ]    },    "insured": {      "use_insured": 1,      "insured_value": 10000    },    "service": {      "service_type": 0,      "service_name": "标准快递"    }  }}

                      返回数据示例

                      {  "waybill_id": "1234567890123",  "rendered_waybill_template": "PGh0bWw+dGVzdDwvaHRtbD4="}

                      模板渲染语法

                      1. 所有渲染语法由##开始,可参考示例。
                      2. ##VAR(key) 用参数key对应的值填充。支持的参数如下表格所示
                      keyvalue
                      sys.waybillid运单 ID
                      sys.wxaappid商户小程序 APPID
                      waybilldata.*下单事件返回中的WaybillData,快递侧自定义的数据
                      custom.*是商户侧下单 API 中传入的字段
                      custom.order_id唯一标识订单的 ID,由商户传入
                      custom.custom_remark快递备注,会打印到面单的自定义区,比如"易碎物品"
                      custom.sender.name发件人名字
                      custom.sender.tel发件人座机号码
                      custom.sender.mobile发件人手机号码
                      custom.sender.company发件人公司名
                      custom.sender.post_code发件人邮编
                      custom.sender.country发件人所在国家
                      custom.sender.province发件人省份
                      custom.sender.city发件人地区/市
                      custom.sender.area发件人区/县
                      custom.sender.address发件人详细地址
                      custom.receiver.name收件人名字
                      custom.receiver.tel收件人座机号码
                      custom.receiver.mobile收件人手机号码
                      custom.receiver.company收件人公司名
                      custom.receiver.post_code收件人邮编
                      custom.receiver.country收件人所在国家
                      custom.receiver.province收件人省份
                      custom.receiver.city收件人地区/市
                      custom.receiver.area收件人区/县
                      custom.receiver.address收件人详细地址
                      custom.cargo.count包裹数量
                      custom.cargo.weight包裹总重量,单位是千克(kg)
                      custom.cargo.space_x包裹长度,单位是厘米(cm)
                      custom.cargo.space_y包裹宽度,单位是厘米(cm)
                      custom.cargo.space_z包裹高度,单位是厘米(cm)
                      custom.shop.goods_name商品名称
                      custom.shop.goods_count商品数量
                      custom.insured.use_insured是否使用保价
                      custom.insured.insured_value报价金额,单位是分
                      custom.service.service_type服务类型 ID
                      custom.service.service_name服务名称
                      1. ##TIME(DATE) 用日期填充当前位置,格式为%Y/%m/%d,比如2018/11/22。
                      2. ##TIME(TIME) 用时间填充当前位置,格式为%H:%M:%S,比如17:54:06。
                      3. ##TIME(FULL) 用日期时间填充当前位置,格式为%Y/%m/%d %H:%M:%S,比如2018/11/22 17:54:06。
                      4. ##STRBLOAT(VAR(sys.waybillid)) 获取运单 ID,然后在每个字符间填充空格。
                      5. ##CODE128(VAR(sys.waybillid)) 获取运单 ID,然后转换成CODE128条码,图片为base64编码。
                      6. ##QRCODE(VAR(sys.waybillid)) 获取运单 ID,然后转换为二维码,图片为base64编码。
                      7. ##WXASUNCODE(VAR(sys.wxaappid)) 获取商户的小程序码,图片为base64编码。
                      举例,如果想在面单上打印一个集包地信息的条形码,可以在面单中增加:
                      <img src="data:image/jpeg;base64, ##CODE128(VAR(waybilldata.ZTO_bagAddr))" class="block_5__barCode">

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.previewTemplate
                      需在 config.json 中配置 logistics.previewTemplate API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      waybillIdstring运单 ID
                      waybillTemplatestring面单 HTML 模板内容(需经 Base64 编码)
                      waybillDatastring面单数据。详情参考下单事件返回值中的 WaybillData
                      customObject商户下单数据,格式是商户侧下单 API 中的请求体

                      返回值

                      Object

                      属性类型说明
                      waybillIdstring运单 ID
                      renderedWaybillTemplatestring渲染后的面单 HTML 文件(已经过 Base64 编码)
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      -1其他错误
                      40199运单 ID 错误,未查到运单
                      9300507Token 不正确
                      9300502预览模板中出现该错误,一般是waybill_data数据错误
                      9300512模板格式错误,渲染失败

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.previewTemplate({        custom: {          openid: 'oABC123456',          sender: {            name: '张三',            tel: '18666666666',            mobile: '020-88888888',            company: '公司名',            country: '中国',            province: '广东省',            city: '广州市',            area: '海珠区',            address: 'XX路XX号XX大厦XX栋XX',            postCode: '123456'          },          receiver: {            name: '王小蒙',            tel: '18610000000',            mobile: '020-77777777',            company: '公司名',            country: '中国',            province: '广东省',            city: '广州市',            area: '天河区',            address: 'XX路XX号XX大厦XX栋XX',            postCode: '654321'          },          shop: {            wxaPath: '/index/index?from=waybill',            imgUrl: 'https://mmbiz.qpic.cn/mmbiz_png/KfrZwACMrmwbPGicysN6kibW0ibXwzmA3mtTwgSsdw4Uicabduu2pfbfwdKicQ8n0v91kRAUX6SDESQypl5tlRwHUPA/640',            goodsName: '一千零一夜钻石包&爱马仕柏金钻石包',            goodsCount: 2          },          cargo: {            count: 2,            weight: 5.5,            spaceX: 30.5,            spaceY: 20,            spaceZ: 20,            detailList: [              {                name: '一千零一夜钻石包',                count: 1              },              {                name: '爱马仕柏金钻石包',                count: 1              }            ]          },          insured: {            useInsured: 1,            insuredValue: 10000          },          service: {            serviceType: 0,            serviceName: '标准快递'          },          orderId: '012345678901234567890123456789',          deliveryId: 'ZTO',          bizId: 'xyz',          customRemark: '易碎物品'        },        waybillId: '1234567890123',        waybillData: '##ZTO_mark##11-22-33##ZTO_bagAddr##广州##',        waybillTemplate: 'PGh0bWw+dGVzdDwvaHRtbD4='      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "waybillId": "1234567890123",  "renderedWaybillTemplate": "PGh0bWw+dGVzdDwvaHRtbD4=",  "errMsg": "openapi.logistics.previewTemplate:ok"}


                      logistics.updateBusiness

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      更新商户审核结果

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/delivery/service/business/update?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      shop_app_idstring商户的小程序AppID,即审核商户事件中的 ShopAppID
                      biz_idstring商户账户
                      result_codenumber审核结果,0 表示审核通过,其他表示审核失败
                      result_msgstring审核错误原因,仅 result_code 不等于 0 时需要设置

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0成功
                      -1其他错误
                      40013非法的商户小程序 AppID
                      9300525商户未申请过审核

                      请求数据示例

                      {  "shop_app_id": "wxABCD",  "biz_id": "xyz",  "result_code": 0,  "result_msg": "审核通过"}

                      返回数据示例

                      {  "errcode": 0,  "errmsg": "ok"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.updateBusiness
                      需在 config.json 中配置 logistics.updateBusiness API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      shopAppIdstring商户的小程序AppID,即审核商户事件中的 ShopAppID
                      bizIdstring商户账户
                      resultCodenumber审核结果,0 表示审核通过,其他表示审核失败
                      resultMsgstring审核错误原因,仅 result_code 不等于 0 时需要设置

                      返回值

                      Object

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      -1其他错误
                      40013非法的商户小程序 AppID
                      9300525商户未申请过审核

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.updateBusiness({        shopAppId: 'wxABCD',        bizId: 'xyz',        resultCode: 0,        resultMsg: '审核通过'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "errCode": 0,  "errMsg": "openapi.logistics.updateBusiness:ok"}


                      logistics.updatePath

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      更新运单轨迹

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/delivery/path/update?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      tokenstring商户侧下单事件中推送的 Token 字段
                      waybill_idstring运单 ID
                      action_timenumber轨迹变化 Unix 时间戳
                      action_typenumber轨迹变化类型
                      action_msgstring轨迹变化具体信息说明,展示在快递轨迹详情页中。若有手机号码,则直接写11位手机号码。使用UTF-8编码。

                      action_type 的合法值

                      说明最低版本
                      100001揽件阶段-揽件成功
                      100002揽件阶段-揽件失败
                      100003揽件阶段-分配业务员
                      200001运输阶段-更新运输轨迹
                      300002派送阶段-开始派送
                      300003派送阶段-签收成功
                      300004派送阶段-签收失败
                      400001异常阶段-订单取消
                      400002异常阶段-订单滞留

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0成功
                      -1系统失败
                      40199运单 ID 错误,未查到运单
                      9300507Token 不正确

                      请求数据示例

                      {  "token": "TOKEN",  "waybill_id": "12345678901234567890",  "action_time": 1533052800,  "action_type": 300002,  "action_msg": "丽影邓丽君【18666666666】正在派件"}

                      返回数据示例

                      {  "errcode": 0,  "errmsg": "ok"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.logistics.updatePath
                      需在 config.json 中配置 logistics.updatePath API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      tokenstring商户侧下单事件中推送的 Token 字段
                      waybillIdstring运单 ID
                      actionTimenumber轨迹变化 Unix 时间戳
                      actionTypenumber轨迹变化类型
                      actionMsgstring轨迹变化具体信息说明,展示在快递轨迹详情页中。若有手机号码,则直接写11位手机号码。使用UTF-8编码。

                      actionType 的合法值

                      说明最低版本
                      100001揽件阶段-揽件成功
                      100002揽件阶段-揽件失败
                      100003揽件阶段-分配业务员
                      200001运输阶段-更新运输轨迹
                      300002派送阶段-开始派送
                      300003派送阶段-签收成功
                      300004派送阶段-签收失败
                      400001异常阶段-订单取消
                      400002异常阶段-订单滞留

                      返回值

                      Object

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      -1系统失败
                      40199运单 ID 错误,未查到运单
                      9300507Token 不正确

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.logistics.updatePath({        token: 'TOKEN',        waybillId: '12345678901234567890',        actionTime: 1533052800,        actionType: 300002,        actionMsg: '丽影邓丽君【18666666666】正在派件'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "errCode": 0,  "errMsg": "openapi.logistics.updatePath:ok"}


                      ad.getUserActionSets

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      广告数据源查询

                      说明

                      微信广告文档:https://ad.weixin.qq.com/guide/457

                      对应接口 https://api.weixin.qq.com/marketing/user_action_sets/get

                      云调用使用说明

                      外链文档中可能只有 HTTP 形式的定义,对云调用方式,调用时参数与 HTTP 需求的参数一致,但是无需传入 access_token,同时所有的参数无论 get/post 都只需作为接口参数 JS 对象中的一个字段传入即可。

                      而对于 FormData 的请求,如果一个参数的类型是 Buffer,则其字段应传入有如下字段的对象:

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      示例

                      假设外链文档要求是 POST 方法,要求传入如下参数

                      属性类型位置说明
                      xxxstringURL 参数...
                      yyynumberJSON body...

                      则调用示例如下:

                      cloud.openapi.ad.getUserActionSets({  xxx: '字符串',  yyy: 100,})

                      假设外链文档要求是 POST FormData,要求传入如下参数

                      属性类型位置说明
                      xxxstringURL 参数...
                      mediabufferFormData图片 buffer

                      则调用示例如下:

                      cloud.openapi.ad.getUserActionSets({  xxx: '字符串',  media: {    contentType: 'image/png',    value: Buffer  },})


                      ad.addUserActionSet

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      广告创建数据源

                      说明

                      微信广告文档:https://ad.weixin.qq.com/guide/457

                      对应接口 https://api.weixin.qq.com/marketing/user_action_sets/add

                      云调用使用说明

                      外链文档中可能只有 HTTP 形式的定义,对云调用方式,调用时参数与 HTTP 需求的参数一致,但是无需传入 access_token,同时所有的参数无论 get/post 都只需作为接口参数 JS 对象中的一个字段传入即可。

                      而对于 FormData 的请求,如果一个参数的类型是 Buffer,则其字段应传入有如下字段的对象:

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      示例

                      假设外链文档要求是 POST 方法,要求传入如下参数

                      属性类型位置说明
                      xxxstringURL 参数...
                      yyynumberJSON body...

                      则调用示例如下:

                      cloud.openapi.ad.addUserActionSet({  xxx: '字符串',  yyy: 100,})

                      假设外链文档要求是 POST FormData,要求传入如下参数

                      属性类型位置说明
                      xxxstringURL 参数...
                      mediabufferFormData图片 buffer

                      则调用示例如下:

                      cloud.openapi.ad.addUserActionSet({  xxx: '字符串',  media: {    contentType: 'image/png',    value: Buffer  },})


                      ad.addUserAction

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      回传广告数据

                      说明

                      微信广告文档:https://ad.weixin.qq.com/guide/457

                      对应接口 https://api.weixin.qq.com/marketing/user_actions/add

                      云调用使用说明

                      外链文档中可能只有 HTTP 形式的定义,对云调用方式,调用时参数与 HTTP 需求的参数一致,但是无需传入 access_token,同时所有的参数无论 get/post 都只需作为接口参数 JS 对象中的一个字段传入即可。

                      而对于 FormData 的请求,如果一个参数的类型是 Buffer,则其字段应传入有如下字段的对象:

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      示例

                      假设外链文档要求是 POST 方法,要求传入如下参数

                      属性类型位置说明
                      xxxstringURL 参数...
                      yyynumberJSON body...

                      则调用示例如下:

                      cloud.openapi.ad.addUserAction({  xxx: '字符串',  yyy: 100,})

                      假设外链文档要求是 POST FormData,要求传入如下参数

                      属性类型位置说明
                      xxxstringURL 参数...
                      mediabufferFormData图片 buffer

                      则调用示例如下:

                      cloud.openapi.ad.addUserAction({  xxx: '字符串',  media: {    contentType: 'image/png',    value: Buffer  },})


                      ad.getUserActionSetReports

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      广告数据源报表查询

                      说明

                      微信广告文档:https://ad.weixin.qq.com/guide/457

                      对应接口 https://api.weixin.qq.com/marketing/user_action_set_reports/get

                      云调用使用说明

                      外链文档中可能只有 HTTP 形式的定义,对云调用方式,调用时参数与 HTTP 需求的参数一致,但是无需传入 access_token,同时所有的参数无论 get/post 都只需作为接口参数 JS 对象中的一个字段传入即可。

                      而对于 FormData 的请求,如果一个参数的类型是 Buffer,则其字段应传入有如下字段的对象:

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      示例

                      假设外链文档要求是 POST 方法,要求传入如下参数

                      属性类型位置说明
                      xxxstringURL 参数...
                      yyynumberJSON body...

                      则调用示例如下:

                      cloud.openapi.ad.getUserActionSetReports({  xxx: '字符串',  yyy: 100,})

                      假设外链文档要求是 POST FormData,要求传入如下参数

                      属性类型位置说明
                      xxxstringURL 参数...
                      mediabufferFormData图片 buffer

                      则调用示例如下:

                      cloud.openapi.ad.getUserActionSetReports({  xxx: '字符串',  media: {    contentType: 'image/png',    value: Buffer  },})


                      img.aiCrop

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      本接口提供基于小程序的图片智能裁剪能力。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cv/img/aicrop?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      img_urlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息

                      使用说明

                      说明 文件大小限制:小于2M 图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 ratios参数为可选,如果为空,则算法自动裁剪最佳宽高比;如果提供多个宽高比,请以英文逗号“,”分隔,最多支持5个宽高比

                      请求数据示例

                      示例1:

                      curl -F 'ratios=1,2.35' "http://api.weixin.qq.com/cv/img/aicrop?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN"

                      示例2:

                      curl -F 'img=@test.jpg' -F 'ratios=1,2.35' 'http://api.weixin.qq.com/cv/img/aicrop?access_token=ACCESS_TOCKEN'

                      返回数据示例

                      {   "errcode": 0,   "errmsg": "ok",   "results": [ //智能裁剪结果   {       "crop_left": 112,       "crop_top": 0,       "crop_right": 839,       "crop_bottom": 727   },   {       "crop_left": 0,       "crop_top": 205,       "crop_right": 965,       "crop_bottom": 615   }   ],   "img_size": { //图片大小       "w": 966,       "h": 728   }}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.img.aiCrop
                      需在 config.json 中配置 img.aiCrop API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      img 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      使用说明

                      说明 文件大小限制:小于2M 图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 ratios参数为可选,如果为空,则算法自动裁剪最佳宽高比;如果提供多个宽高比,请以英文逗号“,”分隔,最多支持5个宽高比

                      返回数据示例

                      {   "errcode": 0,   "errmsg": "ok",   "results": [ //智能裁剪结果   {       "crop_left": 112,       "crop_top": 0,       "crop_right": 839,       "crop_bottom": 727   },   {       "crop_left": 0,       "crop_top": 205,       "crop_right": 965,       "crop_bottom": 615   }   ],   "img_size": { //图片大小       "w": 966,       "h": 728   }}


                      img.scanQRCode

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      本接口提供基于小程序的条码/二维码识别的API。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cv/img/qrcode?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      img_urlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息

                      使用说明

                      图片说明 文件大小限制:小于2M

                      二维码说明 支持条码、二维码、DataMatrix和PDF417的识别。 二维码、DataMatrix会返回位置坐标,条码和PDF417暂不返回位置坐标。

                      请求数据示例

                      示例1:

                      curl https://api.weixin.qq.com/cv/img/qrcode?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      示例2:

                      curl -F 'img=@test.jpg' 'https://api.weixin.qq.com/cv/img/qrcode?access_token=ACCESS_TOCKEN'

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "code_results": [        {            "type_name": "QR_CODE",            "data": "http://www.qq.com",            "pos": {                "left_top": {                    "x": 585,                    "y": 378                },                "right_top": {                    "x": 828,                    "y": 378                },                "right_bottom": {                    "x": 828,                    "y": 618                },                "left_bottom": {                    "x": 585,                    "y": 618                }            }        },        {            "type_name": "QR_CODE",            "data": "https://mp.weixin.qq.com",            "pos": {                "left_top": {                    "x": 185,                    "y": 142                },                "right_top": {                    "x": 396,                    "y": 142                },                "right_bottom": {                    "x": 396,                    "y": 353                },                "left_bottom": {                    "x": 185,                    "y": 353                }            }        },        {            "type_name": "EAN_13",            "data": "5906789678957"        },        {            "type_name": "CODE_128",            "data": "50090500019191"        }    ],    "img_size": {        "w": 1000,        "h": 900    }}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.img.scanQRCode
                      需在 config.json 中配置 img.scanQRCode API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      img 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      使用说明

                      图片说明 文件大小限制:小于2M

                      二维码说明 支持条码、二维码、DataMatrix和PDF417的识别。 二维码、DataMatrix会返回位置坐标,条码和PDF417暂不返回位置坐标。

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "code_results": [        {            "type_name": "QR_CODE",            "data": "http://www.qq.com",            "pos": {                "left_top": {                    "x": 585,                    "y": 378                },                "right_top": {                    "x": 828,                    "y": 378                },                "right_bottom": {                    "x": 828,                    "y": 618                },                "left_bottom": {                    "x": 585,                    "y": 618                }            }        },        {            "type_name": "QR_CODE",            "data": "https://mp.weixin.qq.com",            "pos": {                "left_top": {                    "x": 185,                    "y": 142                },                "right_top": {                    "x": 396,                    "y": 142                },                "right_bottom": {                    "x": 396,                    "y": 353                },                "left_bottom": {                    "x": 185,                    "y": 353                }            }        },        {            "type_name": "EAN_13",            "data": "5906789678957"        },        {            "type_name": "CODE_128",            "data": "50090500019191"        }    ],    "img_size": {        "w": 1000,        "h": 900    }}


                      img.superresolution

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      本接口提供基于小程序的图片高清化能力。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cv/img/superresolution?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      img_urlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息

                      使用说明

                      说明 文件大小限制:小于2M 图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 目前支持将图片超分辨率高清化2倍,即生成图片分辨率为原图2倍大小

                      请求数据示例

                      示例1:

                      curl 'https://api.weixin.qq.com/cv/img/superresolution?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN'

                      示例2:

                      curl -F 'img=@test.jpg' 'https://api.weixin.qq.com/cv/img/superresolution?access_token=ACCESS_TOCKEN'

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "media_id": "6WXsIXkG7lXuDLspD9xfm5dsvHzb0EFl0li6ySxi92ap8Vl3zZoD9DpOyNudeJGB"}

                      说明

                      返回的media_id有效期为3天,期间可以通过“获取临时素材”接口获取图片二进制,示例:

                      curl "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID" -o "output.jpg"

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.img.superresolution
                      需在 config.json 中配置 img.superresolution API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      img 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      使用说明

                      说明 文件大小限制:小于2M 图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 目前支持将图片超分辨率高清化2倍,即生成图片分辨率为原图2倍大小

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "media_id": "6WXsIXkG7lXuDLspD9xfm5dsvHzb0EFl0li6ySxi92ap8Vl3zZoD9DpOyNudeJGB"}


                      immediateDelivery.abnormalConfirm

                      本接口应在服务器端调用,详细说明参见服务端API

                      异常件退回商家商家确认收货接口

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/confirm_return?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      shopidstring商家id,由配送公司分配的appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号,在配送公司登记,闪送必填,值为店铺id
                      delivery_signstring用配送公司提供的appSecret加密的校验串说明
                      waybill_idstring配送单id
                      remarkstring备注

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述

                      使用场景

                      当订单配送异常,骑手把货物退还给商家,商家收货以后调用本接口返回确认收货。

                      请求示例

                      {   "shopid": "123456",   "shop_order_id": "123456",   "shop_no": "shop_no_111"   "waybill_id": "123456",   "remark": "remark",   "delivery_sign": "123456"}

                      返回数据示例

                      {  "resultcode": 0,  "resultmsg": "ok"}


                      immediateDelivery.addOrder

                      本接口应在服务器端调用,详细说明参见服务端API

                      下配送单接口

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/add?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      delivery_tokenstring预下单接口返回的参数,配送公司可保证在一段时间内运费不变
                      shopidstring商家id,由配送公司分配的appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成, 不超过128字节
                      shop_nostring商家门店编号,在配送公司登记,如果只有一个门店,美团闪送必填, 值为店铺id
                      delivery_signstring用配送公司提供的appSecret加密的校验串说明
                      delivery_idstring配送公司ID
                      openidstring下单用户的openid
                      senderObject发件人信息,顺丰同城急送必须填写,美团配送、达达、闪送,若传了shop_no的值可不填该字段
                      receiverObject收件人信息
                      cargoObject货物信息
                      order_infoObject订单信息
                      shopObject商品信息,会展示到物流通知消息中
                      sub_biz_idstring子商户id,区分小程序内部多个子商户

                      sender 的结构

                      属性类型默认值必填说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      receiver 的结构

                      属性类型默认值必填说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      cargo 的结构

                      属性类型默认值必填说明
                      goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
                      goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
                      goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
                      goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_detailObject货物详情,最长不超过10240个字符
                      goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
                      goods_delivery_infostring货物交付信息,最长不超过100个字符
                      cargo_first_classstring品类一级类目, 详见品类表
                      cargo_second_classstring品类二级类目

                      goods_detail 的结构

                      属性类型默认值必填说明
                      goodsArray.<Object>货物列表

                      goods 的结构

                      属性类型默认值必填说明
                      good_countnumber货物数量
                      good_namestring货品名称
                      good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
                      good_unitstring货品单位,最长不超过20个字符

                      order_info 的结构

                      属性类型默认值必填说明
                      delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
                      order_typenumber0订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
                      expected_delivery_timenumber0期望派单时间(达达支持,表示达达系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
                      expected_finish_timenumber0期望送达时间(美团、顺丰同城急送支持),unix-timestamp, 比如1586342180
                      expected_pick_timenumber0期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
                      poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
                      notestring备注,最长不超过200个字符
                      order_timenumber用户下单付款时间, 顺丰必填, 比如1555220757
                      is_insurednumber0是否保价,0,非保价,1.保价
                      declared_valuenumber保价金额,单位为元,精确到分
                      tipsnumber小费,单位为元, 下单一般不加小费
                      is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
                      cash_on_deliverynumber骑手应付金额,单位为元,精确到分
                      cash_on_pickupnumber骑手应收金额,单位为元,精确到分
                      rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
                      is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
                      is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

                      shop 的结构

                      属性类型默认值必填说明
                      wxa_pathstring商家小程序的路径,建议为订单页面
                      img_urlstring商品缩略图 url
                      goods_namestring商品名称
                      goods_countnumber商品数量
                      wxa_appidstring若结算方式为:第三方向配送公司统一结算,商户后续和第三方结算,则该参数必填;在该结算模式下,第三方用自己的开发小程序替授权商户发起下单,并将授权小程序的appid给平台,后续配送通知中可回流授权商户小程序。

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述
                      feenumber实际运费(单位:元),运费减去优惠券费用
                      deliverfeenumber运费(单位:元)
                      couponfeenumber优惠券费用(单位:元)
                      tipsnumber小费(单位:元)
                      insurancefeenumber保价费(单位:元)
                      distancenumber配送距离(整数单位:米)
                      waybill_idstring配送单号
                      order_statusnumber配送状态
                      finish_codenumber收货码
                      pickup_codenumber取货码
                      dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0

                      使用场景

                      商家可调用本接口向配送公司请求下配送单,配送公司会返回这一单的配送单号、配送费、预计骑手接单时间等信息。如遇下单错误,请先确认一下编码方式,python建议 json.dumps(b, ensure_ascii=False),php建议 json_encode($arr, JSON_UNESCAPED_UNICODE) 可预约时间:达达:72小时内,闪送2小时以后,48小时以内

                      请求示例

                      {   "cargo": {       "cargo_first_class": "美食夜宵",       "cargo_second_class": "零食小吃",       "goods_detail": {           "goods": [               {                   "good_count": 1,                   "good_name": "水果",                   "good_price": 10,                   "good_unit": "元"               },               {                   "good_count": 2,                   "good_name": "蔬菜",                   "good_price": 20,                   "good_unit": "元"               }           ]       },       "goods_height": 1,       "goods_length": 3,       "goods_value": 5,       "goods_weight": 1,       "goods_width": 2   },   "delivery_id": "SFTC",   "delivery_sign": "01234567890123456789",   "openid": "oABC123456",   "order_info": {       "delivery_service_code": "",       "expected_delivery_time": 0,       "is_direct_delivery": 0,       "is_finish_code_needed": 1,       "is_insured": 0,       "is_pickup_code_needed": 1,       "note": "test_note",       "order_time": 1555220757,       "order_type": 0,       "poi_seq": "1111",       "tips": 0   },   "receiver": {       "address": "xxx地铁站",       "address_detail": "2号楼202",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.1529600000,       "lng": 116.5060300000,       "name": "老王",       "phone": "18512345678"   },   "sender": {       "address": "xx大厦",       "address_detail": "1号楼101",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.4486120000,       "lng": 116.3830750000,       "name": "刘一",       "phone": "13712345678"   },   "shop": {       "goods_count": 2,       "goods_name": "宝贝",       "img_url": "https://mmbiz.qpic.cn/mmbiz_png/xxxxxxxxx/0?wx_fmt=png",       "wxa_path": "/page/index/index"   },   "shop_no": "12345678",   "sub_biz_id": "sub_biz_id_1",   "shop_order_id": "SFTC_001",   "shopid": "122222222",   "delivery_token": "xxxxxxxx"}

                      返回示例

                      下单成功

                      {  "resultcode": 0,  "resultmsg": "ok",  "fee": 10,  "deliverfee": 10,  "couponfee": 0,  "tips": 0,  "insurancfee": 0,  "distance": 1000,  "waybill_id": "123456789",  "order_status": 101,  "finish_code": 1024,  "pickup_code": 2048,  "dispatch_duration": 300}

                      下单失败

                      {  "resultcode": 1010,  "resultmsg": "收件人信息不正确"}


                      immediateDelivery.addTip

                      本接口应在服务器端调用,详细说明参见服务端API

                      可以对待接单状态的订单增加小费。需要注意:订单的小费,以最新一次加小费动作的金额为准,故下一次增加小费额必须大于上一次小费额

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/addtips?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      shopidstring商家id, 由配送公司分配的appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号,在配送公司登记,如果只有一个门店,闪送shop_no必填,值为店铺id
                      delivery_signstring用配送公司提供的appSecret加密的校验串说明
                      waybill_idstring配送单id
                      openidstring下单用户的openid
                      tipsnumber小费金额(单位:元) 各家配送公司最大值不同
                      remarkstring备注

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述

                      使用场景

                      调用本接口,可以给待接单状态的订单增加小费,各家配送公司增加消费的规则如下:

                      配送公司加小费规则
                      顺丰同城急送支持加小费,小费规则:骑手接单前可加小费,上限10次,200元封顶
                      闪送支持加小费,小费规则:骑手接单前可加小费,需按固定档位加小费,档位为2、3、5、10、15、20、50、100
                      美团配送不支持加小费
                      达达配送支持加小费,小费规则:骑手接单前可加小费,小费金额以最新一次为准,同一单新增的小费额须大于上一次的小费额,小费不可以超过货值,上限30元

                      请求示例

                      {   "shopid": "123456",   "shop_order_id": "123456",   "waybill_id": "123456",   "tips": 5,   "remark": "gogogo",   "delivery_sign": "123456",   "shop_no": "shop_no_111"}

                      返回数据示例

                      {  "resultcode": 0,  "resultmsg": "ok"}


                      immediateDelivery.bindAccount

                      本接口应在服务器端调用,详细说明参见服务端API

                      第三方代商户发起绑定配送公司帐号的请求

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/shop/add?access_token=COMPNENT_ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      delivery_idstring配送公司ID

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述

                      errcode 的合法值

                      说明最低版本
                      0成功
                      86000不是第三方的调用
                      930561delivery_id无效

                      使用场景

                      1. 只能由第三方服务商调用此接口
                      2. 服务商可通过本接口代开发的小程序发起绑定配送公司帐号的操作,当调用成功,小程序管理员将收到模版消息,点击详情进入配送公司网站进行绑定操作

                      返回数据示例

                      {  "resultcode": 0,  "resultmsg": "ok",}


                      immediateDelivery.cancelOrder

                      本接口应在服务器端调用,详细说明参见服务端API

                      取消配送单接口

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/cancel?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      shopidstring商家id, 由配送公司分配的appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号,如果只有一个门店,闪送shop_no必填,值为店铺id
                      delivery_signstring用配送公司提供的appSecret加密的校验串说明
                      delivery_idstring快递公司ID
                      waybill_idstring配送单id
                      cancel_reason_idnumber取消原因Id
                      cancel_reasonstring取消原因

                      cancel_reason_id 的合法值

                      说明最低版本
                      1暂时不需要邮寄
                      2价格不合适
                      3订单信息有误,重新下单
                      4骑手取货不及时
                      5骑手配送不及时
                      6其他原因( 如果选择6,需要填写取消原因,否则不需要填写 )

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述
                      deduct_feenumber扣除的违约金(单位:元),精确到分
                      descstring说明

                      使用场景

                      调用本接口可向配送公司请求取消配送单,各家取消规则如下:

                      配送公司取消规则
                      顺丰同城急送配送完成前任意节点可取消配送单
                      闪送配送完成前任意节点可取消配送单
                      美团配送配送完成前任意节点可取消配送单
                      达达骑手取货之前可取消配送单

                      请求示例

                      {   "shopid": "123456",   "shop_order_id": "123456",   "waybill_id": "123456",   "delivery_id": "123456",   "cancel_reason_id": 1,   "cancel_reason": "",   "delivery_sign": "123456",   "shop_no": "shop_no_111"}

                      返回数据示例

                      {  "resultcode": 0,  "resultmsg": "ok",  "deduct_fee": 5,  "desc": "blabla"}


                      immediateDelivery.getAllImmeDelivery

                      本接口应在服务器端调用,详细说明参见服务端API

                      获取已支持的配送公司列表接口

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/delivery/getall?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述
                      listArray.<Object>配送公司列表

                      list 的结构

                      属性类型说明
                      delivery_idstring配送公司Id
                      delivery_namestring配送公司名称

                      使用场景

                      查询即时配送接口已支持的配送公司和delivery_id

                      返回数据示例

                      {  "resultcode": 0,  "resultmsg": "ok",  "list": [     {         "delivery_id": "SFTC",         "delivery_name": "顺发同城"     },     {         "delivery_id": "MTPS",         "delivery_name": "美团配送"     }  ]}


                      immediateDelivery.getBindAccount

                      本接口应在服务器端调用,详细说明参见服务端API

                      拉取已绑定账号

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/shop/get?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述
                      shop_listArray.<Object>绑定的商家签约账号列表

                      shop_list 的结构

                      属性类型说明
                      delivery_idstring配送公司Id
                      shopidstring商家id
                      audit_resultnumber审核状态

                      audit_result 的合法值

                      说明最低版本
                      0审核通过
                      1审核中
                      2审核不通过

                      使用场景

                      1. 商家可通过本接口查询自己已经在小程序后台绑定的和配送公司签约的账号;
                      2. 服务商可通过本接口查询代开发的小程序在小程序后台绑定的和配送公司签约的账号,为其完成后续的接口代开发业务。

                      返回数据示例

                      {  "resultcode": 0,  "resultmsg": "ok",  "shop_list": [      {       "delivery_id": "SFTC",       "shopid": "123456",       "audit_result": 0      },      {       "delivery_id": "MTPS",       "shopid": "123456",       "audit_result": 0      }  ]}


                      immediateDelivery.getOrder

                      本接口应在服务器端调用,详细说明参见服务端API

                      拉取配送单信息

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/get?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      shopidstring商家id, 由配送公司分配的appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司登记,如果只有一个门店,可以不填
                      delivery_signstring用配送公司提供的appSecret加密的校验串说明

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述
                      order_statusnumber配送状态,枚举值
                      waybill_idstring配送单号
                      rider_namestring骑手姓名
                      rider_phonestring骑手电话
                      rider_lngnumber骑手位置经度, 配送中时返回
                      rider_latnumber骑手位置纬度, 配送中时返回
                      reach_timenumber预计还剩多久送达时间, 配送中时返回,单位秒, 已取货配送中需返回,比如5分钟后送达,填300

                      使用场景

                      商家可使用本接口查询某一配送单的配送状态,便于商家掌握配送情况。


                      immediateDelivery.mockUpdateOrder

                      本接口应在服务器端调用,详细说明参见服务端API

                      模拟配送公司更新配送单状态, 该接口只用于沙盒环境,即订单并没有真实流转到运力方

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/test_update_order?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      shopidstring商家id, 必须是 "test_shop_id"
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      action_timenumber状态变更时间点,Unix秒级时间戳
                      order_statusnumber配送状态,枚举值
                      action_msgstring附加信息

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述

                      使用场景

                      该接口只能用于测试

                      请求示例

                      {   "shopid": "test_shop_id",   "shop_order_id": "xxxxxxxxxxx",   "waybill_id": "xxxxxxxxxxxxx",   "action_time": 12345678,   "order_status": 101,   "action_msg": "",}

                      返回数据示例

                      {  "resultcode": 0,  "resultmsg": "ok"}


                      immediateDelivery.onOrderStatus

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      配送单配送状态更新通知接口

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 update_waybill_status,不区分大小写
                      shopidstring商家id, 由配送公司分配的appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司侧登记
                      waybill_idstring配送单id
                      action_timenumberUnix时间戳
                      order_statusnumber配送状态,枚举值
                      action_msgstring附加信息
                      agentObject骑手信息

                      agent 的结构

                      属性类型说明
                      namestring骑手姓名
                      phonestring骑手电话
                      reach_timenumber预计送达时间戳, 配送中返回

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 update_waybill_status,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述

                      使用场景

                      当配送公司更新订单配送状态时,微信会通过本接口同步通知商户

                      消息数据包示例

                      JSON 格式

                      {  "ToUserName": "toUser",  "FromUserName": "fromUser",  "CreateTime": 1546924844,  "MsgType": "event",  "Event": "update_waybill_status",  "shopid": "123456",  "shop_order_id": "123456",  "waybill_id": "123456",  "action_time": 1546924844,  "order_status": 102,  "action_msg": "",  "shop_no": "123456",  "agent": {     "name": "xxx",     "phone": "1234567"  }}


                      immediateDelivery.openDelivery

                      本接口应在服务器端调用,详细说明参见服务端API

                      第三方代商户发起开通即时配送权限

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/open?access_token=COMPNENT_ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述

                      errcode 的合法值

                      说明最低版本
                      0成功
                      43016小程序未认证
                      86000不是第三方的调用
                      930568不支持个人类型小程序
                      930569已经开通不需要再开通
                      930571该商户没有内测权限

                      使用场景

                      1. 只能由第三方服务商调用此接口
                      2. 服务商可通过本接口代开发的小程序发起开通即时配送接口权限的操作,当调用成功,小程序管理员将收到模版消息,进行开通操作

                      返回数据示例

                      {  "resultcode": 0,  "resultmsg": "ok",}


                      immediateDelivery.preAddOrder

                      本接口应在服务器端调用,详细说明参见服务端API

                      预下配送单接口

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/pre_add?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      shopidstring商家id, 由配送公司分配的appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成, 不超过128字节
                      shop_nostring商家门店编号,在配送公司登记,美团、闪送必填
                      delivery_signstring用配送公司提供的appSecret加密的校验串说明
                      delivery_idstring配送公司ID
                      openidstring下单用户的openid
                      senderObject发件人信息,闪送、顺丰同城急送必须填写,美团配送、达达,若传了shop_no的值可不填该字段
                      receiverObject收件人信息
                      cargoObject货物信息
                      order_infoObject订单信息
                      shopObject商品信息,会展示到物流通知消息中
                      sub_biz_idstring子商户id,区分小程序内部多个子商户

                      sender 的结构

                      属性类型默认值必填说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      receiver 的结构

                      属性类型默认值必填说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      cargo 的结构

                      属性类型默认值必填说明
                      goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
                      goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
                      goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
                      goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_detailObject货物详情,最长不超过10240个字符
                      goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
                      goods_delivery_infostring货物交付信息,最长不超过100个字符
                      cargo_first_classstring品类一级类目, 详见品类表
                      cargo_second_classstring品类二级类目

                      goods_detail 的结构

                      属性类型默认值必填说明
                      goodsArray.<Object>货物列表

                      goods 的结构

                      属性类型默认值必填说明
                      good_countnumber货物数量
                      good_namestring货品名称
                      good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
                      good_unitstring货品单位,最长不超过20个字符

                      order_info 的结构

                      属性类型默认值必填说明
                      delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
                      order_typenumber0订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
                      expected_delivery_timenumber0期望派单时间(美团、达达支持,美团表示商家发单时间,达达表示系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
                      expected_finish_timenumber0期望送达时间(顺丰同城急送支持),unix-timestamp, 比如1586342180
                      expected_pick_timenumber0期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
                      poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
                      notestring备注,最长不超过200个字符
                      order_timenumber用户下单付款时间, 比如1555220757
                      is_insurednumber0是否保价,0,非保价,1.保价
                      declared_valuenumber保价金额,单位为元,精确到分
                      tipsnumber小费,单位为元, 下单一般不加小费
                      is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
                      cash_on_deliverynumber骑手应付金额,单位为元,精确到分
                      cash_on_pickupnumber骑手应收金额,单位为元,精确到分
                      rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
                      is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
                      is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

                      shop 的结构

                      属性类型默认值必填说明
                      wxa_pathstring商家小程序的路径,建议为订单页面
                      img_urlstring商品缩略图 url
                      goods_namestring商品名称
                      goods_countnumber商品数量
                      wxa_appidstring若结算方式为:第三方向配送公司统一结算,商户后续和第三方结算,则该参数必填;在该结算模式下,第三方用自己的开发小程序替授权商户发起下单,并将授权小程序的appid给平台,后续配送通知中可回流授权商户小程序。

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述
                      feenumber实际运费(单位:元),运费减去优惠券费用
                      deliverfeenumber运费(单位:元)
                      couponfeenumber优惠券费用(单位:元)
                      tipsnumber小费(单位:元)
                      insurancefeenumber保价费(单位:元)
                      distancenumber配送距离(单位:米)
                      dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0
                      delivery_tokenstring配送公司可以返回此字段,当用户下单时候带上这个字段,保证在一段时间内运费不变

                      使用场景

                      1. 在用户提交外卖订单时,商家可调用本接口查询配送公司是否可接单、预计多久接单、运费预估等。预估运费可作为展示给用户的运费参考值。
                      2. 举个例子:商家通过预下配送单接口返回的预估运费是8元,商家可决定前端顾客下外卖单时展示给顾客看的运费是真实的8元,还是其他商家指定的金额。
                      3. 说明:本接口非必须调用接口,若不需要获取配送公司是否可接单、预计多久接单、运费预估等,也可不调用本接口,直接下配送单。
                      4. 顺丰同城可返回配送费用、配送距离、预计骑手接单时间,不支持返回delivery_token。
                      5. 闪送可返回配送费用、配送距离、预计骑手接单时间,不支持返回delivery_token。
                      6. 美团配送返回0时表示校验通过,不支持返回配送费用、配送距离、预计骑手接单时间和delivery_token。
                      7. 达达支持预下单查询配送费用、配送距离、预计骑手接单时间和delivery_token(有效期3分钟)。

                      请求示例

                      {   "cargo": {       "cargo_first_class": "美食夜宵",       "cargo_second_class": "零食小吃",       "goods_detail": {           "goods": [               {                   "good_count": 1,                   "good_name": "水果",                   "good_price": 10,                   "good_unit": "元"               },               {                   "good_count": 2,                   "good_name": "蔬菜",                   "good_price": 20,                   "good_unit": "元"               }           ]       },       "goods_height": 1,       "goods_length": 3,       "goods_value": 5,       "goods_weight": 1,       "goods_width": 2   },   "delivery_id": "SFTC",   "delivery_sign": "01234567890123456789",   "openid": "oABC123456",   "order_info": {       "delivery_service_code": "",       "expected_delivery_time": 0,       "is_direct_delivery": 0,       "is_finish_code_needed": 1,       "is_insured": 0,       "is_pickup_code_needed": 1,       "note": "test_note",       "order_time": 1555220757,       "order_type": 0,       "poi_seq": "1111",       "tips": 0   },   "receiver": {       "address": "xxx地铁站",       "address_detail": "2号楼202",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.1529600000,       "lng": 116.5060300000,       "name": "老王",       "phone": "18512345678"   },   "sender": {       "address": "xx大厦",       "address_detail": "1号楼101",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.4486120000,       "lng": 116.3830750000,       "name": "刘一",       "phone": "13712345678"   },   "shop": {       "goods_count": 2,       "goods_name": "宝贝",       "img_url": "https://mmbiz.qpic.cn/mmbiz_png/xxxxxxxxx/0?wx_fmt=png",       "wxa_path": "/page/index/index"   },   "shop_no": "12345678",   "sub_biz_id": "sub_biz_id_1",   "shop_order_id": "SFTC_001",   "shopid": "122222222",}

                      返回示例

                      下单成功

                      {  "resultcode": 0,  "resultmsg": "ok",  "fee": 10,  "deliverfee": 10,  "couponfee": 0,  "tips": 0,  "insurancfee": 0,  "distance": 1000,  "dispatch_duration": 300,  "delivery_token": "1111111"}

                      下单失败

                      {  "resultcode": 1010,  "resultmsg": "收件人信息不正确"}


                      immediateDelivery.preCancelOrder

                      本接口应在服务器端调用,详细说明参见服务端API

                      预取消配送单接口

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/precancel?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      shopidstring商家id, 由配送公司分配的appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号,在配送公司登记,闪送shop_no必填,值为店铺id
                      delivery_signstring用配送公司提供的appSecret加密的校验串说明
                      delivery_idstring快递公司ID
                      waybill_idstring配送单id
                      cancel_reason_idnumber取消原因Id
                      cancel_reasonstring取消原因

                      cancel_reason_id 的合法值

                      说明最低版本
                      1暂时不需要邮寄
                      2价格不合适
                      3订单信息有误,重新下单
                      4骑手取货不及时
                      5骑手配送不及时
                      6其他原因( 如果选择6,需要填写取消原因,否则不需要填写 )

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述
                      deduct_feenumber预计扣除的违约金(单位:元),精确到分
                      descstring说明

                      使用场景

                      在正式取消配送单前,商家可调用本接口查询该订单是否可以取消,取消订单配送公司需要扣除的费用是多少。各家取消规则如下:

                      配送公司取消规则
                      顺丰同城急送配送完成前任意节点可取消配送单
                      闪送配送完成前任意节点可取消配送单
                      美团配送配送完成前任意节点可取消配送单
                      达达骑手取货之前可取消配送单

                      请求示例

                      {   "shopid": "123456",   "shop_order_id": "123456",   "waybill_id": "123456",   "delivery_id": "123456",   "cancel_reason_id": 1,   "cancel_reason": "",   "delivery_sign": "123456",   "shop_no": "shop_no_111"}

                      返回数据示例

                      {  "resultcode": 0,  "resultmsg": "ok",  "deduct_fee": 5,  "desc": "blabla"}


                      immediateDelivery.realMockUpdateOrder

                      本接口应在服务器端调用,详细说明参见服务端API

                      模拟配送公司更新配送单状态, 该接口用于测试账户下的单,将请求转发到运力测试环境

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/realmock_update_order?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      shopidstring商家id
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      action_timenumber状态变更时间点,Unix秒级时间戳
                      order_statusnumber配送状态,枚举值
                      action_msgstring附加信息
                      delivery_signstring用配送公司提供的appSecret加密的校验串说明

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述

                      使用场景

                      该接口只能用于测试,请求会转发到运力测试环境, 目前支持顺丰同城和达达

                      1. 顺丰同城测试号
                      • shopid: 1534713176
                      • appsecret: d80400f91e156f63b38886e616d84590
                      • shopno: 3243279847393
                      • 支持变更状态: 102 202 202 302
                      1. 达达测试号
                      • shopid: dadaaee18818d97e236
                      • appsecret: 1c6f40492d6d89caaad80b85f7d31670
                      • shopno: 77071-47913
                      • 支持变更状态: 102 201 202 301 302 304 305

                      请求示例

                      {   "shopid": "xxxxxxx",   "shop_order_id": "xxxxxxxxxxx",   "action_time": 1584145981,   "order_status": 101,   "action_msg": "",   "delivery_sign": "xxxxxxx",}

                      返回数据示例

                      {  "resultcode": 0,  "resultmsg": "ok"}


                      immediateDelivery.reOrder

                      本接口应在服务器端调用,详细说明参见服务端API

                      重新下单

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/readd?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      delivery_tokenstring预下单接口返回的参数,配送公司可保证在一段时间内运费不变
                      shopidstring商家id, 由配送公司分配的appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成, 不超过128字节
                      shop_nostring商家门店编号,在配送公司登记,如果只有一个门店,闪送shop_no必填,值为店铺id
                      delivery_signstring用配送公司提供的appSecret加密的校验串说明
                      delivery_idstring配送公司ID
                      openidstring下单用户的openid
                      senderObject发件人信息,顺丰同城急送必须填写,美团配送、达达、闪送,若传了shop_no的值可不填该字段
                      receiverObject收件人信息
                      cargoObject货物信息
                      order_infoObject订单信息
                      shopObject商品信息,会展示到物流通知消息中
                      sub_biz_idstring子商户id,区分小程序内部多个子商户

                      sender 的结构

                      属性类型默认值必填说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      receiver 的结构

                      属性类型默认值必填说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber0坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      cargo 的结构

                      属性类型默认值必填说明
                      goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
                      goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
                      goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
                      goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_detailObject货物详情,最长不超过10240个字符
                      goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
                      goods_delivery_infostring货物交付信息,最长不超过100个字符
                      cargo_first_classstring品类一级类目, 详见品类表
                      cargo_second_classstring品类二级类目

                      goods_detail 的结构

                      属性类型默认值必填说明
                      goodsArray.<Object>货物列表

                      goods 的结构

                      属性类型默认值必填说明
                      good_countnumber货物数量
                      good_namestring货品名称
                      good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
                      good_unitstring货品单位,最长不超过20个字符

                      order_info 的结构

                      属性类型默认值必填说明
                      delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
                      order_typenumber0订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
                      expected_delivery_timenumber0期望派单时间(美团、达达支持,美团表示商家发单时间,达达表示系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
                      expected_finish_timenumber0期望送达时间(顺丰同城急送支持),unix-timestamp, 比如1586342180
                      expected_pick_timenumber0期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
                      poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
                      notestring备注,最长不超过200个字符
                      order_timenumber用户下单付款时间, 比如1555220757
                      is_insurednumber0是否保价,0,非保价,1.保价
                      declared_valuenumber保价金额,单位为元,精确到分
                      tipsnumber小费,单位为元, 下单一般不加小费
                      is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
                      cash_on_deliverynumber骑手应付金额,单位为元,精确到分
                      cash_on_pickupnumber骑手应收金额,单位为元,精确到分
                      rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
                      is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
                      is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

                      shop 的结构

                      属性类型默认值必填说明
                      wxa_pathstring商家小程序的路径,建议为订单页面
                      img_urlstring商品缩略图 url
                      goods_namestring商品名称
                      goods_countnumber商品数量
                      wxa_appidstring若结算方式为:第三方向配送公司统一结算,商户后续和第三方结算,则该参数必填;在该结算模式下,第三方用自己的开发小程序替授权商户发起下单,并将授权小程序的appid给平台,后续配送通知中可回流授权商户小程序。

                      返回值

                      Object

                      属性类型说明
                      errcodenumber错误码, 当errcode==0或者不存在还需要看resultcode
                      errmsgstring错误描述
                      resultcodenumber运力返回的错误码
                      resultmsgstring运力返回的错误描述
                      feenumber实际运费(单位:元),运费减去优惠券费用
                      deliverfeenumber运费(单位:元)
                      couponfeenumber优惠券费用(单位:元)
                      tipsnumber小费(单位:元)
                      insurancefeenumber保价费(单位:元)
                      distancenumber配送距离(单位:米)
                      waybill_idstring配送单号
                      order_statusnumber配送状态
                      finish_codenumber收货码
                      pickup_codenumber取货码
                      dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0

                      使用场景

                      在调用下配送单接口、订单被取消、过期或者投递异常的情况下,可调用此接口,重新下单,需要保持orderid一致。 备注:美团不支持重新下单接口,如果订单被取消商家需要重新下单,请修改orderid之后,调用下配送单接口下单。

                      请求示例

                      {   "cargo": {       "cargo_first_class": "美食夜宵",       "cargo_second_class": "零食小吃",       "goods_detail": {           "goods": [               {                   "good_count": 1,                   "good_name": "水果",                   "good_price": 10,                   "good_unit": "元"               },               {                   "good_count": 2,                   "good_name": "蔬菜",                   "good_price": 20,                   "good_unit": "元"               }           ]       },       "goods_height": 1,       "goods_length": 3,       "goods_value": 5,       "goods_weight": 1,       "goods_width": 2   },   "delivery_id": "SFTC",   "delivery_sign": "01234567890123456789",   "openid": "oABC123456",   "order_info": {       "delivery_service_code": "",       "expected_delivery_time": 0,       "is_direct_delivery": 0,       "is_finish_code_needed": 1,       "is_insured": 0,       "is_pickup_code_needed": 1,       "note": "test_note",       "order_time": 1555220757,       "order_type": 0,       "poi_seq": "1111",       "tips": 0   },   "receiver": {       "address": "xxx地铁站",       "address_detail": "2号楼202",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.1529600000,       "lng": 116.5060300000,       "name": "老王",       "phone": "18512345678"   },   "sender": {       "address": "xx大厦",       "address_detail": "1号楼101",       "city": "北京市",       "coordinate_type": 0,       "lat": 40.4486120000,       "lng": 116.3830750000,       "name": "刘一",       "phone": "13712345678"   },   "shop": {       "goods_count": 2,       "goods_name": "宝贝",       "img_url": "https://mmbiz.qpic.cn/mmbiz_png/xxxxxxxxx/0?wx_fmt=png",       "wxa_path": "/page/index/index"   },   "shop_no": "12345678",   "sub_biz_id": "sub_biz_id_1",   "shop_order_id": "SFTC_001",   "shopid": "122222222",   "delivery_token": "xxxxxxxx"}

                      返回示例

                      下单成功

                      {  "resultcode": 0,  "resultmsg": "ok",  "fee": 10,  "deliverfee": 10,  "couponfee": 0,  "tips": 0,  "insurancfee": 0,  "distance": 1000,  "waybill_id": "123456789",  "order_status": 101,  "finish_code": 1024,  "pickup_code": 2048,  "dispatch_duration": 300}

                      下单失败

                      {  "resultcode": 1010,  "resultmsg": "收件人信息不正确"}


                      immediateDelivery.onAgentPosQuery

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      查询骑手当前位置信息

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_get_agent_pos,不区分大小写
                      shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司侧登记
                      waybill_idstring配送单id

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_get_agent_pos,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述
                      lngnumber经度,火星坐标,精确到小数点后6位
                      latnumber纬度,火星坐标,精确到小数点后6位
                      distancenumber和目的地距离,已取货配送中需返回,单位米
                      reach_timenumber预计还剩多久送达时间, 单位秒, 已取货配送中需返回,比如5分钟后送达,填300


                      immediateDelivery.onAuthInfoGet

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      使用授权码拉取授权信息

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 get_auth_info,不区分大小写
                      wx_appidstring发起授权的商户小程序appid
                      codestring授权码

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 get_auth_info,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述
                      appkeystring配送公司分配的appkey,对应shopid
                      accountstring帐号名称
                      account_typenumber帐号类型:0.不确定,1.预充值,2,月结,3,其它


                      immediateDelivery.onCancelAuth

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      取消授权帐号

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 cancel_auth_account,不区分大小写
                      shopidstring商家id, 配送公司唯一标识
                      wx_appidstring发起授权的商户小程序appid

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 cancel_auth_account,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述


                      immediateDelivery.onMockUpdateOrder

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      模拟更新订单状态接口

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 mock_update_order_status,不区分大小写
                      shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司侧登记
                      waybill_idstring配送单id
                      delivery_signstring用配送公司侧提供的appSecret加密的校验串
                      order_statusnumber订单状态,见之前order_status 枚举值
                      action_timenumber状态变更时间点,Unix秒级时间戳
                      action_msgstring附加信息(选填)

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 mock_update_order_status,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述


                      immediateDelivery.onOrderAdd

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      真实发起下单任务

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_add_order,不区分大小写
                      wx_tokenstring微信订单 Token。请保存该Token,调用更新配送单状态接口(updateOrder)时需要传入
                      delivery_tokenstring配送公司侧在预下单时候返回的token,用于保证运费不变
                      shopidstring商家id, 由配送公司分配的appkey
                      shop_nostring商家门店编号, 在配送公司侧登记
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      delivery_signstring用配送公司侧提供的appSecret加密的校验串
                      senderObject发件人信息,如果配送公司能从shopid+shop_no对应到门店地址,则不需要填写,否则需填写
                      receiverObject收件人信息
                      cargoObject货物信息
                      order_infoObject订单信息

                      sender 的结构

                      属性类型说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      receiver 的结构

                      属性类型说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      cargo 的结构

                      属性类型说明
                      goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
                      goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
                      goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
                      goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_detailObject货物详情,最长不超过10240个字符
                      goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
                      goods_delivery_infostring货物交付信息,最长不超过100个字符
                      cargo_first_classstring品类一级类目, 详见品类表
                      cargo_second_classstring品类二级类目

                      goods_detail 的结构

                      属性类型说明
                      goodsArray.<Object>货物列表

                      goods 的结构

                      属性类型说明
                      good_countnumber货物数量
                      good_namestring货品名称
                      good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
                      good_unitstring货品单位,最长不超过20个字符

                      order_info 的结构

                      属性类型说明
                      delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
                      order_typenumber订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
                      expected_delivery_timenumber期望派单时间(达达支持,表示达达系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
                      expected_finish_timenumber期望送达时间(美团、顺丰同城急送支持),unix-timestamp, 比如1586342180
                      expected_pick_timenumber期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
                      poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
                      notestring备注,最长不超过200个字符
                      order_timenumber用户下单付款时间, 顺丰必填, 比如1555220757
                      is_insurednumber是否保价,0,非保价,1.保价
                      declared_valuenumber保价金额,单位为元,精确到分
                      tipsnumber小费,单位为元, 下单一般不加小费
                      is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
                      cash_on_deliverynumber骑手应付金额,单位为元,精确到分
                      cash_on_pickupnumber骑手应收金额,单位为元,精确到分
                      rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
                      is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
                      is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_add_order,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述
                      feenumber实际运费(单位:元),运费减去优惠券费用
                      deliverfeenumber运费(单位:元)
                      couponfeenumber优惠券费用(单位:元)
                      tipsnumber小费(单位:元)
                      insurancefeenumber保价费(单位:元)
                      distancenumber配送距离(整数,单位:米)
                      waybill_idstring配送单号, 可以在API1更新配送单状态异步返回
                      order_statusnumber配送单状态
                      finish_codenumber收货码
                      pickup_codenumber取货码
                      dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0
                      sender_lngnumber发货方经度,火星坐标,精确到小数点后6位, 用于消息通知,如果下单请求里有发货人信息则不需要
                      sender_latnumber发货方纬度,火星坐标,精确到小数点后6位, 用于消息通知,如果下单请求里有发货人信息则不需要


                      immediateDelivery.onOrderAddTips

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      可以对待接单状态的订单增加小费。需注意:各家小费规则不一致,请参考配送公司信息表小费规则说明来添加。

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_add_tips,不区分大小写
                      shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司侧登记
                      waybill_idstring配送单id
                      delivery_signstring用配送公司侧提供的appSecret加密的校验串
                      tipsnumber小费金额(单位:元)
                      remarkstring备注

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_add_tips,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述


                      immediateDelivery.onOrderCancel

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      取消订单操作,取消逻辑参照各配送公司取消规则)

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_cancel_order,不区分大小写
                      shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司侧登记
                      waybill_idstring配送单id
                      delivery_signstring用配送公司侧提供的appSecret加密的校验串
                      cancel_reason_idnumber取消原因id
                      cancel_reasonstring取消原因

                      cancel_reason_id 的合法值

                      说明最低版本
                      1暂时不需要邮寄
                      2价格不合适
                      3订单信息有误,重新下单
                      4骑手取货不及时
                      5骑手配送不及时
                      6其他原因( 如果选择6,需要填写取消原因,否则不需要填写 )

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_cancel_order,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述
                      deduct_feenumber扣除的违约金(单位:元),可能没有
                      descstring扣费说明


                      immediateDelivery.onOrderConfirmReturn

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      异常妥投商户收货确认(达达、闪送、人人快送支持)

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_confirm_return_to_biz,不区分大小写
                      shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司侧登记
                      waybill_idstring配送单id
                      delivery_signstring用配送公司侧提供的appSecret加密的校验串

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_confirm_return_to_biz,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述


                      immediateDelivery.onOrderPreAdd

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      并非真正发单,用来验证是否配送公司是否可以接单,并在成功时返回时效、计价等信息,也可用来验证地址以及时间是否在配送范围内。注意:预下单和下单时候由于时间差或者配送公司策略问题,返回的运费可能不一致,如果配送公司返回delivery_token,商家真正下单时候带上delivery_token,配送公司需保证在这一段时间内运费不变

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_precreate_order,不区分大小写
                      shopidstring商家id, 由配送公司分配的appkey
                      shop_nostring商家门店编号, 在配送公司侧登记
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      delivery_signstring用配送公司侧提供的appSecret加密的校验串
                      senderObject发件人信息,如果配送公司能从shopid+shop_no对应到门店地址,则不需要填写,否则需填写
                      receiverObject收件人信息
                      cargoObject货物信息
                      order_infoObject订单信息

                      sender 的结构

                      属性类型说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      receiver 的结构

                      属性类型说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      cargo 的结构

                      属性类型说明
                      goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
                      goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
                      goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
                      goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_detailObject货物详情,最长不超过10240个字符
                      goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
                      goods_delivery_infostring货物交付信息,最长不超过100个字符
                      cargo_first_classstring品类一级类目, 详见品类表
                      cargo_second_classstring品类二级类目

                      goods_detail 的结构

                      属性类型说明
                      goodsArray.<Object>货物列表

                      goods 的结构

                      属性类型说明
                      good_countnumber货物数量
                      good_namestring货品名称
                      good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
                      good_unitstring货品单位,最长不超过20个字符

                      order_info 的结构

                      属性类型说明
                      delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
                      order_typenumber订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
                      expected_delivery_timenumber期望派单时间(美团、达达支持,美团表示商家发单时间,达达表示系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
                      expected_finish_timenumber期望送达时间(顺丰同城急送支持),unix-timestamp, 比如1586342180
                      expected_pick_timenumber期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
                      poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
                      notestring备注,最长不超过200个字符
                      order_timenumber用户下单付款时间, 比如1555220757
                      is_insurednumber是否保价,0,非保价,1.保价
                      declared_valuenumber保价金额,单位为元,精确到分
                      tipsnumber小费,单位为元, 下单一般不加小费
                      is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
                      cash_on_deliverynumber骑手应付金额,单位为元,精确到分
                      cash_on_pickupnumber骑手应收金额,单位为元,精确到分
                      rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
                      is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
                      is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_precreate_order,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述
                      feenumber实际运费(单位:元),运费减去优惠券费用
                      deliverfeenumber运费(单位:元)
                      couponfeenumber优惠券费用(单位:元)
                      tipsnumber小费(单位:元)
                      insurancefeenumber保价费(单位:元)
                      distancenumber配送距离(单位:米)
                      dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0
                      delivery_tokenstring配送公司可以返回此字段,当用户下单时候带上这个字段,配送公司可保证在一段时间内运费不变


                      immediateDelivery.onOrderPreCancel

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      预取消订单操作,用于在取消订单前查询是否可以取消以及取消扣除的违约金(非必须)

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_precancel_order,不区分大小写
                      shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司侧登记
                      waybill_idstring配送单id
                      delivery_signstring用配送公司侧提供的appSecret加密的校验串
                      cancel_reason_idnumber取消原因id
                      cancel_reasonstring取消原因

                      cancel_reason_id 的合法值

                      说明最低版本
                      1暂时不需要邮寄
                      2价格不合适
                      3订单信息有误,重新下单
                      4骑手取货不及时
                      5骑手配送不及时
                      6其他原因( 如果选择6,需要填写取消原因,否则不需要填写 )

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_precancel_order,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述
                      deduct_feenumber预计扣除的违约金(单位:元),可能没有
                      descstring扣费说明


                      immediateDelivery.onOrderQuery

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      查询订单状态

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_query_order_status,不区分大小写
                      shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司侧登记
                      waybill_idstring配送单id
                      delivery_signstring用配送公司侧提供的appSecret加密的校验串

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_query_order_status,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述
                      order_statusnumber当前订单状态,枚举值
                      action_msgstring附加信息
                      waybill_idstring配送单id


                      immediateDelivery.onOrderReAdd

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      在调用下单接口后,订单被取消或者投递异常的情况下,调用此接口重新下单

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_readd_order,不区分大小写
                      wx_tokenstring微信订单 Token。请保存该Token,调用更新配送单状态接口(updateOrder)时需要传入
                      delivery_tokenstring配送公司侧在预下单时候返回的token,用于保证运费不变
                      shopidstring商家id, 由配送公司分配的appkey
                      shop_nostring商家门店编号, 在配送公司侧登记
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      delivery_signstring用配送公司侧提供的appSecret加密的校验串
                      senderObject发件人信息,如果配送公司能从shopid+shop_no对应到门店地址,则不需要填写,否则需填写
                      receiverObject收件人信息
                      cargoObject货物信息
                      order_infoObject订单信息

                      sender 的结构

                      属性类型说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      receiver 的结构

                      属性类型说明
                      namestring姓名,最长不超过256个字符
                      citystring城市名称,如广州市
                      addressstring地址(街道、小区、大厦等,用于定位)
                      address_detailstring地址详情(楼号、单元号、层号)
                      phonestring电话/手机号,最长不超过64个字符
                      lngnumber经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,确到小数点后6位
                      latnumber纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用,精确到小数点后6位)
                      coordinate_typenumber坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标

                      cargo 的结构

                      属性类型说明
                      goods_valuenumber货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-5000]
                      goods_heightnumber货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-45]
                      goods_lengthnumber货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-65]
                      goods_widthnumber货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_weightnumber货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为(0-50]
                      goods_detailObject货物详情,最长不超过10240个字符
                      goods_pickup_infostring货物取货信息,用于骑手到店取货,最长不超过100个字符
                      goods_delivery_infostring货物交付信息,最长不超过100个字符
                      cargo_first_classstring品类一级类目, 详见品类表
                      cargo_second_classstring品类二级类目

                      goods_detail 的结构

                      属性类型说明
                      goodsArray.<Object>货物列表

                      goods 的结构

                      属性类型说明
                      good_countnumber货物数量
                      good_namestring货品名称
                      good_pricenumber货品单价,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数)
                      good_unitstring货品单位,最长不超过20个字符

                      order_info 的结构

                      属性类型说明
                      delivery_service_codestring配送服务代码 不同配送公司自定义, 顺丰和达达不填
                      order_typenumber订单类型, 0: 即时单 1 预约单,如预约单,需要设置expected_delivery_time或expected_finish_time或expected_pick_time
                      expected_delivery_timenumber期望派单时间(达达支持,表示达达系统调度时间, 到那个时间才会有状态更新的回调通知),unix-timestamp, 比如1586342180
                      expected_finish_timenumber期望送达时间(美团、顺丰同城急送支持),unix-timestamp, 比如1586342180
                      expected_pick_timenumber期望取件时间(闪送、顺丰同城急送支持,闪送需要设置两个小时后的时间,顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可,同时都传则以expected_finish_time为准),unix-timestamp, 比如1586342180
                      poi_seqstring门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
                      notestring备注,最长不超过200个字符
                      order_timenumber用户下单付款时间, 顺丰必填, 比如1555220757
                      is_insurednumber是否保价,0,非保价,1.保价
                      declared_valuenumber保价金额,单位为元,精确到分
                      tipsnumber小费,单位为元, 下单一般不加小费
                      is_direct_deliverynumber是否选择直拿直送(0:不需要;1:需要。选择直拿直送后,同一时间骑手只能配送此订单至完成,配送费用也相应高一些,闪送必须选1,达达可选0或1,其余配送公司不支持直拿直送)
                      cash_on_deliverynumber骑手应付金额,单位为元,精确到分
                      cash_on_pickupnumber骑手应收金额,单位为元,精确到分
                      rider_pick_methodnumber物流流向,1:从门店取件送至用户;2:从用户取件送至门店
                      is_finish_code_needednumber收货码(0:不需要;1:需要。收货码的作用是:骑手必须输入收货码才能完成订单妥投)
                      is_pickup_code_needednumber取货码(0:不需要;1:需要。取货码的作用是:骑手必须输入取货码才能从商家取货)

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_readd_order,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述
                      feenumber实际运费(单位:元),运费减去优惠券费用
                      deliverfeenumber运费(单位:元)
                      couponfeenumber优惠券费用(单位:元)
                      tipsnumber小费(单位:元)
                      insurancefeenumber保价费(单位:元)
                      distancenumber配送距离(单位:米)
                      waybill_idstring配送单号, 可以在API1更新配送单状态异步返回
                      order_statusnumber配送单状态
                      finish_codenumber收货码
                      pickup_codenumber取货码
                      dispatch_durationnumber预计骑手接单时间,单位秒,比如5分钟,就填300, 无法预计填0
                      sender_lngnumber发货方经度,火星坐标,精确到小数点后6位, 用于消息通知,如果下单请求里有发货人信息则不需要
                      sender_latnumber发货方纬度,火星坐标,精确到小数点后6位, 用于消息通知,如果下单请求里有发货人信息则不需要


                      immediateDelivery.onPreAuthCodeGet

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      获取预授权码

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 get_pre_auth_code,不区分大小写
                      wx_appidstring发起授权的商户小程序appid

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 get_pre_auth_code,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述
                      pre_auth_codestring预授权码


                      immediateDelivery.onRiderScoreSet

                      本文档描述服务器端接收的消息或事件,详细说明参见消息推送

                      给骑手评分

                      消息参数

                      Object

                      属性类型说明
                      ToUserNamestring快递公司小程序 UserName
                      FromUserNamestring微信团队的 OpenID (固定值)
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_set_rider_score,不区分大小写
                      shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司侧登记
                      waybill_idstring配送单id
                      delivery_ontime_scorenumber配送准时分数,范围 1 - 5
                      cargo_intact_scorenumber货物完整分数,范围1-5
                      attitude_scorenumber服务态度分数 范围1-5

                      消息返回

                      属性类型默认值必填说明
                      ToUserNamestring原样返回请求中的 FromUserName
                      FromUserNamestring快递公司小程序 UserName
                      CreateTimenumber事件时间,Unix时间戳
                      MsgTypestring消息类型,固定为 event
                      Eventstring事件类型,固定为 transport_set_rider_score,不区分大小写
                      resultcodenumber错误码
                      resultmsgstring错误描述


                      immediateDelivery.updateOrder

                      本接口应在服务器端调用,详细说明参见服务端API

                      配送公司更新配送单状态

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/express/local/delivery/update_order?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      wx_tokenstring下单事件中推送的wx_token字段
                      shopidstring商家id, 由配送公司分配,可以是dev_id或者appkey
                      shop_order_idstring唯一标识订单的 ID,由商户生成
                      shop_nostring商家门店编号, 在配送公司侧登记
                      waybill_idstring配送单id
                      action_timenumber状态变更时间点,Unix秒级时间戳
                      order_statusnumber订单状态,枚举值,下附枚举值列表及说明
                      action_msgstring附加信息
                      wxa_pathstring配送公司小程序跳转路径,用于用户收到消息会间接跳转到这个页面
                      agentObject骑手信息, 骑手接单时需返回
                      expected_delivery_timenumber预计送达时间戳, 骑手接单时需返回

                      agent 的结构

                      属性类型默认值必填说明
                      namestring骑手姓名
                      phonestring骑手电话
                      is_phone_encryptednumber0电话是否加密

                      返回值

                      Object

                      属性类型说明
                      resultcodenumber错误码
                      resultmsgstring错误描述


                      ocr.bankcard

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      本接口提供基于小程序的银行卡 OCR 识别

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cv/ocr/bankcard?type=MODE&img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      img_urlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息
                      numberstring银行卡号

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

                      拍摄图片样例

                      请求数据示例

                      示例1:

                      curl "https://api.weixin.qq.com/cv/ocr/bankcard?img_url= ENCODE_URL&access_token=ACCESS_TOCKEN"

                      示例2:

                      curl -F ‘img=@test.jpg’ “https://api.weixin.qq.com/cv/ocr/bankcard?access_token=ACCESS_TOCKEN”

                      返回数据示例

                      {  "errcode": "0",  "errmsg": "ok",  "id": "622213XXXXXXXXX"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.ocr.bankcard
                      需在 config.json 中配置 ocr.bankcard API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      img 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息
                      numberstring银行卡号

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

                      拍摄图片样例

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.bankcard({        type: 'photo',        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

                      // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.bankcard({  type: 'photo',  img: {    contentType: 'image/png',    value: Buffer  }})

                      返回数据示例

                      {  "errcode": "0",  "errmsg": "ok",  "id": "622213XXXXXXXXX"}


                      ocr.businessLicense

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      本接口提供基于小程序的营业执照 OCR 识别

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cv/ocr/bizlicense?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      img_urlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息
                      reg_numstring注册号
                      serialstring编号
                      legal_representativestring法定代表人姓名
                      enterprise_namestring企业名称
                      type_of_organizationstring组成形式
                      addressstring经营场所/企业住所
                      type_of_enterprisestring公司类型
                      business_scopestring经营范围
                      registered_capitalstring注册资本
                      paid_in_capitalstring实收资本
                      valid_periodstring营业期限
                      registered_datestring注册日期/成立日期
                      cert_positionstring营业执照位置
                      img_sizestring图片大小

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      返回字段仅包含当前营业执照图片中存在的字段,若对应字段不存在则不返回

                      拍摄图片样例

                      请求数据示例

                      示例1:

                      curl https://api.weixin.qq.com/cv/ocr/bizlicense?img_url= ENCODE_URL&access_token=ACCESS_TOCKEN

                      示例2:

                      curl -F ‘img=@test.jpg’“https://api.weixin.qq.com/cv/ocr/bizlicense?access_token=ACCESS_TOCKEN”

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "reg_num": "123123",                                                     //注册号    "serial": "123123",                                                      //编号    "legal_representative": "张三",                                          //法定代表人姓名    "enterprise_name": "XX饮食店",                                           //企业名称    "type_of_organization": "个人经营",                                      //组成形式    "address": "XX市XX区XX路XX号",                                           //经营场所/企业住所    "type_of_enterprise": "xxx",                                             //公司类型    "business_scope": "中型餐馆(不含凉菜、不含裱花蛋糕,不含生食海产品)。",  //经营范围    "registered_capital": "200万",                                           //注册资本    "paid_in_capital": "200万",                                              //实收资本    "valid_period": "2019年1月1日",                                          //营业期限    "registered_date": "2018年1月1日",                                       //注册日期/成立日期    "cert_position": {                                                       //营业执照位置        "pos": {            "left_top": {                "x": 155,                "y": 191            },            "right_top": {                "x": 725,                "y": 157            },            "right_bottom": {                "x": 743,                "y": 512            },            "left_bottom": {                "x": 164,                "y": 525            }        }    },    "img_size": {                                                            //图片大小        "w": 966,        "h": 728    }}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.ocr.businessLicense
                      需在 config.json 中配置 ocr.businessLicense API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      img 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息
                      regNumstring注册号
                      serialstring编号
                      legalRepresentativestring法定代表人姓名
                      enterpriseNamestring企业名称
                      typeOfOrganizationstring组成形式
                      addressstring经营场所/企业住所
                      typeOfEnterprisestring公司类型
                      businessScopestring经营范围
                      registeredCapitalstring注册资本
                      paidInCapitalstring实收资本
                      validPeriodstring营业期限
                      registeredDatestring注册日期/成立日期
                      certPositionstring营业执照位置
                      imgSizestring图片大小

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      返回字段仅包含当前营业执照图片中存在的字段,若对应字段不存在则不返回

                      拍摄图片样例

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.businessLicense({        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

                      // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.businessLicense({  img: {    contentType: 'image/png',    value: Buffer  }})

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "reg_num": "123123",                                                     //注册号    "serial": "123123",                                                      //编号    "legal_representative": "张三",                                          //法定代表人姓名    "enterprise_name": "XX饮食店",                                           //企业名称    "type_of_organization": "个人经营",                                      //组成形式    "address": "XX市XX区XX路XX号",                                           //经营场所/企业住所    "type_of_enterprise": "xxx",                                             //公司类型    "business_scope": "中型餐馆(不含凉菜、不含裱花蛋糕,不含生食海产品)。",  //经营范围    "registered_capital": "200万",                                           //注册资本    "paid_in_capital": "200万",                                              //实收资本    "valid_period": "2019年1月1日",                                          //营业期限    "registered_date": "2018年1月1日",                                       //注册日期/成立日期    "cert_position": {                                                       //营业执照位置        "pos": {            "left_top": {                "x": 155,                "y": 191            },            "right_top": {                "x": 725,                "y": 157            },            "right_bottom": {                "x": 743,                "y": 512            },            "left_bottom": {                "x": 164,                "y": 525            }        }    },    "img_size": {                                                            //图片大小        "w": 966,        "h": 728    }}


                      ocr.driverLicense

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      本接口提供基于小程序的驾驶证 OCR 识别

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cv/ocr/drivinglicense?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      img_urlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息
                      id_numstring证号
                      namestring姓名
                      sexstring性别
                      namestring姓名
                      addressstring地址
                      birth_datestring出生日期
                      issue_datestring初次领证日期
                      car_classstring准驾车型
                      valid_fromstring有效期限起始日
                      valid_tostring有效期限终止日
                      official_sealstring印章文构

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

                      拍摄图片样例

                      请求数据示例

                      示例1:

                      curl http://api.weixin.qq.com/cv/ocr/drivinglicense?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      示例2:

                      curl -F ‘img=@test.jpg’“http://api.weixin.qq.com/cv/ocr/drivinglicense?access_token=ACCESS_TOCKEN”

                      返回数据示例

                      { "errcode": 0, "errmsg": "ok", "id_num": "660601xxxxxxxx1234", "name": "张三", "sex": "男", "nationality": "中国", "address": "广东省东莞市xxxxx号", "birth_date": "1990-12-21", "issue_date": "2012-12-21", "car_class": "C1", "valid_from": "2018-07-06", "valid_to": "2020-07-01", "official_seal": "xx市公安局公安交通管理局"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.ocr.driverLicense
                      需在 config.json 中配置 ocr.driverLicense API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      img 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息
                      idNumstring证号
                      namestring姓名
                      sexstring性别
                      namestring姓名
                      addressstring地址
                      birthDatestring出生日期
                      issueDatestring初次领证日期
                      carClassstring准驾车型
                      validFromstring有效期限起始日
                      validTostring有效期限终止日
                      officialSealstring印章文构

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

                      拍摄图片样例

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.driverLicense({        type: 'photo',        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

                      // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.driverLicense({  type: 'photo',  img: {    contentType: 'image/png',    value: Buffer  }})

                      返回数据示例

                      { "errcode": 0, "errmsg": "ok", "id_num": "660601xxxxxxxx1234", "name": "张三", "sex": "男", "nationality": "中国", "address": "广东省东莞市xxxxx号", "birth_date": "1990-12-21", "issue_date": "2012-12-21", "car_class": "C1", "valid_from": "2018-07-06", "valid_to": "2020-07-01", "official_seal": "xx市公安局公安交通管理局"}


                      ocr.idcard

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      本接口提供基于小程序的身份证 OCR 识别

                      调用方式:

                      • HTTPS 调用
                      • 云调用
                      • 增量调用(加强版)

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cv/ocr/idcard?type=MODE&img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      img_urlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息
                      typestring正面或背面,Front / Back
                      valid_datestring有效期

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。更强的能力需求,可以走服务市场调用。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

                      拍摄图片样例

                      photo:拍照模型,带背景的图片(示例如下)

                      scan:扫描模式,不带背景的图片(示例如下)

                      请求数据示例

                      示例1:

                      curl https://api.weixin.qq.com/cv/ocr/idcard?type=photo&img_url= ENCODE_URL&access_token=ACCESS_TOCKEN

                      示例2:

                      curl -F ‘img=@test.jpg’“https://api.weixin.qq.com/cv/ocr/idcard?type=photo&access_token=ACCESS_TOCKEN”

                      返回数据示例

                      正面返回

                      {  "errcode": "0",  "errmsg": "ok",  "type": "Front",  "name": "张三",  "id": "123456789012345678",  "addr": "广东省广州市",  "gender": "男",  "nationality": "汉"}

                      背面返回

                      { "errcode": 0, "errmsg": "ok", "type": "Back", "valid_date": "20070105-20270105"}

                      常见错误码

                      错误码errmsg说明
                      -1system error系统错误,请稍后重试
                      101000invalid image url图片URL错误或拉取URL图像错误
                      101001certificate not found图片中无法找到证件
                      101002invalid image data图片数据无效

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.ocr.idcard
                      需在 config.json 中配置 ocr.idcard API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      img 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息
                      typestring正面或背面,Front / Back
                      validDatestring有效期

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。更强的能力需求,可以走服务市场调用。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

                      拍摄图片样例

                      photo:拍照模型,带背景的图片(示例如下)

                      scan:扫描模式,不带背景的图片(示例如下)

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.idcard({        type: 'photo',        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

                      // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.idcard({  type: 'photo',  img: {    contentType: 'image/png',    value: Buffer  }})

                      返回数据示例

                      正面返回

                      {  "errCode": 0,  "errMsg": "openapi.ocr.idcard:ok",  "type": "Front",  "name": "张三",  "id": "123456789012345678",  "addr": "广东省广州市",  "gender": "男",  "nationality": "汉"}

                      背面返回

                      {  "errCode": 0,  "errMsg": "openapi.ocr.idcard:ok",  "type": "Back",  "validDate": "20070105-20270105"}


                      ocr.printedText

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      本接口提供基于小程序的通用印刷体 OCR 识别

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cv/ocr/comm?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      img_urlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息
                      itemsstring识别结果
                      img_sizestring图片大小

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 通用印刷体OCR适用于屏幕截图、印刷体照片等场景

                      请求数据示例

                      示例1:

                      curl http://api.weixin.qq.com/cv/ocr/comm?img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      示例2:

                      curl -F ‘img=@test.jpg’“http://api.weixin.qq.com/cv/ocr/comm?access_token=ACCESS_TOCKEN”

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "items": [ //识别结果        {            "text": "腾讯",            "pos": {                "left_top": {                    "x": 575,                    "y": 519                },                "right_top": {                    "x": 744,                    "y": 519                },                "right_bottom": {                    "x": 744,                    "y": 532                },                "left_bottom": {                    "x": 573,                    "y": 532                }            }        },        {            "text": "微信团队",            "pos": {                "left_top": {                    "x": 670,                    "y": 516                },                "right_top": {                    "x": 762,                    "y": 517                },                "right_bottom": {                    "x": 762,                    "y": 532                },                "left_bottom": {                    "x": 670,                    "y": 531                }            }        }    ],    "img_size": { //图片大小        "w": 1280,        "h": 720    }}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.ocr.printedText
                      需在 config.json 中配置 ocr.printedText API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      img 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息
                      itemsstring识别结果
                      imgSizestring图片大小

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。 通用印刷体OCR适用于屏幕截图、印刷体照片等场景

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.printedText({        type: 'photo',        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

                      // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.printedText({  type: 'photo',  img: {    contentType: 'image/png',    value: Buffer  }})

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "items": [ //识别结果        {            "text": "腾讯",            "pos": {                "left_top": {                    "x": 575,                    "y": 519                },                "right_top": {                    "x": 744,                    "y": 519                },                "right_bottom": {                    "x": 744,                    "y": 532                },                "left_bottom": {                    "x": 573,                    "y": 532                }            }        },        {            "text": "微信团队",            "pos": {                "left_top": {                    "x": 670,                    "y": 516                },                "right_top": {                    "x": 762,                    "y": 517                },                "right_bottom": {                    "x": 762,                    "y": 532                },                "left_bottom": {                    "x": 670,                    "y": 531                }            }        }    ],    "img_size": { //图片大小        "w": 1280,        "h": 720    }}


                      ocr.vehicleLicense

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      本接口提供基于小程序的行驶证 OCR 识别

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cv/ocr/driving?type=MODE&img_url=ENCODE_URL&access_token=ACCESS_TOCKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      typestring图片识别模式,photo(拍照模式)或 scan(扫描模式)
                      img_urlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息
                      vehicle_typestring车辆类型
                      ownerstring所有人
                      addrstring住址
                      use_characterstring使用性质
                      modelstring品牌型号
                      vinstring车辆识别代
                      engine_numstring发动机号码
                      register_datestring注册日期
                      issue_datestring发证日期
                      plate_num_bstring车牌号码
                      recordstring号牌
                      passengers_numstring核定载人数
                      total_qualitystring总质量
                      totalprepare_quality_qualitystring整备质量

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

                      拍摄图片样例

                      请求数据示例

                      示例1:

                      curl https://api.weixin.qq.com/cv/ocr/driving?type=photo&img_url= ENCODE_URL&access_token=ACCESS_TOCKEN

                      示例2:

                      curl -F ‘img=@test.jpg’“https://api.weixin.qq.com/cv/ocr/driving?type=photo&access_token=ACCESS_TOCKEN”

                      返回数据示例

                      {"vhicle_type": "小型普通客⻋","owner": "东莞市xxxxx机械厂","addr": "广东省东莞市xxxxx号","use_character": "非营运","model": "江淮牌HFCxxxxxxx","vin": "LJ166xxxxxxxx51","engine_num": "J3xxxxx3","register_date": "2018-07-06","issue_date": "2018-07-01","plate_num_b": "粤xxxxx","record": "441xxxxxx3","passengers_num": "7人","total_quality": "2700kg","prepare_quality": "1995kg"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.ocr.vehicleLicense
                      需在 config.json 中配置 ocr.vehicleLicense API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      typestring图片识别模式,photo(拍照模式)或 scan(扫描模式)
                      imgUrlstring要检测的图片 url,传这个则不用传 img 参数。
                      imgFormDataform-data 中媒体文件标识,有filename、filelength、content-type等信息,传这个则不用传 img_url。

                      img 的结构

                      属性类型默认值必填说明
                      contentTypestring数据类型,传入 MIME Type
                      valueBuffer文件 Buffer

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息
                      vehicleTypestring车辆类型
                      ownerstring所有人
                      addrstring住址
                      useCharacterstring使用性质
                      modelstring品牌型号
                      vinstring车辆识别代
                      engineNumstring发动机号码
                      registerDatestring注册日期
                      issueDatestring发证日期
                      plateNumBstring车牌号码
                      recordstring号牌
                      passengersNumstring核定载人数
                      totalQualitystring总质量
                      totalprepareQualityQualitystring整备质量

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      使用说明

                      接口限制 内测期间已认证的订阅号、服务号、企业号、小程序可直接调用,次数限制为500次/天。

                      使用 Tips 此接口为后台接口,可基于自有业务承载情况,搭配小程序的拍照、相册选照等一起使用,即可完成身份证照片的采集、上传、识别、信息返回等流程,用于需要基于身份证、银行卡等实体卡或证,采集照片或文字信息等的业务场景。

                      图片说明 文件大小限制:小于2M

                      图片支持使用img参数实时上传,也支持使用img_url参数传送图片地址,由微信后台下载图片进行识别。type 有两种类型

                      拍摄图片样例

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.ocr.vehicleLicense({        type: 'photo',        imgUrl: 'ENCODE_URL'      })    return result  } catch (err) {    return err  }}

                      // cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.ocr.vehicleLicense({  type: 'photo',  img: {    contentType: 'image/png',    value: Buffer  }})

                      返回数据示例

                      {"vhicle_type": "小型普通客⻋","owner": "东莞市xxxxx机械厂","addr": "广东省东莞市xxxxx号","use_character": "非营运","model": "江淮牌HFCxxxxxxx","vin": "LJ166xxxxxxxx51","engine_num": "J3xxxxx3","register_date": "2018-07-06","issue_date": "2018-07-01","plate_num_b": "粤xxxxx","record": "441xxxxxx3","passengers_num": "7人","total_quality": "2700kg","prepare_quality": "1995kg"}


                      operation.getFeedback

                      本接口应在服务器端调用,详细说明参见服务端API

                      获取用户反馈列表

                      请求地址

                      GET https://api.weixin.qq.com/wxaapi/feedback/list?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      typenumber反馈的类型,默认拉取全部类型,详细定义见下面
                      pagenumber分页的页数,从1开始
                      numnumber分页拉取的数据数量

                      请求示例

                      {  "page":1,  "num":10}

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      listArray.<Object>反馈列表
                      total_numnumber总条数

                      反馈类型type的定义

                      说明
                      1无法打开小程序
                      2小程序闪退
                      3卡顿
                      4黑屏白屏
                      5死机
                      6界面错位
                      7界面加载慢
                      8其他异常

                      响应示例

                      {  "list": [      {          "record_id": 1,          "create_time": 1587571200,          "content": "白屏了",          "phone": 18800000000,          "openid": "openidxxxxxx",          "nickname": "反馈用户昵称",          "head_url": "反馈用户头像",          "type": 1,          "systemInfo": "{}"      }  ],  "total_num": 100,  "errcode": 0}


                      operation.getJsErrSearch

                      本接口应在服务器端调用,详细说明参见服务端API

                      错误查询

                      请求地址

                      POST https://api.weixin.qq.com/wxaapi/log/jserr_search?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      errmsg_keywordstring错误关键字
                      typenumber查询类型,1 为客户端, 2为服务直达
                      client_versionstring客户端版本,可以通过 getVersionList 接口拉取, 不传或者传空代表所有版本
                      start_timenumber开始时间
                      end_timenumber结束时间
                      startnumber分页起始值
                      limitnumber一次拉取最大值

                      请求示例

                      {  "errmsg_keyword":"",  "type":1,  "client_version": "",  "start_time": 1587021734,  "end_time": 1587626534,  "start": 1,  "limit": 1  "sceneDesc": "测试数据"}

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      resultsArray.<Object>错误列表
                      totalnumber总条数

                      响应示例

                      {  "results": [      {          "time": 1587571200,          "client_version": "7.0.14",          "app_version": "2.8.21",          "version_error_cnt": 1,          "total_error_cnt": 1,          "errmsg": "setBackgroundAudioState:fail:src is null
                      Error: setBackgroundAudioState:fail:src is null
                          at fail (https://lib/WASubContext.js:2:876609)
                          at Object.fail (https://lib/WASubContext.js:2:115688)
                          at b (https://lib/WASubContext.js:2:431732)
                          at https://lib/WASubContext.js:2:432886
                      "      }  ],  "total": 91,  "errcode": 0}


                      operation.getPerformance

                      本接口应在服务器端调用,详细说明参见服务端API

                      性能监控

                      请求地址

                      POST https://api.weixin.qq.com/wxaapi/log/get_performance?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      cost_time_typenumber可选值 1(启动总耗时), 2(下载耗时),3(初次渲染耗时)
                      default_start_timenumber查询开始时间
                      default_end_timenumber查询结束时间
                      devicestring系统平台,可选值 "@_all:"(全部),1(IOS), 2(android)
                      is_download_codestring是否下载代码包,当 type 为 1 的时候才生效,可选值 "@_all:"(全部),1(是), 2(否)
                      scenestring访问来源,当 type 为 1 或者 2 的时候才生效,通过 getSceneList 接口获取
                      networktypestring网络环境, 当 type 为 2 的时候才生效,可选值 "@_all:",wifi, 4g, 3g, 2g

                      请求示例

                      {  "cost_time_type": 2,  "default_start_time": 1572339403,  "default_end_time": 1574931403,  "device": "@_all",  "networktype": "@_all",  "scene": "@_all",  "is_download_code": "@_all"}

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      default_time_datastring错误查询数据(json字符串,结构如下所述的 strbody)
                      compare_time_datastring比较数据

                      strbody 的结构

                      属性类型说明
                      ref_datestring日期
                      cost_time_typenumber意思同参数里面的 cost_time_type
                      cost_timenumber耗时(毫秒)

                      响应示例

                      {  "default_time_data": "{"list":[{"ref_date":"20191029","cost_time_type":2,"cost_time":1533},{"ref_date":"20191030","cost_time_type":2,"cost_time":1682}]}",  "compare_time_data": "",  "errcode": 0}


                      operation.getSceneList

                      本接口应在服务器端调用,详细说明参见服务端API

                      获取访问来源

                      请求地址

                      GET https://api.weixin.qq.com/wxaapi/log/get_scene?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      sceneArray.<Object>访问来源

                      scene 的结构

                      属性类型说明
                      namestring来源中文名
                      valuestring}number

                      响应示例

                      {   "errcode": 0,   "errmsg": "ok",   "scene": [      {          "name": "全部",          "value": "@_all"      },      {          "name": "小程序历史列表"          "value": 1      }   ]}


                      operation.getVersionList

                      本接口应在服务器端调用,详细说明参见服务端API

                      获取客户端版本

                      请求地址

                      GET https://api.weixin.qq.com/wxaapi/log/get_client_version?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      cvlistArray.<Object>版本列表

                      cvlist 的结构

                      属性类型说明
                      typenumber查询类型 1 代表客户端,2 代表服务直达
                      client_version_listArray.<String>版本列表

                      响应示例

                      {   "errcode": 0,   "errmsg": "ok",   "cvlist": [      {          "type": 1,          "client_version_list": []      },      {          "type": 2,          "client_version_list": []      }   ]}


                      operation.realtimelogSearch

                      本接口应在服务器端调用,详细说明参见服务端API

                      实时日志查询

                      请求地址

                      GET https://api.weixin.qq.com/wxaapi/userlog/userlog_search?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      datestringYYYYMMDD格式的日期,仅支持最近7天
                      begintimenumber开始时间,必须是date指定日期的时间
                      endtimenumber结束时间,必须是date指定日期的时间
                      startnumber0开始返回的数据下标,用作分页,默认为0
                      limitnumber20返回的数据条数,用作分页,默认为20
                      traceIdstring小程序启动的唯一ID,按TraceId查询会展示该次小程序启动过程的所有页面的日志。
                      urlstring小程序页面路径,例如pages/index/index
                      idstring用户微信号或者OpenId
                      filterMsgstring开发者通过setFileterMsg/addFilterMsg指定的filterMsg字段
                      levelnumber日志等级,返回大于等于level等级的日志,level的定义为2(Info)、4(Warn)、8(Error),如果指定为4,则返回大于等于4的日志,即返回Warn和Error日志。

                      返回值

                      Object

                      属性类型说明
                      dataObject返回的日志数据和日志条数总量
                      listArray.<Object>返回的日志数据列表
                      errcodenumber微信侧错误码,下单失败时返回
                      errmsgstring微信侧错误信息,下单失败时返回

                      list 的结构

                      属性类型说明
                      levelnumber日志等级,是msg数组里面的所有level字段的或操作得到的结果。例如msg数组里有两条日志,Info(值为2)和Warn(值为4),则level值为6
                      libraryVersionstring基础库版本
                      clientVersionstring客户端版本
                      idstring微信用户OpenID
                      timestampnumber打日志的Unix时间戳
                      platformnumber1 安卓 2 IOS
                      urlstring小程序页面链接
                      msgArray.<Object>日志内容数组,log.info等的内容存在这里
                      traceidstring小程序启动的唯一ID,按TraceId查询会展示该次小程序启动过程的所有页面的日志。
                      filterMsgstring微信用户OpenID

                      list.msg 的结构

                      属性类型说明
                      timenumberlog.info调用的时间
                      msgArray.<string>log.info调用的内容,每个参数分别是数组的一项
                      levelnumberlog.info调用的日志等级

                      errcode 的合法值

                      说明最低版本
                      -1系统失败
                      200002参数错误,date、begintime、endtime必填。date只能是最近三天的日期,endtime必须大于begintime
                      200010操作过于频繁,目前限制每分钟50次
                      200007无权限

                      返回示例

                      查询成功 { "errcode": 0, "errmsg": "", "data": { "list": [{ "level": 6, "platform": 1, "libraryVersion": "2.8.3", "clientVersion": "7.0.7", "id": "oXu034-Kl5Et2U0vsexKDsFaon0Q", "timestamp": 1570852796, "msg": [{ "time": 1570852795, "msg": ["hello world"], "level": 2 }, { "time": 1570852795, "msg": ["get msg list mig 10006"], "level": 4 }], "url": "pages/chat/chat", "traceid": "oXu03410akoNqfsrMMswk6Zwwl1U_1570852656", "filterMsg": "NetworkExceed08 ReportTimeTotal" }], "total": 1000 } }


                      search.imageSearch

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      本接口提供基于小程序的站内搜商品图片搜索能力

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/imagesearch?access_token=TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      imgArray.<FormData>form-data中媒体文件标识,有filename、filelength、content-type等信息

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息
                      itemsArray.<Object>搜索结果列表

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统繁忙,此时请开发者稍候再试
                      41005获取图片数据失败,请检查图片数据格式

                      items 的结构

                      属性类型说明
                      titlestring小程序商品页面标题
                      img_urlstring小程序商品页面主图url
                      pricestring小程序商品页面价格
                      pathstring小程序商品页面地址

                      请求示例

                      curl -F 'img=@test.jpg' "https://api.weixin.qq.com/wxa/imagesearch?access_token=TOKEN"

                      云调用请求示例

                      // javascript// cloud = require('wx-server-sdk')// ...// 方法返回 Promisecloud.openapi.search.imageSearch({  img: {     contentType: 'image/png',     value: Buffer  }})

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.search.imageSearch
                      需在 config.json 中配置 search.imageSearch API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      imgArray.<FormData>form-data中媒体文件标识,有filename、filelength、content-type等信息

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息
                      itemsArray.<Object>搜索结果列表

                      errCode 的合法值

                      说明最低版本
                      0成功

                      items 的结构

                      属性类型说明
                      titlestring小程序商品页面标题
                      imgUrlstring小程序商品页面主图url
                      pricestring小程序商品页面价格
                      pathstring小程序商品页面地址

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值


                      说明最低版本
                      -1系统繁忙,此时请开发者稍候再试
                      41005获取图片数据失败,请检查图片数据格式


                      search.siteSearch

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      小程序内部搜索API提供针对页面的查询能力,小程序开发者输入搜索词后,将返回自身小程序和搜索词相关的页面。因此,利用该接口,开发者可以查看指定内容的页面被微信平台的收录情况;同时,该接口也可供开发者在小程序内应用,给小程序用户提供搜索能力。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/sitesearch?access_token=TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      keywordstring关键词
                      next_page_infostring请求下一页的参数,开发者无需理解。为空时查询的是第一页内容,如需查询下一页,把返回参数的next_page_info填充到这里即可

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息
                      itemsArray.<Object>搜索结果列表
                      has_next_pageboolean是否有下一页
                      next_page_infostring请求下一页的参数,开发者无需理解,如需查询下一页结果,把该参数填充到下页请求参数中的next_page_info即可
                      hit_countnumber估算索引文档数

                      errcode 的合法值

                      说明最低版本
                      -1系统繁忙,此时请开发者稍候再试
                      47101搜索结果总数超过了1000条
                      47102next_page_info参数错误

                      items 的结构

                      属性类型说明
                      titlestring小程序页面标题
                      descriptionstring小程序页面摘要
                      imagestring小程序页面代表图
                      pathstring小程序页面路径

                      使用示例

                      curl -d '{    "query": "微信",    "next_page_info": ""}' https://api.weixin.qq.com/wxa/sitesearch?access_token=TOKEN

                      调用成功时的返回示例

                      {    "errcode":0,    "errmsg":"ok",    "items": [        {            "title": "<em class="highlight">微信</em>版本更新!",            "description": "...今日,<em class="highlight">微信</em>官方发布<em class="highlight">微信</em>X.Y.Z版本...",            "image": "http://image.weixin.qq.com/1.jpeg",            "path": "pages/normal/index?id=20191210A0C29X00"        },        {            "title": "<em class="highlight">微信</em>小程序发布新功能!",            "description": "<em class="highlight">微信</em>小程序发布了XXX功能...",            "image": "http://image.weixin.qq.com/2.jpeg",            "path": "pages/normal/index?id=20191210A0C29X11"        },    ],    "has_next_page": 1,    "hit_count": 100,    "next_page_info":"eyJwYWdlX3BhcmFtIjpbeyJzdWJzeXNfdHlwZSI6MTAsInNlcnZlcl9vZmZzZXQiOjAsInNlcnZlcl9saW1pdCI6MTIwLCJpbmRleF9zdGVwIjoyMCwiaW5kZXhfb2Zmc2V0IjoyMH1dLCJjbGllbnRfb2Zmc2V0IjowLCJjbGllbnRfbGltaXQiOjEwfQ=="}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.search.siteSearch
                      需在 config.json 中配置 search.siteSearch API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      keywordstring关键词
                      nextPageInfostring请求下一页的参数,开发者无需理解。为空时查询的是第一页内容,如需查询下一页,把返回参数的next_page_info填充到这里即可

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息
                      itemsArray.<Object>搜索结果列表
                      hasNextPageboolean是否有下一页
                      nextPageInfostring请求下一页的参数,开发者无需理解,如需查询下一页结果,把该参数填充到下页请求参数中的next_page_info即可
                      hitCountnumber估算索引文档数

                      errCode 的合法值

                      说明最低版本
                      0成功

                      items 的结构

                      属性类型说明
                      titlestring小程序页面标题
                      descriptionstring小程序页面摘要
                      imagestring小程序页面代表图
                      pathstring小程序页面路径

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值


                      说明最低版本
                      -1系统繁忙,此时请开发者稍候再试
                      47101搜索结果总数超过了1000条
                      47102next_page_info参数错误


                      search.submitPages

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      小程序开发者可以通过本接口提交小程序页面url及参数信息,让微信可以更及时的收录到小程序的页面信息,开发者提交的页面信息将可能被用于小程序搜索结果展示。

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/search/wxaapi_submitpages?access_token=TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      pagesArray.<Object>小程序页面信息列表

                      pages 的结构

                      属性类型默认值必填说明
                      pathstring页面路径
                      querystring页面参数

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodestring错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      -1系统繁忙,此时请开发者稍候再试
                      0请求成功
                      40066递交的页面被sitemap标记为拦截,具体查看errmsg提示。
                      40210pages 中的path参数不存在或为空
                      40212paegs 当中存在不合法的query,query格式遵循URL标准,即k1=v1&k2=v2
                      40219pages不存在或者参数为空
                      47001http请求包不是合法的JSON
                      47004每次提交的页面数超过1000(备注:每次提交页面数应小于或等于1000)
                      47006当天提交页面数达到了配额上限,请明天再试
                      85091小程序的搜索开关被关闭。请访问设置页面打开开关再重试
                      85083小程序的搜索功能被禁用

                      请求示例

                      curl -d '{    "pages": [        {            "path": "pages/index/index",            "query": "userName=wechat_user"        },        {            "path": "pages/video/index",            "query": "vid=123"        }    ]}' https://api.weixin.qq.com/wxa/search/wxaapi_submitpages?access_token=TOKEN

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.search.submitPages
                      需在 config.json 中配置 search.submitPages API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      pagesArray.<Object>小程序页面信息列表

                      pages 的结构

                      属性类型默认值必填说明
                      pathstring页面路径
                      querystring页面参数

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodestring错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      -1系统繁忙,此时请开发者稍候再试
                      40066递交的页面被sitemap标记为拦截,具体查看errmsg提示。
                      40210pages 中的path参数不存在或为空
                      40212paegs 当中存在不合法的query,query格式遵循URL标准,即k1=v1&k2=v2
                      40219pages不存在或者参数为空
                      47001http请求包不是合法的JSON
                      47004每次提交的页面数超过1000(备注:每次提交页面数应小于或等于1000)
                      47006当天提交页面数达到了配额上限,请明天再试
                      85091小程序的搜索开关被关闭。请访问设置页面打开开关再重试
                      85083小程序的搜索功能被禁用


                      serviceMarket.invokeService

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      调用服务平台提供的服务

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxa/servicemarket?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      servicestring服务 ID
                      apistring接口名
                      datastring服务提供方接口定义的 JSON 格式的数据
                      client_msg_idstring随机字符串 ID,调用方请求的唯一标识

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      template_idstring添加至帐号下的模板id,发送小程序模板消息时所需

                      请求数据示例

                      {  "service" : "wx79ac3de8be320b71",  "api" : "OcrAllInOne",  "data" : {    "img_url": "http://mmbiz.qpic.cn/mmbiz_jpg/7UFjuNbYxibu66xSqsQqKcuoGBZM77HIyibdiczeWibdMeA2XMt5oibWVQMgDibriazJSOibLqZxcO6DVVcZMxDKgeAtbQ/0",    "data_type": 3,    "ocr_type": 1  },  "client_msg_id" : "id123"}

                      返回数据示例

                      { "errcode": 0, "errmsg": "ok", "data": "{"idcard_res":{"type":0,"name":{"text":"abc","pos"…0312500}}},"image_width":480,"image_height":304}}"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.serviceMarket.invokeService
                      需在 config.json 中配置 serviceMarket.invokeService API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      servicestring服务 ID
                      apistring接口名
                      datastring服务提供方接口定义的 JSON 格式的数据
                      clientMsgIdstring随机字符串 ID,调用方请求的唯一标识

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息
                      templateIdstring添加至帐号下的模板id,发送小程序模板消息时所需

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      请求数据示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.serviceMarket.invokeService({        service: 'wx79ac3de8be320b71',        api: 'OcrAllInOne',        data: {          imgUrl: 'http://mmbiz.qpic.cn/mmbiz_jpg/7UFjuNbYxibu66xSqsQqKcuoGBZM77HIyibdiczeWibdMeA2XMt5oibWVQMgDibriazJSOibLqZxcO6DVVcZMxDKgeAtbQ/0',          dataType: 3,          ocrType: 1        },        clientMsgId: 'id123'      })    return result  } catch (err) {    return err  }}

                      返回数据示例

                      {  "errCode": 0,  "errMsg": "openapi.serviceMarket.invokeService:ok",  "data": "{"idcardRes":{"type":0,"name":{"text":"abc","pos"…0312500}}},"imageWidth":480,"imageHeight":304}}"}


                      soter.verifySignature

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      SOTER 生物认证秘钥签名验证

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/soter/verify_signature?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      openidstring用户 openid
                      json_stringstring通过 wx.startSoterAuthentication 成功回调获得的 resultJSON 字段
                      json_signaturestring通过 wx.startSoterAuthentication 成功回调获得的 resultJSONSignature 字段

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errmsgstring错误信息
                      errcodenumber错误码
                      is_okboolean验证结果

                      请求示例

                      {  "openid": "$openid",  "json_string": "$resultJSON",  "json_signature": "$resultJSONSignature"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.soter.verifySignature
                      需在 config.json 中配置 soter.verifySignature API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      openidstring用户 openid
                      jsonStringstring通过 wx.startSoterAuthentication 成功回调获得的 resultJSON 字段
                      jsonSignaturestring通过 wx.startSoterAuthentication 成功回调获得的 resultJSONSignature 字段

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errMsgstring错误信息
                      errCodenumber错误码
                      isOkboolean验证结果

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errMsgstring错误信息
                      errCodenumber错误码

                      errCode 的合法值

                      说明最低版本

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.soter.verifySignature({        openid: '$openid',        jsonString: '$resultJSON',        jsonSignature: '$resultJSONSignature'      })    return result  } catch (err) {    return err  }}


                      subscribeMessage.addTemplate

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      组合模板并添加至帐号下的个人模板库

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxaapi/newtmpl/addtemplate?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      tidstring模板标题 id,可通过接口获取,也可登录小程序后台查看获取
                      kidListArray.<number>开发者自行组合好的模板关键词列表,关键词顺序可以自由搭配(例如 [3,5,4] 或 [4,5,3]),最多支持5个,最少2个关键词组合
                      sceneDescstring服务场景描述,15个字以内

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      priTmplIdstring添加至帐号下的模板id,发送小程序订阅消息时所需

                      errcode 的合法值

                      说明最低版本
                      200014模版 tid 参数错误
                      200020关键词列表 kidList 参数错误
                      200021场景描述 sceneDesc 参数错误
                      200011此账号已被封禁,无法操作
                      200013此模版已被封禁,无法选用
                      200012个人模版数已达上限,上限25个

                      请求示例

                      content-type: application/json;

                      {  "tid":"401",  "kidList":[1,2],  "sceneDesc": "测试数据"}

                      响应示例

                      {  "errmsg": "ok",  "errcode": 0,  "priTmplId": "9Aw5ZV1j9xdWTFEkqCpZ7jWySL7aGN6rQom4gXINfJs"}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.subscribeMessage.addTemplate
                      需在 config.json 中配置 subscribeMessage.addTemplate API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      tidstring模板标题 id,可通过接口获取,也可登录小程序后台查看获取
                      kidListArray.<number>开发者自行组合好的模板关键词列表,关键词顺序可以自由搭配(例如 [3,5,4] 或 [4,5,3]),最多支持5个,最少2个关键词组合
                      sceneDescstring服务场景描述,15个字以内

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息
                      priTmplIdstring添加至帐号下的模板id,发送小程序订阅消息时所需

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      200014模版 tid 参数错误
                      200020关键词列表 kidList 参数错误
                      200021场景描述 sceneDesc 参数错误
                      200011此账号已被封禁,无法操作
                      200013此模版已被封禁,无法选用
                      200012个人模版数已达上限,上限25个

                      请求示例

                      content-type: application/json;

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.addTemplate({        tid: '401',        kidList: [          1,          2        ],        sceneDesc: '测试数据'      })    return result  } catch (err) {    return err  }}

                      响应示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.addTemplate({        errmsg: 'ok',        errcode: 0,        priTmplId: '9Aw5ZV1j9xdWTFEkqCpZ7jWySL7aGN6rQom4gXINfJs'      })    return result  } catch (err) {    return err  }}


                      subscribeMessage.deleteTemplate

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      删除帐号下的个人模板

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/wxaapi/newtmpl/deltemplate?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      priTmplIdstring要删除的模板id

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      请求示例

                      content-type: application/json;

                      {  "priTmplId": "wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc"}

                      响应示例

                      {  "errmsg": "ok",  "errcode": 0}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.subscribeMessage.deleteTemplate
                      需在 config.json 中配置 subscribeMessage.deleteTemplate API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      priTmplIdstring要删除的模板id

                      请求示例

                      content-type: application/json;

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.deleteTemplate({        priTmplId: 'wDYzYZVxobJivW9oMpSCpuvACOfJXQIoKUm0PY397Tc'      })    return result  } catch (err) {    return err  }}

                      响应示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.deleteTemplate({        errmsg: 'ok',        errcode: 0      })    return result  } catch (err) {    return err  }}


                      subscribeMessage.getCategory

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取小程序账号的类目

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/wxaapi/newtmpl/getcategory?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      dataArray.<Object>类目列表

                      data 的结构

                      属性类型说明
                      idnumber类目id,查询公共库模版时需要
                      namestring类目的中文名

                      响应示例

                      {   "errcode": 0,   "errmsg": "ok",   "data": [       {           "id": 616,           "name": "公交"       }   ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.subscribeMessage.getCategory
                      需在 config.json 中配置 subscribeMessage.getCategory API 的权限,详情

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getCategory({})    return result  } catch (err) {    return err  }}

                      响应示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getCategory({        errcode: 0,        errmsg: 'ok',        data: [          {            id: 616,            name: '公交'          }        ]      })    return result  } catch (err) {    return err  }}


                      subscribeMessage.getPubTemplateKeyWordsById

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取模板标题下的关键词列表

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatekeywords?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      tidstring模板标题 id,可通过接口获取

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      countnumber模版标题列表总数
                      dataArray.<Object>关键词列表

                      data 的结构

                      属性类型说明
                      kidnumber关键词 id,选用模板时需要
                      namestring关键词内容
                      examplestring关键词内容对应的示例
                      rulestring参数类型

                      请求示例

                      {  "tid": "99"}

                      响应示例

                      {   "errcode": 0,   "errmsg": "ok",   "data": [       {           "kid": 1,           "name": "物品名称",           "example": "名称",           "rule": "thing"       }   ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.subscribeMessage.getPubTemplateKeyWordsById
                      需在 config.json 中配置 subscribeMessage.getPubTemplateKeyWordsById API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      tidstring模板标题 id,可通过接口获取

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息
                      countnumber模版标题列表总数
                      dataArray.<Object>关键词列表

                      data 的结构

                      属性类型说明
                      kidnumber关键词 id,选用模板时需要
                      namestring关键词内容
                      examplestring关键词内容对应的示例
                      rulestring参数类型

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getPubTemplateKeyWordsById({        tid: ''      })    return result  } catch (err) {    return err  }}

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getPubTemplateKeyWordsById({        tid: '99'      })    return result  } catch (err) {    return err  }}

                      响应示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getPubTemplateKeyWordsById({        errcode: 0,        errmsg: 'ok',        data: [          {            kid: 1,            name: '物品名称',            example: '名称',            rule: 'thing'          }        ]      })    return result  } catch (err) {    return err  }}


                      subscribeMessage.getPubTemplateTitleList

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取帐号所属类目下的公共模板标题

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/wxaapi/newtmpl/getpubtemplatetitles?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      idsstring类目 id,多个用逗号隔开
                      startnumber用于分页,表示从 start 开始。从 0 开始计数。
                      limitnumber用于分页,表示拉取 limit 条记录。最大为 30。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      countnumber模版标题列表总数
                      dataArray.<Object>模板标题列表

                      errcode 的合法值

                      说明最低版本
                      200016start 参数错误
                      200017limit 参数错误
                      200018类目 ids 缺失
                      200019类目 ids 不合法

                      data 的结构

                      属性类型说明
                      tidnumber模版标题 id
                      titlestring模版标题
                      typenumber模版类型,2 为一次性订阅,3 为长期订阅
                      categoryIdnumber模版所属类目 id

                      请求示例

                      {  "ids": "2,616",  "start": 0,  "limit": 1}

                      响应示例

                      {   "errcode": 0,   "errmsg": "ok",   "count": 55,   "data": [       {           "tid": 99,           "title": "付款成功通知",           "type": 2,           "categoryId": "616"       }   ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.subscribeMessage.getPubTemplateTitleList
                      需在 config.json 中配置 subscribeMessage.getPubTemplateTitleList API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      idsstring类目 id,多个用逗号隔开
                      startnumber用于分页,表示从 start 开始。从 0 开始计数。
                      limitnumber用于分页,表示拉取 limit 条记录。最大为 30。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息
                      countnumber模版标题列表总数
                      dataArray.<Object>模板标题列表

                      errCode 的合法值

                      说明最低版本
                      0成功

                      data 的结构

                      属性类型说明
                      tidnumber模版标题 id
                      titlestring模版标题
                      typenumber模版类型,2 为一次性订阅,3 为长期订阅
                      categoryIdnumber模版所属类目 id

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      200016start 参数错误
                      200017limit 参数错误
                      200018类目 ids 缺失
                      200019类目 ids 不合法

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getPubTemplateTitleList({        ids: '',        start: '',        limit: ''      })    return result  } catch (err) {    return err  }}

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getPubTemplateTitleList({        ids: '2,616',        start: 0,        limit: 1      })    return result  } catch (err) {    return err  }}

                      响应示例

                      {  "errCode": 0,  "errMsg": "openapi.subscribeMessage.getPubTemplateTitleList:ok",  "count": 55,  "data": [    {      "tid": 99,      "title": "付款成功通知",      "type": 2,      "categoryId": "616"    }  ]}


                      subscribeMessage.getTemplateList

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      获取当前帐号下的个人模板列表

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      GET https://api.weixin.qq.com/wxaapi/newtmpl/gettemplate?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      dataArray.<Object>个人模板列表

                      data 的结构

                      属性类型说明
                      priTmplIdstring添加至帐号下的模板 id,发送小程序订阅消息时所需
                      titlestring模版标题
                      contentstring模版内容
                      examplestring模板内容示例
                      typenumber模版类型,2 为一次性订阅,3 为长期订阅

                      响应示例

                      {   "errcode": 0,   "errmsg": "ok",   "data": [       {          "priTmplId": "9Aw5ZV1j9xdWTFEkqCpZ7mIBbSC34khK55OtzUPl0rU",          "title": "报名结果通知",          "content": "会议时间:{{date2.DATA}}
                      会议地点:{{thing1.DATA}}
                      ",          "example": "会议时间:2016年8月8日
                      会议地点:TIT会议室
                      ",          "type": 2       }   ]}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.subscribeMessage.getTemplateList
                      需在 config.json 中配置 subscribeMessage.getTemplateList API 的权限,详情

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息
                      dataArray.<Object>个人模板列表

                      data 的结构

                      属性类型说明
                      priTmplIdstring添加至帐号下的模板 id,发送小程序订阅消息时所需
                      titlestring模版标题
                      contentstring模版内容
                      examplestring模板内容示例
                      typenumber模版类型,2 为一次性订阅,3 为长期订阅

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getTemplateList({})    return result  } catch (err) {    return err  }}

                      响应示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.getTemplateList({        errcode: 0,        errmsg: 'ok',        data: [          {            priTmplId: '9Aw5ZV1j9xdWTFEkqCpZ7mIBbSC34khK55OtzUPl0rU',            title: '报名结果通知',            content: '会议时间:{{date2.DATA}}
                      会议地点:{{thing1.DATA}}
                      ',            example: '会议时间:2016年8月8日
                      会议地点:TIT会议室
                      ',            type: 2          }        ]      })    return result  } catch (err) {    return err  }}


                      subscribeMessage.send

                      本接口应在服务器端调用,详细说明参见服务端API
                      本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载
                      wx-server-sdk >= 0.4.0

                      发送订阅消息

                      调用方式:

                      • HTTPS 调用
                      • 云调用

                      HTTPS 调用

                      请求地址

                      POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      touserstring接收者(用户)的 openid
                      template_idstring所需下发的订阅模板id
                      pagestring点击模板卡片后的跳转页面,仅限本小程序内的页面。支持带参数,(示例index?foo=bar)。该字段不填则模板无跳转。
                      dataObject模板内容,格式形如 { "key1": { "value": any }, "key2": { "value": any } }
                      miniprogram_statestring跳转小程序类型:developer为开发版;trial为体验版;formal为正式版;默认为正式版
                      langstring进入小程序查看”的语言类型,支持zh_CN(简体中文)、en_US(英文)、zh_HK(繁体中文)、zh_TW(繁体中文),默认为zh_CN

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      40003touser字段openid为空或者不正确
                      40037订阅模板id为空不正确
                      43101用户拒绝接受消息,如果用户之前曾经订阅过,则表示用户取消了订阅关系
                      47003模板参数不准确,可能为空或者不满足规则,errmsg会提示具体是哪个字段出错
                      41030page路径不正确,需要保证在现网版本小程序中存在,与app.json保持一致

                      接口限制

                      次数限制:开通支付能力的是3kw/日,没开通的是1kw/日。

                      请求示例

                      {  "touser": "OPENID",  "template_id": "TEMPLATE_ID",  "page": "index",  "miniprogram_state":"developer",  "lang":"zh_CN",  "data": {      "number01": {          "value": "339208499"      },      "date01": {          "value": "2015年01月05日"      },      "site01": {          "value": "TIT创意园"      } ,      "site02": {          "value": "广州市新港中路397号"      }  }}

                      订阅消息参数值内容限制说明

                      参数类别参数说明参数值限制说明
                      thing.DATA事物20个以内字符可汉字、数字、字母或符号组合
                      number.DATA数字32位以内数字只能数字,可带小数
                      letter.DATA字母32位以内字母只能字母
                      symbol.DATA符号5位以内符号只能符号
                      character_string.DATA字符串32位以内数字、字母或符号可数字、字母或符号组合
                      time.DATA时间24小时制时间格式(支持+年月日),支持填时间段,两个时间点之间用“~”符号连接例如:15:01,或:2019年10月1日 15:01
                      date.DATA日期年月日格式(支持+24小时制时间),支持填时间段,两个时间点之间用“~”符号连接例如:2019年10月1日,或:2019年10月1日 15:01
                      amount.DATA金额1个币种符号+10位以内纯数字,可带小数,结尾可带“元”可带小数
                      phone_number.DATA电话17位以内,数字、符号电话号码,例:+86-0766-66888866
                      car_number.DATA车牌8位以内,第一位与最后一位可为汉字,其余为字母或数字车牌号码:粤A8Z888挂
                      name.DATA姓名10个以内纯汉字或20个以内纯字母或符号中文名10个汉字内;纯英文名20个字母内;中文和字母混合按中文名算,10个字内
                      phrase.DATA汉字5个以内汉字5个以内纯汉字,例如:配送中

                      符号表示除中文、英文、数字外的常见符号,不能带有换行等控制字符。 时间格式支持HH:MM:SS或者HH:MM。 日期包含年月日,为y年m月d日,y年m月、m月d日格式,或者用‘-’、‘/’、‘.’符号连接,如2018-01-01,2018/01/01,2018.01.01,2018-01,01-01。 每个模板参数都会以类型为前缀,例如第一个数字模板参数为number01.DATA,第二个为number02.DATA

                      例如,模板的内容为

                      姓名: {{name01.DATA}}金额: {{amount01.DATA}}行程: {{thing01.DATA}}日期: {{date01.DATA}}

                      则对应的json为

                      {  "touser": "OPENID",  "template_id": "TEMPLATE_ID",  "page": "index",  "data": {      "name01": {          "value": "某某"      },      "amount01": {          "value": "¥100"      },      "thing01": {          "value": "广州至北京"      } ,      "date01": {          "value": "2018-01-01"      }  }}

                      云调用

                      云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

                      接口方法

                      openapi.subscribeMessage.send
                      需在 config.json 中配置 subscribeMessage.send API 的权限,详情

                      请求参数

                      属性类型默认值必填说明
                      touserstring接收者(用户)的 openid
                      templateIdstring所需下发的订阅模板id
                      pagestring点击模板卡片后的跳转页面,仅限本小程序内的页面。支持带参数,(示例index?foo=bar)。该字段不填则模板无跳转。
                      dataObject模板内容,格式形如 { "key1": { "value": any }, "key2": { "value": any } }
                      miniprogramStatestring跳转小程序类型:developer为开发版;trial为体验版;formal为正式版;默认为正式版
                      langstring进入小程序查看”的语言类型,支持zh_CN(简体中文)、en_US(英文)、zh_HK(繁体中文)、zh_TW(繁体中文),默认为zh_CN

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      0成功

                      异常

                      Object

                      抛出的异常

                      属性类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      errCode 的合法值

                      说明最低版本
                      40003touser字段openid为空或者不正确
                      40037订阅模板id为空不正确
                      43101用户拒绝接受消息,如果用户之前曾经订阅过,则表示用户取消了订阅关系
                      47003模板参数不准确,可能为空或者不满足规则,errmsg会提示具体是哪个字段出错
                      41030page路径不正确,需要保证在现网版本小程序中存在,与app.json保持一致

                      请求示例

                      const cloud = require('wx-server-sdk')cloud.init()exports.main = async (event, context) => {  try {    const result = await cloud.openapi.subscribeMessage.send({        touser: 'OPENID',        page: 'index',        lang: 'zh_CN',        data: {          number01: {            value: '339208499'          },          date01: {            value: '2015年01月05日'          },          site01: {            value: 'TIT创意园'          },          site02: {            value: '广州市新港中路397号'          }        },        templateId: 'TEMPLATE_ID',        miniprogramState: 'developer'      })    return result  } catch (err) {    return err  }}


                      为了帮助开发者简单和高效地开发微信小程序,我们推出了全新的开发者工具,集成了开发调试、代码编辑及程序发布等功能。

                      devtools

                      扫码登录


                      启动工具时,开发者需要使用已在后台绑定成功的微信号扫描二维码登录,后续所有的操作都会基于这个微信帐号

                      启动页

                      登录页

                      在登录页,可以使用微信扫码登陆开发者工具,开发者工具将使用这个微信帐号的信息进行小程序的开发和调试。

                      login

                      项目列表

                      登录成功后,会看到已经存在的项目列表和代码片段列表,
                      在项目列表可以选择公众号网页调试,进入到公众号网页调试模式
                      projectlist

                      新建项目

                      当符合以下条件时,可以在本地创建一个小程序项目

                      1. 需要一个小程序的 AppID;如没有 AppID,可以选择申请使用测试号。
                      2. 登录的微信号需要是该 AppID 的开发者;
                      3. 需要选择一个空目录,或者选择的非空目录下存在 app.json 或者 project.config.json。当选择空目录时,可以选择是否在该目录下生成一个简单的项目。

                      addproject

                      多开项目

                      工具支持同时打开多个项目,每次打开项目时会从新窗口打开,入口有以下几种:

                      1. 从项目选择页打开项目,处于项目窗口时可以从菜单栏的项目 -> 查看所有项目打开项目选择页
                      2. 从菜单栏的最近打开项目列表中打开的项目会从新窗口打开
                      3. 新建项目
                      4. 命令行或 HTTP 调用工具打开项目

                      管理项目

                      对本地项目进行删除和批量删除

                      projectmanage


                      主界面

                      开发者工具主界面,从上到下,从左到右,分别为:菜单栏、工具栏、模拟器、编辑器、调试器 五大部分。

                      parts

                      菜单栏

                      微信web开发者工具

                      切换帐号:快速切换登录用户关于:关于开发者工具检查更新:检查版本更新开发者论坛:前往开发者论坛开发者文档:前往开发者文档调试:调试开发者工具、调试编辑器;如果遇到疑似开发者工具或者编辑器的 bug,可以打开调试工具查看是否有出错日志,欢迎在论坛上反馈相关问题更换开发模式:快速切换公众号网页调试和小程序调试退出:退出开发者工具

                      项目

                      新建项目:快速新建项目打开最近:可以查看最近打开的项目列表,并选择是否进入对应项目查看所有项目:新窗口打开启动页的项目列表页关闭当前项目:关闭当前项目,回到启动页的项目列表页

                      文件

                      新建文件保存保存所有关闭文件

                      编辑:可以查看编辑相关的操作和快捷键

                      工具

                      编译:编译当前小程序项目刷新:与编译的功能一致,由于历史原因保留对应的快捷键 ctrl(⌘) + R编译配置:可以选择普通编译或自定义编译条件前后台切换:模拟客户端小程序进入后台运行和返回前台的操作清除缓存:清除文件缓存、数据缓存、以及授权数据

                      界面:控制主界面窗口模块的显示与隐藏

                      设置:

                      外观设置:控制编辑器的配色主题、字体、字号、行距编辑设置:控制文件保存的行为,编辑器的表现代理设置:选择直连网络、系统代理和手动设置代理通知设置:设置是否接受某种类型的通知

                      工具栏

                      点击用户头像可以打开个人中心,在这里可以便捷的切换用户和查看开发者工具收到的消息。

                      noticecenter

                      用户头像右侧是控制主界面模块显示/隐藏的按钮。至少需要有一个模块显示。

                      showandhide

                      工具栏中间,可以选择普通编译,也可以新建并选择自定义条件进行编译和预览。

                      通过切后台按钮,可以模拟小程序进入后台的情况

                      background

                      工具栏上提供了清缓存的快速入口。可以便捷的清除工具上的文件缓存、数据缓存、还有后台的授权数据,方便开发者调试。

                      工具栏右侧是开发辅助功能的区域,在这里可以上传代码、申请测试、上传腾讯云、查看项目信息

                      righttools

                      工具栏管理

                      在工具栏上点击鼠标右键,可以打开工具栏管理

                      toolbarmanager

                      模拟器

                      模拟器可以模拟小程序在微信客户端的表现。小程序的代码通过编译后可以在模拟器上直接运行。

                      开发者可以选择不同的设备,也可以添加自定义设备来调试小程序在不同尺寸机型上的适配问题。

                      device

                      在模拟器底部的状态栏,可以直观地看到当前运行小程序的场景值,页面路径及页面参数

                      独立窗口

                      点击 模拟器/调试器 右上角的按钮可以使用独立窗口显示 模拟器/调试器

                      popup

                      poped


                      项目页卡主要有三大功能:


                      显示当前项目细节

                      包括图标、AppID、第三方平台名(只有第三方平台的开发小程序才会显示)、目录信息、上次提交代码的时间以及代码包大小。


                      基础库版本切换

                      开发者可以在此选择任意基础库版本,用于开发和调试旧版本兼容问题。

                      clientlib


                      项目配置

                      ES6 转 ES5

                      在 0.10.101000 以及之后版本的开发工具中,会默认使用babel将开发者代码ES6语法转换为三端都能很好支持的ES5的代码,帮助开发者解决环境不同所带来的开发问题。开发者可以在项目设置中关闭这个功能。详情

                      需要注意的是:

                      • 为了提高代码质量,在开启ES6转换功能的情况下,默认启用 javasctipt 严格模式,请参考 "use strict"

                      压缩代码

                      开启此选项,开发工具在上传代码时候将会帮助开发者压缩javascript代码,减小代码包体积。

                      样式补全

                      开启此选项,开发工具会自动检测并补全缺失样式,保证在低版本系统上的正常显示。尽管可以规避大部分的问题 ,还是建议开发者需要在 iOS 和 Android 上分别检查小程序的真实表现。

                      代码保护

                      开启此选项,开发者工具会尝试对项目代码进行保护,主要是对文件进行扁平化处理并替换 require 引用的文件名,以下情况不适合使用此功能

                      1. 对于小程序只有简单页面的情况下,开启此功能效果不佳
                      2. 有文件超过 500kb,且其中有使用 require 引用项目中的文件的情况,在运行时可能会报文件没有找到
                      3. 动态引用的情况,如 var a = 'somefile.js'; require(a);
                      4. 将 require 函数赋值给其他变量的情况,如 var a = require; a('somefile.js');
                      5. 将 require 作为二元运算符的参数的情况,如 require + 1;
                      6. 使用 ... 运算符且未开启 ES6 转 ES5 的情况

                      不校验请求域名及 TLS 版本

                      正式发布的小程序的网络请求是需要校验合法域名以及域名的 TLS 版本,可以在 mp 管理后台进行配置。 在开发过程中可以开启此选项,开发工具将不会校验安全域名,以及 TLS 版本,帮助在开发过程中更方便的完成调试工作。

                      启用多核心编译

                      在四核及以上的电脑上此选项可见。启用此选项,会充分利用 CPU 资源来编译项目的 JS 代码,提高编译的效率。可以选择关闭此选项。


                      域名信息

                      将显示小程序的安全域名信息,合法域名可在 mp 管理后台进行设置。

                      host


                      设置页提供对编辑器(外观和代码编辑)、代理和通知的配置。菜单栏上点击设置,或者使用快捷键 ctrl(⌘) + , 可以打开设置页。

                      入口

                      菜单栏上点击设置可以打开设置页。设置页侧边栏分别是编辑器、代理和通知的配置。

                      settings_main

                      编辑器配置

                      编辑器支持配置外观和代码编辑器习惯和风格。

                      编辑器外观配置

                      • 主题:白色、深色、黑色
                      • 字体
                      • 字号
                      • 行距 

                      编辑配置支持

                      • 修改文件时自动保存
                      • 编译时自动保存所有文件
                      • 文件保存时自动编译小程序
                      • 自动折行
                      • 用空格代替 Tab
                      • 代码缩略图
                      • 总是在新标签页打开文件
                      • Git 比较文件内容时,忽略 Windows 风格回车符
                      • Tab 大小

                      如果选中了 “总是在新标签页打开文件”,则在编辑器目录树点击文件时,总是会在一个新标签页中打开此文件,而非在临时标签页中打开。

                          


                      代理配置

                      可以配置不使用代理,或使用系统代理,或使用自定义代理。   


                      通知配置

                      可以配置系统消息和开发者社区消息通知。

                      settings_bbs

                      快捷键

                      本节介绍一些快捷键的使用。

                      Mac OS 快捷键Windows 快捷键说明
                      ⌘ + Q退出开发者工具
                      ⇧ + ⌘ + Nshift + ctrl + N新建项目
                      ⇧ + ⌘ + Wshift + ctrl + W关闭当前项目

                      文件
                      ⌘ + Nctrl + N新建文件
                      ⌘ + Sctrl + S保存文件
                      ⇧ + ⌘ + Sshift + ctrl + S保存所有文件
                      ⌘ + Wctrl + W关闭当前文件

                      编辑
                      ⌘ + Zctrl + Z撤销
                      ⇧ + ⌘ + Zshift + ctrl + Z重做
                      ⌘ + Cctrl + C复制
                      ⌘ + Xctrl + X剪切
                      ⌘ + Vctrl + V粘贴
                      ⌘ + [ctrl + [代码左缩进
                      ⌘ + ]ctrl + ]代码右缩进
                      ⇧ + ⌥ + Fshift + alt + F格式化代码
                      ⌥ + ⬆alt + ⬆代码上移一行
                      ⌥ + ⬇alt + ⬆代码上移一行
                      ⇧ + ⌥ + ⬆shift + alt + ⬆复制并向上粘贴
                      ⇧ + ⌥ + ⬇shift + alt + ⬆复制并向下粘贴
                      ⌘ + Pctrl + P跳到文件
                      ⌘ + Ectrl + E跳到最近文件
                      ⌘ + ⌥ + ⬅ctrl + alt + ⬅打开当前文件编辑器左边的文件
                      ⌘ + ⌥ + ➡ctrl + alt + ➡打开当前文件编辑器右边的文件
                      ⌘ + Fctrl + F文件内搜索
                      ⇧ + ⌘ + Fshift + ctrl + F项目内搜索
                      ⇧ + ⌘ + Rshift + ctrl + R焦点在编辑器内,表示替换

                      工具
                      ⌘ + Bctrl + B编译项目
                      ⌘ + Rctrl + R焦点在编辑器外,编译项目
                      ⇧ + ⌘ + Pshift + ctrl + P预览代码
                      ⇧ + ⌘ + Ushift + ctrl + U上传代码

                      界面
                      ⌘ + ,ctrl + ,打开设置窗口

                      编辑区可以对当前项目进行代码编写和文件的添加、删除以及重命名等基本操作。


                      文件格式

                      因 iOS 下仅支持 UTF8 编码格式,最新版本的开发者工具会在上传代码时候对代码文件做一次编码格式校验。


                      文件支持

                      工具目前提供了5种文件的编辑:wxmlwxssjsjson、wxs以及图片文件的预览。


                      文件操作

                      新建页面有两种方式

                      1. 在目录树上右键,选择新建 Page,将自动生成页面所需要的 wxml、wxss、js、json
                      2. 在 app.json 的 pages 字段,添加需要新建的页面的路径,将会自动生成该页面所需要的文件

                      自动保存

                      编辑代码后,工具会自动帮助用户保存当前的代码编辑状态,直接关闭工具或者切换到别的项目,并不会丢失已经编辑的文件状态,但需要注意的是,只有用户主动保存文件,修改内容才会真实的写到硬盘上。

                      如果设置中开启了 “修改文件时自动保存”(设置-编辑设置-修改文件自动保存),工具在修改文件时会自动保存到硬盘中,无需手动保存的效果。

                      设置中开启 “编译时自动保存所有文件”(设置-编译设置-编译时自动保存所有文件),在点击编译时自动保存所有文件的效果。

                      实时预览


                      如果设置中开启了“文件保存时自动编译小程序”(位置在:设置 - 编辑 - 文件保存时自动编译小程序),那么当 js, json, wxml 或 wxss 文件修改时,可以通过模拟器实时预览编辑的情况:

                      实时预览

                      自动补全

                      同大部分编辑器一样,我们提供了完善的自动补全

                      • js 文件编辑会帮助开发补全所有的 API 及相关的注释解释,并提供代码模板支持
                      • wxml 文件编辑会帮助开发者直接写出相关的标签和标签中的属性
                      • json 文件编辑会帮助开发者补全相关的配置,并给出实时的提示

                      js 补全

                      edit1_1

                      代码模板支持

                      edit1_2 

                      json 补全

                      edit3 

                      wxml 补全

                      edit4 


                      TypeScript 支持

                      如果项目需要使用 TypeScript 语言开发,开发者工具在创建项目选择快速启动模板时,提供了使用 TypeScript 语言的 QuickStart 项目,可以选择创建此项目并进行后续开发。

                      要构建并使用 TypeScript 项目,可能需要安装 npm。通过自定义预处理,可以实现在编译前运行 tsc 以将其编译到 js 文件。

                      如需配置 TypeScript 编译选项,请参考 tsconfig.json 的配置。

                      注:小程序仅支持运行 JS 文件,因此所有的 TS 文件都默认不会被打包上传。

                      Git 状态展示

                      如果所在的小程序工程目录(project.config.json 所在目录)存在 Git 仓库,编辑器可以展示目前的 Git 状态。

                      目录树

                      如图所示,当某些文件存在变动时,目录树的文件右侧将展示相应的图标来表明这一状态。当某一处于收起状态的目录下存在有变动的文件时,此目录的右侧亦会展示一个圆点图标表明此情况。

                      文件图标状态的含义如下:

                      图标含义
                      U文件未追踪(Untracked)
                      A新文件(Added, Staged)
                      M文件有修改(Modified)
                      +M文件有修改(Modified, Staged)
                      C文件有冲突(Conflict)
                      D文件被删除(Deleted)

                      文件夹目录图标状态的含义如下:

                      图标含义
                      小红点目录下至少存在一个删除状态的文件
                      小橙点目录下至少存在一个冲突状态的文件
                      小蓝点目录下至少存在一个未追踪状态的文件
                      小绿点目录下至少存在一个修改状态的文件

                      如果某一文件存在修改(Modified),可以右键点击此文件,并选择 “与上一版本比较”,则可以查看当前工作区文件与 HEAD 版本的比较。

                      文件编辑

                      存在 Git 仓库时,状态栏会展示此 Git 仓库目前的分支信息。例如,下图表明目前 Git 仓库处于 v2 分支。

                      同时,编辑文件内容时,将会在所编辑代码左侧实时显示相对于上一版本内容的比较。

                      样式说明如下:

                      文件夹目录图标状态的含义如下:

                      样式含义
                      蓝色线条此处的代码有变动
                      绿色线条此处的代码是新增的
                      红色三角箭头此处有代码被删除

                      Windows 风格回车设置

                      如需忽略 Windows 风格的回车符,可以前往 “设置” - “编辑”,并勾选 “Git 比较文件内容时,忽略 Windows 风格回车符”。

                      勾选后,在编辑文件进行内容比较时,所有 Windows 风格的回车符将被当作 Unix 风格的回车符对待。


                      项目配置文件

                      可以在项目根目录使用 project.config.json 文件对项目进行配置。

                      字段名类型说明
                      miniprogramRootPath String指定小程序源码的目录(需为相对路径)
                      qcloudRootPath String指定腾讯云项目的目录(需为相对路径)
                      pluginRootPath String指定插件项目的目录(需为相对路径)
                      compileTypeString编译类型
                      settingObject项目设置
                      libVersionString基础库版本
                      appidString项目的 appid,只在新建项目时读取
                      projectnameString项目名字,只在新建项目时读取
                      packOptionsObject打包配置选项
                      debugOptionsObject调试配置选项
                      scriptsObject自定义预处理

                      compileType 有效值

                      名字说明
                      miniprogram当前为普通小程序项目
                      plugin当前为小程序插件项目

                      setting 中可以指定以下设置

                      字段名类型说明
                      es6Boolean是否启用 es6 转 es5
                      postcssBoolean上传代码时样式是否自动补全
                      minifiedBoolean上传代码时是否自动压缩
                      urlCheckBoolean是否检查安全域名和 TLS 版本
                      uglifyFileNameBoolean是否进行代码保护

                      scripts 中指定自定义预处理的命令

                      名字说明
                      beforeCompile编译前预处理命令
                      beforePreview预览前预处理命令
                      beforeUpload上传前预处理命令

                      packOptions

                      packOptions 用以配置项目在打包过程中的选项。打包是预览、上传时对项目进行的必须步骤。

                      目前可以指定 packOptions.ignore 字段,用以配置打包时对符合指定规则的文件或文件夹进行忽略,以跳过打包的过程,这些文件或文件夹将不会出现在预览或上传的结果内。

                      packOptions.ignore 为一对象数组,对象元素类型如下:

                      字段名类型说明
                      valuestring路径1或取值
                      typestring类型

                      其中,type 可以取的值为 folder、file、suffix、prefix、regexp2、glob2,分别对应文件夹、文件、后缀、前缀、正则表达式、Glob 规则。所有规则值都会自动忽略大小写。

                      注 1: value 字段的值若表示文件或文件夹路径,以小程序目录 (miniprogramRoot) 为根目录。

                      注 2: regexp、glob 仅 1.02.1809260 及以上版本工具支持。

                      示例配置如下。

                      {  "packOptions": {    "ignore": [{      "type": "file",      "value": "test/test.js"    }, {      "type": "folder",      "value": "test"    }, {      "type": "suffix",      "value": ".webp"    }, {      "type": "prefix",      "value": "test-"    }, {      "type": "glob",      "value": "test/**/*.js"    }, {      "type": "regexp",      "value": ".jsx$"    }]  }}

                      注: 这部分设置的更改可能需要重新打开项目才能生效。

                      debugOptions

                      debugOptions 用以配置在对项目代码进行调试时的选项。

                      目前可以指定 debugOptions.hidedInDevtools 字段,用以配置调试时于调试器 Sources 面板隐藏源代码的文件。

                      hidedInDevtools 的配置规则和 packOptions.ignore 是一致的。

                      当某个 js 文件符合此规则时,调试器 Sources 面板中此文件源代码正文内容将被隐藏,显示为:

                      // xxx.js has been hided by project.config.json
                      注:配置此规则后,可能需要关闭并重新打开项目才能看到效果。

                      项目配置示例:

                      {  "miniprogramRoot": "./src",  "qcloudRoot": "./svr",  "setting": {    "postcss": true,    "es6": true,    "minified": true,    "urlCheck": false  },  "packOptions": {    "ignore": []  },  "debugOptions": {}}

                      快捷键

                      见工具菜单栏

                      程序调试主要有三大功能区:模拟器调试工具小程序操作区

                      模拟器

                      模拟器模拟微信小程序在客户端真实的逻辑表现,对于绝大部分的 API 均能够在模拟器上呈现出正确的状态。

                      模拟器

                      编译代码

                      点击工具左下角的编译按钮或者使用快捷键 Ctrl(Command) + B,可以编译当前代码,并自动刷新模拟器。

                      同时为了帮助开发者调试具体页面或者进入的场景值,如同,开发者可以选择自定义编译模式。

                      wxml


                      自定义预处理

                      projectsetting

                      在项目设置页卡,我们提供了以下几个默认的预处理,可以解决大部分的代码文件预处理的问题

                      1. ES6 转 ES5(可以应用于编译、预览、上传),使用 "babel-core": "^6.26.0"
                      2. 上传代码时样式自动补全,使用 "postcss": "^6.0.1"
                      3. 上传代码时自动压缩,使用 "uglify-js": "3.0.27"

                      对于高级开发者来说,完全可以自己编写自动化构建脚本对代码文件进行预处理,所以我们提供了 启用自定义处理命令 选项 开发者可以指定 编译前/预览前/上传前 需要预处理的命令 开发者工具使用 shell 的方式运行指定的命令,并在控制台中输出命令的执行日志

                      预处理命令的执行顺序

                      1. 自定义预处理命令
                      2. 默认预处理命令
                      3. 编译/预览/上传

                      注:

                      1. 编译前预处理命令,需要手动点击 "编译" 按钮,或者使用快捷键编译才能触发。文件修改无法触发该命令。
                      2. Mac 版本的开发者工具无法复用 bash 中的 Path 环境变量。可能需要手动设置系统的 Path 环境变量,才能正常执行命令。

                      调试工具

                      调试工具分为 7 大功能模块:Wxml、Console、Sources、Network、Appdata、Storage、Sensor

                      Wxml Panel

                      Wxml Panel 用于帮助开发者开发 Wxml 转化后的界面。在这里可以看到真实的页面结构以及结构对应的 wxss 属性,同时可以通过修改对应 wxss 属性,在模拟器中实时看到修改的情况。通过调试模块左上角的选择器,还可以快速找到页面中组件对应的 wxml 代码。

                      wxml

                      Sources panel

                      Sources panel 用于显示当前项目的脚本文件,同浏览器开发不同,微信小程序框架会对脚本文件进行编译的工作,所以在 Sources panel 中开发者看到的文件是经过处理之后的脚本文件,开发者的代码都会被包裹在 define 函数中,并且对于 Page 代码,在尾部会有 require 的主动调用。

                      sources

                      Network panel

                      Netwrok Pannle 用于观察和显示 request 和 socket 的请求情况

                      network

                      注:uploadFile 和 downloadFile 暂时不支持在 Network Panel 中查看

                      Appdata panel

                      Appdata panel 用于显示当前项目当前时刻 appdata 具体数据,实时地反馈项目数据情况,可以在此处编辑数据,并及时地反馈到界面上。

                      appdata

                      Storage panel

                      Storage panel 用于显示当前项目的使用 wx.setStorage 或者 wx.setStorageSync 后的数据存储情况。

                      storage


                      Console Pannel

                      Console Pannel 有两大功能:

                      • 开发者可以在此输入和调试代码

                        console1

                      • 小程序的错误输出,会显示在此处

                        4

                      Sensor panel

                      Sensor panel 有两大功能:

                      • 开发者可以在这里选择模拟地理位置

                        location

                      • 开发可以在这里模拟移动设备表现,用于调试重力感应 API

                        accelerometerchange



                      小程序操作区

                      小程序操作区帮助开发者模拟一些客户端的环境操作。例如当用户从小程序中回到聊天窗口,会触发一个小程序被设置为后台的api。

                      5

                      当小程序使用到多窗口的时候,可以在顶部操作区进行页面切换,需要注意的是这个操作只是为了方便开发者才存在的,在真实的微信客户端中是不会有的。

                      7


                      自定义数据上报

                      开发者工具上可以编辑和调试自定义分析的数据上报功能,点击菜单栏中的 “工具 - 自定义分析” 即可弹窗打开自定义分析:

                      event_list

                      在页面中可以新建、查看或修改事件,在修改事件的页面中编辑完毕后,点击底部的保存并测试按钮将保存当前配置,同时工具将在调试器上提示收到最新配置,并展示配置信息,展示的内容包括事件的 ID 和名称,以及每个动作的触发条件和上报数据:

                      begin_test

                      接着可以在模拟器中操作和触发事件。在模拟器中刷新小程序也将获取该测试配置,除非窗口被关闭。窗口关闭后模拟器不会再收到配置。当事件被触发上报时,工具上会展示上报信息,包括事件 ID、触发页面、触发方式、触发时动作、以及上报的字段值和数据:

                      report_ide

                      同时可以在窗口中点击 “同步结果” 会同步显示上报的数据:

                      report_mp

                      关闭窗口后,配置将全部失效,模拟器不再收到配置并不再触发上报(小程序中使用 wx.reportAnalytics API 进行的数据上报仍会在工具中输出)。 测试成功后,可到小程序后台发布事件配置,即可正式生效收集所定义的事件数据。


                      自动预览

                      自动预览可以实现编写小程序时快速预览,免去了每次查看小程序效果时都要扫码或者使用小程序开发助手的麻烦。只需按下快捷键,保持前台运行的微信即可自动唤出或刷新小程序。

                      要使用自动预览功能,需要配合 6.6.7 及以上的微信客户端版本。


                      要开始使用 “自动预览” 功能,可以在打开预览二维码的时候,点击 “自动预览” 标签以切换到自动预览模式。切换到自动预览模式后,只需按下预览快捷键,或者点击浮窗上的 “编译并预览” 按钮,即可触发自动预览。此时工具会上传代码,保持前台运行的微信客户端会自动刷新当前开发的小程序。

                      当自动预览成功时,工具栏上的预览图标会显示为一个绿勾。如果预览出错,则会显示为一个红色惊叹号,可以点击查看详情。

                      注意,自动预览功能仅限与登陆开发者工具的同帐号微信使用。如需换回普通预览模式,只需要点击 “扫描二维码预览” 标签即可。

                      用户可以在快捷键设置里自定义预览快捷键。

                      13


                      特殊场景调试

                      小程序开发者工具是对微信客户端的模拟,受限于桌面设备同移动设备的差异,以及微信的一些特有数据,同时考虑到开发的便捷性,部分 API 在工具和微信中有所不同。

                      扫码接口

                      同手机端直接调用摄像头来扫码不同,在 PC 或者 Mac 上调用摄像头来扫码完成调试是一个低效的行为,所以在开发工具上调用二维码扫码 API 后,开发者可以选择一个本地的图片来进行后续的逻辑调试,而不是真正的启用摄像头来扫码,流程有所不同,但是接口的输入和输出是一致的。

                      微信支付

                      最新版本的开发者工具已经支持微信支付的调试,但是为了兼顾到安全,同手机上直接调用微信支付有所不同:

                      • 新绑定的开发者需要 24 小时后才有权限进行微信支付的调试
                      • 开发者在工具上调用微信支付的 API 后,开发工具会出现一个二维码,开发者必须使用当前开发所使用的微信号扫码后在手机上完成支付的流程
                      • 工具会同步移动端微信支付的回包到工具中,开发者自行进行后续的操作

                      使用的交互有所不同,但是接口的输入输出工具同客户端是保持一致的。

                      启动使用自定义参数

                      在日常使用中,用户可以通过扫码、分享打开一个小程序,这时候会依据设置的启动页面:path 跳转到对应的小程序页面(不一定是首页)并且可以携带参数:query。在开发者工具中,开发者同样可以通过自定义编译条件的方式来达到调试不同启动页面和启动参数的目的。

                      例如下图是选择进入页面是 page/API/index,参数 是 name=can

                      args

                      进入场景值

                      在微信客户端中,用户可能在各个场景下打开小程序 详情 ,然而在开发者工具中是没有真实的环境去模拟这些场景的。开发者可以通过条件编译的方式来达到调试不同场景的目的。

                      sence

                      普通的转发

                      开发者工具上调用转发是一个模拟的行为,并不会真实的转发给用户,开发可以通过这个模拟行为判断是否正确的调用了转发 API。

                      带 shareTicket 的转发

                      带 shareTicket 的转发可以获取到更多的转发信息,例如群聊的名称以及群的标识 openGId。在小程序开发者工具上,开发者可以通过以下方式来调试带 shareTicket 的转发。

                      调用 wx.showShareMenu 的参数 withShareTicket 为 true 时,点击模拟器右上角菜单后出现的转发按钮,会出现一个测试群列表,如图:

                      withShareTicket

                      开发者点击选取任何一个群,可以通过接口的回包获取到 shareTicket ,通过调用 wx.getShareInfo 可以获取到相关转发的信息

                      当开发者需要调试从某一个群点开,并且带有 shareTicket 的场景时,可以使用自定义编译中的 1044:群聊会话中的小程序消息卡片(带 shareTicket) 同时可以选择任一模拟测试群,如图

                      withShareTicket

                      预览使用自定义编译条件

                      同 启动使用自定义参数 相同,提交预览时,开发者可以通过自定义预览的方式来达到在移动设备上调试不同启动页面和启动参数 的目的。我们可以选择已经创建好的自定义编译条件进行预览。

                      跳转小程序调试支持

                      小程序跳转开发调试可以分为两个部分

                      调试小程序是否能够正确的跳转

                      出于小程序代码的安全考虑,在工具上调用 wx.navigateToMiniProgram 的时候,开发者工具不会真实的打开和跳转到另外的小程序,但是工具会判断当前小程序与需要跳转的小程序之间的绑定关系,输出相关信息给到开发者。开发者可以根据成功或者失败的回调函数来判断调用是否成功。

                      调试被打开的小程序时候正确的接收参数

                      选择 自定义编译 进入场景选择 1037 从小程序进入 可以调试小程序被打开时候是否接收到了正确的参数并做了相关处理。

                      navigateToMiniProgram

                      选择 自定义编译 进入场景选择 1038 从小程序返回 可以调试小程序返回时候是否接收到了正确的参数并做了相关处理。

                      navigateToMiniProgram


                      真机调试

                      真机远程调试功能可以实现直接利用开发者工具,通过网络连接,对手机上运行的小程序进行调试,帮助开发者更好的定位和查找在手机上出现的问题。

                      调试流程

                      要发起一个真机远程调试流程,需要先点击开发者工具的工具栏上 “远程调试” 按钮。


                      此时,工具会将本地代码进行处理打包并上传,就绪之后,使用手机客户端扫描二维码即可弹出调试窗口,开始远程调试。

                      远程调试窗口

                      使用手机扫描此二维码,即可开始远程调试。

                      要结束调试,直接关闭此调试窗口,或点击右下角 “结束调试” 按钮即可。


                      远程调试窗口分为两部分,分别是左侧的调试器视图、右侧的信息视图。开发者可以在调试器里直接进行代码的调试,并查看 Storage 情况;信息视图则可以查看目前与手机和服务器的连接情况,以及发生的错误信息等。

                      调试器

                      在远程调试的调试器里,开发者可以在 Console 面板里对代码进行调试,在 Sources 面板里查看小程序的源代码并进行断点单步调试,在 Storage 面板里查看小程序的 Storage 使用情况等。


                      注意,要在 Console 里对小程序进行调试,需要将调试的上下文切换到 VM Context 1,如图所示。


                      在 Sources 面板查看源代码时,开发者所有的文件路径都是以 weapp:// 开头的。


                      除了可以在调试器进行单步调试,开发者还能在代码中手动插入 debugger; 语句进行断点调试。因此,如果想要在小程序启动的尽早时刻断点,可以在进入远程调试之前,编辑代码手动在需要断点处的代码插入 debugger; 语句来实现。

                      WXML、AppData、Storage 面板的操作和开发者工具调试模拟器时的操作一致。注意,如果在右侧信息视图取消勾选了 “使用工具端的 Storage”,则所有的 Storage 数据将被存储在手机上,将不再出现 Storage 面板。




                      信息视图

                      右侧的信息视图展示了手机、网络连接的信息。手机信息展示手机的型号、系统、名称、微信版本等信息,以及通信延时。通信延时越小,与手机的通信越流畅。

                      在 “连接信息” 里,展示了工具与服务器的连接信息,包括了连接状态、服务器状态等,当连接故障、服务器阻塞影响到调试的过程和流畅度时,此处将展示这一状态。当连接状态为 “已结束” 时,表明调试已被终止。

                      “警告和错误” 展示了最近发生的错误和警告信息。如果网络连接断开,此处将会询问开发者是否需要重新连接。

                      手机端展示

                      调试过程中的手机端展示如下所示。

                      当手机无网络或者进入了断点状态时,将会出现一个浮层提示并阻止进一步的操作。

                      小游戏远程调试

                      目前仅支持 1.02.1809260 及以上版本工具, iOS 11.2 ~ 11.4.1 系统 6.7.2 及以上版本微信客户端,以及 Android 系统 6.7.3 及以上版本微信客户端。

                      与小程序不同的是,在调试窗口的右侧可能会出现 “Contexts” 栏,可以点选希望调试的不同的 JavaScript 上下文。

                      默认情况下,为了方便调试,工具会上传带有完整源代码的 Source Map。如果不希望上传,或者出现代码行列数映射错乱的情况,可以在右下侧选项中关闭这个选项,并取消勾选项目详情中的 “上传代码时自动压缩混淆” 选项。

                      注:目前尚不支持 Storage 面板。


                      多账号调试

                      开发者工具需要使用微信号登录,我们以此帐号作为所有打开的项目的主帐号,当登录的帐号改变时,其登录态将同步到所有已打开的项目窗口; 当小程序/小游戏需要多个微信号才能共同完成一项工作的话,我们提供了多帐号调试的功能。

                      功能入口

                      通过 菜单 - 工具 - 多帐号调试 可以使用多帐号调试功能

                      如何使用


                      使用不同于主帐号的微信扫描二维码可以添加一个测试帐号,如果该测试帐号登录了其他开发者工具客户端,登录态将失效

                      点击 ‘+’、‘-’ 我们可以添加多个测试号,或者删除已添加的测试号;按住 ‘ctrl’ 键,鼠标可以多选


                      我们可以同时勾选多个帐号,打开多个调试窗口来调试同一个项目;调试窗口与项目主窗口不同,只有模拟器和调试器;对项目代码编辑还是需要在项目主窗口进行,代码保存后,各个调试窗口可以同步执行最新的代码



                      小程序开发者工具是对微信客户端的模拟,受限于桌面设备同移动设备不同,以及微信的一些特有数据,同时考虑到开发的便捷性,那么有部分 API 在工具和微信中是有所不同的。

                      扫码接口

                      同手机端直接调用摄像头来扫码不同,在 PC 或者 Mac 上调用摄像头来扫码完成调试是一个低效的行为,所以在开发工具上调用二维码扫码 API 后,开发者可以选择一个本地的图片来进行后续的逻辑调试,而不是真正的启用摄像头来扫码,流程有所不同,但是接口的输入和输出是一致的。

                      微信支付

                      最新版本的开发者工具已经支持微信支付的调试,但是为了兼顾到安全,同手机上直接调用微信支付有所不同:

                      • 新绑定的开发者需要 24 小时后才有权限进行微信支付的调试
                      • 开发者在工具上调用微信支付的 API 后,开发工具会出现一个二维码,开发者必须使用当前开发所使用的微信号扫码后在手机上完成支付的流程
                      • 工具会同步移动端微信支付的回包到工具中,开发者自行进行后续的操作

                      使用的交互有所不同,但是接口的输入输出工具同客户端是保持一致的。

                      普通的转发

                      开发者工具上调用转发是一个模拟的行为,并不会真实的转发给用户,开发可以通过这个模拟行为判断是否正确的调用了转发 API。

                      带 shareTicket 的转发

                      带 shareTicket 的转发可以获取到更多的转发信息,例如群聊的名称以及群的标识 openGId。在小程序开发者工具上,开发者可以通过以下方式来调试带 shareTicket 的转发。

                      调用 wx.showShareMenu 的参数 withShareTicket 为 true 时,点击模拟器右上角菜单后出现的转发按钮,会出现一个测试群列表,如图:


                      开发者点击选取任何一个群,可以通过接口的回包获取到 shareTicket ,通过调用 wx.getShareInfo 可以获取到相关转发的信息

                      当开发者需要调试从某一个群点开,并且带有 shareTicket 的场景时,可以使用自定义编译中的 1044:群聊会话中的小程序消息卡片(带 shareTicket) 同时可以选择任一模拟测试群,如图


                      进入场景值

                      在微信客户端中,用户可能在各个场景下打开小程序 详情 然而在开发者工具中是没有真实的环境去模拟这些场景的。开发者可以通过条件编译的方式来达到调试不同场景的目的。


                      启动使用自定义参数

                      在日常使用中,用户可以打开一个小程序,并且依据传入的 path 跳转到对应的小程序页面而非启动页面,或者可以通过 参数 使得小程序区别默认开打状态,开发者工具中,开发者同样可以通过条件编译的方式来达到调试不同 path 和 参数 的目的。

                      例如下图是选择进入页面是 pages/name/name 参数 是 name=linchao


                      预览使用自定义参数

                      同 启动使用自定义参数 相同,提交预览时,开发者可以通过自定义预览的方式来达到在移动设备上调试不同 path 和 参数 的目的。

                      例如下图是选择进入页面是 pages/name/name 参数 是 name=linchao


                      小程序跳转的调试支持

                      小程序跳转开发调试可以分为两个部分

                      调试小程序是否能够正确的跳转

                      出于小程序代码的安全考虑,在工具上调用 wx.navigateToMiniProgram 的时候,开发者工具不会真实的打开和跳转到另外的小程序,但是工具会判断当前小程序与需要跳转的小程序之间的绑定关系,输出相关信息给到开发者。开发者可以根据成功或者失败的回调函数来判断调用是否成功。

                      调试被打开的小程序时候正确的接收参数

                      选择 自定义编译 进入场景选择 1037 从小程序进入 可以调试小程序被打开时候是否接收到了正确的参数并做了相关处理。


                      选择 自定义编译 进入场景选择 1038 从小程序返回 可以调试小程序返回时候是否接收到了正确的参数并做了相关处理。


                      开发者工具提供了命令行与 HTTP 服务两种接口供外部调用,开发者可以通过命令行或 HTTP 请求指示工具进行登录、预览、上传等操作。

                      命令行

                      通过命令行调用安装完成的工具可执行文件,完成登录、预览、上传、自动化测试等操作。调用返回码为 0 时代表正常,为 -1 时错误。

                      命令行工具所在位置:

                      macOS: <安装路径>/Contents/Resources/app.nw/bin/cli

                      Windows: <安装路径>/cli.bat

                      1. 命令行启动工具

                      -o, --open [projectpath]: 打开工具,如果不带 projectpath,只是打开工具。如果带 project path,则打开路径中的项目,每次执行都会自动编译刷新,并且自动打开模拟器和调试器。projectpath 不能是相对路径。项目路径中必须含正确格式的 project.config.json 且其中有 appid 和 projectname 字段。

                      示例:

                      # 打开工具cli -o# 打开路径 /Users/username/demo 下的项目cli -o base64@/Users/username/demo

                      2. 命令行登录

                      命令行提供两种登录方式:一是将登录二维码转成 base64 给用户,让用户自己集成到自己系统中使用;二是将二维码打印在命令行中。

                      -l, --login: 启动登录逻辑。

                      --login-qr-output [format[@path]]: 指定二维码输出形式,format 可选值包括 terminal(命令行输出), base64, image。如果有填 path,表示结果输出到指定路径的文件中。如果没填 path,表示将结果输出到命令行。不使用此选项或使用了但没有填 format 的话则默认为命令行打印。

                      示例:

                      # 登录,在终端中打印登录二维码cli -l# 登录,在终端中打印登录 base64 形式的二维码cli -l --login-qr-output base64# 登录,二维码转成 base64 并存到文件 /Users/username/code.txt cli -l --login-qr-output base64@/Users/username/code.txt

                      3. 命令行提交预览

                      预览时必须处于登录状态,如果没有登录,会提示需先登录。预览的二维码可命令行打印也可以转成 base64。ES6 等项目配置从 project.config.json 读。

                      -p, --preview <project_root>: 预览代码,project_root 指定项目根路径。

                      --preview-qr-output [format[@path]]: 指定二维码输出形式,语义同登录用的选项 --login-qr-output。

                      示例:

                      # 预览,在终端中打印登录二维码cli -p /Users/username/demo# 预览,二维码转成 base64 并存到文件 /Users/username/code.txtcli -p /Users/username/demo --preview-qr-output base64@/Users/username/code.txt

                      4. 命令行上传代码

                      上传代码时必须处于登录状态,如果没有登录,会提示需先登录。

                      上传代码需要的信息包括项目根目录、版本号、以及可选的版本备注。

                      -u, --upload <version@project_root>: 上传代码,version 指定版本号,project_root 指定项目根路径。

                      --upload-desc <desc>: 上传代码时的备注。

                      示例:

                      # 上传路径 /Users/username/demo 下的项目,指定版本号为 1.0.0,版本备注为 initial releasecli -u 1.0.0@/Users/username/demo --upload-desc 'initial release'

                      5. 支持自动化测试

                      -t, --test <project_root>: 提交自动化测试,project_root 指定项目根路径。

                      示例:

                      # 提交测试路径 /Users/username/demo 下的项目cli -t /Users/username/demo

                      开发者工具提供了命令行与 HTTP 服务两种接口供外部调用,开发者可以通过命令行或 HTTP 请求指示工具进行登录、预览、上传等操作。

                      HTTP

                      http 服务在工具启动后自动开启,HTTP 服务端口号在用户目录下记录,可通过检查用户目录、检查用户目录下是否有端口文件及尝试连接来判断工具是否安装/启动。

                      端口号文件位置:

                      macOS : ~/Library/Application Support/微信web开发者工具/Default/.ide

                      Windows : ~/AppData/Local/微信web开发者工具/User Data/Default/.ide

                      1. 打开工具或指定项目

                      接口定义:

                      URL: /open

                      HTTP 方法: GET

                      URL 参数必填说明
                      projectpath打开指定路径中的项目。如项目已打开,自动刷新项目。如项目未创建,自动创建并打开项目

                      示例:

                      # 打开工具http://127.0.0.1:端口号/open# 打开/刷新项目http://127.0.0.1:端口号/open?projectpath=项目全路径

                      注意:

                      • 项目路径中必须含正确格式的 project.config.json 且其中有 appid 和 projectname 字段。
                      • 项目路径需经 URL encode

                      2. 登录

                      接口定义:

                      URL:/login

                      HTTP 方法:GET

                      URL 参数必填说明
                      format指定登录二维码返回格式,可选值有 image、base64、terminal,默认 image。图片格式为 png
                      qroutput指定文件路径,在文件写入二维码数据。如指定,二维码将被写入指定路径的文件内,如未指定,二维码将作为请求相应体返回

                      示例:

                      # 登录,返回图片格式的二维码http://127.0.0.1:端口号/login# 登录,取 base64 格式二维码http://127.0.0.1:端口号/login?format=base64# 登录,取 base64 格式二维码,并写入 /Users/username/logincode.txthttp://127.0.0.1:端口号/login?format=base64&qroutput=%2FUsers%2Fusername%2Flogincode.txt

                      3. 预览

                      接口定义:

                      URL:/preview

                      HTTP 方法:GET

                      URL 参数必填说明
                      projectpath预览指定路径中的项目。如项目已打开,自动刷新项目。如项目未创建,自动创建并预览项目
                      format指定登录二维码返回格式,可选值有 image、base64、terminal,默认 image。图片格式为 png
                      qroutput指定文件路径,在文件中写入二维码数据。如指定,二维码将被写入指定路径的文件内,如未指定,二维码将作为请求相应体返回

                      示例:

                      # 预览路径为 /Users/username/demo 的项目,返回图片格式的二维码http://127.0.0.1:端口号/preview?projectpath=%2FUsers%2Fusername%2Fdemo# 预览路径为 /Users/username/demo 的项目,返回 base64 格式的二维码http://127.0.0.1:端口号/preview?projectpath=%2FUsers%2Fusername%2Fdemo&format=base64# 预览路径为 /Users/username/demo 的项目,返回 base64 格式的二维码,并写入 /Users/username/logincode.txthttp://127.0.0.1:端口号/preview?projectpath=%2FUsers%2Fusername%2Fdemo&format=base64&qroutput=%2FUsers%2Fusername%2Flogincode.txt

                      4. 上传

                      接口定义:

                      URL:/upload

                      HTTP 方法:GET

                      URL 参数必填说明
                      projectpath上传指定路径中的项目
                      version版本号
                      desc本次上传的版本备注

                      示例:

                      # 上传路径为 /Users/username/demo 的项目,指定版本号为 v1.0.0http://127.0.0.1:端口号/upload?projectpath=%2FUsers%2Fusername%2Fdemo&version=v1.0.0# 上传路径为 /Users/username/demo 的项目,指定版本号为 v1.0.0,并带上备注http://127.0.0.1:端口号/upload?projectpath=%2FUsers%2Fusername%2Fdemo&version=v1.0.0&desc=test

                      5. 自动化测试

                      接口定义:

                      URL:/test

                      HTTP 方法:GET

                      URL 参数必填说明
                      projectpath测试指定路径中的项目

                      示例:

                      # 提交路径为 /Users/username/demo 的项目进行测试http://127.0.0.1:端口号/test?projectpath=%2FUsers%2Fusername%2Fdemo

                      请求响应

                      正常情况下 HTTP 相应状态码为 200,错误时 400,返回如下格式的 JSON 字符串:

                      {  "code": 40000,  "error": "原因"}

                      代码片段是一种可分享的小项目,可用于分享小程序和小游戏的开发经验、展示组件和 API 的使用、复现开发问题等等。分享代码片段会得到一个链接,所有拥有此分享链接的人可以在工具中导入此代码片段。如果网页可点击的链接指向的是分享链接,那么点击链接也会自动打开工具进入代码片段导入页。使用最新版的开发者工具可以点此体验导入代码片段

                      创建代码片段


                      在工具选择项目的界面中,右侧可以选择代码片段页卡,查看所有本地代码片段,在右下角可以点击创建代码片段。

                      select-project

                      创建代码片段需要填入代码片段名称、本地存放目录。AppID 不是必填项,如果需要演示依赖 AppID 的操作则需填写。如果存放目录是空目录,则可在下方选择小程序、小游戏等的快速启动模板。

                      create-minicode

                      信息填写正确后,点击创建即可完成创建并打开代码片段。

                      代码片段主界面


                      代码片段的主界面与普通项目主要有以下几点区别:

                      1. 没有上传、腾讯云和申请测试报告等功能
                      2. 详情页中会展示上次分享的链接,并可以一键复制
                      3. 代码片段的快速启动模板与普通项目的快速启动模板不同,体积更小,功能更精简

                      project

                      分享代码片段


                      在工具栏上点击分享按钮即可开启分享代码片段的流程,在分享信息中需要填写以下内容:

                      • 项目描述:简要介绍此代码片段的功能和目的
                      • 是否需要 AppID:如果是,开发者导入代码片段时会建议其填入 AppID 以完整运行代码片段
                      • 最低库版本:开发者打开导入的代码片段时详情页的调试基础库不会低于指定的版本

                      分享的小程序代码片段最大大小为 100KB,小游戏代码片段最大为 200KB。

                      share

                      分享成功后会展示分享链接,可复制分享给其他开发者,其他开发者在工具中选择导入代码片段并粘贴链接即可导入。

                      share-success

                      分享的链接除了可以粘贴到导入页导入外,还可以设置为可点击的链接。如果 html <a> 标签的 href 属性设置为分享的链接,如 <a href="wechatide://minicode/76b799966b6ead1837edac517cc02e02" rel="external nofollow" target="_blank" >代码片段示例</a>,则用户点击此链接时会自动打开工具进入代码片段导入页,最后点击导入即可完成导入。在开发者社区发帖时,如果想要提供 demo 示例,如果想要提供 demo 示例,可以插入一个链接为代码片段分享链接的超链接。

                      share-bbs

                      导入代码片段


                      在选择代码片段的页面的右下角可以点击导入进入导入页,或者点击菜单栏上的项目选项卡下的导入代码片段来打开导入页。导入时需要填写分享链接或代码片段 ID。链接的最后一部分即是代码片段的 ID,如 wechatide://minicode/76b799966b6ead1837edac517cc02e02 的 ID 为 76b799966b6ead1837edac517cc02e02。

                      import-minicode

                      导入时可选择存放目录和 AppID。存放目录默认是在临时文件夹。

                      import-minicode-info

                      概述

                      同开发普通的小程序不同,开发第三方平台小程序具有一定的复杂性,首先需要确认三个概念

                      • open3rd:第三方平台,是小程序官方认可的第三方开发商 详情
                      • 3rdMiniProgramAppid:第三方平台申请的并绑定在该平台上的小程序,用于开发小程序模板
                      • extAppid:授权给第三方平台的小程序

                      因为以上的这些不同,第三方平台相关的小程序开发需要做一些特殊的处理

                      • 小程序模板的开发
                      • 小程序模板结合 extAppid 的开发调试

                      最新版本的开发工具支持第三方平台小程序的开发和预览。

                      创建项目

                      与开发普通小程序一致,第三方平台开发者填入相关的 3rdMiniProgramAppid ,设定项目名称和选择项目目录即可创建项目。

                      对于第三方平台小程序,可以在项目页卡查看到相关的 open3rd 信息以及当前的第三方的 3rdMiniProgramAppid ,如若项目配置了相关的 extAppid ,那么项目页卡中也会有相关信息。

                      ext1

                      小程序模板开发

                      与开发普通小程序一致,开发者在开发工具上开发好相关的业务逻辑之后,在项目页卡中提交预览既可以在微信中查看小程序的真实表现,

                      有所不同的是,第三方平台小程序的提交上传是上传至该第三方平台的 open 帐号下的模板草稿箱中,该平台的管理员需要自行对该模板进行相应的设置,更多请参考 open平台的文档 。

                      extAppid 的开发调试

                      为了方便第三方平台的开发者引入 extAppid 的开发调试工作,需要引入ext.json的概念。

                      ext.json是一个配置文件,放置在小程序项目的根目录下。

                      以下是一个包含了所有配置选项的ext.json

                      {  "extEnable": true,  "extAppid": "wxf9c4501a76931b33",  "ext": {    "name": "wechat",    "attr": {      "host": "open.weixin.qq.com",      "users": [        "user_1",        "user_2"      ]    }  },  "extPages": {    "pages/logs/logs": {      "navigationBarTitleText": "logs"    }  },  "window":{    "backgroundTextStyle":"light",    "navigationBarBackgroundColor": "#fff",    "navigationBarTitleText": "Demo",    "navigationBarTextStyle":"black"  },  "tabBar": {    "list": [{      "pagePath": "pages/index/index",      "text": "首页"    }, {      "pagePath": "pages/logs/logs",      "text": "日志"    }]  },  "networkTimeout": {    "request": 10000,    "downloadFile": 10000  }}

                      ext.json中的配置字段分为两种

                      • 特有的字段
                      • app.json相同的字段

                      特有的字段

                      属性类型必填描述
                      extEnableBoolean配置 ext.json 是否生效
                      extAppidString配置 extAppid
                      extObject开发自定义的数据字段
                      extPagesString Array单独设置每个页面的 json

                      extEnable

                      extEnable是一个Boolean类型的字段,用于规定当前的ext.json文件是否生效,开发者可以通过修改这个字段来开启和关闭 extAppid 的结合开发。


                      extAppid

                      extAppid是授权调试的AppID,例如开发者在此处填写的是wxf9c4501a76931b33那么在extEnable为真的情况下,后续的开发逻辑都会基于wxf9c4501a76931b33来运行。


                      ext

                      ext字段是开发自定义的数据字段,在小程序中可以通过 wx.getExtConfigSync 或者 wx.getExtConfig 获取到这些配置信息。

                      例如上面的例子中,通过wx.getExtConfigSync就可以获得ext字段的所有配置

                      {  "name": "wechat",  "attr": {    "host": "open.weixin.qq.com",    "users": [      "user_1",      "user_2"    ]  }}


                      extPages

                      extPages是一个对象,对象中的每个key应该是该小程序模板app.json中定义的页面,每个key对应的value是 page.json 中所规定的各项配置。

                      当开发者设置这个配置以后,小程序框架会对应的修改相对应的page的配置信息。

                      app.json相同的字段

                      ext.json中的字段同app.json中一致时,ext.json的字段会覆盖app.json中的对应字段,例如以下的ext.json

                      {  ········  "window":{    "backgroundTextStyle":"light",    "navigationBarBackgroundColor": "#fff",    "navigationBarTitleText": "ext navigationBarTitleText",    "navigationBarTextStyle":"black"  }}

                      那么该小程序最终的navigationBarTitleText应该是ext navigationBarTitleText

                      创建插件项目


                      小程序的 AppID 可以创建小程序插件项目,插件是独立于小程序之外的,但是 AppID 是公用的,所以不要使用原有的小程序项目进行插件开发。 在创建项目页面,选择一个空文件夹作为项目路径,可以选择创建小程序插件快速启动模板

                      快速启动模板说明:

                      1. miniprogram 文件夹是一个普通小程序项目,用来编写小程序插件的使用 Demo,上传插件代码时这个 Demo 会一起上传,并作为小程序插件的发布的审核依据.
                      2. plugin 文件就是小程序插件项目,用来编写小程序插件的代码。
                      3. project.config.json 需要关注 compileType 字段,compileType == 'plugin' 时才能正常的使用插件项目。详情

                      打开已存在的插件项目


                      如果是之前创建的插件项目,可以在项目列表中直接打开;

                      如果重新创建项目,选择一个非空目录,那么这个非空目录中需要有 project.config.json 详情,确保这个文件中有以下字段:

                      {  "miniprogramRoot": "./miniprogram",  "pluginRoot": "./plugin",  "compileType": "plugin"}

                      在项目开发期间,可以手动修改 project.config.json 文件的 compileType 字段来切换项目的编译类型。

                      插件上传


                      上传插件代码前,需要指定版本号,格式为 数字.数字.数字 ,每个数字最大为 999。

                      每次提交版本号需要递增,插件使用者会用到这个版本号,请谨慎填写。

                      上传插件时,同时会将 project.config.json 中 miniprogramRoot 指定的目录的内容作为插件使用 Demo 一起上传,这个 Demo 需要覆盖到插件的所有使用场景,便于插件的审核

                      插件使用


                      在小程序项目的 app.json 的 plugins 字段中可以声明使用插件。如果当前的编译类型为小程序时,需要指定已发布的插件的版本号,开发者工具会根据版本号去拉取对应版本的插件进行编译。

                      只有在 project.config.json 的 compileType == 'plugin' 时,插件的版本号才能为 'dev'

                      名词解释

                      Git:是一个免费开源的分布式版本控制系统。我们可以使用 Git 管理我们的小程序代码。

                      TGit:是腾讯云提供的基于 Git 的在线代码托管服务。


                      TGit开通及配置流程

                      1.开通TGit

                      开发者可登录小程序管理后台,在 “设置-开发者工具” 内开通 TGit 功能。

                      2.配置项目信息、管理员信息

                      填写小程序项目名称。小程序管理员将作为 TGit 项目管理员,可自定义管理员的用户名和密码。

                      用户名配置完成后,会生成完整的 TGit 用户名,用于在 TGit 内验证身份,可在权限控制页面查看完整用户名。

                      提交后,查看完整的 TGit 用户名,TGit 内验证身份需要填写完整用户名。

                      3.开通后,进入“查看权限”,可查看和配置 TGit 项目成员信息

                      4.添加 TGit 项目成员

                      (1)选择成员:通过微信号搜索,选择小程序的一个开发者添加到项目中。

                      (2)填写 TGit 用户名

                      填写用户名,注意:在添加成员后,可在成员配置页面查看成员完整的用户名,使用 git clone 命令时需要使用完整的用户名进行验证。

                      注:开通 TGit,添加项目成员操作耗时较久,请耐心等待


                      微信开发者工具

                      在微信开发者工具的工具栏上可以通过 “代码仓库” 按钮快速进入 TGit 管理后台


                      如何使用

                      1. 下载并安装 Git,https://git-scm.com/downloads
                      2. 熟悉 Git 使用方法,详情
                      3. 使用 Git 命令或者 Git 可视化工具将代码提交到 TGit
                      4. 使用 TGit 进行代码托管和多人协作

                      素材管理


                      素材管理将为你一键开通腾讯云的 "对象存储(COS)" 和 "内容分发网络(CDN)" 的产品功能:

                      • 支持从 微信开发者工具 上传素材到腾讯云;
                      • 提供临时域名供你在开发过程中调试;
                      • 提供简单页面管理和上传你的素材资源;
                      • 赠送一定免费的额度供开发和调试;

                      名词解释

                      • 对象存储(COS):是腾讯云为企业和个人开发者们提供的一种能够存储海量数据的分布式存储服务,用户可随时通过互联网对您的大量数据进行批量存储和处理。
                      • 内容分发网络(CDN):是腾讯云针对门户网站、电子商务、UGC 社区等业务场景,提供的静态内容(如网页样式、图片、小文件)加速分发处理能力,极大地缩减了站点响应时间,实现复杂内容秒级加载,显著提升了网页用户的体验。
                      • 外网下行流量:指直接通过对象域名链接下载对象或通过静态网站地址浏览对象产生的流量
                      • CDN 回源流量:指将存储在 COS 上的文件,分发同步到 CDN 的流量,整个同步过程由系统自动完成。
                      • 加速域名: 在开启 CDN 加速后,腾讯云会默认生成一条 CDN 加速域名供开发者使用,通过该域名可以直接访问开发者上传的素材文件,若需要领用开通后前 6 个月每个月 50GB免费流量,需要开发者绑定自己备案的域名。

                      免费额度

                      • 对象存储(COS): 每月提供免费资源包括: 50 GB 存储空间,10 GB 外网下行流量,10 GB 腾讯云 CDN 回源流量, 100 万次 读请求, 100 万次 写请求,点击 了解详情
                      • 内容分发网络(CDN): 新开通 CDN 的用户在开通后的 6 个月内每月收到腾讯云赠送的 50GB 流量包,此外接入加速域名后用户每月均可享受 10GB 免费流量包,自接入加速域名后于每月1号发放至您的账户。点击 了解详情

                      收费情况

                      对象存储(COS)和 内容分发网络(CDN)都属于后付费的产品,开通本服务后,意味着用户同意在不中断服务的情况下,使用付费的服务。当赠送的流量在过期/快用尽的时候系统将统一通知,请留意用量和系统推送的消息,避免在不知情的情况下产生费用。

                      相关收费情况,请查看下面的文档:

                      产品介绍

                      1. 对象存储(COS)点击 了解详情
                      2. 内容分发网络(CDN)点击 了解详情

                      开通步骤

                      一、通过微信公众平台授权登录腾讯云

                      未将小程序授权给腾讯云需要进行前往 微信公众平台 注册并登录小程序,按如下步骤操作:

                      • 单击左侧菜单栏中的【设置】
                      • 单击右侧 Tab 栏中的【开发者工具】
                      • 单击【腾讯云】,进入腾讯云工具页面,单击【开通】
                      • 使用小程序绑定的微信扫码即可将小程序授权给腾讯云,开通之后会自动进去腾讯云微信小程序控制台,显示开发环境已开通,此时可以进行后续操作

                      进入微信公众平台后台

                      开通腾讯云

                      二、前往腾讯云开通 素材管理 服务

                      单击后台管理按钮

                      开通素材管理服务

                      注:小程序管理员在 mp 管理后台跳转到腾讯云管理界面后,浏览器中输入 https://console.cloud.tencent.com/lagame 跳转到开通页面

                      Windows 仅支持 Windows 7 及以上版本

                      稳定版 Stable Build (1.05.2103190)

                      测试版缺陷收敛后转为稳定版

                      Windows 64Windows 32macOS

                      预发布版 RC Build (1.05.2103051)

                      预发布版,包含大的特性;通过内部测试,稳定性尚可

                      Windows 64Windows 32macOS

                      开发版 Nightly Build (1.05.2103262)

                      日常构建版本(基于 NW.js 0.49.3) ,用于尽快修复缺陷和敏捷上线小的特性;开发自测验证,稳定性欠佳,

                      Windows 64Windows 32macOS


                      javascript && wxss


                      微信小程序运行在三端:iOS、Android 和 用于调试的开发者工具。

                      三端的脚本执行环境聚以及用于渲染非原生组件的环境是各不相同的:

                      • 在 iOS 上,小程序的 javascript 代码是运行在 JavaScriptCore 中,是由 WKWebView 来渲染的,环境有 iOS8、iOS9、iOS10
                      • 在 Android 上,小程序的 javascript 代码是通过 X5 JSCore来解析,是由 X5 基于 Mobile Chrome 37 内核来渲染的
                      • 在 开发工具上, 小程序的 javascript 代码是运行在 nwjs 中,是由 Chrome Webview 来渲染的

                      尽管三端的环境是十分相似的,但是还是有些许区别:

                      • ES6语法支持不一致,语法上开发者可以通过开启ES6ES5的功能来规避。详情

                      • wxss渲染表现不一致,尽管可以通过开启样式补全来规避大部分的问题 详情,还是建议开发者需要在 iOS 和 Android 上检查小程序的真实表现。


                      客户端可信域名校验


                      开发者使用手机扫码调试的场景下,打开调试模式之后,最新版的客户端将不检查可信域名。


                      代码文件必须 UTF8 编码

                      iOS下仅支持 UTF8 编码格式,最新版本的开发者工具会在上传代码时候对代码文件做一次编码格式校验。

                      ES6 APi 支持情况

                      微信小程序已经支持了绝大部分的 ES6 API 具体表格如下:

                      1. tip: TBS 3.0 是指微信小程序 Android 运行环境
                      2. tipArray.values不支持
                      3. tipProxy不支持
                      StringiOS8iOS9iOS10TBS3.0
                      codePointAt    
                      normalize    
                      includes    
                      startsWith    
                      endsWith    
                      repeat    
                      String.fromCodePoint    
                      ArrayiOS8iOS9iOS10TBS3.0
                      copyWithin    
                      find    
                      findIndex    
                      fill    
                      entries    
                      keys    
                      values  
                      includes    
                      Array.from    
                      Array.of    
                      NumberiOS8iOS9iOS10TBS3.0
                      isFinite    
                      isNaN    
                      parseInt    
                      parseFloat    
                      isInteger    
                      EPSILON    
                      isSafeInteger    
                      MathiOS8iOS9iOS10TBS3.0
                      trunc    
                      sign    
                      cbrt    
                      clz32    
                      imul    
                      fround    
                      hypot    
                      expm1    
                      log1p    
                      log10    
                      log2    
                      sinh    
                      cosh    
                      tanh    
                      asinh    
                      acosh    
                      atanh    
                      ObjectiOS8iOS9iOS10TBS3.0
                      is    
                      assign    
                      getOwnPropertyDescriptor    
                      keys    
                      getOwnPropertyNames    
                      getOwnPropertySymbols    
                      OtheriOS8iOS9iOS10 TBS3.0
                      Symbol     
                      Set     
                      Map     
                      Proxy  
                      Reflect     
                      Promise     

                      同 正式 版本不同,本页面提供的是开发者工具测试版本的下载,我们将修复 bug 和一些新的特性以 beta 方式先发布。

                      小程序新版工具内测


                      新版本的小程序开发工具优化了以下几个方面

                      • 重构了工具的整体架构和逻辑,编译和启动速度有 100% 以上的提升
                      • 优化了整体交互,预览以及上传代码等高频操作会更加便捷
                      • 重构了视觉呈现

                      除外,全新提供了两大功能

                      • 腾讯云服务:开发者提供免费的云端开发能力以及环境 详情
                      • 自动化测试:为小程序提供真机测试报告

                      Tips: 新版工具的安装不会覆盖旧版本,两个版本可以同时存在

                      下载地址


                      windows 64 、 windows 32 、 mac

                      2017.08.24 更新日志

                      1. A: 新增 自定义设备宽高的添加和删除
                      2. F: 修复 WXS 中使用 console 只打印第一个参数的问题。
                      3. F: 修复 编辑器 wxss、wxml 无法格式化的问题
                      4. F: 修复 编辑器 当前选中文件没有高亮的问题
                      5. F: 修复 编辑器 代码无法折叠的问题
                      6. F: 修复 编辑器 无法自动匹配的问题
                      7. F: 修复 wxml panel 无法显示 dataset 的问题
                      8. F: 修复 wx.openLocation、wx.chooseLocation 调用失败的问题
                      9. F: 修复 从浏览器拖动图片到开发者工具会加载该图片导致工具无法使用的问题
                      10. F: 修复 公众号调试模式下快捷键缺失的问题
                      11. U: 优化 公众号调试模式下模拟器可以缩放
                      12. U: 优化 编译条件选择场景值的交互
                      13. U: 优化 上传腾讯云的交互
                      14. U: 优化 小屏幕工具栏的显示

                      2017.08.22 更新日志


                      1. F: 修复 wxml panel 没有显示样式源文件,无法点击跳转到源文件的问题
                      2. F: 修复 wxml panel 勾选、取消勾选样式时不生效的问题
                      3. F: 修复 wxml panel 没有显示 element.style 的问题
                      4. F: 修复 APIwx.navigateToMiniProgram、wx.navigateBackMiniProgram、wx.exitMiniProgram、wx.startPullDownRefresh、wx.openWeRunSetting、wx.chooseInvoiceTitle 缺失的问题
                      5. F: 修复 page.json 不生效的问题
                      6. F: 修复 ctrl/command + r 编译快捷键丢失的问题
                      7. F: 修复 同时勾选 "编译时自动保存所有文件" 和 "保存时自动编译小程序" 时会出现无法正常编译的问题
                      8. A: 新增 WXS 功能

                      Git 版本管理

                      为了方便开发者更简单快捷地进行代码版本管理,简化一些常用的 Git 操作,以及降低代码版本管理使用的学习成本,开发者工具集成了 Git 版本管理面板。

                      开发者可以在打开的项目窗口里,点击工具栏上的 “版本管理” 按钮进入 Git 版本管理界面。

                      提交工作区更改

                      在 “工作区” 可以查看到目前工作目录的变更及对比,并直接通过勾选文件前面的复选框将其添加到暂存区。右键点击工作区或者此文件,可以丢弃修改。输入提交标题和详情,点击提交按钮即可以提交本次的变更。在标题栏上点击右键可以使用常用的 Gitmoji 符号。

                      查看历史

                      点击历史或者某个分支,可以查看到当前分支的最新提交记录。每个提交记录都可以看到变更的内容以及目录树详情。展开目录树后,在文件上右键点击,可以保存该提交版本的文件完整内容,或者检出该版本的文件。

                      查看文件修改历史

                      在提交记录的目录树文件上右键点击,可以查看到某个文件截至该提交的所有变更记录,并可直接查看文件内容,方便排查问题。

                      检出和创建分支

                      要检出某分支,直接在分支上点击右键选择 “检出” 即可。要创建分支,可以在要创建的提交记录或者分支名上右键,选择 “创建分支” 即可。

                      拉取,推送和抓取

                      通过工具栏上的拉取,推送和抓取按钮,可以很方便地对远程仓库执行各种操作。某些远程仓库可能需要身份验证或者网络代理配置,可以在 “设置” 页中 “网络和认证” 中配置这些信息。


                      网络和认证设置

                      如果连接远程仓库需要代理或者用户身份验证的设置,可以在设置 “网络和认证” 中配置。

                      用户设置

                      在设置页面可以对用户名进行配置。配置完成后,下次提交时,将会使用此用户名和邮箱进行提交。

                      子模块

                      如果项目包含子模块 (Submodule),可以在子模块列表下查看到子模块的信息。目前不支持对子模块进行更多的操作。

                      初始化 Git 仓库

                      如果所在的项目文件夹下没有找到 Git 仓库,可以根据提示初始化一个仓库,并可选择是否立即提交所有文件,以及自动生成一个 .gitignore 文件模板。

                      体验评分是一项给小程序的体验好坏打分的功能,它会在小程序运行过程中实时检查,分析出一些可能导致体验不好的地方,并且定位出哪里有问题,以及给出一些优化建议。

                      运行环境要求

                      • 下载并安装 1.02.1808300 或以上版本的开发者工具,下载地址
                      • 基础库需要切到 2.2.0 或以上版本。

                      使用流程

                      1. 打开开发者工具,在详情里切换基础库到 2.2.0 或以上版本。 

                      2. 在调试器区域切换到 Audits 面板。 

                      3. 点击”开始“按钮,然后自行操作小程序界面,运行过的页面就会被“体验评分”检测到。

                      图片描述

                      4. 点击 “停止" 则结束检测,在当前面板显示相应的检测报告,开发者可根据报告中的建议对相应功能进行优化。 

                      5. 如需再次运行体验评分,可点击报告上方的“清空体验评分”恢复初始状态。请注意,目前系统不提供报告存储服务,一旦清空体验评分,将无法再查看本次评分结果。

                      图片描述

                      自动运行

                      为了方便开发者能够及时发现小程序的体验问题,从开发者工具 1.02.1811150 版本起支持体验评分的 “自动运行” 功能。

                      该功能会在开发调试小程序时,实时检查,一旦发现体验分数低于 70 分时,系统会在 console 面板打印一个 warning 信息提示开发者,此时开发者可以切到 Audits 面板查看详情。

                      开发者在工具的右上角 “详情” 面板的 本地设置 中勾选 “自动运行体验评分” 选项即可开启。

                      图片描述

                      评分规则

                      具体的评分细则和详情的规则说明可参考下列文档:


                      npm 支持

                      从小程序基础库版本 2.2.1 或以上、及开发者工具 1.02.1808300 或以上开始,小程序支持使用 npm 安装第三方包。

                      此文档要求开发者们对 npm 有一定的了解,因此不会再去介绍 npm 的基本功能。如若之前未接触过 npm,请翻阅官方 npm 文档进行学习。

                      使用 npm 包

                      1. 在小程序中执行命令安装 npm 包:
                      npm install --production

                      此处并没有强制要求 node_modules 必须在小程序根目录下(即 project.config.js 中的 miniprogramRoot 字段),也可以存在于小程序根目录下的各个子目录中。但是不允许 node_modules 在小程序根目录外。

                      PS:此处请务必使用--production选项,可以减少安装一些业务无关的 npm 包,从而减少整个小程序包的大小。
                      1. 点击开发者工具中的菜单栏:工具 --> 构建 npm 
                        construction
                      2. 勾选“使用 npm 模块”选项: 
                        use npm
                      3. 构建完成后即可使用 npm 包。

                      js 中引入 npm 包:

                      const package = require('packageName')const packageOther = require('packageName/other')

                      使用 npm 包中的自定义组件:

                      {  "usingComponents": {    "package": "packageName",    "package-other": "packageName/other"  }}
                      PS:此处使用 npm 包时如果只引入包名,则默认寻找包名下的 index.js 文件或者 index 组件。

                      发布 npm 包

                      发布小程序 npm 包的约束

                      这里要发布的 npm 包是特指专为小程序定制的 npm 包(下称小程序 npm 包)。因为小程序自定义组件的特殊性,原有的 npm 包机制无法满足我们的需求,所以这里需要对小程序 npm 包做一些约束:

                      1. 小程序 npm 包要求根目录下必须有构建文件生成目录(默认为 miniprogram_dist 目录),此目录可以通过在 package.json 文件中新增一个 miniprogram 字段来指定,比如:
                      {  "name": "miniprogram-custom-component",  "version": "1.0.0",  "description": "",  "miniprogram": "dist",  "devDependencies": {},  "dependencies": {}}
                      1. 小程序 npm 包里只有构建文件生成目录会被算入小程序包的占用空间,上传小程序代码时也只会上传该目录的代码。如果小程序 npm 包有一些测试、构建相关的代码请放到构建文件生成目录外。另外也可以使用.npmignore文件来避免将一些非业务代码文件发布到 npm 中。
                      2. 测试、构建相关的依赖请放入 devDependencies 字段中避免被一起打包到小程序包中。

                      发布其他 npm 包的约束

                      如果是已经发布过的一些 npm 包,因为一些原因无法改造成小程序 npm 包的结构的话,也可以通过微调后被使用,但是请确保遵循以下几点:

                      1. 只支持纯 js 包,不支持自定义组件。
                      2. 必须有入口文件,即需要保证 package.json 中的 main 字段是指向一个正确的入口,如果 package.json 中没有 main 字段,则以 npm 包根目录下的 index.js 作为入口文件。
                      3. 测试、构建相关的依赖请放入 devDependencies 字段中避免被一起打包到小程序包中,这一点和小程序 npm 包的要求相同。
                      4. 不支持依赖 c++ addon,不支持依赖 nodejs 的内置库:
                      const addon = require('./addon.node'); // 不支持!const http = require('http'); // 不支持!
                      1. 使用 require 依赖的时候下列几种方式也是不允许的:
                      // 不允许将 require 赋值给其他变量后再使用,以下代码不会去解析出具体依赖let r;r = require;r('testa');let r2 = require;r2('testa');// 不允许 require 一个变量,以下代码依赖运行时,无法解析出具体依赖let m = 'testa';require(m);
                      1. 小程序环境比较特殊,一些全局变量(如 window 对象)和构造器(如 Function 构造器)是无法使用的。

                      发布流程

                      发布 npm 包的流程简述如下:

                      1. 如果还没有 npm 帐号,可以到 npm 官网注册一个 npm 帐号。
                      2. 在本地登录 npm 帐号,在本地执行:
                      npm adduser

                      或者

                      npm login
                      1. 在已完成编写的 npm 包根目录下执行:
                      npm publish

                      到此,npm 包就成功发布到 npm 平台了。

                      PS:一些开发者在开发过程中可能修改过 npm 的源,所以当进行登录或发布时需要注意要将源切回 npm 的源。

                      原理介绍

                      为了帮助大家更好的理解发布 npm 包中提到的各种要求,这里简单介绍一下原理:

                      1. 首先 node_modules 目录不会参与编译、上传和打包中,所以小程序想要使用 npm 包必须走一遍“构建 npm”的过程,在最外层的 node_modules 的同级目录下会生成一个 miniprogram_npm 目录,里面会存放构建打包后的 npm 包,也就是小程序真正使用的 npm 包。
                      2. 构建打包分为两种:小程序 npm 包会直接拷贝构建文件生成目录下的所有文件到 miniprogram_npm 中;其他 npm 包则会从入口 js 文件开始走一遍依赖分析和打包过程(类似 webpack)。
                      3. 寻找 npm 包的过程和 npm 的实现类似,从依赖 npm 包的文件所在目录开始逐层往外找,直到找到可用的 npm 包或是小程序根目录为止。 下面简单介绍下构建打包前后的目录情况,构建之前的结构:
                      |--node_modules|    |--testComp // 小程序 npm 包|    |    |--package.json|    |    |--src|    |    |--miniprogram_dist|    |         |-index.js|    |         |-index.json|    |         |-index.wxss|    |         |-index.wxml|    |--testa // 其他 npm 包|         |--package.json|         |--lib|         |    |--entry.js|         |--node_modules|              |--testb|                   |--package.json|                   |--main.js|--pages|--app.js|--app.wxss|--app.json|--project.config.js

                      构建之后的结构:

                      |--node_modules|--miniprogram_npm|    |--testComp // 小程序 npm 包|    |    |-index.js|    |    |-index.json|    |    |-index.wxss|    |    |-index.wxml|    |--testa // 其他 npm 包|         |--index.js // 打包后的文件|         |--miniprogram_npm|              |--testb|                   |--index.js // 打包后的文件|                   |--index.js.map|--pages|--app.js|--app.wxss|--app.json|--project.config.js
                      PS:打包生成的代码在同级目录下会生成 source map 文件,方便进行逆向调试。

                      js 模块示例

                      以下为官方提供的 js 模块,可以参考并使用:

                      自定义组件相关示例

                      请查阅开发第三方自定义组件文档。

                      稳定版 Stable Build 更新日志

                      1.05.2103190 Windows 64Windows 32macOS

                      2021.03.19

                      1. A 新增 云函数本地调试支持模拟环境变量
                      2. A 新增 云开发云托管消息推送
                      3. A 新增 公众号网页开发支持音频标签
                      4. A 新增 公众号网页调试支持横屏
                      5. A 新增 wx.request 支持使用 enableHttp2 参数
                      6. A 新增 可视化编辑增加组件面板
                      7. A 新增 调试菜单增加打开工具调试相关文件快捷操作
                      8. A 新增 支持 getUserProfile 接口的交互
                      9. U 优化 公众号网页调试窗口支持自定义标题栏
                      10. U 优化 二次编译 JSON 文件的速度
                      11. U 优化 新建云开发项目体验优化
                      12. U 优化 sitemap 文件的检测方式
                      13. U 优化 背景音频支持倍速设置 playbackRate
                      14. U 优化 调试器 js context appservice 展示改为非红色
                      15. U 优化 调试器 sources 面板默认自动展开当前 instanceframe 内的代码目录
                      16. U 优化 10MB以上代码包采用异步方式上传
                      17. U 优化 模拟器更多功能半屏弹窗,横屏时对齐客户端样式
                      18. F 修复 分包插件页无法引用分包组件的问题
                      19. F 修复 小游戏模拟器分离窗口显示不全的问题
                      20. F 修复 调试器 sensor 面板重力模拟无法使用的问题
                      21. F 修复 WeappApplication 目录下 Temp 文件占满磁盘问题
                      22. F 修复 二维码编译打不开的问题
                      23. F 修复 无手机号小程序无法开通云开发的问题
                      24. F 修复 多项目窗口切换登录用户后没有同步头像等状态
                      25. F 修复 代码片段分享失败的问题
                      26. F 修复 模拟器网络设为 offline,WebSocket 依然能通信的问题
                      27. F 修复 showToast icon 为 error 展示不正确的问题
                      28. F 修复 <web-view /> 中 safe-area-inset-bottom 可能失效的问题
                      29. F 修复 小游戏开发模式下读取非 game.json 的 json 文件时,控制台会输出警告的问题
                      30. F 修复 第三方平台开发模式下,真机调试获取不到 ext.json 内容的 bug
                      31. F 修复 导入项目不能选择云开发的问题
                      32. F 修复 部分机器调试器白屏问题
                      33. F 修复 编译条件参数为空时 onLoad 方法获取的 options 为 {"": ""} 的问题

                      2021.02.01

                      1. A 新增 支持调试用微信内素材打开小程序的场景
                      2. A 新增 代码静态依赖分析支持小游戏类型
                      3. A 新增 sourceMap 匹配调试插件
                      4. A 新增 小程序可视化编辑面板
                      5. A 新增 支持小程序复制链接的调试
                      6. A 新增 支持在微信开发者工具中,以仅代码编辑器的形式打开其他类型的项目或文件夹
                      7. A 新增 将编译条件单独配置到 project.private.config.json 
                      8. A 新增 支持公众号调试订阅消息
                      9. U 优化 优化云开发开通界面流程,支持同时开通云开发和创建环境
                      10. U 优化 云开发云托管编辑器支持
                      11. F 修复 暗黑模式下工具启动调试器会白屏的问题
                      12. F 修复 小游戏项目 signature.json 可能校验失败的问题
                      13. F 修复 使用 kbone 项目报错的问题
                      14. F 修复 横屏时 safe-area-inset-bottom 数值不对的问题
                      15. F 修复 部分场景使用体验评分导致工具闪退的问题 
                      16. F 修复 云开发腾讯云弹窗白屏的问题
                      17. F 修复 修复第三方平台在cli预览时参数不正确的问题
                      18. F 修复 WXML 面板自定义组件 class 重复显示的问题
                      19. F 修复 1.05版本工具小游戏真机调试加载失败的问题
                      20. F 修复 真机调试 Network 面板显示请求数不正确的问题 
                      21. F 修复 project.config.json 中的 projectname 未同步的问题
                      22. F 修复 调试器弹出空白的问题
                      23. F 修复 wx.request返回值类型错误的问题 
                      24. F 修复 点击云开发控制台可能无反应的问题 
                      25. F 修复 胶囊位置与客户端保持一致
                      26. F 修复 小程序 webview 组件打开公众号网页出现无效签名报错的问题
                      27. F 修复 开启热重载时修改 js 文件报错的问题
                      28. F 修复 使用2.14.0及以下版本基础库时,配置防盗链的资源可能无法正常使用的问题
                      29. F 修复 使用 weui 拓展库出现 getApp() 返回 undefined 的问题
                      30. F 修复 小程序 tabbar 在刘海屏机型表现和真机不一致的问题
                      31. F 修复 fs.unlink 不为异步的问题
                      32. F 修复 WXML 面板 shadowRoot 子节点不正确的问题
                      33. F 修复 wx.uploadFile 失败的问题 
                      34. F 修复 调用 wx.vibrateLong() 时模拟器会震出屏幕的问题
                      35. F 修复 uniapp 框架生成的小程序 sourcemap 问题 
                      36. F 修复 小程序导航条是黑色时无法看到 home 按钮的问题
                      37. F 修复 小游戏开发模式下读取非 game.json 的 json 文件时,控制台会输出警告的问题
                      38. F 修复 公众号网页调试授权信息缺失的问题
                      39. F 修复 wxml 编译错误显示缺失的问题 
                      40. F 修复 调试器显示 __wxConfig.xxx is deprecated 的问题
                      41. F 修复 showToast 弹窗 icon 为 error 的时候展示不对的问题
                      42. F 修复 Android 模拟器 胶囊有重影的问题
                      43. F 修复 小游戏 downloadFile API 没有自动解压 unzip 返回包的问题

                      2021.01.15

                      1. F 修复 工具一直处于加载中的问题 
                      2. F 修复 多次编译导致工具闪退问题 

                      2021.01.04

                      1. A 新增 小程序插件开发支持打开功能页
                      2. A 新增 wx.getVideoInfo 支持
                      3. A 新增 wx.compressVideo 支持
                      4. A 新增 <wxs/> src 支持使用绝对路径
                      5. A 新增 云开发支持内容管理
                      6. A 新增 云函数本地调试支持快速安装 npm 依赖
                      7. A 新增 快捷键缩放模拟器区域
                      8. A 新增 代码静态依赖分析
                      9. A 新增 env(safe-area-inset-bottom) 支持
                      10. U 优化 iphone 刘海屏机型的模拟器
                      11. U 优化 windows 版本的部分样式
                      12. U 优化 多账号调试窗口的菜单栏
                      13. U 优化 首次打开项目时编译 JSON 耗时过长的问题
                      14. U 优化 首次打开项目文件列表获取异步化
                      15. F 修复 wx.downloadFile 无法下载 200M 大小的文件的问题
                      16. F 修复 WXML 面板中自定义组件数据无法编辑的问题
                      17. F 修复 模拟器区域过小时无法分离模拟器窗口的问题 
                      18. F 修复 项目列表窗口会自动弹出来的问题
                      19. F 修复 调试器 Network 面板无法显示云函数请求大于 1M 的回包请求
                      20. F 修复 wx.getSystemInfo 返回的 safeArea 与真机不一致的问题
                      21. F 修复 1.03.2011120 部分视频无法播放的问题

                      2020.11.26

                      1. A 新增 支持设置插件页面为自定义编译条件的启动页面
                      2. A 新增 第三方平台小程序支持使用企业微信模拟器进行调试
                      3. A 新增 保留上次预览的二维码
                      4. A 新增 云开发控制台文件存储配置
                      5. A 新增 修改 appid 时支持下拉选取最近使用的appid
                      6. A 新增 体验评分支持导出报告
                      7. A 新增 支持切后台后可以获取用户位置
                      8. A 新增 云开发静态网站托管支持自定义域名
                      9. A 新增 静态网站和云存储支持上传文件夹
                      10. A 新增 云开发支持云托管
                      11. A 新增 预览时报错通过弹框提供错误信息
                      12. U 优化 云开发拓展功能入口优化
                      13. U 优化 新建项目流程
                      14. U 优化 安装包体积
                      15. F 修复 调试器在模拟器右侧时,选择机型会导致调试器错位
                      16. F 修复 公众号网页调试模式下调试器白屏
                      17. F 修复 项目列表页,删除项目时的弹框无法纵向滚动
                      18. F 修复 工具导入代码片段会直接新建一个新的代码片段
                      19. F 修复 WXML面板节点元素无法选中
                      20. F 修复 新的编译模块在win7系统预览报错的问题
                      21. F 修复 udp onClose与客户端表现不一致
                      22. F 修复 打开工具全屏的问题
                      23. F 修复 多账号调试,编译一直使用缓存
                      24. F 修复 2.13.0以上基础库,无法触发 onPageNotFound 
                      25. F 修复 非系统菜单栏 Mac 下左上角的放大无法按住option最大化 
                      26. F 修复 关闭所有项目窗口后,不能从菜单里打开项目选择界面
                      27. F 修复 重复CSS样式没有warning提示
                      28. F 修复 cli使用 --appid参数时错误
                      29. F 修复 downloadFile接口三端表现不一致
                      30. F 修复 openSetting中有三个权限一直关不掉
                      31. F 修复 工具上临时文件能被unlink删除的问题
                      32. F 修复 MacOS Big Sur 频繁崩溃的问题
                      33. F 修复 调试器跟随模拟器一起弹出时编辑器部分区域无法触发点击的问题
                      34. F 修复 删除项目后,重启工具,已删除的项目又重新出现的问题
                      35. F 修复 休眠后重新打开会出现项目列表窗口的问题

                      2020.10.27

                      1. A 新增 支持通过打开文件的方式打开项目
                      2. A 新增 云开发支持
                      3. A 新增 项目详情-本地设置-上传时自动压缩样式
                      4. A 新增 MediaTrack.slice 接口支持切割视频
                      5. A 新增 自动化测试支持设置机型
                      6. A 新增 公众号网页调试支持调试开放标签(支持标签渲染和触发 launch 生命周期)
                      7. A 新增 公众号网页调试支持云开发登录 
                      8. A 新增 小程序支持 wasm 文件上传
                      9. A 新增 模拟 wx.navigateToMiniProgram 小程序跳转的交互
                      10. A 新增 wx.getGroupEnterInfo 调试支持
                      11. A 新增 关闭项目前提示是否保存已修改的文件
                      12. A 新增 cli 支持清除缓存操作
                      13. A 新增 预览/真机调试新增代码包信息展示
                      14. A 新增 worker 内支持网络、文件、音频等 API
                      15. U 优化 小程序表单快速填写交互
                      16. U 优化 增加 WXML 代码补全的 catch 事件
                      17. U 优化 变更自定义编译条件时不会改动到 project.config.json
                      18. U 优化 云开发相同的数据库索引建议只提示一次 
                      19. U 优化 内存空间中基础库缓存、工具插件缓存、预览的缓存残余
                      20. U 优化 预览/上传时 miniprogramRoot 目录下有过大的 node_modules 目录时的对比文件耗时
                      21. U 优化 小程序内用 console 打印日志时在控制台显示的日志一级锚点的跳转位置
                      22. F 修复 使用新文件监听模块 Windows 7 部分系统版本保存文件编译无效的问题
                      23. F 修复 win 版无法访问网络位置的项目的问题 
                      24. F 修复 工具栏隐藏后会挡住部分操作区域的问题 
                      25. F 修复 开发小游戏插件无法预览的问题
                      26. F 修复 快捷键设置,需要点击空白处才能修改的问题 
                      27. F 修复 1.03.2006090 版本通过 cli 预览小游戏项目时提示 app.json 找不到的问题 
                      28. F 修复 Kbone 项目 Promise 没有 resolve 的问题 
                      29. F 修复 调试器可能会白屏的问题 
                      30. F 修复 设置了预览时保存文件,使用快捷键预览未能保存文件的问题 
                      31. F 修复 云开发开通无法自动刷新的问题
                      32. F 修复 云开发共享环境报错的问题
                      33. F 修复 云开发配额显示异常的问题
                      34. F 修复 未开通云开发的账户无法使用环境共享的问题
                      35. F 修复 云开发部分环境无法加载文件目录的问题 
                      36. F 修复 WXML 面板样式编辑时 calc 中带 rpx 出错的问题 
                      37. F 修复 WXML 面板空白的问题
                      38. F 修复 Windows 版本打开安全设置白屏问题
                      39. F 修复 页面中的 video 在 navigateTo 下个页面还播放声音的问题
                      40. F 修复 WXML 代码注释方式可能错误的问题
                      41. F 修复 win 版双击应用程序图标无法打开项目列表页的问题 
                      42. F 修复 1.03.2009301 RC cli 调用 build-npm 无效的问题 
                      43. F 修复 控制台中输出非用户定义的字段内容的问题
                      44. F 修复 win 版因 filesystem.readFile 接口没有关闭文件句柄导致清除文件缓存失败的问题
                      45. F 修复 wx.downloadFile 返回的 downloadTask 无法 abort 的问题
                      46. F 修复 WXML 面板中 shadow-root 下 scroll-view 里没有节点的问题 
                      47. F 修复 WXML 文件中因存在 <wxs /> 单闭合标签时代码着色、注释和格式化异常的问题 
                      48. F 修复 第三方平台小程序因 app.json 过大,且存在大量 page.json 时编译卡顿的问题

                      2020.09.15 更新说明

                      1. F 修复 提示 Converting circular structure to JSON 的报错的问题 
                      2. F 修复 onLaunch 里无法断点且网络请求无法显示的问题 
                      3. F 修复 模拟器区域不居中的问题 
                      4. F 修复 合并编译模式下,修改 js 文件无效的问题 
                      5. F 修复 推出动画异常导致模拟器显示白屏的问题 
                      6. F 修复 模拟器显示比例 50%,靠边阈值与展开宽度不理想的问题 
                      7. F 修复 自定义 tabBar 会挡住页面底部的问题 
                      8. F 修复 切换编译条件后不生效的问题 
                      9. F 修复 图片不能在网络面板中预览的问题
                      10. F 修复 命中断点后点击编译无效的问题
                      11. F 修复 wx.getExtConfig 只有 complete 回调的问题 
                      12. F 修复 弹出模拟器后 wxml 面板不可用的问题
                      13. F 修复 自动化脚本无法使用自动真机调试的问题
                      14. F 修复 wx.showTabBar 无效的问题 

                      2020.08.31

                      1. A 新增 设置调试器显示位置
                      2. A 新增 双击模拟器空白处可以隐藏模拟器交互
                      3. A 新增 记录项目窗口的显示大小
                      4. A 新增 wxml/wxss/js 文件修改热重载
                      5. A 新增 云控制台权限控制
                      6. A 新增 云控制台静态网站托管配置
                      7. A 新增 模拟器显示和隐藏切换时的表现设置
                      8. A 新增 使用快捷键退出工具时提醒,防止误操作
                      9. A 新增 登录后触发编译
                      10. A 新增 插件权限校验
                      11. A 新增 微信字体大小设置
                      12. A 新增 支持代码按需注入lazyload
                      13. A 新增 云开发数据库自动查询分析与索引提示
                      14. A 新增 自动化支持获取体验评分报告
                      15. A 新增 提供新的构建 npm 能力
                      16. A 修复 旧app.json包含有index页面的情况下,删除app.json,重新建一个有index页面的app.json的时候,不会新增index页面
                      17. A 新增 支持直接在自动预览界面切换推送到手机/桌面端微信
                      18. A 新增 支持直接在自动真机调试界面切换推送到手机/桌面端微信
                      19. A 新增 getPerformance 部分性能指标
                      20. U 优化 MockApi 面板参数支持全匹配配置
                      21. U 优化 AppData 面板焦点跳动问题
                      22. U 优化 WXML 调试体验
                      23. U 优化 真机调试文件准备速度
                      24. U 优化 小程序模拟器的加载逻辑
                      25. U 优化 公众号网页调试 URL 收藏后,hover 显示全部信息
                      26. U 优化 创建代码片段时显示“请输入导入链接”等错误提示
                      27. U 优化 安装模拟器插件后,需要手动重启才能使用
                      28. U 优化 添加模拟器插件/调试器插件后,无须重启工具可正常运行
                      29. U 优化 预览和真机调试的界面交互
                      30. F 修复 macOS 10.15 无法获取摄像头授权导致 组件无法使用的问题
                      31. F 修复 无法加载独立分包的问题 
                      32. F 修复 小程序插件中有 app.wxss 文件,其内容会覆盖掉小程序的样式的问题
                      33. F 修复 新建小程序云开发项目,第一次启动会报 sitemap.json 未找到的问题
                      34. F 修复 无法在 Network 面板看到 wx.uploadFile 的 Response 内容的问题
                      35. F 修复 调试器面板 mock 右键菜单失效的问题 
                      36. F 修复 使用 wasm 重新编译项目存在内存泄漏
                      37. F 修复 自动预览tsc 失败一次后,再次预览无响应
                      38. F 修复 模拟器在 Tabbar 设置为 top 时样式错乱的问题 
                      39. F 修复 游戏引擎弹窗分包逻辑失效
                      40. F 修复 小游戏模拟器白屏,控制台提示__virtualDOM__未定义
                      41. F 修复 FileSystemManager.stat 工具和真机返回的path格式不一致
                      42. F 修复 小游戏开放数据域使用增强编译异常的问题
                      43. F 修复 windows 项目列表界面,底部工具栏丢失的问题 
                      44. F 修复 自定义 tabbar 文字展示不完整问题
                      45. F 修复 wx.compressImage 返回 tmpFilePath 多了 undefined 
                      46. F 修复 Windows 下最大化可能遮挡任务栏的问题 
                      47. F 修复 wx.compressImage 返回错误 
                      48. F 修复 首次编译 wx.getLaunchOptionsSync 结果可能错误的问题
                      49. F 修复 WXML/WXSS 压缩错误问题
                      50. F 修复 从网页点击导入代码片段会导致工具卡死
                      51. F 修复 windows 关闭新版文件监听模块后,保存project.config.json时会报错
                      52. F 修复 修改 project.config.json 里的 appid 不生效的问题 
                      53. F 修复 导入链接项目已被删除时能够打开的问题
                      54. F 修复 模拟器底部有可能闪现白条的问题 
                      55. F 修复 WXML 面板伪类无法调试的问题
                      56. F 修复 切换企业微信模拟器插件失败的问题
                      57. F 修复 Mac版开发者工具在扫码登录页无法设置代理的问题
                      58. F 修复 切换模拟器网络状态时报错的问题

                      2020.06.19

                      1. A 新增 终端面板
                      2. A 新增 查看并管理开发者工具相关进程
                      3. A 新增 云开发静态资源托管 
                      4. A 新增 小程序设置页面中增加订阅消息开关
                      5. A 新增 小程序强制更新调试支持
                      6. A 新增 小程序/小游戏 收藏事件调试 
                      7. A 新增 通用设置-项目关闭时,控制项目关闭时是否直接打开项目列表窗口
                      8. A 新增 通用设置-快速打开文件,控制模拟器区域底部状态栏点击页面路径时打开的文件类型
                      9. A 新增 搜索回调调试插件
                      10. A 新增 小游戏脚本录制插件
                      11. A 新增 模拟器-模拟操作-事件模拟-内存警告
                      12. A 新增 支持音视频合成调试 详情
                      13. A 新增 代码上传后可以下载对应的 sourcemap 文件
                      14. F 修复 编辑器 WXML 文件格式化快捷键失效的问题
                      15. F 修复 调试器位置顺序无法拖动排序的问题
                      16. F 修复 打开快捷键设置后,编辑器 ctrl/cmd + f 快捷键无法触发文件内搜索的问题 
                      17. F 修复 cli 命令行当项目路径有中文的情况下无法正常启动的问题
                      18. F 修复 新建代码片段时生成多个 sitemap.json 的问题 
                      19. F 修复 mac 版无法读取系统设置的 PATH 环境变量的问题
                      20. F 修复 云函数本地调试没有日志的问题 
                      21. F 修复 API 代码自动补全时按字母序排序不友好的问题 
                      22. F 修复 版本更新通知时,如未选择更新,后续手动检查更新时一直提示正在下载的问题
                      23. F 修复 win 版通知中心顶部操作按钮被遮挡的问题 
                      24. F 修复 小游戏 video 缺少 onVideoProgress 事件回调的问题
                      25. F 修复 1.03.2005140 终止模拟器导致工具奔溃的问题 
                      26. F 修复 1.03.2005140 多帐号调试窗口编译会导致主项目窗口模拟器崩溃的问题 
                      27. F 修复 1.03.2005140 激励视频广告自动显示并无法关闭的问题
                      28. F 修复 独立分包代码被执行两遍的问题 
                      29. F 修复 菜单栏新建或导入项目可能没反应的问题
                      30. F 修复 模拟器在 Tabbar 设置为 top 时样式错乱的问题
                      31. F 修复 Mock 的规则无法删除的问题
                      32. F 修复 自定义预览前预处理命令失败后,再次预览无响应的问题 
                      33. F 修复 新创建的小游戏项目第一次编译可能提示 __virtualDOM__ is not defined 的问题
                      34. F 修复 project.config.json 内容不正确时,无法新建自定义编译条件的问题
                      35. F 修复 project.config.json 中 watchOptions.ignore 删除部分配置后,重启工具无法生效的问题

                      2020.05.25

                      1. A 新增 云函数灰度功能
                      2. A 新增 云控制台支持微信支付
                      3. A 新增 导入代码片段时,若无填写 appid,默认使用测试号
                      4. A 新增 接入 miniprogram-ci 编译模块
                      5. A 新增 wxml 面板 支持 delete/backspace 进行节点删除操作
                      6. A 新增 支持安装在不同路径下并能够同时使用
                      7. A 新增 小程序插件的版本 version 字段支持 "latest"
                      8. A 新增 云控制台直接开通按量付费功能
                      9. A 新增 去掉小程序跳转小程序的限制
                      10. U 优化 设置页面
                      11. U 优化 win 版的标题栏视觉、交互
                      12. U 优化 模拟器胶囊菜单视觉、交互
                      13. U 优化 项目窗口默认在屏幕居中打开,避免窗口在屏幕外导致无法显示窗口的表现
                      14. U 优化 小程序页面跳转速度
                      15. U 优化 可以选择关闭当前网络使用非安全代理的提示
                      16. U 优化 快速回退功能只保留最近三个版本 
                      17. F 修复 wxml 面板 rpx 计算错误的问题
                      18. F 修复 小窗口时无法显示多帐号选择窗口的确定按钮的问题
                      19. F 修复 模拟器静音对视频无效的问题
                      20. F 修复 wxml 文件中有 wxs 语法错误无法正常提示的问题
                      21. F 修复 使用新版编译模块小游戏开放数据域无法使用的问题
                      22. F 修复 console 面板中快速申请点击无效的问题
                      23. F 修复 小游戏模拟器弹出时顶部有白条的问题
                      24. F 修复 无法更改字体设置的问题 
                      25. F 修复 project.config.json 中有 pluginRoot 字段时,会导致小程序页面样式丢失的问题
                      26. F 修复 自定义预处理命令的输入体验问题 
                      27. F 修复 模拟器静音时会有报错的问题 
                      28. F 修复 wxml 面板 componentData 页卡 boolean 字段无法显示的问题 
                      29. F 修复 wxml 面板无法显示动态传入的图片 src 的问题
                      30. F 修复 项目多开时,当一个项目打开真机调试的情况下直接关闭项目,另一个项目无法启动真机调试的问题
                      31. F 修复 项目重命名后,通过菜单无法重新打开该项目的问题
                      32. F 修复 network 面板云开发请求中文乱码的问题
                      33. F 修复 PC 端模拟 touchend 缺少 changedTouches 的问题
                      34. F 修复 开发者工具打开项目时突然报错 illegal operation on a directory 的问题 

                      2020.04.02

                      1. F 修复 32 位系统无法编译小程序、提示重启耗时过久的问题
                      2. F 修复 某些第三方工具不对中文进行转译导致项目打开失败的问题 
                      3. F 修复 ts 项目编译前命令无限执行的问题

                      2020.03.25

                      1. A 新增 云开发控制台支持开通按量付费
                      2. A 新增 云开发支持数据库备份与回档(还原)
                      3. A 新增 支持小程序自动化多帐号调试
                      4. A 新增 显示灰度中的基础库以及基础库支持的客户端版本 
                      5. A 新增 下发测试基础库 
                      6. A 新增 支持模拟 API 的返回内容 
                      7. A 新增 支持同时重命名多个同名的文件
                      8. A 新增 真机调试出现异常时,可手动操作重试
                      9. A 新增 增加工具加载 loading 展示
                      10. A 新增 模拟器支持终止
                      11. A 新增 支持小游戏代码补全
                      12. U 优化 模拟器工具栏及状态栏界面
                      13. U 优化 云开发控制台监控图表展示
                      14. U 优化 模拟器添加边框
                      15. U 优化 更新命令行和 HTTP v2 版本
                      16. F 修复 修改 cloudFunctionRoot 会出现文件找不到的问题 
                      17. F 修复 不能正确打开已被删除文件夹的项目的问题
                      18. F 修复 点击菜单工具栏管理无反应的问题
                      19. F 修复 工具外修改项目配置 cli 上传不生效的问题
                      20. F 修复 工具预览/上传提示文件已经存在的问题
                      21. F 修复 调试器放大会导致 inspect 按钮样式异常的问题
                      22. F 修复 模拟器工具栏样式异常
                      23. F 修复 wx.addPhoneContact时顶部按钮显示错误的问题 
                      24. F 修复 标题栏文字过长覆盖胶囊按钮的问题
                      25. F 修复 文件系统读取代码包内文件规则与真机不一致的问题
                      26. F 修复 关闭多帐号调试窗口 tabbar 内的 icon 无法加载的问题
                      27. F 修复 预览上传错误提示无效的 json 文件
                      28. F 修复 使用非等宽字体时光标可能错位的问题
                      29. F 修复 某些项目可能出现 wxml not found 的问题
                      30. F 修复 真机调试 Appdata 和 WXML 面板可能显示空白的问题
                      31. F 修复 弹出模拟器时 getMenuButtonBoundingClient 调用结果为空的问题
                      32. A 新增 支持小程序自动化截图功能
                      33. A 新增 编辑器面包屑导航条支持自定义快捷导航
                      34. A 新增 模拟小程序进程销毁重启
                      35. A 新增 编辑器行内错误和警告提示
                      36. A 新增 Mac 和 Windows 微信的模拟器类型
                      37. U 优化 1.02.1912261 的安装包结构
                      38. U 优化 MacOS 版关闭项目窗口时,显示项目列表窗口
                      39. U 优化 插件开发模式下 miniprogramRoot 下 app.json 中插件 provider 与项目 appid 一致时,version 必须为 "dev"
                      40. F 修复 1.02.1912261 引入的多帐号调试 tabBar 图标无法加载的问题
                      41. F 修复 1.02.1912261 引入的 jsserverRoot 目录右键菜单缺失部分选项的问题
                      42. F 修复 公众号网页调试中,Base64 图片无法通过调试器打开的问题
                      43. F 修复 cli 调用自动预览无法使用自定义编辑条件的问题
                      44. F 修复 Windows 版无法使用录音功能的问题
                      45. F 修复 插件开发模式下,插件页面配置不生效的问题
                      46. F 修复 小游戏开放数据域使用增强编译报错的问题
                      47. F 修复 Windows 版某些情况下无法显示项目窗口的问题
                      48. F 修复 切换 cloudfunctionsRoot 无法同步云函数的问题 
                      49. F 修复 Wxml 面板丢失 text 标签子节点的问题
                      50. F 修复 上传时文件体积大小提示错误问题 
                      51. F 修复 使用非等宽字体时光标可能错位的问题
                      52. F 修复 文件系统 api 读取代码包内文件规则与真机不一致的问题
                      53. A 新增 编辑器全局替换
                      54. A 新增 编辑器分栏
                      55. A 新增 编辑器文件多选操作和拖动到文件夹
                      56. A 新增 编辑器多选操作和拖动到文件夹
                      57. A 新增 编辑器代码大纲
                      58. A 新增 编辑器文件对比
                      59. A 新增 选取 android 设备上的 profile 文件进行分析
                      60. A 新增 WXML 面板支持自定义组件数据查看与实时修改
                      61. A 新增 WXML 面板支持使用键盘 (上下左右) navigate the DOM tree
                      62. A 新增 WXML 面板支持右键操作 Hide element/Delete element/Scroll Into View/Collapse children/Expand recursively
                      63. A 新增 云控制台数据库高级查询支持聚合操作 
                      64. A 新增 云控制台支持自定义告警
                      65. A 新增 云控制台用户访问 DAU 图表
                      66. A 新增 云控制台自定义数据库读写权限
                      67. A 新增 PC 微信小程序调试支持
                      68. A 新增 wx.getSystemInfo 返回 deviceOrientation 信息
                      69. A 新增 page meta 支持
                      70. A 新增 支持小程序拓展包
                      71. A 新增 清除订阅消息授权数据
                      72. U 优化 编辑器
                      73. U 优化 大型项目目录结构缓存优化
                      74. U 优化 <web-view /> 组件页面的调试入口位置
                      75. F 修复 小游戏 wx.getMenuButtonBoundingClientRect 返回异常的问题
                      76. F 修复 插件页面配置不生效的问题
                      77. F 修复 App.onLaunch 执行两次的问题 
                      78. F 修复 项目列表丢失的问题
                      79. F 修复 onPageNotFound 没有触发的问题
                      80. F 修复  云函数请求大量并发时可能会在小程序 network 面板漏展示的问题
                      81. F 修复 调试器中开启 disableCache 对渲染层无效的问题
                      82. F 修复 模拟器录音不触发 onFrameRecorded 回调的问题
                      83. F 修复 小游戏 wx.onKeyboardComplete 回调没有触发的问题 
                      84. F 修复 页面跳转后触发 onShow 时场景值为 null 的问题
                      85. F 修复 app.json 使用 usingComponents 导致工具卡死的问题

                      2019.12.02

                      1. A 新增 文档搜索
                      2. A 新增 支持引用小程序开发版插件
                      3. A 新增 云控制台高级日志功能
                      4. A 新增 公众号网页调试收藏地址允许删除
                      5. A 新增 小程序快速启动模板默认使用新的组件样式 
                      6. A 新增 小游戏支持 loadFont 接口
                      7. A 新增 在控制台中显示当前页面 scope-data 校验出错信息
                      8. A 新增 云函数本地调试支持 Network 面板
                      9. A 新增 支持主包页面直接跳转到分包内的插件页面
                      10. A 新增 project.config.json 中增加 watchOptions 字段支持忽略部分文件的监听
                      11. F 修复 WXML 代码中没有引号闭合时没有报错的问题
                      12. F 修复 使用 npm sval 模块时异常的问题
                      13. F 修复 CLI/HTTP 调用上传操作因超时导致报错 Error: socket hang up 的问题
                      14. F 修复 工具自动更新后使用 CLI 启动工具时路径错误的问题
                      15. F 修复 云开发控制台中无法删除 _id 为数字的记录
                      16. F 修复 使用 packOptions.ignore 了自定义组件,小程序运行时还是会报对应组件未找到的问题
                      17. F 修复 某些情况下上传代码会报 cannot read property true_true_true_false_production of undefined 的问题
                      18. F 修复 有大量 js 文件的小程序项目在点击预览后工具无法响应的问题
                      19. F 修复 设置 storage 后立即关闭工具并重启,之前设置的数据无法生效的问题
                      20. F 修复 主进程中无法收到 worker 的消息的问题
                      21. F 修复 增强编译在 ios8 下计算属性名语法错误的问题 
                      22. F 修复 将小游戏项目的 appid 直接修改成小程序的 appid 会导致模拟器消失的问题
                      23. F 修复 Page 实例上 getOpenerEventChannel 方法丢失的问题 
                      24. F 修复 小程序插件开发时,修改插件的 json 文件无法生效的问题

                      2019.10.21

                      1. A 新增 云开发新增 19 个付费套餐 
                      2. A 新增 导航条中新增小程序返回首页功能
                      3. A 新增 wx.chooseLocation 支持传入指定地点
                      4. A 新增 云控制台告警设置支持关闭相应告警渠道
                      5. A 新增 真机调试支持直接触发客户端周期性更新 
                      6. A 新增 通用设置增加“使用新版文件监听模块”的设置(默认勾选)
                      7. A 新增 新建项目页面增加测试号文档介绍入口
                      8. A 新增 记录代码上传的更新类型
                      9. A 新增 支持导入二维码创建自定义编译条件时
                      10. A 新增 通用设置调试器最大日志行数
                      11. A 新增 公众号网页调试增加清除全部缓存按钮
                      12. A 新增 本地编译时使用合并编译
                      13. A 新增 WXML 面板 scopeData 校验提示
                      14. A 新增 PC 微信开发版小程序自动预览
                      15. A 新增 自动真机调试
                      16. A 新增 多帐号调试默认测试帐号
                      17. A 新增 周期性更新调试支持
                      18. A 新增 云开发控制台代金券支付
                      19. A 新增 多线程 worker 支持单步调试
                      20. A 新增 公众号网页调试中新增 url 收藏夹
                      21. A 新增 wx.compressImage 调试
                      22. A 新增 小游戏关系链互动数据开发支持
                      23. A 新增 支持小游戏 JSServer
                      24. A 新增 小游戏节点审查插件
                      25. A 新增 云开发环境中的存储桶被删除时,支持在云控制台中创建存储桶
                      26. A 新增 新建 Page 失败后会给出失败提示
                      27. A 新增 JSServer 支持文件 diff
                      28. A 新增 不再存储 project.config.json 里自定义编译条件的 current 值
                      29. A 新增 云控制台支持全局开启/关闭云函数消息推送
                      30. A 新增 项目重命名功能 
                      31. A 新增 编译模式记录通过二维码编译的条件
                      32. U 优化 再次打开项目时的首次编译速度
                      33. U 优化 GPU 加速默认打开
                      34. U 优化 增加 navigationBarBackgroundColor 是否为合法颜色值的监测提示
                      35. U 优化 只有未授权时直接调用 wx.getUserInfo 才会出现升级提示
                      36. U 优化 wx.downloadFile() 指定路径时增加检测文件大小
                      37. U 优化 下线云真机测试功能
                      38. U 优化 小程序插件的版本不正确的时候的提示
                      39. U 提升了真机调试的稳定性
                      40. F 修复 ` 组件在基础库 2.8.2 报错的问题 
                      41. F 修复 播放临时文件时连续获取播放时间导致工具卡死的问题 
                      42. F 修复 miniprogramRoot 为 "/" 时编译报错的问题
                      43. F 修复 代码保护异常时没有报错的问题 
                      44. F 修复 npm 构建时 Uncaught TypeError: Cannot redefine property 错误
                      45. F 修复 真机调试可能报错模块损坏的问题
                      46. F 修复 文件修改后编译不生效的问题
                      47. F 修复 展开文件夹时,目录树焦点不正确的问题
                      48. F 修复 预览时报文件已经存在的问题 
                      49. F 修复 删除用户数据目录后开发者工具启动不了的问题
                      50. F 修复 未使用体验评分时存在内存泄漏的情况
                      51. F 修复 切换页面偶现 WXML 面板内容丢失问题 
                      52. F 修复 调试 WXML 面板 rpx 计算错误导致样式错乱的问题 
                      53. F 修复 WXML 面板三目运算符不会更新的问题
                      54. F 修复 修改页面文本节点 WXML 面板没有同步的问题
                      55. F 修复 project.config.jsonpackOptions.ignore 规则命中的文件夹中存在 __ 开头和结尾的文件夹时无法预览的问题
                      56. F 修复 状态栏一直在 loading 的问题 
                      57. F 修复 wx.downloadFile 下载文件后缀名存在不正确的问题 
                      58. F 修复 云控制台不能删除文件名中含 emoji 的文件
                      59. F 修复 UDP 不能发送 ArrayBuffer 的问题 
                      60. F 修复 1.02.1909051 引入的上传时进行代码保护异常的问题
                      61. F 修复 因基础库中引用的文件网络请求超时导致模拟器加载小程序慢的问题 
                      62. F 修复 PC 意外断电导致代码文件乱码的问题 
                      63. F 修复 <web-view/> 返回异常的问题
                      64. F 修复 小游戏出现 Uncaught TypeError: Illegal invocation 的问题 
                      65. F 修复 打开任意文件然后删除该文件再重新建立该文件时,不能立即进行编辑的问题
                      66. F 修复 小程序插件开发时,修改 plugin.json 中 publicComponents 无法立即生效的问题
                      67. F 修复 小程序内webview页面返回上一级原生页面需要点击两次才能返回的问题
                      68. F 修复 WXML 面板编辑 style 时失焦的问题 
                      69. F 修复 wx.setBackgroundColor 不生效的问题
                      70. F 修复 编辑器删除某文件再创建该文件后不能立即编辑的问题
                      71. F 修复 多帐号时删除 log 文件失败的问题
                      72. F 修复 减少编辑器保存代码时发生异常情况(如突然断电)后代码变成乱码的概率
                      73. F 修复 公众号网页调试网址栏在特定情况下无法删除 URL 的 bug
                      74. F 修复 增强编译下使用类装饰器语法编译报错的问题
                      75. F 修复 打开项目后立即执行预览/真机调试时报错的问题
                      76. F 修复 Wxml 面板调试 CSS 时注释无效重复样式
                      77. F 修复 小程序的 WebView 里无法调用 wx.chooseImage 的问题
                      78. F 修复 云控制台在深色主题下,欢迎页文本颜色变白的问题
                      79. F 修复 小游戏模拟器鼠标移开模拟器区域后有时会报错的问题
                      80. F 修复 编辑器保存时有概率滚回顶部的问题
                      81. F 修复 覆盖安装时 Wxml 面板调试 CSS 时注释无效重复样式 bug 依然存在的问题
                      82. F 修复打开多个项目窗口时,云开发控制台可能打不开的问题
                      83. F 修复 小程序插件开发修改 plugin.json 不生效的问题
                      84. F 修复项目多开时,某些机型顶部会出现黑条的问题
                      85. F 修复 在特定缩放模式下工具栏抖动的问题
                      86. F 修复 增强编译下多线程 worker 提示 loadBabelMod is not define 的问题
                      87. F 修复 多帐号调试窗口无法复制粘贴的问题
                      88. F 修复 在某些情况下自定义分析页面点不了的问题
                      89. F 修复 setData 回调函数中出错没有提示的问题
                      90. F 修复 WXML 面板编辑时失去焦点的问题
                      91. F 修复 编辑器目录展开或关闭时会自动定位到当前 tab 的问题
                      92. F 修复 工具项目窗口全屏下点击窗口关闭按钮会出黑屏的问题 
                      93. F 修复 未写在 app.json pages 中的页面文件会被主动注册的问题
                      94. F 修复 设置快捷键在其他项目窗口失效的问题
                      95. F 修复 选择视频时,视频声音自动播放的问题
                      96. F 修复 自定义导航栏在页面切换时渲染错误

                      2019.08.13

                      1. A 新增 小程序支持自动化测试
                      2. A 新增 预览当前页面
                      3. A 增加 云控制台中监控图表的数据总和显示
                      4. A 新增 setTabBarItem 支持临时文件和网络路径
                      5. A 新增 公众号调试网址栏下拉菜单点击URL路径后自动跳转
                      6. A 新增 通用设置——使用GPU加速模式(默认关闭)
                      7. A 新增 云开发控制台支持黑色主题
                      8. A 新增 云开发控制台支持购买和变更套餐
                      9. A 新增 版本管理支持直接 checkout 远程分支
                      10. U 优化 文件监听模块
                      11. U 优化 体验评分 UI
                      12. U 优化 非 miniprogramRoot 目录下文件的修改不会触发编译
                      13. F 修改 Wxml 的 text 标签内容后页面不能同步更新
                      14. F 修复 调试器点击临时文件地址打不开的问题
                      15. F 修复 1.02.1907160 版本小游戏分包加载异常的问题
                      16. F 修复 小游戏 websocket 连接期间切换 offline 无效的问题
                      17. F 修复 调整模拟器窗口大小操作时鼠标指针在模拟器窗口内释放后会失效的问题
                      18. F 修复 backgroundColorTop/Bottom 只因在 iOS 模拟时生效
                      19. F 修复 使用 componentGenerics 导致编译错误的问题
                      20. F 修复 顶部按钮返回首页时首页无法正常渲染加载的问题
                      21. F 修复 wxml 面板多个选择器共用样式时调试不了样式的问题
                      22. F 修复 1.02.1907232 版可能导致 bindtap 失效的问题
                      23. F 修复 1.02.1907242 引入的 npm 自定义组件模块引用不到的问题
                      24. F 修复 修改语言重启后不生效的问题
                      25. F 修复 页面返回 wxml 面板伪类信息丢失的问题
                      26. F 修复 wxml 面板伪类信息匹配错误的问题
                      27. F 修复 控制台数据库点击数字id的记录没有展示的问题
                      28. F 修复 顶部按钮返回首页时首页无法正常渲染加载的问题
                      29. F 修复 调整模拟器窗口大小操作时鼠标指针在模拟器窗口内释放后会失效的问题

                      2019.07.16

                      1. A 新增 云控制台支持执行数据库脚本/CRUD 高级操作
                      2. A 新增 云控制台全局设置
                      3. A 新增 云控制台支持消息推送配置
                      4. A 新增 云控制台配额展示
                      5. A 新增 云控制台监控图表
                      6. A 新增 云控制台查看云函数详情
                      7. A 新增 云函数支持单文件更新
                      8. A 新增 Network 面板显示云调用信息
                      9. A 新增 内置 ES6+ 语言转义能力增强
                      10. A 新增 任务通知中心
                      11. A 新增 上传时版本号推荐
                      12. A 新增 云开发云调用快速启动模板
                      13. A 新增 素材管理,不再维护的提示
                      14. A 新增 工具联动 sitemap,控制台显示当前页面是否索引
                      15. A 新增 project.config.json 中新增设置 uploadWithSourceMap 
                      16. A 新增 增加设置是否工具启动默认打开项目
                      17. A 新增 小程序 cover-view 支持
                      18. A 新增 cover-view 支持全屏
                      19. A 新增 小程序插件还原原始 sourcemap
                      20. A 新增 小程序 network 展示图片
                      21. A 新增 nightly 的快速更新机制
                      22. A 新增 版本管理支持删除远程仓库
                      23. A 新增 版本管理支持删除 Tag
                      24. A 新增 自定义编译条件增加过滤
                      25. A 新增 编辑设置——上传前保存所有文件
                      26. A 新增 增加通用设置
                      27. A 新增 通用设置——修改默认项目路径
                      28. A 新增 非第三方小程序存在 ext.json 时出 warning 提示
                      29. A 新增 快速体验开发版菜单项
                      30. A 新增 新建编译模式时,自动命名模式名称
                      31. A 新增 cli 自动预览支持自定义编译条件
                      32. A 新增 cli 指定开发者工具启动时监听的服务端口号
                      33. A 新增 wx.getSystemInfo 返回 safeArea
                      34. A 新增 FileSystemManager.stat 支持 recursive 参数
                      35. A 新增 iPhone XS Max 尺寸
                      36. A 新增 体验评分支持小游戏
                      37. A 新增 体验评分支持 “iPhone X兼容” 检验规则
                      38. A 新增 小程序插件快速申请
                      39. A 新增 控制台新增命令 cleanAppCache
                      40. U 更新 Win 版升级 nwjs 到 0.37.5
                      41. U 更新 Mac 版升级 nwjs 到 0.38.5
                      42. U 更新 wxml 属性自动补全采用双引号
                      43. U 优化 项目详情的交互
                      44. U 优化 云函数代码上传
                      45. U 优化 上传时的备注详情可以多行输入
                      46. U 优化 移除菜单栏界面左 / 右移模拟器选项
                      47. U 优化 任务进度框和通知中心的文本应可以复制
                      48. U 优化 视觉调整,弹出模拟器/调试器,界面上不需要有个收回的,关闭窗口即是收回
                      49. U 优化 模拟器的最小边距改小
                      50. U 优化 任务状态栏展示优化
                      51. F 修复 分包中使用自定义组件时出现渲染层错误 cannot read property "length" of undefined 的问题
                      52. F 修复 app.json 中应用全局 npm 组件报错 
                      53. F 修复 小游戏 wx.shareAppMessage 不带 imageUrl 参数无法调用的问题
                      54. F 修复 cli 调用登录时未使用工具代理设置的问题
                      55. F 修复 云函数本地调试时环境变量中有中文时云函数发起调用失败的问题
                      56. F 修复 1.02.1906141 引入的真机调试无法查看网络请求的返回包的问题
                      57. F 修复 上传时使用代码保护导致 workers 报错的问题
                      58. F 修复 npm 构建后 module.exports 动态设置的变量获取不到的问题
                      59. F 修复 公众号网页调试接口调用没有回调的问题
                      60. F 修复 在分包目录下新建 page 时异常的问题
                      61. F 修复 公众号网页调试 wx.checkJsApi 返回格式错误的问题
                      62. F 修复 <camera /> 组件无法使用的问题
                      63. F 修复 当小游戏断点时,点击编译按钮没有效果的问题
                      64. F 修复 分包页面如果没有 json 文件时该页面无法使用全局组件的问题
                      65. F 修复 多开项目时项目之间的断点会互相影响的问题
                      66. F 修复 mac 版开发者工具无法显示项目窗口的问题 
                      67. F 修复 独立分包使用增强编译异常的问题
                      68. F 修复 Wxml 修改样式时自动失去焦点的问题 
                      69. F 修复 Wxml 面板样式无法选择的问题
                      70. F 修复 Wxml 面板样式权重计算错误的问题
                      71. F 修复 Network 面板耗时显示异常的问题
                      72. F 修复 编辑器提示区域丢失文档说明的问题
                      73. F 修复 安全设置面板端口号无法选中的问题
                      74. F 修复 getMenuButtonBoundingClientRect 返回错误值的问题
                      75. F 修复 第三方小程序出现企业微信小程序模式的问题
                      76. F 修复 调试器没有弹出按钮的问题
                      77. F 修复 代码只启用压缩混淆时报错的问题 
                      78. F 修复 插件 md 文档点击预览白屏的问题
                      79. F 修复 页面跳转导致界面无法选择的问题
                      80. F 修复 进入网页调试后再导入项目报错的问题
                      81. F 修复 wxml 面板样式文件路径不显示的问题
                      82. F 修复 切换网络模拟时调试器报错的问题
                      83. F 修复 增强编译 ignore 功能在预览上传时不生效的问题
                      84. F 修复 extAppid 不合法时禁止上传代码
                      85. F 修复 工具自动添加不必要 wxss 文件的问题
                      86. F 修复 packoption.ignore 配置后的异常不应输出堆栈
                      87. F 修复 fs.appendFile 不支持传入 ArrayBuffer 的问题
                      88. F 修复 小程序项目中有 sitemap.json 但是 app.json 中没有指定 sitemapLocation 时 sitemap.json 会被覆盖掉
                      89. F 修复 偶现 appLaunch with an already exist webviewId 错误
                      90. F 修复 小游戏模拟器弹出时,wx.showKeyboard 会一闪而过的问题
                      91. F 修复 提交版本的 "项目备注" 历史缓存没了的问题
                      92. F 修复 wx.downloadFile 由于代理问题下载不到文件时,会导致逻辑层卡顿的问题
                      93. F 修复 开发者工具中 backgroundAudioManager 背景音频获取不到 duration 的问题
                      94. F 修复 模拟器第一次弹出,devtools 没有 reload 的问题
                      95. F 修复 模拟器 TabBar 多次点击后空白的问题
                      96. F 修复 企业微信小程序模式,compileType 错误的问题
                      97. F 修复 手动修改 project.config.json 把 appid 变成空字符串会出现项目列表重复的问题
                      98. F 修复 切换开发模式,状态栏一直显示某个文件编译中的问题
                      99. F 修复 工程文件多编译很慢时,系统错误不会报的问题
                      100. F 修复 windows 真机调试,配置了 functionpages 的小程序会报错的问题
                      101. F 修复 分包调试时,app.js 初始化两次的问题
                      102. F 修复 开发者工具下 makeDirSync 不支持递归创建目录的问题
                      103. F 修复 windows nightly 小包更新会项目报错的问题
                      104. F 修复 真机调试未读取 packOptions 中的 ignore 的问题
                      105. F 修复 大小超过代码包最大限制没有提示代码包大小是多少的问题
                      106. F 修复 设置中启动打开最后一次修改项目未生效的问题
                      107. F 修复 预览和上传时没有提示超出大小
                      108. F 修复 调用 downloadFile 接口没有跳过域名校验
                      109. F 修复 网页调试模式有 home 和返回按钮的问题
                      110. F 修复 代理设置输入失败问题
                      111. F 修复 横竖屏切换,多操作几次会出现无法重排页面问题
                      112. F 修复 项目详情切换 AppID 后同步云环境列表失败的问题
                      113. F 修复 路径中包含「'」的项目无法打开的问题
                      114. F 修复 BackgroundAudioManager.onPlay 运行时机应比 onCanPlay 晚的问题
                      115. F 修复 工具旧版本基础库新发布线上插件报找不到 vd_version_info 错误的问题
                      116. F 修复 app.json 中的 usingComponents 不应扩散到独立分包内的问题
                      117. F 修复 app.json 中 plugins 字段删除后,仍保留了插件引用信息的问题
                      118. F 修复 模拟 offline 断网时没有同时阻止一些请求的问题
                      119. F 修复 模拟器旋转之后没有自动变大小的问题

                      2019.04.17

                      1.02.1904090 Windows 64Windows 32macOS

                      1. A 新增 云函数本地调试
                      2. A 新增 企业微信模拟器插件
                      3. A 新增 CLI/HTTP 调用关闭项目窗口、关闭开发者工具
                      4. A 新增 小程序支持 pageOrientation: "landscape"
                      5. A 新增 分包配置中新增的页面配置会自动生成对应的页面结构
                      6. A 新增 真机调试支持调试 functionalPage
                      7. A 新增 云控制台支持地理位置索引
                      8. U 优化 大型的小程序项目编译卡顿的问题
                      9. U 优化 TS 版快速开始的代码结构
                      10. U 优化 背景音频的交互体验
                      11. F 修复 HTTP 调用无法上传的问题
                      12. F 修复 tabBar 字体颜色支持 rgb 格式与客户端不一致的问题
                      13. F 修复 tabBar 被蒙层遮住的问题
                      14. F 修复 wx.getBackgroundAudioManager 实现与客户端不一致的问题 
                      15. F 修复 navigationStyle: custom 有 web-view 组件的页面没有顶部导航栏的问题
                      16. F 修复 命令行调用上传时 --upload-desc 会截断空格后内容的问题
                      17. F 修复 代理设置本地代理,失去焦点会自动在文字前加空格的问题
                      18. F 修复 基础库占比只在第一次预览之后才显示的问题
                      19. F 修复 wx.connectSocket 超时时最大连接数控制异常的问题
                      20. F 修复 wx.connectSocket 在无法建立连接的情况下没有错误回调的问题
                      21. F 修复 web-view 横屏时无法显示全部的问题
                      22. F 修复 wxss 中使用非数字开头的自定义属性报错的问题
                      23. F 修复 自定义 tabBar 中调用 wx.getSystemInfo 返回的 windowHeight 不正确的问题
                      24. F 修复 自定义分析测试功能失效的问题
                      25. F 修复 没有开通云开发的 appid 选择云开发启动模板新建项目后会弹下拉提示的问题
                      26. F 修复 弹出的模拟器,打开设置授权会出现两个状态栏的问题
                      27. F 修复 wx.chooseMessageFile 在 tabBar 切换后失效的问题
                      28. F 修复 wxss 文件中 keyframe 后有注释会导致 wxml 面板无法解析样式的问题 
                      29. F 修复 弹出模拟器之后 wx.getMenuButtonBoundingClient 异常的问题
                      30. F 修复 wxs 无法显示相同日志的问题
                      31. F 修复 wxs 报错信息没有显示的问题
                      32. F 修复 tabBar 调整会先显示其他 tabBar 页面的问题
                      33. F 修复 npm 构建 mqtt 包会报错的问题
                      34. F 修复 项目列表窗口大小异常的问题
                      35. F 修复 上传时间显示错误的问题

                      2019.02.01

                      1.02.1902010 Windows 64

                      开发者可以使用云开发开发微信小程序、小游戏,无需搭建服务器,即可使用云端能力。

                      云开发为开发者提供完整的原生云端支持和微信服务支持,弱化后端和运维概念,无需搭建服务器,使用平台提供的 API 进行核心业务开发,即可实现快速上线和迭代,同时这一能力,同开发者已经使用的云服务相互兼容,并不互斥。

                      云开发提供了几大基础能力支持:

                      能力作用说明
                      云函数无需自建服务器在云端运行的代码,微信私有协议天然鉴权,开发者只需编写自身业务逻辑代码
                      数据库无需自建数据库一个既可在小程序前端操作,也能在云函数中读写的 JSON 数据库
                      存储无需自建存储和 CDN在小程序前端直接上传/下载云端文件,在云开发控制台可视化管理
                      云调用原生微信服务集成基于云函数免鉴权使用小程序开放接口的能力,包括服务端调用、获取开放数据等能力


                      可以按如下步骤快速开始使用云开发。

                      1. 新建云开发模板
                      2. 开通云开发
                      3. 体验小程序
                      4. 查看控制台

                      1. 新建云开发模板

                      也可以省略此步骤,直接在已有项目上开通和使用云开发。

                      新建项目选择一个空目录,填入 AppID(使用云开发能力必须填写 AppID),勾选创建 “云开发 QuickStart 项目”,点击创建即可得到一个展示云开发基础能力的示例小程序。该小程序与普通 QuickStart 小程序有以下不同需注意:

                      • 无游客模式、也不可以使用 测试号
                      • project.config.json 中增加了字段 cloudfunctionRoot 用于指定存放云函数的目录
                      • cloudfunctionRoot 指定的目录有特殊的图标
                      • 云开发能力从基础库 2.2.3 开始支持(覆盖率 97.3%,查看兼容性问题)

                      从基础库 2.4.1 开始,在小程序插件中可以使用云开发,插件中使用云开发时,使用的是插件方的云资源而非宿主的云资源,在使用方式上与在小程序中使用无异。

                      2. 开通云开发、创建环境

                      创建了第一个云开发小程序后,在使用云开发能力之前需要先开通云开发。在开发者工具工具栏左侧,点击 “云开发” 按钮即可打开云控制台、根据提示开通云开发、创建云环境。默认配额下可以创建两个环境,各个环境相互隔离,每个环境都包含独立的数据库实例、存储空间、云函数配置等资源。每个环境都有唯一的环境 ID 标识,初始创建的环境自动成为默认环境。

                      注:AppID 首次开通云环境后,需等待大约 10 分钟方可正常使用云 API,在此期间官方后台服务正在做准备服务,如尝试在小程序中调用云 API 则会报 cloud init error:{ errMsg: "invalid scope" } 的错误

                      3. 体验小程序

                      开通创建环境后,即可以开始在模拟器上操作小程序体验云开发提供的部分基础能力演示。

                      4. 查看控制台

                      云开发控制台是管理云开发资源的地方,控制台提供以下能力:

                      • 运营分析:查看云开发监控、配额使用量、用户访问情况
                      • 数据库:管理数据库,可查看、增加、更新、查找、删除数据、管理索引、管理数据库访问权限等
                      • 存储管理:查看和管理存储空间
                      • 云函数:查看云函数列表、配置、日志

                      云开发控制台

                      5. 销毁环境

                      如需销毁环境,开发者可通过工单联系我们。具体工单提交方式请参考文档《小程序·云开发工单》。


                      小程序·云开发提供了多个基础能力,以下对各个主要能力介绍。

                      数据库

                      云开发提供了一个 JSON 数据库,顾名思义,数据库中的每条记录都是一个 JSON 格式的对象。一个数据库可以有多个集合(相当于关系型数据中的表),集合可看做一个 JSON 数组,数组中的每个对象就是一条记录,记录的格式是 JSON 对象。

                      关系型数据库和 JSON 数据库的概念对应关系如下表:

                      关系型文档型
                      数据库 database数据库 database
                      表 table集合 collection
                      行 row记录 record / doc
                      列 column字段 field

                      以下是一个示例的集合数据,假设我们有一个 books 集合存放了图书记录,其中有两本书:

                      [  {    "_id": "Wzh76lk5_O_dt0vO",    "title": "The Catcher in the Rye",    "author": "J. D. Salinger",    "characters": [      "Holden Caulfield",      "Stradlater",      "Mr. Antolini"    ],    "publishInfo": {      "year": 1951,      "country": "United States"    }  },  {    "_id": "Wzia0lk5_O_dt0vR",    "_openid": "ohl4L0Rnhq7vmmbT_DaNQa4ePaz0",    "title": "The Lady of the Camellias",    "author": "Alexandre Dumas fils",    "characters": [      "Marguerite Gautier",      "Armand Duval",      "Prudence",      "Count de Varville"    ],    "publishInfo": {      "year": 1848,      "country": "France"    }  }]

                      在图书信息中,我们用 title, author 来记录图书标题和作者,用 characters 数组来记录书中的主要人物,用 publishInfo 来记录图书的出版信息。在其中我们可以看到,字段既可以是字符串或数字,还可以是对象或数组,就是一个 JSON 对象。

                      每条记录都有一个 _id 字段用以唯一标志一条记录、一个 _openid 字段用以标志记录的创建者,即小程序的用户。需要特别注意的是,在管理端(控制台和云函数)中创建的不会有 _openid 字段,因为这是属于管理员创建的记录。开发者可以自定义 _id,但不可自定义和修改 _openid 。_openid 是在文档创建时由系统根据小程序用户默认创建的,开发者可使用其来标识和定位文档。

                      数据库 API 分为小程序端和服务端两部分,小程序端 API 拥有严格的调用权限控制,开发者可在小程序内直接调用 API 进行非敏感数据的操作。对于有更高安全要求的数据,可在云函数内通过服务端 API 进行操作。云函数的环境是与客户端完全隔离的,在云函数上可以私密且安全的操作数据库。

                      数据库 API 包含增删改查的能力,使用 API 操作数据库只需三步:获取数据库引用、构造查询/更新条件、发出请求。以下是一个在小程序中查询数据库的发表于美国的图书记录的例子:

                      // 1. 获取数据库引用const db = wx.cloud.database()// 2. 构造查询语句// collection 方法获取一个集合的引用// where 方法传入一个对象,数据库返回集合中字段等于指定值的 JSON 文档。API 也支持高级的查询条件(比如大于、小于、in 等),具体见文档查看支持列表// get 方法会触发网络请求,往数据库取数据db.collection('books').where({  publishInfo: {    country: 'United States'  }}).get({  success: function(res) {  // 输出 [{ "title": "The Catcher in the Rye", ... }]  console.log(res) }})

                      更多的数据库的 API 的使用和数据库管理,可以参考数据库指引章节。

                      存储

                      云开发提供了一块存储空间,提供了上传文件到云端、带权限管理的云端下载能力,开发者可以在小程序端和云函数端通过 API 使用云存储功能。

                      在小程序端可以分别调用 wx.cloud.uploadFile 和 wx.cloud.downloadFile 完成上传和下载云文件操作。下面简单的几行代码,即可实现在小程序内让用户选择一张图片,然后上传到云端管理的功能:

                      // 让用户选择一张图片wx.chooseImage({  success: chooseResult => {    // 将图片上传至云存储空间    wx.cloud.uploadFile({      // 指定上传到的云路径      cloudPath: 'my-photo.png',      // 指定要上传的文件的小程序临时文件路径      filePath: chooseResult.tempFilePaths[0],      // 成功回调      success: res => {        console.log('上传成功', res)      },    })  },})

                      上传完成后可在控制台中看到刚上传的图片。

                      更多的存储 API 和管理,可以参考存储指引章节。

                      云函数

                      云函数是一段运行在云端的代码,无需管理服务器,在开发工具内编写、一键上传部署即可运行后端代码。

                      小程序内提供了专门用于云函数调用的 API。开发者可以在云函数内使用 wx-server-sdk 提供的 getWXContext 方法获取到每次调用的上下文(appid、openid 等),无需维护复杂的鉴权机制,即可获取天然可信任的用户登录态(openid)。

                      比如我们如下定义一个云函数,命名为 add ,功能是将传入的两个参数 a 和 b 相加:

                      // index.js 是入口文件,云函数被调用时会执行该文件导出的 main 方法// event 包含了调用端(小程序端)调用该函数时传过来的参数,同时还包含了可以通过 getWXContext 方法获取的用户登录态 `openId` 和小程序 `appId` 信息const cloud = require('wx-server-sdk')exports.main = (event, context) => {  let { userInfo, a, b} = event  let { OPENID, APPID } = cloud.getWXContext() // 这里获取到的 openId 和 appId 是可信的  let sum = a + b  return {    OPENID,    APPID,    sum  }}

                      在开发者工具中上传部署云函数后,我们在小程序中可以这么调用:

                      除了部署云函数进行调用外,我们还支持云函数本地调试,可以不用部署云函数即可测试
                      wx.cloud.callFunction({  // 需调用的云函数名  name: 'add',  // 传给云函数的参数  data: {    a: 12,    b: 19,  },  // 成功回调  complete: console.log})// 当然 promise 方式也是支持的wx.cloud.callFunction({  name: 'add',  data: {    a: 12,    b: 19  }}).then(console.log)

                      如需在云函数中操作数据库、管理云文件、调用其他云函数等操作,可使用官方提供的 npm 包 wx-server-sdk 进行操作。

                      更多的云函数管理和 API,可以参考云函数指引章节。

                      云调用

                      云调用是云开发提供的基于云函数使用小程序开放接口的能力,支持在云函数调用服务端开放接口,如发送模板消息、获取小程序码等操作都可以在云函数中完成,详情可见具体开发指引。

                      HTTP API

                      云开发资源也可以通过 HTTP 接口访问,即在小程序外访问,接口见HTTP API 文档。

                      通过这个章节,我们已经了解了云开发是什么,提供了哪些能力,能做什么,接下来跟着我们一起进入开发指引的章节,看看如何上手开发吧!


                      重要概念

                      在此提供云开发的一些重要概念解释,掌握这些概念对理解云开发和其开发模式非常重要:

                      1.资源环境

                      一个环境对应一整套独立的云开发资源,包括数据库、存储空间、云函数等资源。各个环境是相互独立的,用户开通云开发后即创建了一个环境,默认可拥有最多两个环境。在实际开发中,建议每一个正式环境都搭配一个测试环境,所有功能先在测试环境测试完毕后再上到正式环境。以初始可创建的两个环境为例,建议一个创建为 test 测试环境,一个创建为 release 正式环境。

                      为了方便开发者调试,从开发者工具 1.02.1905302 及基础库 2.7.1 起,在 wx.cloud.init 后会在调试器中输出 SDK 中所使用的默认环境:

                      devtools-network-cloud-init

                      同时,在 Network 面板中会输出各个云开发操作的请求详情,其中包括该调用所请求的环境 ID:

                      devtools-network-env


                      2.配额说明

                      资源配额

                      以下为云开发各类资源配额指标,由腾讯云 TCB 提供存储和计算服务。 用户可通过下载最新的微信开发者工具使用该功能。 资源配额可分为三类:资源均衡型、CDN 资源消耗型、云函数资源消耗型、数据库资源消耗型。

                      资源均衡型

                      分类参数基础版 1基础版 2专业版 1专业版 2专业版 3旗舰版 1旗舰版 2旗舰版 3企业版 1
                      存储容量5GB10GB50GB100GB300GB500GB700GB1000GB1300GB
                      下载操作次数150万/月200万/月750万/月1500万/月2500万/月3750万/月4500万/月5000万/月6000万/月
                      上传操作次数60万/月100万/月300万/月600万/月1000万/月1500万/月2000万/月2500万/月3000万/月
                      CDN回源流量15GB/月10GB/月50GB/月150GB/月300GB/月500GB/月600GB/月800GB/月1000GB/月
                      CDNCDN流量5GB/月25GB/月50GB/月150GB/月300GB/月500GB/月1000GB/月2000GB/月4000GB/月
                      云函数资源使用量GBs34万/月20万/月40万/月150万/月300万/月400万/月1500万/月3000万/月4000万/月
                      外网出流量1GB/月3GB/月5GB/月10GB/月20GB/月25GB/月100GB/月200GB/月400GB/月
                      数据库容量2GB3GB5GB10GB20GB10GB50GB100GB200GB
                      同时连接数42050100200300400500500500
                      读操作数5万/天25万/天50万/天150万/天300万/天500万/天1000万/天2000万/天5000万/天
                      写操作数3万/天15万/天30万/天100万/天200万/天300万/天500万/天1000万/天3000万/天
                      集合限制100个150个200个300个400个400个500个600个800个
                      总价免费30 元/月104 元/月390 元/月690 元/月860 元/月2,499 元/月4,699 元/月8,999 元/月

                      CDN 资源消耗型

                      分类参数CDN 版 1CDN 版 2CDN 版 3
                      存储容量50GB100GB500GB
                      下载操作次750万/月1500万/月3750万/月
                      上传操作次数300万/月600万/月1500万/月
                      CDN回源流量50GB/月150GB/月500GB/月
                      CDNCDN流量500GB/月3072GB/月10240GB/月
                      云函数资源使用量GBs20万/月50万/月150万/月
                      外网出流量3GB/月5GB/月10GB/月
                      数据库容量3GB5GB10GB
                      同时连接数50100200
                      读操作数25万/天50万/天150万/天
                      写操作数15万/天30万/天100万/天
                      集合限制150个200个300个
                      总价149 元/月690 元/月2,199 元/月

                      云函数资源消耗型

                      分类参数云函数版 1云函数版 2云函数版 3
                      存储容量5GB10GB50GB
                      下载操作次数150万/月200万/月750 万/月
                      上传操作次数60万/月100 万/月300万/月
                      CDN回源流量5GB/月10GB/月50GB/月
                      CDNCDN流量5GB/月25GB/月150GB/月
                      云函数资源使用量GBs40万/月400万/月1500万/月
                      外网出流量5GB/月25GB/月100GB/月
                      数据库容量3GB10GB20GB
                      同时连接数50200300
                      读操作数25万/天150万/天300万/天
                      写操作数15万/天100万/天200万/天
                      集合限制150个300个400个
                      总价79 元/月390 元/月1,299 元/月

                      数据库资源消耗型

                      分类参数数据库版 1数据库版 2数据库版 3
                      存储容量5GB10GB50GB
                      下载操作次数150万/月200万/月750 万/月
                      上传操作次数60万/月100 万/月300万/月
                      CDN回源流量5GB/月10GB/月50GB/月
                      CDNCDN流量5GB/月25GB/月50GB/月
                      云函数资源使用量GBs20万/月150万/月400万/月
                      外网出流量3GB/月10GB/月25GB/月
                      数据库容量5GB50GB200GB
                      同时连接数100400500
                      读操作数50万/天500万/天5000万/天
                      写操作数30万/天300万/天3000万/天
                      集合限制200个400个800个
                      总价69 元/月590 元/月1,799 元/月

                      除以上配额参数外,小程序·云开发资源还包括以下系统参数限制(所有版本配额都遵守相同的系统参数限制):

                      • 云函数(单次运行)运行内存:256M5
                      • 云函数数量:50个
                      • 云函数并发数:10006
                      • 数据库流量:单次出包大小为16M
                      • 数据库单集合索引限制:20个
                      • 单个小程序的小程序端请求频率限制:100 万次/分钟

                      注:

                      1. CDN回源流量:指开启了 CDN 加速后,CDN 回源存储时产生的流量。
                      2. 云函数调用次数:已放开调用次数限制,现所有套餐均改为无限调用次数
                      3. 云函数资源使用量 GBs:资源使用量 = 函数配置内存 X 运行计费时长。用户资源使用量,是由函数配置内存,乘以函数运行时的计费时长得出,其中配置内存转换为 GB 单位,计费时长由毫秒(ms)转换为秒(s)单位,因此,资源使用量的计算单位为 GBs(GB-秒)。例如,配置为 256MB 的函数,单次运行了 1760 ms,计费时长为 1800 ms,则单次运行的资源使用量为 (256/1024)*(1800/1000) = 0.45 GBs。针对函数的每次运行,均会计算资源使用量,并按月汇总求和,作为当月的资源使用量。
                      4. 数据库同时连接数 :数据库请求并发数量,如同时有三十个数据库操作请求,则有二十个会同时执行,剩下十个返回超出并发错误;一次数据库请求(无论小程序端发起还是云函数端发起)将耗费一个连接;每个云环境分别有一个同时连接数限制、独立计数。假如数据库查询平均耗时 10ms,那么一个连接可以支持 100qps(1000ms/10ms=100),20个连接可以支持到 2000qps。
                      5. 云函数(单次运行)运行内存:云函数运行时最大可用内存为 256 MB。在云函数运行日志中展示的运行内存信息,为当次运行时的实际使用内存。实际使用内存可能低于最大可用内存,计费时按配置内存即 256 MB 计算。
                      6. 云函数同时连接数:已放开同时连接数限制,现所有套餐均改为统一的最大上限 1000

                      服务等级协议

                      小程序·云开发由腾讯云 TCB 提供存储和计算服务,因此小程序·云开发遵循《腾讯云云开发服务等级协议(SLA)》中的相关规定。

                      对于已购买云开发套餐并已产生费用的客户,如服务可用性低于标准,开发者有权根据服务等级协议中的赔偿方案,通过相应账户的 工单 申请赔付。具体可用性计算规则、赔偿标准和申请方式遵循《腾讯云云开发服务等级协议(SLA)》中的规定。

                      特别说明

                      • 自付费功能上线起,将不再受理通过邮箱申请的小程序·云开发配额调整申请。
                      • 对于截止2019-06-21日前申请调整的配额的截止日期统一延长至2019-08-31。


                      小程序插件中使用云开发

                      从基础库 2.4.1 开始,在小程序插件中可以使用云开发,插件中使用云开发时,使用的是插件方的云资源而非宿主的云资源,在使用方式上与在小程序中使用无异。


                      开发指引

                      云开发提供了一整套云服务及简单、易用的 API 和管理界面,以尽可能降低后端开发成本,让开发者能够专注于核心业务逻辑的开发、尽可能轻松的完成后端的操作和管理。

                      下面我们将分一下部分介绍如何上手使用云能力:


                      云开发控制台

                      云开发提供了一个控制台用于可视化管理云资源。控制台包含以下几大模块。

                      • 概览:查看云资源的总体使用情况
                      • 用户管理:查看小程序的用户访问记录
                      • 数据库:管理数据库集合、记录、权限设置、索引设置
                      • 存储管理:管理云文件、权限设置
                      • 云函数:管理云函数、查看调用日志、监控记录
                      • 统计分析:查看云资源详细使用统计

                      在用户管理中会显示使用云能力的小程序的访问用户列表,默认以访问时间倒叙排列,访问时间的触发点是在小程序端调用 wx.cloud.init 方法,且其中的 traceUser 参数传值为 true。例:

                      wx.cloud.init({  traceUser: true})

                      初始化

                      在小程序端开始使用云能力前,需先调用 wx.cloud.init 方法完成云能力初始化(注意小程序需先开通云服务,开通的方法是点击工具栏左上角的 “控制台” 按钮)。因此,如果要使用云能力,通常我们在小程序初始化时即调用这个方法。

                      wx.cloud.init 方法的定义如下:

                      function init(options): void

                      wx.cloud.init 方法接受一个可选的 options 参数,方法没有返回值。

                      options 参数定义了云开发的默认配置,该配置会作为之后调用其他所有云 API 的默认配置,options 提供的可选配置如下:

                      字段数据类型必填默认值说明
                      envstring | objectdefault默认环境配置,传入字符串形式的环境 ID 可以指定所有服务的默认环境,传入对象可以分别指定各个服务的默认环境,见下方详细定义
                      traceUserbooleanfalse是否在将用户访问记录到用户管理中,在控制台中可见

                      当 env 传入参数为对象时,可以指定各个服务的默认环境,可选字段如下:

                      字段数据类型必填默认值说明
                      databasestringdefault数据库 API 默认环境配置
                      storagestringdefault存储 API 默认环境配置
                      functionsstringdefault云函数 API 默认环境配置

                      示例代码:

                      wx.cloud.init({  env: 'test-x1dzi'})

                      云函数端初始化

                      cloud.init 方法的定义如下:

                      function init(options): void

                      cloud.init 方法接受一个可选的 options 参数,方法没有返回值。方法只能调用一次,多次调用时只有第一次调用生效。

                      options 参数定义了云开发的默认配置,该配置会作为之后调用其他所有云 API 的默认配置,options 提供的可选配置如下:

                      字段数据类型必填默认值说明
                      envstring | object后续 API 调用的默认环境配置,传入字符串形式的环境 ID 或传入 cloud.DYNAMIC_CURRENT_ENV 可以指定所有服务的默认环境,传入对象可以分别指定各个服务的默认环境,见下方详细定义

                      当 env 传入参数为对象时,可以指定各个服务的默认环境,可选字段如下:

                      字段数据类型必填默认值说明
                      databasestringdefault数据库 API 默认环境配置
                      storagestringdefault存储 API 默认环境配置
                      functionsstringdefault云函数 API 默认环境配置
                      defaultstring缺省时 API 默认环境配置

                      注意:env 设置只会决定本次云函数 API 调用的云环境,并不会决定接下来其他被调云函数中的 API 调用的环境,在其他被调云函数中需要通过 init 方法重新设置环境。

                      建议:在设置 env 时指定 cloud.DYNAMIC_CURRENT_ENV 常量 (需 SDK v1.1.0 或以上) ,这样云函数内发起数据库请求、存储请求或调用其他云函数的时候,默认请求的云环境就是云函数当前所在的环境:

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event) => {  const { ENV, OPENID, APPID } = cloud.getWXContext()  // 如果云函数所在环境为 abc,则下面的调用就会请求到 abc 环境的数据库  const dbResult = await cloud.database().collection('test').get()  return {    dbResult,    ENV,    OPENID,    APPID,  }}
                      注:上述代码中的 env 参数的值不能用 cloud.getWXContext().ENV 替代,因为在 exports.main 外部调用的 getWXContext() 无法获取到当前环境

                      API 风格

                      云开发的 API 风格与框架组件和 API 风格一致,但同时支持回调风格和Promise风格。在传入 API 的 Object 参数中,如果传入了 success、fail、complete 字段,则我们认为是采用回调风格,API 方法调用不返回 Promise。如果传入 API 的 Object 参数中 success、fail、complete 这三个字段都不存在,则我们认为是采用Promise风格,API 方法调用返回一个 Promise,Promise resolve 的结果同传入 success 回调的参数,reject 的结果同传入 fail 的参数。

                      注意事项

                      • 如果 init 时不传 env 参数,后续 API 调用将默认请求到第一个创建的环境,但这种方式并不总是预期的,因此这种方式已废弃,请务必明确传入 env 参数


                      调试

                      • 云函数本地调试
                      • Network 面板
                      • 环境提示

                      云函数本地调试

                      云开发提供了云函数本地调试功能,在本地提供了一套与线上一致的 Node.js 云函数运行环境,让开发者可以在本地对云函数调试,使用本地调试可以提高开发、调试效率:

                      • 单步调试/断点调试:比起通过云开发控制台中查看线上打的日志的方法进行调试,使用本地调试后可以对云函数 Node.js 实例进行单步调试/断点调试
                      • 集成小程序测试:在模拟器中对小程序发起的交互点击等操作如果触发了开启了本地调试的云函数,会请求到本地实例而不是云端
                      • 优化开发流程、提高开发效率:调试阶段不需上传部署云函数,在调试云函数时,相对于不使用本地调试时的调试流程(“本地修改代码 -> 上传部署云函数 -> 调用")的调试流程,省去了上传等待的步骤,改成只需 “本地修改 -> 调用” 的流程,大大提高开发调试效率

                      同时,本地调试还定制化提供了特殊的调试能力,包括 Network 面板支持展示 HTTP 请求和云开发请求、调用关系图展示、本地代码修改时热重载等等能力,帮助开发者更好的开发调试云函数。功能具体介绍见下方。

                      建议开发者在开发阶段和上传代码前先使用本地调试测试通过后再上线部署。

                      更详细的文档点此查看。

                      Network 面板

                      从微信开发者工具 1.02.1905302 及基础库 2.7.1 起,在小程序 Network 面板中会显示云开发请求(数据库、云函数、文件存储等调用),在 Network 面板中呈现时展示的是 API 名(wx.cloud.uploadFile 和 wx.cloud.downloadFile 除外),有特殊的请求类型 cloud,会展示调用所实际请求的环境 ID、请求体(数据库调用的请求体以 SDK 语法展示)、JSON 回包、耗时、及调用堆栈。

                      注意事项: 在开发者工具中云开发接口的实现与客户端有差异,开发者工具中的耗时普遍会比客户端慢,我们在特定环境下的测试结果是客户端会比开发者工具快 33% 左右。

                      以下是示例:

                      devtools-cloud-network

                      数据库调用详情示例:

                      devtools-cloud-network

                      回包示例:

                      devtools-cloud-network

                      环境提示

                      从微信开发者工具 1.02.1905302 及基础库 2.7.1 起,在小程序调试器中,如果使用到 wx.cloud.init,则会在调试器中输出当前配置的小程序中使用的默认调用环境。

                      devtools-network-cloud-init


                      如在云开发数据库的基础介绍中所说,云开发提供了一个 JSON 数据库,本章将介绍以下内容:

                      • 上手:用控制台创建我的第一个集合,插入我的第一条数据
                      • 数据类型:了解数据库提供的数据类型
                      • 权限控制:控制集合与记录的读写权限
                      • 初始化:初始化数据库 API
                      • 插入数据
                      • 读取数据:读取数据
                      • 构建查询条件:构建简单或复杂的查询条件
                      • 更新数据:数据的局部更新与替换更新
                      • 删除数据
                      • 索引管理:为字段添加索引实现高效读写

                      另外可参考小程序端和云函数端的数据库 API 文档


                      上手云数据库

                      这一节我们将介绍如何在控制台中创建我们的第一个数据库集合、往集合上插入数据、以及在控制台中查看刚刚插入的数据。

                      创建第一个集合

                      打开控制台,选择 "数据库" 标签页,通过 "添加集合" 入口创建一个集合。假设我们要创建一个待办事项小程序,我们创建一个名为 todos 的集合。创建成功后,可以看到 todos 集合管理界面,界面中我们可以添加记录、查找记录、管理索引和管理权限。

                      数据库

                      创建第一条记录

                      控制台提供了可视化添加数据的交互界面,点击 "添加记录" 添加我们的第一条待办事项:

                      {  // 描述,String 类型  "description": "learn mini-program cloud service",  // 截止时间,Date 类型  "due": Date("2018-09-01"),  // 标签,Array 类型  "tags": [    "tech",    "mini-program",    "cloud"  ],  // 个性化样式,Object 类型  "style": {    "color": "red"  },  // 是否已完成,Boolean 类型  "done": false}

                      添加完成后可在控制台中查看到刚添加的数据。

                      导入数据

                      云控制台支持上传文件导入已有的数据,可查看导入指引了解如何操作。

                      接下来,我们一起了解下数据库都提供了哪些数据类型。


                      数据类型

                      云开发数据库提供以下几种数据类型:

                      • String:字符串
                      • Number:数字
                      • Object:对象
                      • Array:数组
                      • Bool:布尔值
                      • GeoPoint:地理位置点
                      • Date:时间
                      • Null

                      下面对几个需要额外说明的字段做下补充说明。

                      Date

                      Date 类型用于表示时间,精确到毫秒,在小程序端可用 JavaScript 内置 Date 对象创建。需要特别注意的是,在小程序端创建的时间是客户端时间,不是服务端时间,这意味着在小程序端的时间与服务端时间不一定吻合,如果需要使用服务端时间,应该用 API 中提供的 serverDate 对象来创建一个服务端当前时间的标记,当使用了 serverDate 对象的请求抵达服务端处理时,该字段会被转换成服务端当前的时间,更棒的是,我们在构造 serverDate 对象时还可通过传入一个有 offset 字段的对象来标记一个与当前服务端时间偏移 offset 毫秒的时间,这样我们就可以达到比如如下效果:指定一个字段为服务端时间往后一个小时。

                      那么当我们需要使用客户端时间时,存放 Date 对象和存放毫秒数是否是一样的效果呢?不是的,我们的数据库有针对日期类型的优化,建议大家使用时都用 Date 或 serverDate 构造时间对象。

                      GeoPoint

                      GeoPoint 类型用于表示地理位置点,用经纬度唯一标记一个点,这是一个特殊的数据存储类型。注意,如果需要对类型为地理位置的字段进行查找,一定要建立地理位置索引。

                      具体的地理位置 API 可参考 Geo API 文档

                      Null

                      null 相当于一个占位符,表示一个字段存在但是值为空。


                      权限控制

                      数据库的权限分为小程序端和管理端,管理端包括云函数端和控制台。小程序端运行在小程序中,读写数据库受权限控制限制,管理端运行在云函数上,拥有所有读写数据库的权限。云控制台的权限同管理端,拥有所有权限。小程序端操作数据库应有严格的安全规则限制。

                      初期我们对操作数据库开放以下几种权限配置,每个集合可以拥有一种权限配置,权限配置的规则是作用在集合的每个记录上的。出于易用性和安全性的考虑,云开发为云数据库做了小程序深度整合,在小程序中创建的每个数据库记录都会带有该记录创建者(即小程序用户)的信息,以 _openid 字段保存用户的 openid 在每个相应用户创建的记录中。因此,权限控制也相应围绕着一个用户是否应该拥有权限操作其他用户创建的数据展开。

                      以下按照权限级别从宽到紧排列如下:

                      • 仅创建者可写,所有人可读:数据只有创建者可写、所有人可读;比如文章。
                      • 仅创建者可读写:数据只有创建者可读写,其他用户不可读写;比如用私密相册。
                      • 仅管理端可写,所有人可读:该数据只有管理端可写,所有人可读;如商品信息。
                      • 仅管理端可读写:该数据只有管理端可读写;如后台用的不暴露的数据。

                      简而言之,管理端始终拥有读写所有数据的权限,小程序端始终不能写他人创建的数据,小程序端的记录的读写权限其实分为了 “所有人可读,只有创建者可写“、”仅创建者可读写“、”所有人可读,仅管理端可写“、”所有人不可读,仅管理端可读写“。

                      对一个用户来说,不同模式在小程序端和管理端的权限表现如下:

                      模式小程序端
                      读自己创建的数据
                      小程序端
                      写自己创建的数据
                      小程序端
                      读他人创建的数据
                      小程序端
                      写他人创建的数据
                      管理端
                      读写任意数据
                      仅创建者可写,所有人可读×
                      仅创建者可读写××
                      仅管理端可写,所有人可读××
                      仅管理端可读写:该数据只有管理端可读写××××

                      在设置集合权限时应谨慎设置,防止出现越权操作。


                      初始化

                      在开始使用数据库 API 进行增删改查操作之前,需要先获取数据库的引用。以下调用获取默认环境的数据库的引用:

                      const db = wx.cloud.database()

                      如需获取其他环境的数据库引用,可以在调用时传入一个对象参数,在其中通过 env 字段指定要使用的环境。此时方法会返回一个对测试环境数据库的引用。

                      示例:假设有一个环境名为 test,用做测试环境,那么可以如下获取测试环境数据库:

                      const testDB = wx.cloud.database({  env: 'test'})

                      要操作一个集合,需先获取它的引用。在获取了数据库的引用后,就可以通过数据库引用上的 collection 方法获取一个集合的引用了,比如获取待办事项清单集合:

                      const todos = db.collection('todos')

                      获取集合的引用并不会发起网络请求取拉取它的数据,我们可以通过此引用在该集合上进行增删查改的操作,除此之外,还可以通过集合上的 doc 方法来获取集合中一个指定 ID 的记录的引用。同理,记录的引用可以用于对特定记录进行更新和删除操作。

                      假设我们有一个待办事项的 ID 为 todo-identifiant-aleatoire,那么我们可以通过 doc 方法获取它的引用:

                      const todo = db.collection('todos').doc('todo-identifiant-aleatoire')

                      接下来,我们看看如何往集合中插入数据。


                      插入数据

                      可以通过在集合对象上调用 add 方法往集合中插入一条记录。还是用待办事项清单的例子,比如我们想新增一个待办事项:

                      db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    // _id: 'todo-identifiant-aleatoire', // 可选自定义 _id,在此处场景下用数据库自动分配的就可以了    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    // 为待办事项添加一个地理位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    // res 是一个对象,其中有 _id 字段标记刚创建的记录的 id    console.log(res)  }})

                      当然,Promise 风格也是支持的,只要传入对象中没有 success, fail 或 complete,那么 add 方法就会返回一个 Promise:

                      db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    location: new db.Geo.Point(113, 23),    done: false  }}).then(res => {  console.log(res)})

                      数据库的增删查改 API 都同时支持回调风格和 Promise 风格调用。

                      在创建成功之后,我们可以在控制台中查看到刚新增的数据。

                      可以在 add API 文档中查阅完整的 API 定义。

                      接下来,我们将学习如何使用 API 查询到刚插入的数据。


                      读取数据

                      在记录和集合上都有提供 get 方法用于获取单个记录或集合中多个记录的数据。

                      假设我们已有一个集合 todos,其中包含以下格式记录:

                      [  {    _id: 'todo-identifiant-aleatoire',    _openid: 'user-open-id', // 假设用户的 openid 为 user-open-id    description: "learn cloud database",    due: Date("2018-09-01"),    progress: 20,    tags: [      "cloud",      "database"    ],    style: {      color: 'white',      size: 'large'    },    location: Point(113.33, 23.33), // 113.33°E,23.33°N    done: false  },  {    _id: 'todo-identifiant-aleatoire-2',    _openid: 'user-open-id', // 假设用户的 openid 为 user-open-id    description: "write a novel",    due: Date("2018-12-25"),    progress: 50,    tags: [      "writing"    ],    style: {      color: 'yellow',      size: 'normal'    },    location: Point(113.22, 23.22), // 113.22°E,23.22°N    done: false  }  // more...]

                      获取一个记录的数据

                      我们先来看看如何获取一个记录的数据,假设我们已有一个 ID 为 todo-identifiant-aleatoire 的在集合 todos 上的记录,那么我们可以通过在该记录的引用调用 get 方法获取这个待办事项的数据:

                      db.collection('todos').doc('todo-identifiant-aleatoire').get({  success: function(res) {    // res.data 包含该记录的数据    console.log(res.data)  }})

                      也可以用 Promise 风格调用:

                      db.collection('todos').doc('todo-identifiant-aleatoire').get().then(res => {  // res.data 包含该记录的数据  console.log(res.data)})

                      获取多个记录的数据

                      我们也可以一次性获取多条记录。通过调用集合上的 where 方法可以指定查询条件,再调用 get 方法即可只返回满足指定查询条件的记录,比如获取用户的所有未完成的待办事项:

                      db.collection('todos').where({  _openid: 'user-open-id',  done: false}).get({  success: function(res) {    // res.data 是包含以上定义的两条记录的数组    console.log(res.data)  }})

                      where 方法接收一个对象参数,该对象中每个字段和它的值构成一个需满足的匹配条件,各个字段间的关系是 "与" 的关系,即需同时满足这些匹配条件,在这个例子中,就是查询出 todos 集合中 _openid 等于 user-open-id 且 done 等于 false 的记录。在查询条件中我们也可以指定匹配一个嵌套字段的值,比如找出自己的标为黄色的待办事项:

                      db.collection('todos').where({  _openid: 'user-open-id',  style: {    color: 'yellow'  }}).get({  success: function(res) {    console.log(res.data)  }})

                      也可以用 "点表示法" 表示嵌套字段:

                      db.collection('todos').where({  _openid: 'user-open-id',  'style.color': 'yellow'}).get({  success: function(res) {    console.log(res.data)  }})

                      获取一个集合的数据

                      如果要获取一个集合的数据,比如获取 todos 集合上的所有记录,可以在集合上调用 get 方法获取,但通常不建议这么使用,在小程序中我们需要尽量避免一次性获取过量的数据,只应获取必要的数据。为了防止误操作以及保护小程序体验,小程序端在获取集合数据时服务器一次默认并且最多返回 20 条记录,云函数端这个数字则是 100。开发者可以通过 limit 方法指定需要获取的记录数量,但小程序端不能超过 20 条,云函数端不能超过 100 条。

                      db.collection('todos').get({  success: function(res) {    // res.data 是一个包含集合中有权限访问的所有记录的数据,不超过 20 条    console.log(res.data)  }})

                      也可以用 Promise 风格调用:

                      db.collection('todos').get().then(res => {  // res.data 是一个包含集合中有权限访问的所有记录的数据,不超过 20 条  console.log(res.data)})

                      下面是在云函数端获取一个集合所有记录的例子,因为有最多一次取 100 条的限制,因此很可能一个请求无法取出所有数据,需要分批次取:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const MAX_LIMIT = 100exports.main = async (event, context) => {  // 先取出集合记录总数  const countResult = await db.collection('todos').count()  const total = countResult.total  // 计算需分几次取  const batchTimes = Math.ceil(total / 100)  // 承载所有读操作的 promise 的数组  const tasks = []  for (let i = 0; i < batchTimes; i++) {    const promise = db.collection('todos').skip(i * MAX_LIMIT).limit(MAX_LIMIT).get()    tasks.push(promise)  }  // 等待所有  return (await Promise.all(tasks)).reduce((acc, cur) => {    return {      data: acc.data.concat(cur.data),      errMsg: acc.errMsg,    }  })}

                      接下来,我们将学习如何使用进阶的查询条件来完成简单或复杂的查询。


                      构建查询条件

                      使用数据库 API 提供的 where 方法我们可以构造复杂的查询条件完成复杂的查询任务。

                      查询指令

                      假设我们需要查询进度大于 30% 的待办事项,那么传入对象表示全等匹配的方式就无法满足了,这时就需要用到查询指令。数据库 API 提供了大于、小于等多种查询指令,这些指令都暴露在 db.command 对象上。比如查询进度大于 30% 的待办事项:

                      const _ = db.commanddb.collection('todos').where({  // gt 方法用于指定一个 "大于" 条件,此处 _.gt(30) 是一个 "大于 30" 的条件  progress: _.gt(30)}).get({  success: function(res) {    console.log(res.data)  }})

                      API 提供了以下查询指令:

                      查询指令说明
                      eq等于
                      neq不等于
                      lt小于
                      lte小于或等于
                      gt大于
                      gte大于或等于
                      in字段值在给定数组中
                      nin字段值不在给定数组中

                      具体的查询指令 API 文档可参考数据库 API 文档。

                      逻辑指令

                      除了指定一个字段满足一个条件之外,我们还可以通过指定一个字段需同时满足多个条件,比如用 and 逻辑指令查询进度在 30% 和 70% 之间的待办事项:

                      const _ = db.commanddb.collection('todos').where({  // and 方法用于指定一个 "与" 条件,此处表示需同时满足 _.gt(30) 和 _.lt(70) 两个条件  progress: _.gt(30).and(_.lt(70))}).get({  success: function(res) {    console.log(res.data)  }})

                      既然有 and,当然也有 or 了,比如查询进度为 0 或 100 的待办事项:

                      const _ = db.commanddb.collection('todos').where({  // or 方法用于指定一个 "或" 条件,此处表示需满足 _.eq(0) 或 _.eq(100)  progress: _.eq(0).or(_.eq(100))}).get({  success: function(res) {    console.log(res.data)  }})

                      如果我们需要跨字段进行 "或" 操作,可以做到吗?答案是肯定的,or 指令还可以用来接受多个(可以多于两个)查询条件,表示需满足多个查询条件中的任意一个,比如我们查询进度小于或等于 50% 或颜色为白色或黄色的待办事项:

                      const _ = db.commanddb.collection('todos').where(_.or([  {    progress: _.lte(50)  },  {    style: {      color: _.in(['white', 'yellow'])    }  }])).get({  success: function(res) {    console.log(res.data)  }})

                      具体的逻辑查询指令 API 文档可参考数据库 API 文档。

                      接下来,我们一起学习如何更新数据。


                      更新数据

                      现在我们一起看看如何使用数据库 API 完成数据更新。

                      更新数据主要有两个方法:

                      API说明
                      update局部更新一个或多个记录
                      set替换更新一个记录

                      局部更新

                      使用 update 方法可以局部更新一个记录或一个集合中的记录,局部更新意味着只有指定的字段会得到更新,其他字段不受影响。

                      比如我们可以用以下代码将一个待办事项置为已完成:

                      db.collection('todos').doc('todo-identifiant-aleatoire').update({  // data 传入需要局部更新的数据  data: {    // 表示将 done 字段置为 true    done: true  },  success: function(res) {    console.log(res.data)  }})

                      除了用指定值更新字段外,数据库 API 还提供了一系列的更新指令用于执行更复杂的更新操作,更新指令可以通过 db.command 取得:

                      更新指令说明
                      set设置字段为指定值
                      remove删除字段
                      inc原子自增字段值
                      mul原子自乘字段值
                      push如字段值为数组,往数组尾部增加指定值
                      pop如字段值为数组,从数组尾部删除一个元素
                      shift如字段值为数组,从数组头部删除一个元素
                      unshift如字段值为数组,往数组头部增加指定值

                      比如我们可以将一个待办事项的进度 +10%:

                      const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').update({  data: {    // 表示指示数据库将字段自增 10    progress: _.inc(10)  },  success: function(res) {    console.log(res.data)  }})

                      用 inc 指令而不是取出值、加 10 再写进去的好处在于这个写操作是个原子操作,不会受到并发写的影响,比如同时有两名用户 A 和 B 取了同一个字段值,然后分别加上 10 和 20 再写进数据库,那么这个字段最终结果会是加了 20 而不是 30。如果使用 inc 指令则不会有这个问题。

                      如果字段是个数组,那么我们可以使用 push、pop、shift 和 unshift 对数组进行原子更新操作,比如给一条待办事项加多一个标签:

                      const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').update({  data: {    tags: _.push('mini-program')  },  success: function(res) {    console.log(res.data)  }})

                      可能读者已经注意到我们提供了 set 指令,这个指令有什么用呢?这个指令的用处在于更新一个字段值为另一个对象。比如如下语句是更新 style.color 字段为 'blue' 而不是把 style 字段更新为 { color: 'blue' } 对象:

                      const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').update({  data: {    style: {      color: 'blue'    }  },  success: function(res) {    console.log(res.data)  }})

                      如果需要将这个 style 字段更新为另一个对象,可以使用 set 指令:

                      const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').update({  data: {    style: _.set({      color: 'blue'    })  },  success: function(res) {    console.log(res.data)  }})

                      如果需要更新多个数据,需在 Server 端进行操作(云函数),在 where 语句后同样的调用 update 方法即可,比如将所有未完待办事项的进度加 10%:

                      // 使用了 async await 语法const cloud = require('wx-server-sdk')const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: false      })    .update({      data: {        progress: _.inc(10)      },    })  } catch(e) {    console.error(e)  }}

                      更完整详细的更新指令可以参考数据库 API 文档

                      替换更新

                      如果需要替换更新一条记录,可以在记录上使用 set 方法,替换更新意味着用传入的对象替换指定的记录:

                      const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').set({  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    style: {      color: "skyblue"    },    // 位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    console.log(res.data)  }})

                      如果指定 ID 的记录不存在,则会自动创建该记录,该记录将拥有指定的 ID。

                      接下来,我们将一起学习如何删除记录。


                      删除数据

                      我们一起看看如何使用数据库 API 完成数据删除。

                      删除一条记录

                      对记录使用 remove 方法可以删除该条记录,比如:

                      db.collection('todos').doc('todo-identifiant-aleatoire').remove({  success: function(res) {    console.log(res.data)  }})

                      删除多条记录

                      如果需要更新多个数据,需在 Server 端进行操作(云函数)。可通过 where 语句选取多条记录执行删除,只有有权限删除的记录会被删除。比如删除所有已完成的待办事项:

                      // 使用了 async await 语法const cloud = require('wx-server-sdk')const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: true    }).remove()  } catch(e) {    console.error(e)  }}

                      在大多数情况下,我们希望用户只能操作自己的数据(自己的代表事项),不能操作其他人的数据(其他人的待办事项),这就需要引入权限控制了。

                      接下来,我们看看如何控制集合与记录的读写权限,达到保护数据的目的。


                      索引管理

                      建立索引是保证数据库性能、保证小程序体验的重要手段。我们应为所有需要成为查询条件的字段建立索引。建立索引的入口在控制台中,可分别对各个集合的字段添加索引。

                      单字段索引

                      对需要作为查询条件筛选的字段,我们可以创建单字段索引。如果需要对嵌套字段进行索引,那么可以通过 "点表示法" 用点连接起嵌套字段的名称。比如我们需要对如下格式的记录中的 color 字段进行索引时,可以用 style.color 表示。

                      {  _id: '',  style: {    color: ''  }}

                      在设置单字段索引时,指定排序为升序或降序并没有关系。在需要对索引字段按排序查询时,数据库能够正确的对字段排序,无论索引设置为升序还是降序。

                      组合索引

                      组合索引即一个索引包含多个字段。当查询条件使用的字段包含在索引定义的所有字段或前缀字段里时,会命中索引,优化查询性能。索引前缀即组合索引的字段中定义的前 1 到多个字段,如有在 A, B, C 三个字段定义的组合索引 A, B, C,那么 A 和 A, B 都属于该索引的前缀。

                      组合索引具有以下特点:

                      1. 字段顺序决定索引效果

                      定义组合索引时,多个字段间的顺序不同是会有不同的索引效果的。比如对两个字段 A 和 B 进行索引,定义组合索引为 A, B 与定义组合索引为 B, A是不同的。当定义组合索引为 A, B 时,索引会先按 A 字段排序再按 B 字段排序。因此当组合索引设为 A, B 时,即使我们没有单独对字段 A 设立索引,但对字段 A 的查询可以命中 A, B 索引。需要注意的是,此时对字段 B 的查询是无法命中 A, B 索引的,因为 B 不属于索引 A, B 的前缀之一。

                      2. 字段排序决定排序查询是否可以命中索引

                      加入我们对字段 A 和 B 设置以下索引:

                      A: 升序B: 降序

                      那么当我们查询需要对 A, B 进行排序时,可以指定排序结果为 A 升序 B 降序或 A 降序 B 升序,但不能指定为 A 升序 B 升序或 A 降序 B 降序。


                      索引属性

                      唯一性限制

                      创建索引时可以指定增加唯一性限制,具有唯一性限制的索引会要求被索引集合不能存在被索引字段值都相同的两个记录。即对任意具有唯一性限制的索引 I,假设其索引字段为 <F1, F2, ..., Fn>,则对集合 S 中任意的两个记录 R1 和 R2,必须满足条件 R1.F1 != R2.F1 && R1.F2 != R2.F2 && ... && R1.Fn != R2.Fn。需特别注意的是,假如记录中不存在某个字段,则对索引字段来说其值默认为 null,如果索引有唯一性限制,则不允许存在两个或以上的该字段为空 / 不存在该字段的记录。

                      在创建索引的时候索引属性选择 唯一 即可添加唯一性限制。


                      数据库导入

                      云开发控制台支持从文件导入已有的数据。目前仅支持导入 CSV、JSON 格式的文件数据。

                      要导入数据,需打开云开发控制台,切换到 “数据库” 标签页,并选择要导入数据的集合,点击 “导入” 按钮。

                      数据库

                      选择要导入的 CSV 或者 JSON 文件,以及冲突处理模式,点击 “导入” 按钮即可开始导入。

                      文件格式

                      JSON、CSV 文件必须是 UTF-8 的编码格式,且其内容类似 MongoDB 的导出格式,例如:

                      JSON:

                      {    "_id": "xxxxxx",    "age": 45}{    "_id": "yyyyyy",    "age": 21}

                      CSV:

                      _id,agexxxxxx,45yyyyyy,21

                      需要注意以下几点:

                      1、JSON 数据不是数组,而是类似 JSON Lines,即各个记录对象之间使用   分隔,而非逗号;

                      2、JSON 数据每个键值对的键名首尾不能是 .,例如 ".a"、"abc.",且不能包含多个连续的 .,例如 "a..b";

                      3、键名不能重复,且不能有歧义,例如 {"a": 1, "a": 2} 或 {"a": {"b": 1}, "a.b": 2};

                      4、时间格式须为 ISODate 格式,例如 "date": { "$date" : "2018-08-31T17:30:00.882Z" };

                      5、当使用 Insert 冲突处理模式时,同一文件不能存在重复的 _id 字段,或与数据库已有记录相同的 _id 字段;

                      6、CSV 格式的数据默认以第一行作为导入后的所有键名,余下的每一行则是与首行键名一一对应的键值记录。

                      目前提供了 Insert、Upsert 两种冲突处理模式。Insert 模式会在导入时总是插入新记录,Upsert 则会判断有无该条记录,如果有则更新记录,否则就插入一条新记录。

                      导入完成后,可以在提示信息中看到本次导入记录的情况。

                      数据库


                      数据库导出

                      云开发控制台支持导出集合已有的数据。目前仅支持导出 CSV、JSON 格式的文件数据。

                      要导出数据,需打开云开发控制台,切换到 “数据库” 标签页,并选择要导出数据的集合,点击 “导出” 链接。

                      数据库

                      选择要导出的格式、保存的位置,以及字段,点击 “导出” 按钮即可开始导出的过程。

                      当选择导出格式为 JSON 时,若不填写字段项,则默认导出所有数据。

                      当选择导出格式为 CSV 时,则字段为必填项。字段之间使用英文逗号隔开,例如:

                      _id,name,age,gender

                      数据库备份与回档

                      从开发者工具 1.02.202002282 版本开始,云开发提供了数据库回档功能。系统会自动开启数据库备份,并于每日凌晨自动进行一次数据备份,最长保存 7 天的备份数据。如有需要,开发者可在云控制台上通过新建回档任务将集合回档(还原)至指定时间点。

                      回档期间,数据库的数据访问不受影响。回档完成后,开发者可在集合列表中看到原有数据库集合和回档后的集合。

                      新建回档

                      1. 登录微信开发者工具的云开发控制台。
                      2. 在数据库页面点击数据库回档后可新建回档任务。

                      新建回档任务

                      1. 点击新建回档后,可选择所需回档的时间点和需要回档的集合。请注意:
                      • 一次回档任务只能设置一个回档时间,所有待回档集合的回档时间都以此时间点为准;
                      • 一次回档任务可选择多个集合,点击全选可回档该环境下所有集合。

                      选择回档时间和集合

                      1. 点击下一步后可设置回档后集合名称,请注意:
                      • 每个待回档集合都可单独设置回档后的集合名称;
                      • 系统会默认生成回档后的集合名称,生成规则为:待回档集合名称_bak;
                      • 回档后集合名称不可与已有集合名称重复。

                      回档后集合名称

                      1. 点击确定后,开发者可在数据库回档页面查看回档进度。请注意:
                      • 为避免数据冲突,当前有回档任务在执行时,将无法创建新的回档任务;
                      • 回档完成后,开发者可在集合列表中看到原有数据库集合和回档后的集合。

                      重命名集合

                      回档已完成后,如有需要,开发者可在集合列表中选择对应集合,右键重命名该集合名称。


                      云存储提供高可用、高稳定、强安全的云端存储服务,支持任意数量和形式的非结构化数据存储,如视频和图片,并在控制台进行可视化管理。云存储包含以下功能:

                      • 存储管理:支持文件夹,方便文件归类。支持文件的上传、删除、移动、下载、搜索等,并可以查看文件的详情信息
                      • 权限设置:可以灵活设置哪些用户是否可以读写该文件夹中的文件,以保证业务的数据安全
                      • 上传管理:在这里可以查看文件上传历史、进度及状态
                      • 文件搜索:支持文件前缀名称及子目录文件的搜索
                      • 组件支持:支持在 image、audio 等组件中传入云文件 ID

                      接下来,我们看看云文件管理提供了哪些 API、及如何在控制台中管理云文件:

                      • 存储 API
                      • 控制台中管理文件

                      API 指引

                      上传文件

                      在小程序端可调用 wx.cloud.uploadFile 方法进行上传:

                      wx.cloud.uploadFile({  cloudPath: 'example.png', // 上传至云端的路径  filePath: '', // 小程序临时文件路径  success: res => {    // 返回文件 ID    console.log(res.fileID)  },  fail: console.error})

                      上传成功后会获得文件唯一标识符,即文件 ID,后续操作都基于文件 ID 而不是 URL。

                      下载文件

                      可以根据文件 ID 下载文件,用户仅可下载其有访问权限的文件:

                      wx.cloud.downloadFile({  fileID: '', // 文件 ID  success: res => {    // 返回临时文件路径    console.log(res.tempFilePath)  },  fail: console.error})

                      删除文件

                      可以通过 wx.cloud.deleteFile 删除文件:

                      wx.cloud.deleteFile({  fileList: ['a7xzcb'],  success: res => {    // handle success    console.log(res.fileList)  },  fail: console.error})

                      更详细的 API 可参考小程序端及后端存储 API 文件。

                      组件支持

                      支持在 image、audio 等组件中传入云文件 ID,具体支持列表见文档

                      换取临时链接

                      可以根据文件 ID 换取临时文件网络链接,文件链接有有效期为两个小时:

                      wx.cloud.getTempFileURL({  fileList: ['cloud://xxx.png'],  success: res => {    // fileList 是一个有如下结构的对象数组    // [{    //    fileID: 'cloud://xxx.png', // 文件 ID    //    tempFileURL: '', // 临时文件网络链接    //    maxAge: 120 * 60 * 1000, // 有效期    // }]    console.log(res.fileList)  },  fail: console.error})

                      API 文档

                      可以在此参考详细的小程序端存储 API 文档和服务端 API 文档


                      管理文件

                      在控制台中,选择存储管理标签页,可以在此看到云存储空间中所有的文件,还可以查看文件的详细信息、控制存储空间的读写权限。



                      文件名命名限制

                      • 不能为空
                      • 不能以/开头
                      • 不能出现连续/
                      • 编码长度最大为850个字节
                      • 推荐使用大小写英文字母、数字,即[a-z,A-Z,0-9]和符号 -,!,_,.,* 及其组合
                      • 不支持 ASCII 控制字符中的字符上(↑),字符下(↓),字符右(→),字符左(←),分别对应 CAN(24),EM(25),SUB(26),ESC(27)
                      • 如果用户上传的文件或文件夹的名字带有中文,在访问和请求这个文件或文件夹时,中文部分将按照 URL Encode 规则转化为百分号编码。
                      • 不建议使用的特殊字符: ` ^ " { } [ ] ~ % # > < 及 ASCII 128-255 十进制
                      • 可能需特殊处理后再使用的特殊字符: , : ; = & $ @ + ?(空格)及ASCII 字符范围:00-1F 十六进制(0-31 十进制)以及7F(127 十进制)

                      组件支持

                      小程序组件支持传入云文件 ID,支持列表如下:

                      组件属性
                      imagesrc
                      videosrc、poster
                      cover-imagesrc
                      接口参数
                      getBackgroundAudioManagersrc
                      createInnerAudioContextsrc
                      previewImageurls、current


                      云函数即在云端(服务器端)运行的函数。在物理设计上,一个云函数可由多个文件组成,占用一定量的 CPU 内存等计算资源;各云函数完全独立;可分别部署在不同的地区。开发者无需购买、搭建服务器,只需编写函数代码并部署到云端即可在小程序端调用,同时云函数之间也可互相调用。

                      一个云函数的写法与一个在本地定义的 JavaScript 方法无异,代码运行在云端 Node.js 中。当云函数被小程序端调用时,定义的代码会被放在 Node.js 运行环境中执行。我们可以如在 Node.js 环境中使用 JavaScript 一样在云函数中进行网络请求等操作,而且我们还可以通过云函数后端 SDK 搭配使用多种服务,比如使用云函数 SDK 中提供的数据库和存储 API 进行数据库和存储的操作,这部分可参考数据库存储后端 API 文档。

                      云开发的云函数的独特优势在于与微信登录鉴权的无缝整合。当小程序端调用云函数时,云函数的传入参数中会被注入小程序端用户的 openid,开发者无需校验 openid 的正确性因为微信已经完成了这部分鉴权,开发者可以直接使用该 openid。

                      接下来,我们将逐步学习以下内容:

                      • 我的第一个云函数
                      • 获取小程序用户信息
                      • 异步返回结果
                      • 使用 wx-server-sdk
                      • 在开发者工具中管理云函数
                      • 测试、日志与监控
                      • 注意事项

                      我的第一个云函数

                      我们以定义一个将两个数字相加的函数作为我们第一个云函数的示例。

                      在项目根目录找到 project.config.json 文件,新增 cloudfunctionRoot 字段,指定本地已存在的目录作为云函数的本地根目录

                      示例:

                      {   "cloudfunctionRoot": "./functions/"}

                      project.config.json 的其他配置,详见项目配置文件

                      完成指定之后,云函数的根目录的图标会变成 “云目录图标”,云函数根目录下的第一级目录(云函数目录)是与云函数名字相同的,如果对应的线上环境存在该云函数,则我们会用一个特殊的 “云图标” 标明

                      接着,我们在云函数根目录上右键,在右键菜单中,可以选择创建一个新的 Node.js 云函数,我们将该云函数命名为 add。开发者工具在本地创建出云函数目录和入口 index.js 文件,同时在线上环境中创建出对应的云函数。创建成功后,工具会提示是否立即本地安装依赖,确定后工具会自动安装 wx-server-sdk。我们可以看到类似如下的一个云函数模板:

                      const cloud = require('wx-server-sdk')// 云函数入口函数exports.main = async (event, context) => {}

                      云函数的传入参数有两个,一个是 event 对象,一个是 context 对象。event 指的是触发云函数的事件,当小程序端调用云函数时,event 就是小程序端调用云函数时传入的参数,外加后端自动注入的小程序用户的 openid 和小程序的 appid。context 对象包含了此处调用的调用信息和运行状态,可以用它来了解服务运行的情况。在模板中也默认 require 了 wx-server-sdk,这是一个帮助我们在云函数中操作数据库、存储以及调用其他云函数的微信提供的库,关于 wx-server-sdk 的使用我们在另一个章节讲述。

                      我们填充一下模板:

                      exports.main = async (event, context) => {  return {    sum: event.a + event.b  }}

                      本段代码的意思是将传入的 a 和 b 相加并作为 sum 字段返回给调用端。

                      在小程序中调用这个云函数前,我们还需要先将该云函数部署到云端。在云函数目录上右键,在右键菜单中,我们可以将云函数整体打包上传并部署到线上环境中。

                      部署完成后,我们可以在小程序中调用该云函数:

                      wx.cloud.callFunction({  // 云函数名称  name: 'add',  // 传给云函数的参数  data: {    a: 1,    b: 2,  },  success: function(res) {    console.log(res.result) // 3  },  fail: console.error})

                      当然,Promise 风格的调用也是支持的:

                      wx.cloud.callFunction({  // 云函数名称  name: 'add',  // 传给云函数的参数  data: {    a: 1,    b: 2,  },}).then(res => {  console.log(res.result) // 3}).catch(console.error)

                      那么到这里,我们就成功创建了我们的第一个云函数,并在小程序中成功调用!

                      接下来,我们介绍云函数和小程序登录态如何无缝结合,以及如何在云函数端获取小程序用户信息(openid 和 appid)。


                      获取小程序用户信息

                      云开发的云函数的独特优势在于与微信登录鉴权的无缝整合。当小程序端调用云函数时,云函数的传入参数中会被注入小程序端用户的 openid,开发者无需校验 openid 的正确性,因为微信已经完成了这部分鉴权,开发者可以直接使用该 openid。与 openid 一起同时注入云函数的还有小程序的 appid。

                      从小程序端调用云函数时,开发者可以在云函数内使用 wx-server-sdk 提供的 getWXContext 方法获取到每次调用的上下文(appid、openid等),无需维护复杂的鉴权机制,即可获取天然可信任的用户登录态(openid)。可以写这么一个云函数进行测试:

                      // index.jsconst cloud = require('wx-server-sdk')exports.main = (event, context) => {  // 这里获取到的 openId、 appId 和 unionId 是可信的,注意 unionId 仅在满足 unionId 获取条件时返回  let { OPENID, APPID, UNIONID } = cloud.getWXContext()   return {    OPENID,    APPID,    UNIONID,  }}

                      假设云函数命名为 test,上传并部署该云函数后,可在小程序中测试调用:

                      wx.cloud.callFunction({  name: 'test',  complete: res => {    console.log('callFunction test result: ', res)  }})

                      会在调试器看到输出的 res 为如下结构的对象:

                      {  "APPID": "xxx",  "OPENID": "yyy",  "UNIONID": "zzz", // 仅在满足 unionId 获取条件时返回}

                      接下来,我们一起看看如果在云函数中需要进行一段异步操作再返回的时候该如何处理。


                      异步返回结果

                      经常,我们需要在云函数中处理一些异步操作,在异步操作完成后再返回结果给到调用方。此时我们可以通过在云函数中返回一个 Promise 的方法来完成。

                      一个最简的 setTimeout 示例:

                      // index.jsexports.main = async (event, context) => {  return new Promise((resolve, reject) => {    // 在 3 秒后返回结果给调用方(小程序 / 其他云函数)    setTimeout(() => {      resolve(event.a + event.b)    }, 3000)  })}

                      假设云函数名字为 test,上传部署该云函数后,我们可以在小程序端测试调用:

                      // 在小程序代码中:wx.cloud.callFunction({  name: 'test',  data: {    a: 1,    b: 2,  },  complete: res => {    console.log('callFunction test result: ', res)  },})

                      此时应该看到调试器输出:

                      callFunction test result: 3

                      使用 npm

                      在云函数中我们可以引入第三方依赖来帮助我们更快的开发。云函数的运行环境是 Node.js,因此我们可以使用 npm 安装第三方依赖。比如除了使用 Node.js 提供的原生 http 接口在云函数中发起网络请求,我们还可以使用一个流行的 Node.js 网络请求库 request 来更便捷的发起网络请求。

                      注意,现在上传云函数时不会在云端自动安装依赖,需要开发者在本地安装好依赖后一起打包上传。

                      接下来,我们一起了解下官方提供的云函数端 SDK: wx-server-sdk。


                      在云函数中使用 wx-server-sdk

                      云函数属于管理端,在云函数中运行的代码拥有不受限的数据库读写权限和云文件读写权限。需特别注意,云函数运行环境即是管理端,与云函数中的传入的 openId 对应的微信用户是否是小程序的管理员 / 开发者无关。

                      云函数中使用 wx-server-sdk 需在对应云函数目录下安装 wx-server-sdk 依赖,在创建云函数时会在云函数目录下默认新建一个 package.json 并提示用户是否立即本地安装依赖。请注意云函数的运行环境是 Node.js,因此在本地安装依赖时务必保证已安装 Node.js,同时 node 和 npm 都在环境变量中。如不本地安装依赖,可以用命令行在该目录下运行:

                      npm install --save wx-server-sdk@latest

                      在云函数中调用其他 API 前,同小程序端一样,也需要执行一次初始化方法:

                      const cloud = require('wx-server-sdk')// 默认配置cloud.init()// 或者传入自定义配置cloud.init({  env: 'some-env-id'})

                      wx-server-sdk 与小程序端的云 API 以同样的风格提供了数据库、存储和云函数的 API。下面提供几个简单的操作数据库、存储和云函数的示例:

                      云函数中调用数据库

                      假设在数据库中已有一个 todos 集合,我们可以如下方式取得 todos 集合的数据:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  // collection 上的 get 方法会返回一个 Promise,因此云函数会在数据库异步取完数据后返回结果  return db.collection('todos').get()}

                      云函数中调用存储

                      假设我们要上传在云函数目录中包含的一个图片文件(demo.jpg):

                      const cloud = require('wx-server-sdk')const fs = require('fs')const path = require('path')exports.main = async (event, context) => {  const fileStream = fs.createReadStream(path.join(__dirname, 'demo.jpg'))  return await cloud.uploadFile({    cloudPath: 'demo.jpg',    fileContent: fileStream,  })}
                      在云函数中,__dirname 的值是云端云函数代码所在目录

                      云函数中调用其他云函数

                      假设我们要在云函数中调用另一个云函数 sum 并返回 sum 所返回的结果:

                      const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  return await cloud.callFunction({    name: 'sum',    data: {      x: 1,      y: 2,    }  })}

                      更详细的 wx-server-sdk 文档可参见服务端 API 文档。

                      接下来,我们一起了解下云函数的运行机制。


                      运行机制

                      运行环境

                      云函数运行在云端 Linux 环境1中,一个云函数在处理并发请求的时候会创建多个云函数实例,每个云函数实例之间相互隔离,没有公用的内存或硬盘空间。云函数实例的创建、管理、销毁等操作由平台自动完成。每个云函数实例都在 /tmp 目录下提供了一块 512MB 的临时磁盘空间用于处理单次云函数执行过程中的临时文件读写需求,需特别注意的是,这块临时磁盘空间在函数执行完毕后可能被销毁,不应依赖和假设在磁盘空间存储的临时文件会一直存在。如果需要持久化的存储,请使用云存储功能。

                      无状态函数

                      云函数应是无状态的,幂等的,即一次云函数的执行不依赖上一次云函数执行过程中在运行环境中残留的信息。

                      为了保证负载均衡,云函数平台会根据当前负载情况控制云函数实例的数量,并且会在一些情况下重用云函数实例,这使得连续两次云函数调用如果都由同一个云函数实例运行,那么两者会共享同一个临时磁盘空间,但因为云函数实例随时可能被销毁,并且连续的请求不一定会落在同一个实例,因此云函数不应依赖之前云函数调用中在临时磁盘空间遗留的数据。总的原则即是云函数代码应是无状态的。

                      事件模型

                      云函数的调用采用事件触发模型,小程序端的每一次调用即触发了一次云函数调用事件,云函数平台会新建或复用已有的云函数实例来处理这次调用。同理,因为云函数间也可以相互调用,因此云函数间相互调用也是触发了一次调用事件。

                      自动扩缩容

                      开发者无需关心云函数扩容和缩容的问题,平台会根据负载自动进行扩缩容。

                      Footnotes

                      1. 当前运行环境是在 CentOS 7.2 中,特别注意编写代码不应依赖特定的操作系统或特定的操作系统版本号,运行环境可能会发生变化,代码应尽量与平台无关

                      注意事项 & FAQ

                      临时存储空间

                      云函数的运行环境中在 /tmp 目录下提供了一块 512MB 的临时磁盘空间,用于处理单次云函数执行过程中的临时文件读写需求,需特别注意的是,这块临时磁盘空间在函数执行完毕后可能被销毁,不应依赖和假设在磁盘空间存储的临时文件会一直存在。如果需要持久化的存储,请使用云存储功能。

                      用户代码目录:__dirname

                      在云函数执行过程中,通过 __dirname 可获取当前云函数的根目录,如果有随云函数打包上传的资源文件,可以通过 __dirname 加相对路径引用获取。

                      Node.js native 依赖

                      如果有使用到平台相关的 native 依赖,即依赖需要在相应平台下编译(Windows / macOS / Linux ...)的,务必注意在 Linux 平台(CentOS 7 最佳)下编译后再上传,否则可能出现环境兼容性问题。


                      在开发者工具中管理云函数

                      配置云函数本地目录

                      在项目根目录中可以使用 project.config.json 文件,在其中定义 cloudfunctionRoot 字段,指定本地已存在的目录作为云函数的本地根目录。

                      云函数操作

                      在云函数根目录或者云函数目录上,通过鼠标右键,我们可以唤出右键菜单,完成以下操作

                      1. 查看当前环境
                      2. 切换环境
                      3. 新建 Node.js 云函数
                      4. 下载线上环境的云函数列表
                      5. 下载线上环境的云函数代码并覆盖本地
                      6. 对比本地代码和线上环境的代码
                      7. 上传并部署云函数到线上环境

                      查看和切换环境

                      在云函数根目录上右键,在右键菜单中,可以查看当前对应的环境,同时可以切换环境,之后的所有右键菜单都是在这个环境下进行操作

                      新建 Node.js 云函数

                      在云函数根目录上右键,在右键菜单中,可以选择创建一个新的 Node.js 云函数,开发者工具在本地创建出以下目录和文件,同时在线上环境中创建出对应的云函数:

                      • 云函数目录:以云函数名字命名的目录,存放该云函数的所有代码
                      • index.js:云函数入口文件,云函数被调用时实际执行的入口函数是 index.js 中导出的 main 方法
                      • package.json:npm 包定义文件,其中默认定义了最新 wx-server-sdk 依赖

                      在创建成功后,工具会提示是否为该云函数立即安装本地依赖即 wx-server-sdk,如是,则工具会开启终端执行 npm install


                      下载云函数列表

                      在云函数根目录上右键,在右键菜单中,我们可以将线上环境中的云函数列表同步到本地,开发者工具会根据云函数的名字,在本地中创建出对应的云函数目录

                      下载云函数

                      在一个云函数目录上右键可以在菜单中选择下载该云函数,云函数代码会被下载到指定目录。

                      上传并部署

                      在云函数目录上右键,在右键菜单中,我们可以将云函数整体打包上传并部署到线上环境中

                      更多设置

                      我们通过右键菜单的 “更多设置” 可以进入云函数的沉浸式交互场景,在这个场景里可以完成以上所有的云函数操作,在云目录上按 ctrl 可以进行多选批量操作

                      接下来,我们一起看看如何在开发云函数时进行测试、查看日志、以及查看监控。


                      测试、日志与监控

                      测试

                      云开发提供了云函数测试功能,可以方便地调试你的代码。在控制台的对应云函数的管理面板中,点击 “测试” 按钮即可打开测试弹窗。

                      测试弹窗

                      点击“提交方法”下拉菜单可以选择测试函数的模板方法,当前只支持Hello World 事件模板。模板在测试时作为 event 参数传递给函数。在“测试参数”的编辑器中输入想测试的参数后,点击“执行”按钮即可运行代码。执行完毕后将在“运行测试”栏显示运行结果。

                      除了可视化的云函数测试功能,我们还提供命令行工具 scf-cli, 助你在本地快速调试。

                      日志

                      在这里可以查看云函数的调用日志,方便开发者对开发调试。

                      监控

                      在这里可以查看云函数的调用次数、运行时间、错误次数。并支持将这些数据导出。

                      云调用

                      版本要求:wx-server-sdk >= 0.4.0、开发者工具 >= 1.02.1904090 (RC版下载)

                      云调用是云开发提供的基于云函数使用小程序开放接口的能力,目前覆盖以下使用场景:

                      • 服务端调用
                      • 开放数据调用
                      • 消息推送

                      一、服务端调用

                      云调用需要在云函数中通过 wx-server-sdk 使用。在云函数中使用云调用调用服务端接口无需换取 access_token,只要是在从小程序端触发的云函数中发起的云调用都经过微信自动鉴权,可以在登记权限后直接调用如发送模板消息等开放接口。使用方式如下:

                      1. 查看服务端接口是否支持云调用

                      在服务端接口列表中罗列了所有的服务端接口,如果接口支持云调用,则在接口名称旁会带有 云调用 的标签。同时,在每一个服务端接口文档中,如果接口支持云调用,也会有专门的支持说明以及相应的使用文档。

                      2. 查看接口的云调用文档

                      在支持云调用的接口文档中,会分别列出 HTTPS 调用的文档及云调用的文档,云调用文档同 HTTPS 调用文档一样包含请求参数、返回值及示例。

                      3. 为云函数声明所需调用的接口

                      接着,需要配置云调用权限,每个云函数需要声明其会使用到的接口,否则无法调用,声明的方法是在云函数目录下的 config.json(如无需新建)配置文件的 permissions.openapi 字段中增加要调用的接口名,permissions.openapi 是个字符串数组字段,值必须为所需调用的服务端接口名称。在每次使用微信开发者工具上传云函数时均会根据配置更新权限,该配置有10分钟的缓存,如果更新后提示没有权限,稍等10分钟后再试。以下是一个示例的声明了使用发送模板消息接口的配置文件:

                      {  "permissions": {    "openapi": [      "templateMessage.send"    ]  }}

                      4. 在云函数中使用云调用

                      首先云函数中需要使用版本号至少 0.4.0 的 wx-server-sdk,建议 wx-server-sdk 始终保持最新,保证云函数目录下的 package.json 的 wx-server-sdk 字段为 latest,如本地安装依赖,请执行 npm install --save wx-server-sdk@latest。

                      接下来,可在云函数中使用云调用 API 了。云调用 API 均挂载在 wx-server-sdk 模块的 openapi 对象下,各个开放接口类别在 openapi 对象下设二级命名空间对象(如模板消息接口的方法均在 openapi.templateMessage 下),该对象下挂载该类别下的所有开放方法(比如模板消息的发送接口是 openapi.templateMessage.send)。各接口从属的类别名称和方法名称可以通过接口名称查看,接口名称均以 <类别>.<方法> 命名,如发送模板消息的接口名称是 templateMessage.send。下面是一个给自己发送模板消息的示例:

                      如需可直接运行的示例,请在 IDE 中创建一个云开发快速启动模板的项目,其中有包含发送模板消息的云调用的示例
                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  try {    const result = await cloud.openapi.templateMessage.send({      touser: cloud.getWXContext().OPENID, // 通过 getWXContext 获取 OPENID      page: 'index',      data: {        keyword1: {          value: '339208499'        },        keyword2: {          value: '2015年01月05日 12:30'        },        keyword3: {          value: '腾讯微信总部'        },        keyword4: {          value: '广州市海珠区新港中路397号'        }      },      templateId: 'TEMPLATE_ID',      formId: 'FORMID',      emphasisKeyword: 'keyword1.DATA'    })    // result 结构    // { errCode: 0, errMsg: 'openapi.templateMessage.send:ok' }    return result  } catch (err) {    // 错误处理    // err.errCode !== 0    throw err  }}

                      二、开放数据调用

                      对返回敏感开放数据的小程序端接口,从基础库 2.7.0 起,如果小程序已开通云开发,则可在开放数据接口的返回值中获取到唯一对应敏感开放数据的 cloudID,通过云调用可以直接获取到开放数据,具体使用方法见 云调用直接获取开放数据。

                      三、消息推送

                      云开发也支持通过云函数接收小程序消息推送(如接收到客服消息时触发云函数),具体接入方式见消息推送。


                      微信支付

                      从开发者工具 1.02.2005111 起,云控制台支持云开发微信支付商户绑定,在绑定完成后可在云开发中原生接入微信支付:

                      1. 免签名:所有接口免签名、直接获取小程序 wx.requestPayment 所需参数
                      2. 接收回调:云函数支持接收异步支付结果回调

                      pay

                      资质

                      需要是已经开通了微信支付,且已绑定了商户号的小程序。

                      开通

                      在云控制台 -> 设置 -> 全局设置中开通。

                      权限

                      添加商户号后需要分别进行帐号绑定、jsapi 和 api 退款权限授权。请注意:

                      1)帐号绑定:需要在绑定的商户号管理员在微信支付提供的【微信支付商家助手】小程序上确认授权。

                      2)jsapi 和 api 退款权限,需要前往微信支付商户平台我的授权产品中进行确认授权。说明

                      完成授权后即可调用微信支付相关接口能力。

                      接口

                      wx-server-sdk >= 2.0.2

                      云开发提供了微信支付相关接口和服务端回调,包括统一下单、查询订单、关闭订单、申请退款、查询退款、下载对账单,具体文档见 API 文档。

                      下单关键开发流程:

                      1. 小程序调用云函数,在云函数中调用统一下单接口,参数中带上接收异步支付结果的云函数名和其所在云环境 ID
                      2. 统一下单接口返回的成功结果对象中有 payment 字段,该字段即是小程序端发起支付的接口(wx.requestPayment)所需的所有信息
                      3. 小程序端拿到云函数结果,调用 wx.requestPayemnt 发起支付
                      4. 支付完成后,在统一下单接口中配置的云函数将收到支付结果通知

                      注意:收到支付结果回调的云函数必须返回一个 { "errcode": 0 } 的对象,否则会认为回调处理失败,在接下来两天内会持续收到回调,直到返回成功为止。具体返回值协议见统一下单接口文档。


                      告警

                      目前小程序·云开发提供两种告警配置:

                      • 基础告警:包括资源使用量提醒和计费相关信息,告警规则由系统配置,开发者可修改对应的告警渠道。
                      • 自定义告警:由开发者自定义告警条件。

                      告警群配置

                      开发者可以通过登录 微信开发者工具,在 云开发控制台 的 设置 页面中的 告警设置 中使用该功能。目前加入告警群的方式包括:

                      • 通过扫描二维码加入。
                      • 在告警群中邀请相关人员加入。

                      移除群成员的方式包括:

                      • 告警群中的用户主动退出告警群。
                      • 小程序的开发者在 云开发控制台 中的 设置 页面中的 告警设置 中移除相关人员。

                      自定义告警

                      开发者可通过登录 微信开发者工具,在 云开发控制台 的 设置 页面中的 自定义告警 中配置告警策略。每个环境最多可配置 50 条告警策略,每个告警策略中最多可添加 10 个告警条件。

                      每条告警策略需录入信息包括:

                      • 告警策略名称
                      • 环境 ID
                      • 资源类型:目前仅支持对云函数配置自定义告警
                      • 告警对象:每条告警规则至少需要选择一个告警对象
                      • 告警条件:告警指标:目前仅支持云函数错误次数和云函数运行时间统计周期:目前的统计周期仅支持 5 分钟统计一次比较方式:目前提供的比较方式包括 >、>=、<、<=、= 以及 !=持续周期:目前支持的持续周期包括持续 1 个周期、持续 2 个周期、持续 3 个周期、持续 4 个周期以及持续 5 个周期告警频率:目前支持的告警频率包括每小时告警一次和每 12 个小时告警一次
                      • 告警渠道:目前自定义告警仅支持通过群告警下发消息

                      自定义告警设置

                      基础告警

                      基础告警包括:

                      • 资源使用提醒
                      • 计费相关提醒

                      基础告警为系统默认设置告警规则,开发者暂时无法修改相关告警规则,但可通过 告警渠道配置 设置接收告警的方式。详细的告警规则可参考 告警规则。

                      告警渠道配置

                      目前系统提供两种消息推送渠道,用于推送基础告警:

                      • 通过 微信公众平台 公众号推送告警消息至小程序的相关人员
                      • 推送告警消息至 小程序云监控告警群 中

                      默认情况下,系统同时开启这两种告警渠道。

                      开发者可以通过登录 微信开发者工具,在 云开发控制台 的 设置 页面中的 告警设置 中使用该功能。默认情况下,系统会同时开启 公告号告警 和 群告警 两种渠道。如需调整,可点击 设置 进行修改。

                      告警设置

                      告警规则

                      现有的告警规则包括:

                      情形描述告警规则公众号告警人群
                      资源使用提醒存储容量80% 套餐量,90% 套餐量小程序所有开发者
                      资源使用提醒存储下载调用次数80% 套餐量,90% 套餐量小程序所有开发者
                      资源使用提醒存储上传调用次数80% 套餐量,90% 套餐量小程序所有开发者
                      资源使用提醒CDN 回源流量80% 套餐量,90% 套餐量小程序所有开发者
                      资源使用提醒CDN 流量80% 套餐量,90% 套餐量小程序所有开发者
                      资源使用提醒云函数调用次数80% 套餐量,90% 套餐量小程序所有开发者
                      资源使用提醒云函数资源使用量80% 套餐量,90% 套餐量小程序所有开发者
                      资源使用提醒数据库容量80% 套餐量,90% 套餐量小程序所有开发者
                      资源使用提醒数据库读取次数80% 套餐量,90% 套餐量小程序所有开发者
                      资源使用提醒数据库写入次数80% 套餐量,90% 套餐量小程序所有开发者
                      计费相关提醒新购发货成功通知新购发货成功后下单者和小程序管理员
                      计费相关提醒资源到期通知资源到期前 7 天开始推送小程序所有开发者
                      计费相关提醒续费成功通知续费成功后下单者和小程序管理员
                      计费相关提醒资源停服通知资源停服后小程序所有开发者
                      计费相关提醒资源释放通知资源释放后小程序所有开发者
                      计费相关提醒套餐变更成功通知升配或降配成功后下单者和小程序管理员
                      计费相关提醒资源超限停服通知资源超限停服后小程序所有开发者


                      工单

                      使用说明

                      开发者可通过云开发控制台提供的 工单 功能提交相应的工单用于解决部分资源使用过程中的问题。目前 工单 仅支持处理以下问题:

                      • 资源故障相关
                      • 费用相关

                      其他问题请前往 微信开放社区 提问。

                      新建工单

                      1. 开发者可登录 微信开发者工具 的 云开发控制台,在 工单 功能中点击新建工单。目前仅支持同一小程序下的开发者创建该小程序所属工单记录。

                      创建工单

                      1. 阅读提醒事项后,点击确定即可跳转至工单编辑页面。
                      2. 编辑工单时,目前仅支持文字和图片的输入方式。为保证图片的正常显示,请通过点击 图片 添加按钮的方式添加图片资源。

                      编辑工单

                      1. 提交工单后,开发者还可根据需求,添加相应的工单评论或关闭工单。
                      2. 工单被 客服 人员处理后,系统会通过微信公众平台公众号下发相应的消息提醒。

                      查看工单

                      1. 开发者可登录 微信开发者工具 的 云开发控制台,在 工单 功能中查看工单列表。

                      关闭工单

                      1. 点击相应问题标题,系统即可跳转至工单查看页面。在工单查看页面,开发者还可根据需求,添加相应的工单评论或关闭工单。
                      2. 目前仅支持同一小程序下的开发者查看该小程序所属工单记录。非小程序开发者,无查看权限。

                      关闭工单

                      开发者可通过工单编辑页面的 关闭工单 按钮关闭已处理完毕的工单。对于 已完结 的工单,用户无法继续添加评论。

                      同时,在用户长时间未回复工单情况下,系统会在 7 天后自动关闭工单。

                      关闭工单


                      静态网站托管

                      开发者工具 1.03.2006042 起

                      静态网站托管是云开发为开发者提供的 Web 资源托管服务,网站的静态资源(HTML、JavaScript、CSS、图片、音频、视频等)可以托管在该服务上,并享有以下能力:

                      1. 默认域名:获得对应云环境的唯一专属默认域名,通过域名可访问静态资源,域名可以用于测试或线上使用
                      2. 小程序 webview:小程序不用配置业务域名即可在 <web-view> 打开云开发静态网站托管的域名(仅支持能够使用 <web-view> 标签的小程序)
                      3. CDN 加速
                      4. 可以免鉴权直接打开小程序:非个人主体的认证的小程序,使用静态网站托管的网页,可以免鉴权跳转任意合法合规的小程序,查看详情

                      开通方式

                      开通静态托管要求使用后付费,因此如果环境不是后付费,请先切换至后付费、或新创建一个后付费的环境。

                      静态托管的开通入口在 “设置 -> 拓展功能” 中。

                      文件管理

                      静态资源文件的管理操作同云开发的文件存储能力。

                      索引文档

                      索引文档即网站的首页,如果直接访问域名而不指定具体资源文件路径,则默认访问索引文档。

                      注销

                      静态托管开通后可以随时注销,入口同样在 “设置 -> 拓展功能” 中。

                      Web SDK

                      可使用云开发 Web SDK 访问云开发资源。注意现在 Web 中暂不支持登录访问模式,仅支持未登录访问模式。需要首先在云开发控制台中开启允许未登录访问后,Web 中才可以访问云开发资源。

                      Web SDK 介绍。


                      wx.cloud.init

                      在调用云开发各 API 前,需先调用初始化方法 init 一次(全局只需一次)

                      wx.cloud.init 方法的定义如下:

                      function init(options): void

                      wx.cloud.init 方法接受一个可选的 options 参数,方法没有返回值。

                      options 参数定义了云开发的默认配置,该配置会作为之后调用其他所有云 API 的默认配置,options 提供的可选配置如下:

                      字段数据类型必填默认值说明
                      envstring | objectdefault默认环境配置,传入字符串形式的环境 ID 可以指定所有服务的默认环境,传入对象可以分别指定各个服务的默认环境,见下方详细定义
                      traceUserbooleanfalse是否在将用户访问记录到用户管理中,在控制台中可见

                      当 env 传入参数为对象时,可以指定各个服务的默认环境,可选字段如下:

                      字段数据类型必填默认值说明
                      databasestringdefault数据库 API 默认环境配置
                      storagestringdefault存储 API 默认环境配置
                      functionsstringdefault云函数 API 默认环境配置

                      示例代码:

                      wx.cloud.init({  env: 'test-x1dzi'})

                      小程序·云开发提供了丰富的数据库操作 API,此处是数据库小程序端的 API 参考文档。

                      数据库 API 都是懒执行的,这意味着只有真实需要网络请求的 API 调用才会发起网络请求,其余如获取数据库、集合、记录的引用、在集合上构造查询条件等都是不会触发网络请求的。触发网络请求的 API 有如下几个:

                      API说明
                      get获取集合 / 记录数据
                      add在集合上新增记录
                      update更新集合 / 记录数据
                      set替换更新一个记录
                      remove删除记录
                      count统计查询语句对应的记录条数

                      获取引用的 API 有如下几个:

                      API说明
                      database获取数据库引用,返回 Database 对象
                      collection获取集合引用,返回 Collection 对象
                      doc获取对一个记录的引用,返回 Document 对象

                      在数据库 (Database) 对象上有如下字段:

                      字段说明
                      command获取数据库查询及更新指令,返回 Command
                      serverDate构造服务端时间
                      Geo获取地理位置操作对象,返回 Geo 对象

                      在集合 (Collection) 对象上有如下 API:

                      API说明
                      doc获取对一个记录的引用,返回 Document 对象
                      add在集合上新增记录
                      where构建一个在当前集合上的查询条件,返回 Query,查询条件中可使用查询指令
                      orderBy指定查询数据的排序方式
                      limit指定返回数据的数量上限
                      skip指定查询时从命中的记录列表中的第几项之后开始返回
                      field指定返回结果中每条记录应包含的字段

                      在记录 (Document) 对象上有如下 API:

                      API说明
                      get获取记录数据
                      update局部更新数据
                      set替换更新记录
                      remove删除记录
                      field指定返回结果中记录应包含的字段

                      Command (db.command) 对象上有如下查询指令:

                      API说明
                      eq字段是否等于指定值
                      neq字段是否不等于指定值
                      lt字段是否小于指定值
                      lte字段是否小于或等于指定值
                      gt字段是否大于指定值
                      gte字段是否大于或等于指定值
                      in字段值是否在指定数组中
                      nin字段值是否不在指定数组中
                      and条件与,表示需同时满足另一个条件
                      or条件或,表示如果满足另一个条件也匹配

                      Command (db.command) 对象上有如下更新指令:

                      API说明
                      set设置字段为指定值
                      remove删除字段
                      inc原子自增字段值
                      mul原子自乘字段值
                      push如字段值为数组,往数组尾部增加指定值
                      pop如字段值为数组,从数组尾部删除一个元素
                      shift如字段值为数组,从数组头部删除一个元素
                      unshift如字段值为数组,往数组头部增加指定值

                      wx.cloud.database

                      获取数据库的引用

                      方法签名如下:

                      function database(options?: object): Database

                      方法接受一个可选对象参数 options,其字段定义如下:

                      字段名类型必填默认值说明
                      envstring-环境 ID

                      示例代码

                      以下调用获取默认环境的数据库的引用:

                      const db = wx.cloud.database()

                      假设有一个环境名为 test,用做测试环境,那么可以如下获取测试环境数据库:

                      const testDB = wx.cloud.database({  env: 'test'})``

                      db.collection

                      获取集合的引用

                      方法签名如下:

                      function collection(name: string): Collection

                      方法接受一个 name 参数,指定需引用的集合名称

                      示例代码

                      const db = wx.cloud.database()const todosCollection = db.collection('todos')

                      Collection.doc

                      获取记录的引用

                      方法签名如下:

                      function doc(id: string | number): Document

                      方法接受一个 id 参数,指定需引用的记录 ID

                      示例代码

                      const myTodo = db.collection('todos').doc('my-todo-id')


                      Collection.get / Query.get

                      获取集合数据,或获取根据查询条件筛选后的集合数据。

                      如果没有指定 limit,则默认最多取 20 条记录。

                      如果没有指定 skip,则默认从第 0 条记录开始取,skip 常用于分页,例子可见本节的第二个示例代码。

                      函数签名如下:

                      function get(options?: object): Promise<Result>

                      参数说明

                      options 为可选参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

                      字段名类型必填默认值说明
                      successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
                      failFunction失败回调
                      completeFunction调用结束的回调函数(调用成功、失败都会执行)

                      返回值说明

                      如不传 options 参数,或传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve查询的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      dataArray查询的结果数组,数据的每个元素是一个 Object,代表一条记录

                      示例代码 1

                      获取我的待办事项清单

                      回调风格

                      const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).get({  success: function(res) {    console.log(res.data)  }})

                      Promise 风格

                      const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).get().then(res => {  console.log(res.data)})

                      示例代码 2:分页取数据

                      获取我的第二页的待办事项清单,假设一页 10 条,现在要取第 2 页,则可以指定 skip 10 条记录

                      // Promise 风格const db = wx.cloud.database()db.collection('todos')  .where({    _openid: 'xxx', // 填入当前用户 openid  })  .skip(10) // 跳过结果集中的前 10 条,从第 11 条开始返回  .limit(10) // 限制返回数量为 10 条  .get()  .then(res => {    console.log(res.data)  })  .catch(err => {    console.error(err)  })

                      Document.get

                      获取记录数据,或获取根据查询条件筛选后的记录数据

                      函数签名如下:

                      function get(options?: object): Promise<Result>

                      参数说明

                      options 为可选参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

                      字段名类型必填默认值说明
                      successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
                      failFunction失败回调
                      completeFunction调用结束的回调函数(调用成功、失败都会执行)

                      返回值说明

                      如不传 options 参数,或传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve查询的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      dataObject记录的数据,是一个 Object

                      示例代码

                      获取我的指定待办事项详细信息

                      回调风格

                      const db = wx.cloud.database()db.collection('todos').doc('<some-todo-id>').get({  success: function(res) {    console.log(res.data)  }})

                      Promise 风格

                      const db = wx.cloud.database()db.collection('todos').doc('<some-todo-id>').get().then(res => {  console.log(res.data)})

                      Collection.add

                      在集合上新增记录

                      函数签名如下:

                      function add(options: object): Promise<Result>

                      参数说明

                      options 为必填参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

                      字段名类型必填默认值说明
                      dataObject新增记录的定义
                      successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
                      failFunction失败回调
                      completeFunction调用结束的回调函数(调用成功、失败都会执行)

                      返回值说明

                      如传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise 的 resolve 和 reject的结果定义如下:

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      _idString | Number新增的记录的 ID

                      示例代码

                      新增一条待办事项:

                      回调风格

                      db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    // _id: 'todo-identifiant-aleatoire', // 可选自定义 _id,在此处场景下用数据库自动分配的就可以了    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    // 为待办事项添加一个地理位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    // res 是一个对象,其中有 _id 字段标记刚创建的记录的 id    console.log(res)  },  fail: console.error})

                      Promise 风格

                      db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    location: new db.Geo.Point(113, 23),    done: false  }}).then(res => {  console.log(res)}).catch(console.error)

                      Collection.update / Query.update

                      更新多条记录

                      函数签名如下:

                      function update(options: object): Promise<Result>

                      参数说明

                      options 为必填参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

                      字段名类型必填默认值说明
                      dataObject更新对象
                      successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
                      failFunction失败回调
                      completeFunction调用结束的回调函数(调用成功、失败都会执行)

                      返回值说明

                      如传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise 的 resolve 和 reject的结果定义如下:

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 对象是一个如下结构的对象:

                      字段类型说明
                      updatednumber成功更新的记录数量
                      注:API 调用成功不一定代表想要更新的记录已被更新,比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录,所以会得到更新 API 调用成功但其实没有记录被更新的情况,这种情况可以通过 stats.updated 看出来

                      示例代码

                      更新待办事项,将所有未完待办事项进度加 10:

                      回调风格

                      const _ = db.commanddb.collection('todos').where({  done: false  }).update({  data: {    progress: _.inc(10)  },  success: console.log,  fail: console.error})

                      Promise 风格

                      const _ = db.commanddb.collection('todos').where({  done: false  }).update({  data: {    progress: _.inc(10)  },}).then(console.log).catch(console.error)

                      Document.update

                      更新一条记录

                      函数签名如下:

                      function update(options: object): Promise<Result>

                      参数说明

                      options 为必填参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

                      字段名类型必填默认值说明
                      dataObject更新对象
                      successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
                      failFunction失败回调
                      completeFunction调用结束的回调函数(调用成功、失败都会执行)

                      返回值说明

                      如传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise 的 resolve 和 reject的结果定义如下:

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 对象是一个如下结构的对象:

                      字段类型说明
                      updatednumber成功更新的记录数量,在此只可能为 0 或 1

                      示例代码

                      更新待办事项,将所有未完待办事项进度加 10:

                      回调风格

                      db.collection('todos').doc('todo-identifiant-aleatoire').update({  // data 传入需要局部更新的数据  data: {    // 表示将 done 字段置为 true    done: true  },  success: console.log,  fail: console.error})

                      Promise 风格

                      db.collection('todos').doc('todo-identifiant-aleatoire').update({  // data 传入需要局部更新的数据  data: {    // 表示将 done 字段置为 true    done: true  }}).then(console.log).catch(console.error)

                      Document.set

                      替换更新一条记录

                      函数签名如下:

                      function set(options: object): Promise<Result>

                      参数说明

                      options 为必填参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

                      字段名类型必填默认值说明
                      dataObject更新对象
                      successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
                      failFunction失败回调
                      completeFunction调用结束的回调函数(调用成功、失败都会执行)

                      返回值说明

                      如传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise 的 resolve 和 reject的结果定义如下:

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      _idString | Number记录的 ID
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 对象是一个如下结构的对象:

                      字段类型说明
                      updatednumber成功更新的记录数量,若指定的 _id 已存在则为 1,否则为 0
                      creatednumber成功更新的记录数量,若指定的 _id 已存在则为 0,否则为 1

                      示例代码

                      const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').set({  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    style: {      color: "skyblue"    },    // 位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    console.log(res.data)  }})

                      Document.remove

                      删除一条记录

                      函数签名如下:

                      function remove(options: object): Promise<Result>

                      参数说明

                      options 为必填参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

                      字段名类型必填默认值说明
                      successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
                      failFunction失败回调
                      completeFunction调用结束的回调函数(调用成功、失败都会执行)

                      返回值说明

                      如传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise 的 resolve 和 reject的结果定义如下:

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 对象是一个如下结构的对象:

                      字段类型说明
                      removednumber成功删除的记录数量,在此只可能为 0 或 1

                      示例代码

                      更新待办事项,将所有未完待办事项进度加 10:

                      回调风格

                      db.collection('todos').doc('todo-identifiant-aleatoire').remove({  success: console.log,  fail: console.error})

                      Promise 风格

                      db.collection('todos').doc('todo-identifiant-aleatoire').remove()  .then(console.log)  .catch(console.error)

                      Collection.count / Query.count

                      统计集合记录数或统计查询语句对应的结果记录数,注意这与集合权限设置有关,一个用户仅能统计其有读权限的记录数。

                      函数签名如下:

                      function count(options?: object): Promise<Result>

                      参数说明

                      options 为可选参数,是一个如下格式的对象,如传入 success、fail、complete 三者之一,则表示使用回调风格,不返回 Promise。

                      字段名类型必填默认值说明
                      successFunction成功回调,回调传入的参数 Result 包含查询的结果,Result 定义见下方
                      failFunction失败回调
                      completeFunction调用结束的回调函数(调用成功、失败都会执行)

                      返回值说明

                      如不传 options 参数,或传入的 options 参数没有 success、fail、complete 字段,则返回一个 Promise,否则不返回任何值。Promise的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve查询的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      totalnumber结果数量

                      示例代码

                      获取我的待办事项总数

                      回调风格

                      const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).count({  success: function(res) {    console.log(res.total)  }})

                      Promise 风格

                      const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).count().then(res => {  console.log(res.total)})

                      Collection.where

                      指定筛选条件

                      方法签名如下:

                      function where(rule: object): Query

                      方法接受一个必填对象参数 rule,用于定义筛选条件

                      示例代码

                      找出未完成的进度 50 的待办事项:

                      const db = wx.cloud.database()db.collection('todos').where({  done: false,  progress: 50}).get({  success: console.log,  fail: console.error})

                      Collection.orderBy / Query.orderBy

                      指定查询排序条件

                      方法签名如下:

                      function orderBy(fieldName: string, order: string): Collection | Query

                      方法接受一个必填字符串参数 fieldName 用于定义需要排序的字段,一个字符串参数 order 定义排序顺序。order 只能取 asc 或 desc。

                      如果需要对嵌套字段排序,需要用 "点表示法" 连接嵌套字段,比如 style.color 表示字段 style 里的嵌套字段 color。

                      同时也支持按多个字段排序,多次调用 orderBy 即可,多字段排序时的顺序会按照 orderBy 调用顺序先后对多个字段排序

                      示例代码:按一个字段排序

                      按进度排升序取待办事项

                      const db = wx.cloud.database()db.collection('todos').orderBy('progress', 'asc')  .get()  .then(console.log)  .catch(console.error)

                      示例代码:按多个字段排序

                      先按 progress 排降序(progress 越大越靠前)、再按 description 排升序(字母序越前越靠前)取待办事项:

                      const db = wx.cloud.database()db.collection('todos')  .orderBy('progress', 'desc')  .orderBy('description', 'asc')  .get()  .then(console.log)  .catch(console.error)

                      Collection.limit / Query.limit

                      指定查询结果集数量上限

                      支持端:小程序 , 云函数 , Web

                      指定查询结果集数量上限

                      参数

                      value: number

                      返回值

                      Collection

                      说明

                      limit 在小程序端默认及最大上限为 20,在云函数端默认及最大上限为 1000

                      示例代码

                      db.collection('todos').limit(10)  .get()  .then(console.log)  .catch(console.error)


                      Collection.skip / Query.skip

                      指定查询返回结果时从指定序列后的结果开始返回,常用于分页

                      方法签名如下:

                      function skip(offset: number): Collection | Query

                      示例代码

                      const db = wx.cloud.database()db.collection('todos').skip(10)  .get()  .then(console.log)  .catch(console.error)

                      db.command

                      获取数据库查询及更新指令,列表见 API 列表中的 command 列表

                      示例代码

                      const _ = db.command

                      db.RegExp

                      从基础库 2.3.2 开始(wx-server-sdk 从 0.0.23 开始),数据库支持正则表达式查询,开发者可以在查询语句中使用 JavaScript 原生正则对象或使用 db.RegExp 方法来构造正则对象然后进行字符串匹配。在查询条件中对一个字段进行正则匹配即要求该字段的值可以被给定的正则表达式匹配,注意正则表达式不可用于 db.command 内(如 db.command.in)。

                      使用正则表达式匹配可以满足字符串匹配需求,但不适用于长文本 / 大数据量的文本匹配 / 搜索,因为会有性能问题,对此类场景应使用文本搜索引擎如 ElasticSearch 等实现。

                      db.RegExp 定义如下:

                      function RegExp(initOptions: IInitOptions): DBRegExpinterface IInitOptions {  regexp: string // 正则表达式,字符串形式  options: string // flags,包括 i, m, s 但前端不做强限制}

                      options 支持 i, m, s 这四个 flag,注意 JavaScript 原生正则对象构造时仅支持其中的 i, m 两个 flag,因此需要使用到 s 这个 flag 时必须使用 db.RegExp 构造器构造正则对象。flag 的含义见下表:

                      flag说明
                      i大小写不敏感
                      m跨行匹配;让开始匹配符 ^ 或结束匹配符 $ 时除了匹配字符串的开头和结尾外,还匹配行的开头和结尾
                      s让 . 可以匹配包括换行符在内的所有字符

                      基础用法示例:

                      // 原生 JavaScript 对象db.collection('todos').where({  description: /miniprogram/i})// 数据库正则对象db.collection('todos').where({  description: db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})// 用 new 构造也是可以的db.collection('todos').where({  description: new db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})

                      db.serverDate

                      构造一个服务端时间的引用。可用于查询条件、更新字段值或新增记录时的字段值。

                      方法签名如下:

                      function serverDate(options?: object): ServerDate

                      方法接受一个可选对象参数 options,其字段定义如下:

                      字段名类型必填默认值说明
                      offsetnumber引用的服务端时间偏移量,毫秒为单位,可以是正数或负数

                      示例代码

                      新增记录时设置字段为服务端时间:

                      const db = wx.cloud.database()db.collection('todos').add({  description: 'eat an apple',  createTime: db.serverDate()})

                      更新字段为服务端时间往后一小时:

                      const db = wx.cloud.database()db.collection('todos').doc('my-todo-id').update({  due: db.serverDate({    offset: 60 * 60 * 1000  })})``

                      db.Geo

                      该对象上含有地理位置构造器。

                      拥有字段如下:

                      字段说明
                      Point地理位置点

                      db.Geo.Point

                      构造一个地理位置点。可用于查询条件、更新字段值或新增记录时的字段值。

                      方法签名如下:

                      function Point(longitude: number, latitude: number): Point

                      方法接受两个必填参数,第一个是经度(longitude),第二个是纬度(latitude),务必注意顺序

                      示例代码

                      const db = wx.cloud.database()db.collection('todos').add({  description: 'eat an apple',  location: db.Geo.Point(113, 23)})

                      db.command.eq

                      查询筛选条件,表示字段等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

                      方法签名:

                      function eq(value: any): Command

                      比如筛选出所有自己发表的文章,除了用传对象的方式:

                      const myOpenID = 'xxx'db.collection('articles').where({  _openid: myOpenID})

                      还可以用指令:

                      const _ = db.commandconst myOpenID = 'xxx'db.collection('articles').where({  _openid: _.eq(openid)})

                      注意 eq 指令比对象的方式有更大的灵活性,可以用于表示字段等于某个对象的情况,比如:

                      // 这种写法表示匹配 stat.publishYear == 2018 且 stat.language == 'zh-CN'db.collection('articles').where({  stat: {    publishYear: 2018,    language: 'zh-CN'  }})// 这种写法表示 stat 对象等于 { publishYear: 2018, language: 'zh-CN' }const _ = db.commanddb.collection('articles').where({  stat: _.eq({    publishYear: 2018,    language: 'zh-CN'  })})

                      db.command.neq

                      表示字段不等于某个值,和 db.command.eq 相反


                      db.command.lt

                      查询筛选条件,表示字段需小于指定值。可以传入 Date 对象用于进行日期比较。

                      方法签名:

                      function lt(value: number | Date): Command

                      示例代码

                      找出进度小于 50 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.lt(50)}).get({  success: console.log,  fail: console.error})

                      db.command.lte

                      查询筛选条件,表示字段需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

                      方法签名:

                      function lte(value: number | Date): Command

                      示例代码

                      找出进度小于或等于 50 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.lte(50)}).get({  success: console.log,  fail: console.error})

                      db.command.gt

                      查询筛选条件,表示字段需大于指定值。可以传入 Date 对象用于进行日期比较。

                      方法签名:

                      function gt(value: number | Date): Command

                      示例代码

                      找出进度大于 50 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.gt(50)}).get({  success: console.log,  fail: console.error})

                      db.command.gte

                      查询筛选条件,表示字段需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

                      方法签名:

                      function gte(value: number | Date): Command

                      示例代码

                      找出进度大于或等于 50 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.gte(50)}).get({  success: console.log,  fail: console.error})

                      db.command.in

                      查询筛选条件,表示字段的值需在给定的数组内。

                      方法签名:

                      function in(values: any[]): Command

                      示例代码

                      找出进度为 0 或 100 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.in([0, 100])}).get({  success: console.log,  fail: console.error})

                      db.command.in

                      查询筛选条件,表示字段的值需不在给定的数组内。

                      方法签名:

                      function nin(values: any[]): Command

                      示例代码

                      找出进度不是 0 或 100 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.nin([0, 100])}).get({  success: console.log,  fail: console.error})


                      db.command.and

                      查询指令,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

                      示例代码

                      如筛选出进度大于 50 小于 100 的 todo:

                      流式写法:

                      const _ = db.commanddb.collection('todo').where({  progress: _.gt(50).and(_.lt(100))})

                      前置写法:

                      const _ = db.commanddb.collection('todo').where({  memory: _.and(_.gt(50), _.lt(100))})

                      db.command.or

                      查询指令,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

                      字段值的 “或” 操作指的是指定一个字段值为多个值之一即可:

                      字段值的或操作:示例代码

                      如筛选出进度大于 80 或小于 20 的 todo:

                      流式写法:

                      const _ = db.commanddb.collection('todo').where({  progress: _.gt(80).or(_.lt(20))})

                      前置写法:

                      const _ = db.commanddb.collection('todo').where({  progress: _.or(_.gt(80), _.lt(20))})

                      前置写法也可接收一个数组:

                      const _ = db.commanddb.collection('todo').where({  progress: _.or([_.gt(80), _.lt(20)])})

                      跨字段的 “或” 操作指条件 “或”,相当于可以传入多个 where 语句,满足其中一个即可,示例:

                      跨字段的或操作:示例代码

                      如筛选出进度大于 80 或已标为已完成的 todo:

                      const _ = db.commanddb.collection('todo').where(_.or([  {    progress: _.gt(80)  },  {    done: true  }]))


                      db.command.set

                      更新指令。用于设定字段等于指定值。

                      函数签名:

                      function set(value: any): Command

                      这种方法相比传入纯 JS 对象的好处是能够指定字段等于一个对象:

                      // 以下方法只会更新 style.color 为 red,而不是将 style 更新为 { color: 'red' },即不影响 style 中的其他字段db.collection('todos').doc('doc-id').update({  data: {    style: {      color: 'red'    }  }})// 以下方法更新 style 为 { color: 'red', size: 'large' }db.collection('todos').doc('doc-id').update({  data: {    style: _.set({      color: 'red',      size: 'large'    })  }})

                      db.command.remove

                      更新指令。用于表示删除某个字段。

                      函数签名:

                      function remove(): Command

                      示例代码

                      删除 style 字段:

                      const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    style: _.remove()  }})

                      db.command.inc

                      更新指令。用于指示字段自增某个值,这是个原子操作,使用这个操作指令而不是先读数据、再加、再写回的好处是:

                      1. 原子性:多个用户同时写,对数据库来说都是将字段加一,不会有后来者覆写前者的情况
                      2. 减少一次网络请求:不需先读再写

                      mul 指令同理。

                      函数签名:

                      function inc(value: number): Command

                      示例代码

                      将一个 todo 的进度自增 10:

                      const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    progress: _.inc(10)  }})

                      db.command.mul

                      更新指令。用于指示字段自乘某个值,这是个原子操作,使用这个操作指令而不是先读数据、再加、再写回的好处是:

                      1. 原子性:多个用户同时写,对数据库来说都是将字段自乘,不会有后来者覆写前者的情况
                      2. 减少一次网络请求:不需先读再写

                      inc 指令同理。

                      函数签名:

                      function mul(value: number): Command

                      示例代码

                      将一个 todo 的进度乘 2:

                      const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    progress: _.mul(2)  }})

                      db.command.push

                      更新指令,对一个值为数组的字段,往数组尾部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

                      函数签名:

                      function push(values: any[]): Command

                      示例代码

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push(['mini-program', 'cloud'])  }})

                      db.command.pop

                      更新指令,对一个值为数组的字段,将数组尾部元素删除。

                      函数签名:

                      function pop(values: any[]): Command

                      示例代码

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.pop()  }})

                      db.command.shift

                      更新指令,对一个值为数组的字段,将数组头部元素删除。

                      函数签名:

                      function shift(values: any[]): Command

                      示例代码

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.shift()  }})

                      db.command.unshift

                      更新指令,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

                      函数签名:

                      function unshift(values: any[]): Command

                      示例代码

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.unshift(['mini-program', 'cloud'])  }})

                      get

                      在集合和记录上都有 get 方法:

                      update

                      即可更新单条记录,也可更新多条记录


                      remove

                      小程序端只可删除单条记录,如果需删除多条记录,需使用云函数端 API

                      云开发 Server API 文档

                      云端运行环境为 Node.js,开发时请安装 Node.js 和 npm。

                      使用云开发需在云函数目录中安装 wx-server-sdk 依赖:

                      npm install --save wx-server-sdk

                      在工具云函数根目录中创建云函数时,默认会创建一个定义了 wx-server-sdk 依赖的 package.json,并在创建成功时提示自动安装依赖。如果在你的环境中无法直接使用 npm install,比如需要走代理、使用自建的 npm 源站、使用其他包管理器如 yarn 等的情况,则不能使用工具的自动安装依赖,需手工执行相应依赖安装命令。

                      需要特别注意的是,在 wx-server-sdk 中不再兼容 success、fail、complete 回调,总是只会返回 Promise。

                      以下是 wx-server-sdk API 文档分类入口:

                      • 初始化
                      • 数据库
                      • 存储
                      • 云函数

                      init

                      在调用云开发各 API 前,需先调用初始化方法 init 一次(全局只需一次)

                      init 方法的定义如下:

                      function init(options): void

                      init 方法接受一个可选的 options 参数,方法没有返回值。

                      options 参数定义了云开发的默认配置,该配置会作为之后调用其他所有云 API 的默认配置,options 提供的可选配置如下:

                      字段数据类型必填默认值说明
                      envstring | objectdefault默认环境配置,传入字符串形式的环境 ID 可以指定所有服务的默认环境,传入对象可以分别指定各个服务的默认环境,见下方详细定义

                      当 env 传入参数为对象时,可以指定各个服务的默认环境,可选字段如下:

                      字段数据类型必填默认值说明
                      databasestringdefault数据库 API 默认环境配置
                      storagestringdefault存储 API 默认环境配置
                      functionsstringdefault云函数 API 默认环境配置

                      示例代码:

                      const cloud = require('wx-server-sdk')cloud.init({  env: 'test-x1dzi'})

                      需要特别注意的是,在 wx-server-sdk 中不再兼容 success、fail、complete 回调,总是只会返回 Promise。


                      工具类 API

                      云开发提供了一系列工具类的 API,此处是存储小程序端的 API 参考文档。

                      API说明
                      getWXContext获取微信上下文


                      getWXContext

                      在云函数中获取微信调用上下文,该方法无需传入参数,会返回以下字段:

                      字段含义字段存在条件最低版本
                      OPENID小程序用户 openid小程序端调用云函数时
                      APPID小程序 AppID小程序端调用云函数时
                      UNIONID小程序用户 unionid小程序端调用云函数,并且满足 unionid 获取条件
                      ENV云函数所在环境的 ID0.6.0
                      SOURCE调用来源(云函数本次运行是被什么触发)0.7.0

                      SOURCE 值跟随调用链条传递,会表示调用链路情况(用英文逗号分隔),比如小程序调用云函数 A,再在云函数 A 内调用云函数 B,则 A 获得的 SOURCE 为 wx_client, B 内获得的 SOURCE 为 wx_client,scf(微信小程序调用,然后云函数调用)。

                      SOURCE 的枚举类型:

                      SOURCE 值含义
                      wx_devtools微信 IDE 调用
                      wx_client微信小程序调用
                      wx_http微信 HTTP API 调用
                      wx_unknown微信未知来源调用
                      scf云函数调用云函数
                      其他非微信端触发

                      如果在云函数本地调试中,ENV 会为 local,SOURCE 会为 wx_client。

                      注意事项

                      请不要在 exports.main 外使用 getWXContext,此时尚没有调用上下文,无法获取得到信息。

                      使用示例

                      const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  const {    OPENID,    APPID,    UNIONID,    ENV,  } = cloud.getWXContext()  return {    OPENID,    APPID,    UNIONID,    ENV,  }}


                      小程序·云开发提供了丰富的数据库操作 API,此处是数据库 Server 端的 API 参考文档,可用于云函数运行环境。

                      Server 端的 API 与小程序端基本保持一致,有如下不同:

                      1. Server API 不再接受回调(success, fail, complete),统一返回 Promise
                      2. Server 端有批量写和批量删除的权限,即可在集合或查询语句上调用 update 或 remove
                      3. Server 端独有 API 如创建集合(db.createCollection)

                      数据库 API 都是懒执行的,这意味着只有真实需要网络请求的 API 调用才会发起网络请求,其余如获取数据库、集合、记录的引用、在集合上构造查询条件等都是不会触发网络请求的。触发网络请求的 API 有如下几个:

                      API说明
                      get获取集合 / 记录数据
                      add在集合上新增记录
                      update更新集合 / 记录数据
                      set替换更新一个记录
                      remove删除记录
                      count统计查询语句对应的记录条数

                      获取引用的 API 有如下几个:

                      API说明
                      database获取数据库引用,返回 Database 对象
                      collection获取集合引用,返回 Collection 对象
                      doc获取对一个记录的引用,返回 Document 对象

                      在数据库 (Database) 对象上有如下字段:

                      字段说明
                      command获取数据库查询及更新指令,返回 Command
                      serverDate构造服务端时间
                      Geo获取地理位置操作对象,返回 Geo 对象
                      createCollection创建一个集合

                      在集合 (Collection) 对象上有如下 API:

                      API说明
                      doc获取对一个记录的引用,返回 Document 对象
                      add在集合上新增记录
                      update更新数据
                      where构建一个在当前集合上的查询条件,返回 Query,查询条件中可使用查询指令
                      remove删除匹配相应筛选条件的记录
                      orderBy指定查询数据的排序方式
                      limit指定返回数据的数量上限
                      skip指定查询时从命中的记录列表中的第几项之后开始返回
                      field指定返回结果中每条记录应包含的字段

                      在记录 (Document) 对象上有如下 API:

                      API说明
                      get获取记录数据
                      update局部更新数据
                      set替换更新记录
                      remove删除记录
                      field指定返回结果中记录应包含的字段

                      Command (db.command) 对象上有如下查询指令:

                      API说明
                      eq字段是否等于指定值
                      neq字段是否不等于指定值
                      lt字段是否小于指定值
                      lte字段是否小于或等于指定值
                      gt字段是否大于指定值
                      gte字段是否大于或等于指定值
                      in字段值是否在指定数组中
                      nin字段值是否不在指定数组中
                      and条件与,表示需同时满足另一个条件
                      or条件或,表示如果满足另一个条件也匹配

                      Command (db.command) 对象上有如下更新指令:

                      API说明
                      set设置字段为指定值
                      remove删除字段
                      inc原子自增字段值
                      mul原子自乘字段值
                      push如字段值为数组,往数组尾部增加指定值
                      pop如字段值为数组,从数组尾部删除一个元素
                      shift如字段值为数组,从数组头部删除一个元素
                      unshift如字段值为数组,往数组头部增加指定值

                      API reject 时返回的 Error 对象均含以下两个字段:

                      字段类型说明
                      errCodenumber错误码
                      errMsgstring错误信息

                      cloud.database

                      获取数据库的引用

                      方法签名如下:

                      function database(options?: object): Database

                      方法接受一个可选对象参数 options,其字段定义如下:

                      字段名类型必填默认值说明
                      envstring-环境 ID

                      示例代码

                      以下调用获取默认环境的数据库的引用:

                      const db = wx.cloud.database()

                      假设有一个环境名为 test,用做测试环境,那么可以如下获取测试环境数据库:

                      const testDB = wx.cloud.database({  env: 'test'})

                      也可以通过 init 传入默认环境的方式使得获取数据库时默认是默认环境数据库:

                      cloud.init({  env: 'test'})const testDB = wx.cloud.database()

                      db.collection

                      获取集合的引用

                      方法签名如下:

                      function collection(name: string): Collection

                      方法接受一个 name 参数,指定需引用的集合名称

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const todosCollection = db.collection('todos')

                      Collection.doc

                      获取记录的引用

                      方法签名如下:

                      function doc(id: string | number): Document

                      方法接受一个 id 参数,指定需引用的记录 ID

                      示例代码

                      const myTodo = db.collection('todos').doc('my-todo-id')


                      Collection.get / Query.get

                      获取集合数据,或获取根据查询条件筛选后的集合数据。

                      如果没有指定 limit,则默认最多取 20 条记录。

                      如果没有指定 skip,则默认从第 0 条记录开始取,skip 常用于分页,例子可见第二个示例代码。

                      如果需要取集合中所有的数据,可以参考第三个示例代码

                      函数签名如下:

                      function get(): Promise<Result>

                      返回值说明

                      Promise 的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve查询的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      dataArray查询的结果数组,数据的每个元素是一个 Object,代表一条记录

                      示例代码 1

                      获取我的待办事项清单

                      Promise 风格

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos').where({    _openid: 'xxx' // 填入当前用户 openid  }).get()}

                      示例代码 2:分页取数据

                      获取我的第二页的待办事项清单,假设一页 10 条,现在要取第 2 页,则可以指定 skip 10 条记录

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos')    .where({      _openid: 'xxx', // 填入当前用户 openid    })    .skip(10) // 跳过结果集中的前 10 条,从第 11 条开始返回    .limit(10) // 限制返回数量为 10 条    .get()}

                      示例代码 3:取集合所有数据

                      获取集合中的所有待办事项清单:因为有默认 limit 100 条的限制,因此很可能一个请求无法取出所有数据,需要分批次取:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const MAX_LIMIT = 100exports.main = async (event, context) => {  // 先取出集合记录总数  const countResult = await db.collection('todos').count()  const total = countResult.total  // 计算需分几次取  const batchTimes = Math.ceil(total / 100)  // 承载所有读操作的 promise 的数组  const tasks = []  for (let i = 0; i < batchTimes; i++) {    const promise = db.collection('todos').skip(i * MAX_LIMIT).limit(MAX_LIMIT).get()    tasks.push(promise)  }  // 等待所有  return (await Promise.all(tasks)).reduce((acc, cur) => {    return {      data: acc.data.concat(cur.data),      errMsg: acc.errMsg,    }  })}

                      Document.get

                      获取记录数据,或获取根据查询条件筛选后的记录数据

                      函数签名如下:

                      function get(): Promise<Result>

                      返回值说明

                      Promise 的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve查询的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      dataObject记录的数据,是一个 Object

                      示例代码

                      获取我的指定待办事项详细信息

                      Promise 风格

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('<some-todo-id>').get()  } catch(e) {    console.error(e)  }}


                      Collection.add

                      在集合上新增记录

                      函数签名如下:

                      function add(options: object): Promise<Result>

                      参数说明

                      字段名类型必填默认值说明
                      dataObject新增记录的定义

                      返回值说明

                      Promise 的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      _idString | Number新增的记录的 ID

                      示例代码

                      新增一条待办事项:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').add({      // data 字段表示需新增的 JSON 数据      data: {        description: "learn cloud database",        due: new Date("2018-09-01"),        tags: [          "cloud",          "database"        ],        // 位置(113°E,23°N)        location: new db.Geo.Point(113, 23),        done: false      }    })  } catch(e) {    console.error(e)  }}


                      Collection.update / Query.update

                      更新多条记录

                      函数签名如下:

                      function update(options: object): Promise<Result>

                      参数说明

                      字段名类型必填默认值说明
                      dataObject更新对象

                      返回值说明

                      Promise 的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      success 回调的结果及 Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 对象是一个如下结构的对象:

                      字段类型说明
                      updatednumber成功更新的记录数量
                      注:API 调用成功不一定代表想要更新的记录已被更新,比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录,所以会得到更新 API 调用成功但其实没有记录被更新的情况,这种情况可以通过 stats.updated 看出来

                      示例代码

                      更新待办事项,将所有未完待办事项进度加 10:

                      Promise 风格

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: false      })    .update({      data: {        progress: _.inc(10)      },    })  } catch(e) {    console.error(e)  }}


                      Collection.remove / Query.remove

                      删除多条记录

                      函数签名如下:

                      function remove(options: object): Promise<Result>

                      返回值说明

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 对象是一个如下结构的对象:

                      字段类型说明
                      removednumber成功删除的记录数量

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: true    }).remove()  } catch(e) {    console.error(e)  }}


                      Document.update

                      更新一条记录

                      函数签名如下:

                      function update(options: object): Promise<Result>

                      参数说明

                      字段名类型必填默认值说明
                      dataObject更新对象

                      返回值说明

                      Promise 的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 对象是一个如下结构的对象:

                      字段类型说明
                      updatednumber成功更新的记录数量,在此只可能为 0 或 1

                      示例代码

                      更新待办事项,将所有未完待办事项进度加 10:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').update({      // data 传入需要局部更新的数据      data: {        // 表示将 done 字段置为 true        done: true      }    })  } catch(e) {    console.error(e)  }}


                      Document.set

                      替换更新一条记录

                      函数签名如下:

                      function set(options: object): Promise<Result>

                      参数说明

                      字段名类型必填默认值说明
                      dataObject更新对象

                      返回值说明

                      Promise 的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      _idString | Number记录的 ID
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 对象是一个如下结构的对象:

                      字段类型说明
                      updatednumber成功更新的记录数量,若指定的 _id 已存在则为 1,否则为 0
                      creatednumber成功更新的记录数量,若指定的 _id 已存在则为 0,否则为 1

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').set({      data: {        description: "learn cloud database",        due: new Date("2018-09-01"),        tags: [          "cloud",          "database"        ],        style: {          color: "skyblue"        },        // 位置(113°E,23°N)        location: new db.Geo.Point(113, 23),        done: false      }    })  } catch(e) {    console.error(e)  }}


                      Document.remove

                      删除一条记录

                      函数签名如下:

                      function remove(): Promise<Result>

                      返回值说明

                      结果说明
                      resolve新增记录的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      Promise resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 对象是一个如下结构的对象:

                      字段类型说明
                      removednumber成功删除的记录数量,在此只可能为 0 或 1

                      示例代码

                      更新待办事项,将所有未完待办事项进度加 10:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').remove()  } catch(e) {    console.error(e)  }}


                      Collection.count / Query.count

                      统计集合记录数或统计查询语句对应的结果记录数,云函数端因属于管理端,因此可以统计所有集合的记录数(小程序端统计会受限于权限,可见小程序端的 count

                      函数签名如下:

                      function count(): Promise<Result>

                      返回值说明

                      Promise 的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve查询的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      resolve 的结果 Result 是一个如下结构的对象:

                      字段类型说明
                      totalnumber结果数量

                      示例代码

                      获取我的待办事项总数

                      Promise 风格

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos').where({    _openid: 'xxx' // 填入当前用户 openid  }).count()}


                      Collection.where

                      指定筛选条件

                      方法签名如下:

                      function where(rule: object): Query

                      方法接受一个必填对象参数 rule,用于定义筛选条件

                      示例代码

                      找出未完成的进度 50 的待办事项:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: false,      progress: 50    })    .get()  } catch(e) {    console.error(e)  }}


                      Collection.orderBy / Query.orderBy

                      指定查询排序条件

                      方法签名如下:

                      function orderBy(fieldName: string, order: string): Collection | Query

                      方法接受一个必填字符串参数 fieldName 用于定义需要排序的字段,一个字符串参数 order 定义排序顺序。order 只能取 asc 或 desc。

                      同时也支持按多个字段排序,多次调用 orderBy 即可,多字段排序时的顺序会按照 orderBy 调用顺序先后对多个字段排序

                      示例代码:按一个字段排序

                      按进度排升序取待办事项

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos').orderBy('progress', 'asc').get()}

                      示例代码:按多个字段排序

                      先按 progress 排降序(progress 越大越靠前)、再按 description 排升序(字母序越前越靠前)取待办事项:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos')    .orderBy('progress', 'desc')    .orderBy('description', 'asc')    .get()}


                      Collection.limit / Query.limit

                      指定查询结果集数量上限

                      方法签名如下:

                      function limit(max: number): Collection | Query

                      方法接受一个必填参数 max 用于定义最大结果集返回数量,上限 100

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').limit(10).get()  } catch(e) {    console.error(e)  }}

                      Collection.skip / Query.skip

                      指定查询返回结果时从指定序列后的结果开始返回,常用语分页

                      方法签名如下:

                      function skip(offset: number): Collection | Query

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').skip(10).get()  } catch(e) {    console.error(e)  }}


                      Collection.field / Query.field / Document.field

                      指定返回结果中记录需返回的字段

                      方法签名如下:

                      function field(definition: object): Collection | Query | Document

                      方法接受一个必填字段用于指定需返回的字段

                      示例代码

                      返回 description, done 和 progress 三个字段:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').field({      description: true,      done: true,      progress: true    }).get()  } catch(e) {    console.error(e)  }}

                      db.command

                      获取数据库查询及更新指令,列表见 API 列表中的 command 列表

                      示例代码

                      const _ = db.command

                      db.RegExp

                      从基础库 2.3.2 开始(wx-server-sdk 从 0.0.23 开始),数据库支持正则表达式查询,开发者可以在查询语句中使用 JavaScript 原生正则对象或使用 db.RegExp 方法来构造正则对象然后进行字符串匹配。在查询条件中对一个字段进行正则匹配即要求该字段的值可以被给定的正则表达式匹配,注意正则表达式不可用于 db.command 内(如 db.command.in)。

                      使用正则表达式匹配可以满足字符串匹配需求,但不适用于长文本 / 大数据量的文本匹配 / 搜索,因为会有性能问题,对此类场景应使用文本搜索引擎如 ElasticSearch 等实现。

                      db.RegExp 定义如下:

                      function RegExp(initOptions: IInitOptions): DBRegExpinterface IInitOptions {  regexp: string // 正则表达式,字符串形式  options: string // flags,包括 i, m, s 但前端不做强限制}

                      options 支持 i, m, s 这四个 flag,注意 JavaScript 原生正则对象构造时仅支持其中的 i, m 两个 flag,因此需要使用到 s 这个 flag 时必须使用 db.RegExp 构造器构造正则对象。flag 的含义见下表:

                      flag说明
                      i大小写不敏感
                      m跨行匹配;让开始匹配符 ^ 或结束匹配符 $ 时除了匹配字符串的开头和结尾外,还匹配行的开头和结尾
                      s让 . 可以匹配包括换行符在内的所有字符

                      基础用法示例:

                      // 原生 JavaScript 对象db.collection('todos').where({  description: /miniprogram/i})// 数据库正则对象db.collection('todos').where({  description: db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})// 用 new 构造也是可以的db.collection('todos').where({  description: new db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})


                      db.serverDate

                      构造一个服务端时间的引用。可用于查询条件、更新字段值或新增记录时的字段值。

                      方法签名如下:

                      function serverDate(options?: object): ServerDate

                      方法接受一个可选对象参数 options,其字段定义如下:

                      字段名类型必填默认值说明
                      offsetnumber引用的服务端时间偏移量,毫秒为单位,可以是正数或负数

                      示例代码

                      新增记录时设置字段为服务端时间:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').add({      description: 'eat an apple',      createTime: db.serverDate()    })  } catch(e) {    console.error(e)  }}

                      更新字段为服务端时间往后一小时:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('my-todo-id').update({      due: db.serverDate({        offset: 60 * 60 * 1000      })    })  } catch(e) {    console.error(e)  }}``


                      db.Geo

                      该对象上含有地理位置构造器。

                      拥有字段如下:

                      字段说明
                      Point地理位置点

                      db.Geo.Point

                      构造一个地理位置点。可用于查询条件、更新字段值或新增记录时的字段值。

                      方法签名如下:

                      function Point(longitude: number, latitude: number): Point

                      方法接受两个必填参数,第一个是经度(longitude),第二个是纬度(latitude),务必注意顺序

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').add({      description: 'eat an apple',      location: new db.Geo.Point(113, 23)    })  } catch(e) {    console.error(e)  }}

                      db.command.eq

                      查询筛选条件,表示字段等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array。

                      方法签名:

                      function eq(value: any): Command

                      比如筛选出所有自己发表的文章,除了用传对象的方式:

                      const myOpenID = 'xxx'db.collection('articles').where({  _openid: myOpenID})

                      还可以用指令:

                      const _ = db.commandconst myOpenID = 'xxx'db.collection('articles').where({  _openid: _.eq(openid)})

                      注意 eq 指令比对象的方式有更大的灵活性,可以用于表示字段等于某个对象的情况,比如:

                      // 这种写法表示匹配 stat.publishYear == 2018 且 stat.language == 'zh-CN'db.collection('articles').where({  stat: {    publishYear: 2018,    language: 'zh-CN'  }})// 这种写法表示 stat 对象等于 { publishYear: 2018, language: 'zh-CN' }const _ = db.commanddb.collection('articles').where({  stat: _.eq({    publishYear: 2018,    language: 'zh-CN'  })})

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('articles').where({      stat: _.eq({        publishYear: 2018,        language: 'zh-CN'      })    })    .get()  } catch(e) {    console.error(e)  }}

                      db.command.neq

                      表示字段不等于某个值,和 db.command.eq 相反


                      db.command.lt

                      查询筛选条件,表示字段需小于指定值。

                      方法签名:

                      function lt(value: number): Command

                      示例代码

                      找出进度小于 50 的 todo

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.lt(50)    })    .get()  } catch(e) {    console.error(e)  }}

                      db.command.lte

                      查询筛选条件,表示字段需小于或等于指定值。

                      方法签名:

                      function lte(value: number): Command

                      示例代码

                      找出进度小于或等于 50 的 todo

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.lte(50)    })    .get()  } catch(e) {    console.error(e)  }}

                      db.command.gt

                      查询筛选条件,表示字段需大于指定值。

                      方法签名:

                      function gt(value: number): Command

                      示例代码

                      找出进度大于 50 的 todo

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.gt(50)    })    .get()  } catch(e) {    console.error(e)  }}

                      db.command.gte

                      查询筛选条件,表示字段需大于或等于指定值。

                      方法签名:

                      function gte(value: number): Command

                      示例代码

                      找出进度大于或等于 50 的 todo

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.gte(50)    })    .get()  } catch(e) {    console.error(e)  }}

                      db.command.in

                      查询筛选条件,表示字段的值需在给定的数组内。

                      方法签名:

                      function in(values: any[]): Command

                      示例代码

                      找出进度为 0 或 100 的 todo

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.in([0, 100])    })    .get()  } catch(e) {    console.error(e)  }}

                      db.command.in

                      查询筛选条件,表示字段的值需不在给定的数组内。

                      方法签名:

                      function nin(values: any[]): Command

                      示例代码

                      找出进度不是 0 或 100 的 todo

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      progress: _.nin([0, 100])    })    .get()  } catch(e) {    console.error(e)  }}

                      db.command.nin

                      支持端:小程序 , 云函数 , Web

                      查询筛选操作符,表示要求值不在给定的数组内。

                      参数

                      value: any[]

                      返回值

                      Command

                      示例代码

                      找出进度不是 0 或 100 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.nin([0, 100])}).get({  success: console.log,  fail: console.error})


                      db.command.and

                      查询指令,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

                      示例代码

                      如筛选出进度大于 50 小于 100 的 todo:

                      流式写法:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todo').where({      progress: _.gt(50).and(_.lt(100))    }).get()  } catch(e) {    console.error(e)  }}

                      前置写法:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todo').where({      memory: _.and(_.gt(50), _.lt(100))    }).get()  } catch(e) {    console.error(e)  }}

                      db.command.or

                      查询指令,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

                      字段值的 “或” 操作指的是指定一个字段值为多个值之一即可:

                      字段值的或操作:示例代码

                      如筛选出进度大于 80 或小于 20 的 todo:

                      流式写法:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todo').where({      progress: _.gt(80).or(_.lt(20))    }).get()  } catch(e) {    console.error(e)  }}

                      前置写法:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todo').where({      memory: _.or(_.gt(80), _.lt(20))    }).get()  } catch(e) {    console.error(e)  }}

                      跨字段的 “或” 操作指条件 “或”,相当于可以传入多个 where 语句,满足其中一个即可,示例:

                      跨字段的或操作:示例代码

                      如筛选出进度大于 80 或已标为已完成的 todo:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todo').where(_.or([      {        progress: _.gt(80)      },      {        done: true      }    ]))  } catch(e) {    console.error(e)  }}

                      db.command.not

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      查询操作符,用于表示逻辑 "非" 的关系,表示需不满足指定的条件。

                      参数

                      command: Command

                      返回值

                      Command

                      示例

                      如筛选出进度不等于100的 todo:

                      const _ = db.commanddb.collection('todo').where({  progress: _.not(_.eq(100))})

                      not 也可搭配其他逻辑指令使用,包括 and, or, nor, not,如 or:

                      const _ = db.commanddb.collection('todo').where({  progress: _.not(_.or([_.lt(50), _.eq(100)]))})

                      db.command.nor

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      查询操作符,用于表示逻辑 "都不" 的关系,表示需不满足指定的所有条件。如果记录中没有对应的字段,则默认满足条件。

                      参数

                      expressions: any[]

                      返回值

                      Command

                      示例 1

                      筛选出进度既不小于20又不大于80的 todo :

                      const _ = db.commanddb.collection('todo').where({  progress: _.nor([_.lt(20), _.gt(80)])})

                      以上同时会筛选出不存在 progress 字段的记录,如果要要求 progress 字段存在,可以用 exists 指令:

                      const _ = db.commanddb.collection('todo').where({  progress: _.exists().nor([_.lt(20), _.gt(80)])  // 等价于以下非链式调用的写法:  // progress: _.exists().and(_.nor([_.lt(20), _.gt(80)]))}).get()

                      示例 2

                      筛选出 progress 不小于 20 且 tags 数组不包含 miniprogram 字符串的记录:

                      const _ = db.commanddb.collection('todo').where(_.nor([{  progress: _.lt(20),}, {  tags: 'miniprogram',}])).get()

                      以上会筛选出满足以下条件之一的记录:

                      1. progress 不小于 20 且 tags 数组不包含 miniprogram 字符串
                      2. progress 不小于 20 且 tags 字段不存在
                      3. progress 字段不存在 且 tags 数组不包含 miniprogram 字符串
                      4. progress 不小于 20 且 tags 字段不存在

                      如果要求 progress 和 tags 字段存在,可以用 exists 指令:

                      const _ = db.commanddb.collection('todo').where(  _.nor([{    progress: _.lt(20),  }, {    tags: 'miniprogram',  }])  .and({    progress: _.exists(true),    tags: _.exists(true),  }))

                      调用风格

                      方法接收两种传参方式,一是传入一个数组参数,二是传入多个参数,效果一样。

                      // 传入数组function nor(expressions: Expression[]): Command// 传入多参数function nor(...expressions: Expression[]): Command


                      db.command.set

                      更新指令。用于设定字段等于指定值。

                      函数签名:

                      function set(value: any): Command

                      这种方法相比传入纯 JS 对象的好处是能够指定字段等于一个对象:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  try {    // 以下方法只会更新 style.color 为 red,而不是将 style 更新为 { color: 'red' },即不影响 style 中的其他字段    const res1 = await db.collection('todos').doc('doc-id').update({      data: {        style: {          color: 'red'        }      }    })    // 以下方法更新 style 为 { color: 'red', size: 'large' }    const res2 = await db.collection('todos').doc('doc-id').update({      data: {        style: _.set({          color: 'red',          size: 'large'        })      }    })    return {      res1,      res2,    }  } catch(e) {    console.error(e)  }}

                      db.command.remove

                      更新指令。用于表示删除某个字段。

                      函数签名:

                      function remove(): Command

                      示例代码

                      删除 style 字段:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-id').update({      data: {        style: _.remove()      }    })  } catch(e) {    console.error(e)  }}

                      db.command.inc

                      更新指令。用于指示字段自增某个值,这是个原子操作,使用这个操作指令而不是先读数据、再加、再写回的好处是:

                      1. 原子性:多个用户同时写,对数据库来说都是将字段加一,不会有后来者覆写前者的情况
                      2. 减少一次网络请求:不需先读再写

                      mul 指令同理。

                      函数签名:

                      function inc(value: number): Command

                      示例代码

                      将一个 todo 的进度自增 10:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-id').update({      data: {        progress: _.inc(10)      }    })  } catch(e) {    console.error(e)  }}

                      db.command.mul

                      更新指令。用于指示字段自乘某个值,这是个原子操作,使用这个操作指令而不是先读数据、再加、再写回的好处是:

                      1. 原子性:多个用户同时写,对数据库来说都是将字段自乘,不会有后来者覆写前者的情况
                      2. 减少一次网络请求:不需先读再写

                      inc 指令同理。

                      函数签名:

                      function mul(value: number): Command

                      示例代码

                      将一个 todo 的进度乘 2:

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-id').update({      data: {        progress: _.mul(2)      }    })  } catch(e) {    console.error(e)  }}

                      db.command.push

                      更新指令,对一个值为数组的字段,往数组尾部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

                      函数签名:

                      function push(values: any[]): Command

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('doc-id').update({      data: {        tags: _.push(['mini-program', 'cloud'])      }    })  } catch(e) {    console.error(e)  }}

                      db.command.pop

                      更新指令,对一个值为数组的字段,将数组尾部元素删除。

                      函数签名:

                      function pop(values: any[]): Command

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('doc-id').update({      data: {        tags: _.pop()      }    })  } catch(e) {    console.error(e)  }}

                      db.command.shift

                      更新指令,对一个值为数组的字段,将数组头部元素删除。

                      函数签名:

                      function shift(values: any[]): Command

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('doc-id').update({      data: {        tags: _.shift()      }    })  } catch(e) {    console.error(e)  }}

                      db.command.unshift

                      更新指令,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

                      函数签名:

                      function unshift(values: any[]): Command

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('doc-id').update({      data: {        tags: _.unshift(['mini-program', 'cloud'])      }    })  } catch(e) {    console.error(e)  }}

                      Database.createCollection

                      创建集合,如果集合已经存在会创建失败

                      函数签名如下:

                      function createCollection(): Promise<Result>

                      返回值说明

                      Promise 的 resolve 和 reject 的结果定义如下:

                      结果说明
                      resolve查询的结果,Result 定义见下方
                      reject失败原因

                      Result 说明

                      Promise resolve 的结果 Result 是一个仅含 errMsg 的对象

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init()const db = cloud.database()exports.main = async (event, context) => {  return await db.createCollection('todos')}


                      update

                      即可更新单条记录,也可更新多条记录

                      remove

                      即可删除单条记录,也可更新多条记录

                      存储 API

                      云开发提供了一系列存储操作 API,此处是存储小程序端的 API 参考文档。

                      API说明
                      uploadFile上传文件
                      downloadFile下载文件
                      deleteFile删除文件
                      getTempFileURL换取临时链接

                      uploadFile

                      将本地资源上传至云存储空间,如果上传至同一路径则是覆盖。

                      请求参数

                      字段说明数据类型默认值必填
                      cloudPath云存储路径String-Y
                      fileContent要上传文件的内容fs.ReadStream-Y

                      Promise返回结果说明

                      字段说明数据类型
                      fileID文件 IDString
                      statusCode服务器返回的 HTTP 状态码Number

                      错误返回参数

                      字段说明数据类型
                      errCode错误码Number
                      errMsg错误信息,格式 apiName:fail msgString

                      使用示例

                      Promise 风格

                      const cloud = require('wx-server-sdk')const fs = require('fs')const path = require('path')exports.main = async (event, context) => {  const fileStream = fs.createReadStream(path.join(__dirname, 'demo.jpg'))  return await cloud.uploadFile({    cloudPath: 'demo.jpg',    fileContent: fileStream,  })}


                      downloadFile

                      从云存储空间下载文件

                      请求参数

                      字段说明数据类型默认值必填
                      fileID云文件 IDString-Y

                      Promise 返回参数

                      字段说明数据类型
                      fileContent文件内容Buffer
                      statusCode服务器返回的 HTTP 状态码Number

                      错误返回参数

                      字段说明数据类型
                      errCode错误码Number
                      errMsg错误信息,格式 apiName:fail msgString

                      使用示例

                      Promise 风格

                      const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  const fileID = 'xxxx'  const res = await cloud.downloadFile({    fileID: fileID,  })  const buffer = res.fileContent  return buffer.toString('utf8')}

                      getTempFileURL

                      用云文件 ID 换取真实链接,可自定义有效期,默认一天且最大不超过一天

                      请求参数

                      字段说明数据类型默认值必填
                      fileList要换取临时链接的云文件 ID 列表String[]-Y

                      fileList 数组中的每一个元素是一个云文件 fileID

                      Promise 返回参数

                      字段说明数据类型
                      fileList文件列表Object

                      fileList 数组中的每一个元素是有如下字段的 Object

                      字段说明数据类型
                      fileID云文件 IDString
                      tempFileURL临时文件路径String
                      status状态码,0 为成功Number
                      errMsg成功为 ok,失败为失败原因String

                      错误返回参数

                      字段说明数据类型
                      errCode错误码Number
                      errMsg错误信息,格式 apiName:fail msgString

                      使用示例

                      Promise 风格

                      const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  const fileList = ['cloud://xxx', 'cloud://yyy']  const result = await cloud.getTempFileURL({    fileList: fileList,  })  return result.fileList}


                      deleteFile

                      从云存储空间删除文件

                      请求参数

                      字段说明数据类型默认值必填
                      fileList云文件 ID 字符串数组String[]-Y

                      Promise 返回参数

                      字段说明数据类型
                      fileList删除结果列表,列表中的每一个对象的定义见下表Object[]

                      fileList 列表中的对象说明

                      字段说明数据类型
                      fileID云文件 IDString
                      status状态码,0 为成功Number
                      errMsg成功为 ok,失败为失败原因String

                      错误返回参数

                      字段说明数据类型
                      errCode错误码Number
                      errMsg错误信息,格式 apiName:fail msgString

                      使用示例

                      const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  const fileIDs = ['xxx', 'xxx']  const result = await cloud.deleteFile({    fileList: fileIDs,  })  return result.fileList}


                      支付方式

                      小程序·云开发在开通时,开发者会授权将小程序的注册信息用于进行云服务的初始化。此时,小程序帐号会对应生成或绑定一个腾讯云帐号。

                      • 生成:如果该小程序帐号在开通云开发前,并未授权为某个腾讯云帐号的微信公众平台登录方式,则系统会新建一个腾讯云帐号。
                      • 绑定:如果该小程序帐号在开通云开发前,已授权为某个腾讯云帐号的微信公众平台登录方式,则系统会自动关联该腾讯云帐号。

                      支付方式

                      目前小程序·云开发支持三种支付方式:

                      • 预付费:个人账户扣款:适用于个人账户结算的小程序,目前仅支付微信支付
                      • 预付费:腾讯云账户扣款:适用于通过腾讯云账户统一结算的小程序
                      • 按量付费:腾讯云账户扣款:适用于暂时无法准确预估使用量的小程序,目前仅支持从腾讯云账户扣款

                      其中,系统默认使用的支付方式为预付费:个人账户扣款。如需使用其他支付方式,需下载最新 nightly 版本 的开发者工具进行选择或切换。

                      初次购买预付费套餐

                      对于初次购买预付费配额的小程序,可在选定配额后,选择订单的支付方式。

                      一旦该订单支付成功,后续该环境下的订单将自动使用所选支付方式进行扣款。如需调整可前往 环境设置-支付方式 切换支付方式。

                      初次购买

                      开通按量付费

                      环境创建后,开发者可按需在配额设置中直接开通按量付费。小程序一旦开通按量付费后,将无法再切换到预付费支付方式,请开发者谨慎操作。

                      具体按量付费计费策略请参考文档《小程序·云开发按量付费》。

                      开通按量付费

                      切换支付方式

                      对于已经购买过付费配额的小程序,如需调整支付方式,可在云开发控制台 环境设置-支付方式 进行切换。目前,在切换支付方式时,开发者可选择的支付方式包括:

                      • 预付费:个人账户扣款
                      • 预付费:腾讯云账户扣款
                      • 按量付费:腾讯云账户扣款

                      当出现以下几种情况时,小程序则无法进行支付方式的切换:

                      • 当前支付方式为按量付费的环境暂不支持切换支付方式;
                      • 由于可开发发票余额小于退费金额,则无法进行付费方式切换。此时,开发者可选择在可开发票金额大于退费金额后或退回发票后再切换支付方式。详情请参考《小程序·云开发发票管理》;
                      • 该小程序从未购买过任何预付费配额时,将无法切换支付方式。开发者可在初次购买预付费配额时,直接选择支付方式或直接开通按量付费;
                      • 超过切换次数限制:单个小程序帐号累计支付方式切换次数不得超过 4 次;单个小程序帐号每月有且仅能切换一次支付方式;
                      • 切换至按量计费后无法再切换支付方式,请谨慎操作;
                      • 环境由于到期未续费,已经处于隔离期时,需先进行续费,才可再切换支付方式。

                      如遇特殊情况,可通过工单联系我们,具体工单提交方式请参考文档《小程序·云开发工单》。

                      切换支付方式

                      腾讯云费用中心

                      对于使用预付费:腾讯云账户扣款或按量付费:腾讯云账户扣款支付方式的小程序,可通过云开发控制台 环境设置——支付方式 中的腾讯云账户费用中心入口登录腾讯云费用中心,进行充值、订单管理、续费管理、发票与合同管理等操作。

                      同时开发者也可以登录腾讯云官网,使用微信公众号作为登录方式,选择对应的小程序帐号授权登录腾讯云控制台。并前往费用中心,进行充值、订单管理、续费管理、发票与合同管理等操作。

                      请注意:

                      • 对于使用预付费:个人账户扣款或按量付费:腾讯云账户扣款支付的订单需在云开发控制台 费用中心-发票管理 中开具对应订单金额的发票。
                      • 对于使用预付费:腾讯云账户扣款或按量付费:腾讯云账户扣款支付的订单需在腾讯云费用中心 发票与合同管理 中开具对应订单金额的发票。


                      预付费

                      目前小程序·云开发提供的预付费模式包括:

                      • 预付费:个人账户扣款:适用于个人账户结算的小程序,目前仅支付微信支付
                      • 预付费:腾讯云账户扣款:适用于通过腾讯云账户统一结算的小程序

                      系统默认使用的支付方式为预付费:个人账户扣款。以上预付费方式的计费单位为 元/月,在满足配额调整规则的条件下开发者可随时调整配置。

                      同时,为方便开发者以最低的资源成本进行功能开发,小程序·云开发还提供了免费版套餐供开发者试用。

                      分类参数免费额度
                      存储容量5GB
                      下载操作次数150 万次/月
                      上传操作次数60 万次/月
                      CDN回源流量5GB/月
                      CDNCDN流量5GB/月
                      云函数资源使用量 GBs4 万 GBs/月
                      外网出流量1GB/月
                      数据库容量2GB
                      同时连接数20
                      读操作次数5万次/天
                      写操作次数3万次/天
                      集合限制100个

                      配额说明

                      资源配额

                      以下为云开发各类资源配额指标,由腾讯云 TCB 提供存储和计算服务。 用户可通过下载最新的微信开发者工具使用该功能。 资源配额可分为三类:资源均衡型、CDN 资源消耗型、云函数资源消耗型、数据库资源消耗型。

                      资源均衡型

                      分类参数基础版 1基础版 2专业版 1专业版 2专业版 3旗舰版 1旗舰版 2旗舰版 3企业版 1
                      存储容量5GB10GB50GB100GB300GB500GB700GB1000GB1300GB
                      下载操作次数150万/月200万/月750万/月1500万/月2500万/月3750万/月4500万/月5000万/月6000万/月
                      上传操作次数60万/月100万/月300万/月600万/月1000万/月1500万/月2000万/月2500万/月3000万/月
                      CDN回源流量15GB/月10GB/月50GB/月150GB/月300GB/月500GB/月600GB/月800GB/月1000GB/月
                      CDNCDN流量5GB/月25GB/月50GB/月150GB/月300GB/月500GB/月1000GB/月2000GB/月4000GB/月
                      云函数资源使用量GBs34万/月20万/月40万/月150万/月300万/月400万/月1500万/月3000万/月4000万/月
                      外网出流量1GB/月3GB/月5GB/月10GB/月20GB/月25GB/月100GB/月200GB/月400GB/月
                      数据库容量2GB3GB5GB10GB20GB10GB50GB100GB200GB
                      同时连接数42050100200300400500500500
                      读操作数5万/天25万/天50万/天150万/天300万/天500万/天1000万/天2000万/天5000万/天
                      写操作数3万/天15万/天30万/天100万/天200万/天300万/天500万/天1000万/天3000万/天
                      集合限制100个150个200个300个400个400个500个600个800个
                      总价免费30 元/月104 元/月390 元/月690 元/月860 元/月2,499 元/月4,699 元/月8,999 元/月

                      CDN 资源消耗型

                      分类参数CDN 版 1CDN 版 2CDN 版 3
                      存储容量50GB100GB500GB
                      下载操作次750万/月1500万/月3750万/月
                      上传操作次数300万/月600万/月1500万/月
                      CDN回源流量50GB/月150GB/月500GB/月
                      CDNCDN流量500GB/月3072GB/月10240GB/月
                      云函数资源使用量GBs20万/月50万/月150万/月
                      外网出流量3GB/月5GB/月10GB/月
                      数据库容量3GB5GB10GB
                      同时连接数50100200
                      读操作数25万/天50万/天150万/天
                      写操作数15万/天30万/天100万/天
                      集合限制150个200个300个
                      总价149 元/月690 元/月2,199 元/月

                      云函数资源消耗型

                      分类参数云函数版 1云函数版 2云函数版 3
                      存储容量5GB10GB50GB
                      下载操作次数150万/月200万/月750 万/月
                      上传操作次数60万/月100 万/月300万/月
                      CDN回源流量5GB/月10GB/月50GB/月
                      CDNCDN流量5GB/月25GB/月150GB/月
                      云函数资源使用量GBs40万/月400万/月1500万/月
                      外网出流量5GB/月25GB/月100GB/月
                      数据库容量3GB10GB20GB
                      同时连接数50200300
                      读操作数25万/天150万/天300万/天
                      写操作数15万/天100万/天200万/天
                      集合限制150个300个400个
                      总价79 元/月390 元/月1,299 元/月

                      数据库资源消耗型

                      分类参数数据库版 1数据库版 2数据库版 3
                      存储容量5GB10GB50GB
                      下载操作次数150万/月200万/月750 万/月
                      上传操作次数60万/月100 万/月300万/月
                      CDN回源流量5GB/月10GB/月50GB/月
                      CDNCDN流量5GB/月25GB/月50GB/月
                      云函数资源使用量GBs20万/月150万/月400万/月
                      外网出流量3GB/月10GB/月25GB/月
                      数据库容量5GB50GB200GB
                      同时连接数100400500
                      读操作数50万/天500万/天5000万/天
                      写操作数30万/天300万/天3000万/天
                      集合限制200个400个800个
                      总价69 元/月590 元/月1,799 元/月

                      除以上配额参数外,小程序·云开发资源还包括以下系统参数限制(所有版本配额都遵守相同的系统参数限制):

                      • 云函数(单次运行)运行内存:256M5
                      • 云函数数量:50个
                      • 云函数并发数:10006
                      • 数据库流量:单次出包大小为16M
                      • 数据库单集合索引限制:20个
                      • 单个小程序的小程序端请求频率限制:100 万次/分钟

                      注:

                      1. CDN回源流量:指开启了 CDN 加速后,CDN 回源存储时产生的流量。
                      2. 云函数调用次数:已放开调用次数限制,现所有套餐均改为无限调用次数
                      3. 云函数资源使用量 GBs:资源使用量 = 函数配置内存 X 运行计费时长。用户资源使用量,是由函数配置内存,乘以函数运行时的计费时长得出,其中配置内存转换为 GB 单位,计费时长由毫秒(ms)转换为秒(s)单位,因此,资源使用量的计算单位为 GBs(GB-秒)。例如,配置为 256MB 的函数,单次运行了 1760 ms,计费时长为 1800 ms,则单次运行的资源使用量为 (256/1024)*(1800/1000) = 0.45 GBs。针对函数的每次运行,均会计算资源使用量,并按月汇总求和,作为当月的资源使用量。
                      4. 数据库同时连接数 :数据库请求并发数量,如同时有三十个数据库操作请求,则有二十个会同时执行,剩下十个返回超出并发错误;一次数据库请求(无论小程序端发起还是云函数端发起)将耗费一个连接;每个云环境分别有一个同时连接数限制、独立计数。假如数据库查询平均耗时 10ms,那么一个连接可以支持 100qps(1000ms/10ms=100),20个连接可以支持到 2000qps。
                      5. 云函数(单次运行)运行内存:云函数运行时最大可用内存为 256 MB。在云函数运行日志中展示的运行内存信息,为当次运行时的实际使用内存。实际使用内存可能低于最大可用内存,计费时按配置内存即 256 MB 计算。
                      6. 云函数同时连接数:已放开同时连接数限制,现所有套餐均改为统一的最大上限 1000

                      服务等级协议

                      小程序·云开发由腾讯云 TCB 提供存储和计算服务,因此小程序·云开发遵循《腾讯云云开发服务等级协议(SLA)》中的相关规定。

                      对于已购买云开发套餐并已产生费用的客户,如服务可用性低于标准,开发者有权根据服务等级协议中的赔偿方案,通过相应账户的 工单 申请赔付。具体可用性计算规则、赔偿标准和申请方式遵循《腾讯云云开发服务等级协议(SLA)》中的规定。

                      特别说明

                      • 自付费功能上线起,将不再受理通过邮箱申请的小程序·云开发配额调整申请。
                      • 对于截止2019-06-21日前申请调整的配额的截止日期统一延长至2019-08-31。

                      配额调整

                      配额调整方式

                      如需调整配额,可按照以下方式操作:

                      1. 登录 微信开发者工具 并打开 云控制台。
                      2. 点击 设置 页面,选择需调整到的配额版本。

                      调整配额

                      1. 核对调整信息并确认已阅读并同意《小程序·云开发资源配额调整规则》。
                      2. 在购买页选择相应的购买时长,确认无误后点击 提交订单。
                      • 配额:为当前将购买的配额版本,目前系统分别提供了基础版、专业版、旗舰版、企业版和豪华版共计 5 种配额以适用于不同的业务场景。
                      • 价格:为当前将购买的配额版本的价格信息,计费单位为月。
                      • 购买时长:用户可根据自身需求选择相应的购买时长,目前单次购买时长最低不得低于 1 个月,最高不得超过 6 个月。
                      • 到期时间:到期时间的计算规则可参考《小程序·云开发资源配额调整规则》。
                      • 合计价格:根据用户选择的配额、到期时间等信息计算得到。具体计算规则可参考《小程序·云开发资源配额调整规则》。

                      提交订单

                      1. 提交订单后可选择相应的支付方式并进行支付。系统目前仅支持微信支付,由于受微信支付的支付额度限制,单日支付金额需小于 ¥50,000 元。

                      查看订单详情

                      提交订单,用户可以在 历史配额 页面的订单记录列表中,查看订单号、创建时间和订单状态等,并可通过点击订单记录查看详细的订单信息。

                      订单状态

                      当订单处于不同的状态时,将影响环境的配额调整操作。具体情况如下:

                      • 当有订单处于未支付、支付中 以及发货中的状态时,用户将无法对当前环境再进行任何的配额调整操作。
                      • 对于升配、降配和续费成功的订单,订单状态将处于发货成功,届时用户可再次进行配额调整或续费操作。
                      • 对于升配或续费失败的订单,订单状态将处于 已退款 ,届时用户可重新发起配额调整或续费操作。
                      • 对于降配失败的订单,订单状态将处于 已取消,届时用户可重新发起配额调整。

                      取消订单

                      对于 未支付 的订单用户可通过点击 取消 按钮,取消该订单。

                      取消订单

                      删除订单

                      对于已取消的订单,用户可通过点击 删除 按钮,删除该订单。删除后订单将不再显示在 历史配额 中。

                      删除订单


                      配额调整规则

                      根据用户选择调整到的配额版本和当前配额版本的差异,配额调整可分为升配和降配。升配和降配具体的调整规则如下所述:

                      升配规则

                      第一次从基础版升配

                      从用户创建环境开始计算,第一次从基础版升级到其他配额时:

                      • 用户可手动输入输入购买时长,单次购买时长不得低于 1 个月,且不得高于 6 个月。
                      • 到期时间将根据根据购买时长在当前购买时间的基础上进行延长。
                      • 升配费用将根据新配额的按月价格和购买时长等计算得到,具体计算方法为:
                      升配费用 = 新配置按月价格 * 升配月数 * 新配置适用折扣;(无折扣不用乘折扣系数)
                      • 系统目前仅支持微信支付。由于受微信支付的支付额度限制,单日支付金额需小于 ¥50,000 元。

                      非第一次从基础版升配

                      从用户创建环境开始计算,非第一次从基础版升级到其他配额时:

                      • 到期时间将沿用当前生效配额的到期时间。
                      • 升配月数将根据资源到期时间和当前时间计算得到,具体计算方法为:
                      升配月数 = (资源到期时间 - 当前时间)/ (365 / 12);
                      • 升配费用将按照配置的按月价格和升配月数等参数计算得到,具体计算方法为:
                      升配费用 = 新配置按月价格 * 升配月数 * 新配置适用折扣- 老配置按月价格 * 升配月数 * 老配置适用折扣;(无折扣不用乘折扣系数)

                      降配规则

                      降配说明

                      当从较高版本的资源配额调整到较低版本的资源配额时,将产生降配操作。降配过程中:

                      1. 出现以下情形时,系统将限制用户降配,具体包括:
                      • 存储容量、数据库容量以及数据库集合数量超过配额限制将无法降配。用户可以清理资源后再进行降配。
                      • 存储下载次数、上传次数、CDN回源流量、CDN流量、云函数调用次数、云函数资源使用量、云函数外网出流量超过降配配额限制将无法降配。可在下一资源生命周期再进行降配。
                      • 数据库读操作次数和数据库写操作次数超限后,可选择下一自然日再进行配额调整或强制降配。强制降配将导致已超限资源本自然日内无法继续使用。
                      • 降配产生的退费金额超过了可开发票金额将无法降配。用户可将发票退回或当退费金额小于可开发票金额后再进行降配。发票退回操作步骤可参考《发票管理》。
                      1. 到期时间将沿用当前生效配额的到期时间。

                      退款金额

                      资源降配遵循先退款再购买原则,具体计算方法为:

                      降配退款金额 = 资源清退退款 - 资源新购费用

                      其中:

                      1. 资源清退退款:按照非全额退款规则计算退款金额,具体计算方法为:
                      退款金额 = 当前有效订单金额 + 未开始订单金额 - 资源已消费金额其中:- 当前有效订单金额/未开始订单金额:付费现金- 资源已消费金额 =(已使用时长/总时长)* 订单金额
                      1. 资源新购费用:按新购的价格及对应折扣进行计算购买金额。

                      退款途径

                      降配退款金额依据购买时使用的非代金券费用按支付方式(现金/赠送金)及支付比例退还到支付方账户。


                      续费说明

                      基础版续费

                      基础版可供开发者免费使用,因此在资源生命周期到期日,系统会自动进行续费操作,无需开发者手动续费。每次续费将按照一个月的粒度延长资源的到期时间。

                      非基础版配额续费

                      非基础版配额需用户手动进行续费并支付相应的费用。具体操作流程如下:

                      1. 用户可通过选择当前生效配额,并点击续费按钮进行续费。

                      续费

                      1. 用户可选择续费时长并提交订单。续费时需注意:
                      • 用户可手动输入购买时长,单次购买时长不得低于 1 个月,且不得高于 6 个月。
                      • 到期时间将根据续费时长在当前环境的到期时间的基础上进行延长。
                      • 续费价格将根据当前配额的按月价格和购买时长计算得到,具体计算方法为:
                      续费费用 = 续费配额的按月价格 * 购买月数 * 适用折扣;(无折扣不用乘折扣系数)
                      • 系统目前仅支持微信支付。由于受微信支付的支付额度限制,单日支付金额需小于 ¥50,000 元。

                      提交续费

                      隔离期续费说明

                      资源到期当天会系统会推送资源停服通知。到期次日至到期后 7 天,资源进入隔离期,在此期间用户对资源可以进行续费找回。具体续费规则如下:

                      • 用户续费金额按照续费时长计算费用。
                      • 到期时间为原有配额的到期时间加上续费时长。例如:用户原来到期时间是 19 年 7 月 20 日,隔离期从 7 月 21 日 - 7 月 27 日,在隔离期续费一个月,所需支付1个月的费用,新的到期时间为 19 年 8 月 20 日;

                      资源超限和到期停服规则

                      资源超限

                      在一个计费周期内,若某项资源使用量超出当前配额限制,系统将限制对该资源的使用,具体限制策略如下:

                      • 存储容量、数据库容量、数据库集合超限时,将无法存储或处理更多数据。除非清理数据到上限值以下或升级到更高配额套餐。
                      • CDN 流量、CDN 回源流量、存储下载次数限制、存储上传次数限制、云函数调用次数、云函数资源使用量和云函数外网出流量超限时,在下一资源生命周期前将无法使用资源。除非升级到更高配额套餐。
                      • 数据库读操作次数和数据库写操作次数超限时,在当前自然日内将无法使用资源。除非升级到更高配额套餐。
                      • 同时连接数、函数并发达到上限后后续的连接都将被拒,直到某些现有连接关闭为止。已连接的用户可以继续使用应用。除非升级到更高配额套餐。

                      到期通知

                      资源会在到期前 7 天开始,隔天推送到期通知,通知消息将通过微信公众平台公众号通知到小程序的开发者。

                      停服通知

                      资源到期当天会推送资源停服通知,通知消息将通过微信公众平台公众号通知到小程序的开发者。到期次日至到期后 7 天,仍可以进行续费找回。若到期 7 天后(包括第 7 天)未进行续费,系统将在到期后第 8 天开始释放资源,届时环境中的数据将被清除且不可恢复。

                      到期停服后:

                      • 存储、数据库和 CDN 资源均无法使用。
                      • 对于云函数:已有函数无法被触发。定时触发器暂停运行,停止触发函数。对于同步调用,函数将报错并无法执行。

                      回收机制

                      • 资源到期前 7 天,系统会开始发送到期通知。
                      • 资源到期当日系统会发送资源停服通知。
                      • 到期次日至到期后 7 天,仍可以进行续费找回。
                      • 若到期 7 天后(包括第 7 天)未进行续费,系统将在到期后第 8 天开始释放资源,届时环境中的数据将被清除且不可恢复。


                      按量付费

                      小程序·云开发已提供按量付费功能。在按量付费模式下,系统每月会提供一定的免费额度供开发者使用,超过免费额度的资源消耗将按照对应的刊例价扣除费用。

                      在使用按量付费功能时请注意:

                      • 小程序一旦开通按量付费后,将无法再切换到预付费支付方式,请开发者谨慎操作;
                      • 通过小程序管理后台和微信开发者工具云控制台申请的代金券无法用于按量付费模式;
                      • 同时,在按量付费模式下,基础告警功能将不再适用,但是开发者仍然可以使用自定义告警功能。具体告警功能使用方式可参考文档《小程序·云开发告警》;
                      • 需下载最新 nightly 版本 的开发者工具进行开通。

                      费用计算

                      按量付费的每月免费额度和刊例价信息如下:

                      参数价格免费额度
                      存储空间0.0043 元/GB/天5GB
                      存储下载操作次数0.01 元/万次150 万次/月
                      存储上传操作次数0.01 元/万次60 万次/月
                      CDN回源流量0.15 元/GB5GB/月
                      CDN流量0.18 元/GB5GB/月
                      云函数资源使用量0.00011108 元/GBs4 万 GBs/月
                      云函数外网出流量0.8 元/GB1GB/月
                      数据库容量0.07 元/GB2GB
                      数据库读操作次数0.015 元/万次5万次/天
                      数据库写操作次数0.05 元/万次3万次/天

                      可选拓展功能的按量付费的每月免费额度和刊例价信息如下:

                      参数价格免费额度
                      静态资源容量0.0042 元/GB/天开通后前两个月 1GB/天
                      静态资源流量0.15 元/万次开通后前两个月 5GB

                      请注意,小程序·云开发资源在按量付费模式下,需遵守以下系统参数限制:

                      • 数据库容量:2TB
                      • 云函数(单次运行)运行内存1:256M
                      • 云函数并发数2:1000
                      • 数据库同时连接数3:1000
                      • 单个小程序的小程序端请求频率限制:100 万次/分钟

                      在按量付费模式下,系统会每日进行资源消耗和结算并进行扣费。开发者可登录腾讯云费用中心进行充值或查看账单信息。

                      注:

                      1. 云函数(单次运行)运行内存:云函数运行时最大可用内存为 256MB。在云函数运行日志中展示的运行内存信息,为当次运行时的实际使用内存。实际使用内存可能低于最大可用内存,计费时按配置内存即 256MB 计算。
                      2. 云函数并发数:云函数的并发数量是指在任意指定时间对函数代码的执行数量。对于当前的 SCF 函数来说,每个发布的事件请求就会执行一次。因此,这些触发器发布的事件数(即请求量)会影响函数的并发数。开发者以使用以下公式来估算并发的函数实例总数目。每秒请求量 * 函数执行时间(按秒) 例如,考虑一个处理存储事件的函数,假定函数平均用时0.2秒(即200毫秒),存储每秒发布300个请求至函数。这样将同时生产 300 * 0.2 = 60 个函数实例。
                      3. 数据库同时连接数 :数据库请求并发数量,如同时有三十个数据库操作请求,则有二十个会同时执行,剩下十个返回超出并发错误;一次数据库请求(无论小程序端发起还是云函数端发起)将耗费一个连接;每个云环境分别有一个同时连接数限制、独立计数。假如数据库查询平均耗时 10ms,那么一个连接可以支持 100qps(1000ms/10ms=100),20个连接可以支持到 2000qps。

                      欠费和停服处理

                      从账户余额被扣为负值时,系统会通过微信公众平台公众号通知到小程序管理员并同步欠费信息至小程序云监控告警群,提示开发者尽快充值。

                      从账户余额被扣为负值时刻起,小程序·云开发资源在 12 小时内可继续使用且继续扣费,12 小时后未及时充值,系统将自动隔离资源且停止扣费。

                      进入资源隔离期后,系统会通过微信公众平台公众号通知到小程序管理员并同步停服信息至小程序云监控告警群。同时:

                      • 7*24 小时内,若充值至余额大于 0,计费将继续,用户可继续使用小程序·云开发提供的服务。
                      • 7*24 小时内,若账户余额尚未充值到大于 0,则无法使用服务。
                      • 7*24 小时后,若账户余额未充值到大于 0,按量计费环境将被回收。届时环境中的数据将被清除且不可恢复。

                      进入资源隔离期后:

                      • 存储、数据库和 CDN 资源均无法使用。
                      • 对于云函数:已有函数无法被触发。定时触发器暂停运行,停止触发函数。对于同步调用,函数将报错并无法执行。


                      发票管理

                      可开发票金额

                      可开发票金额为该帐号(小程序帐号)下所有环境购买订单所产生的可开发票金额。其计算方式为:

                      可开发票金额 = 总金额 - 已开发票金额

                      其中:

                      • 总金额为该帐号(小程序帐号)下所有环境购买订单所产生的总金额。
                      • 已开发票金额为该帐号(小程序帐号)下所有已开发票的总金额。

                      申请开票

                      小程序·云开发由腾讯云 TCB 提供存储和计算服务,因此发票由腾讯云计算(北京)有限责任公司开具。具体申请开票流程如下:

                      1. 用户可通过点击 申请开票 开具所需金额发票。

                      发票

                      1. 开发票时需填入相应的开票信息,具体包括:
                      • 开票金额
                      • 发票类型
                      • 邮寄地址

                      申请开票时请注意:

                      • 开票金额不得超过可开发票金额。
                      • 当开票金额小于 10 元时,发票将采取顺丰到付的邮寄方式,运费由用户承担。当开票金额不低于 10 元时,系统将提供免费的邮寄服务。
                      • 当天 24 点前可取消开发票申请。
                      • 若因信息填写错误导致发票不可用或丢失,需发起退票申请(流程周期较长),请仔细核对发票信息和邮寄地址。
                      • 对于个人增值税普通发票,发票抬头一律为 个人。
                      • 只有主体类型为 企业 的小程序才可开具 企业增值税专用发票,且发票抬头为小程序主体名称,用户不可自行修改。

                      查看开票详情

                      申请开票后,用户可以在 发票 页面的申请记录列表中,确认发票开具金额和状态,并可通过点击发票记录查看详细的发票信息和邮寄信息。

                      取消开发票申请

                      当天 24 点前,用户均可通过 取消 操作取消该开发票申请。一旦状态变更为开票中,用户将无法再取消该申请。

                      发票退回

                      若出现以下情况,可提交工单进行退票。提交工单时需填写问题描述为退发票,需写明退票原因,提交工单后将由客服人员处理。具体原因包括:

                      • 发票类型错误。
                      • 退费退票。
                      • 税号、开户行账号错误。
                      • 发票打印错误。
                      • 主体工商名称变更。
                      • 发票金额有误。

                      退票过程中请注意:

                      • 退票需用户自行邮寄发票及相关证明,邮费需自行支付。
                      • 此操作一旦进行将无法撤回,请谨慎操作。
                      • 不同情况下退票需邮寄的材料包括:退票时专票已抵扣需提供:税务局开具的 红字通知单 + 发票复印件 + 公司拒收证明。退票时专票未抵扣需提供:发票原件 + 公司拒收证明。其他退票:发票原件。

                      发票丢失处理

                      增值税普通发票:我们可以为你提供发票底联复印件(加盖发票章)或扫描件,用户可在控制台 提交工单 申请,工单中请写明原因及发票号码和金额。税务确认信息后,将于5 - 7个工作日内回复。

                      增值税专用发票:用户需要在其所在地主管税局办理发票遗失流程后,提供《行政处罚决定书》复印件(加盖公章)邮寄到对应收件地址。由税务到税局开具《丢失增值税专用发票已报税证明单》,用户收到该凭证后可凭《丢失增值税发票已报税证明单》入账并抵扣相应税款。

                      注意:

                      • 《丢失增值税发票已报税证明单》只适用丢失增值税专用发票;丢失增值税普通发票税局不支持开具。
                      • 具体邮寄地址可通过子在云开发控制台提交 工单 获取。


                      代金券申请方式

                      为助力开发者以更低的资源成本实现小程序的功能迭代,小程序·云开发提供了以下两种代金券:

                      • 通用代金券:专业版/旗舰版;
                      • 特殊代金券。

                      申请代金券前请注意:

                      • 通用代金券和特殊代金券仅适用于预付费的模式,不支持在按量付费模式中使用;
                      • 申请过通用代金券的帐号将无法再申请特殊代金券;
                      • 申请过特殊代金券的帐号待发券完成后,可继续申请通用代金券。

                      开发者可在 nightly 版本微信开发者工具云开发控制台费用管理的代金券模块申请相应的代金券。

                      代金券

                      通用代金券

                      申请标准

                      系统提供的专业版(104 元/月)和旗舰版(860 元/月)两种代金券,每种代金券的申请标准分别为:

                      • 专业版:最近 31 天,连续 5 天每天记录到用户访问中的独立访客(UV)不低于 100 的小程序可申请专业版代金券。
                      • 旗舰版:最近 31 天,连续 5 天每天记录到用户访问中的独立访客(UV)不低于 2000 的小程序可申请旗舰版代金券。

                      其中:

                      • 连续 5 天:是指不低于连续 5 天。连续 5 天、连续 6 天、连续 7 天等均为有效数据。
                      • 记录到用户访问中:如需将访问用户记录到云控制台的用户访问中,在调用 wx.cloud.init 方法时,需将 traceUser 置为 true。未被记录到用户访问中的用户将不作为有效数据,具体使用方式请参考 wx.cloud.init.
                      • 独立访客(UV):是指按照访客进行去重,每个独立用户为一次有效数据。
                      • 不低于 100/2000:是指大于或等于 100/2000。

                      满足旗舰版申请标准的小程序帐号同时也满足专业版的申请标准。但是,每个小程序帐号有且仅能申请专业版/旗舰版中的一种,且当代金券申请进入发券中状态时,将无法更换申请的代金券类型,请谨慎申请。

                      申请说明

                      代金券申请包括以下几个状态:

                      • 未申请:在未申请状态时,如果满足代金券申请标准,则小程序的开发者可发起代金券申请。
                      • 未审核:提交申请后,代金券申请会处于未审核状态。此时开发者可取消申请,取消后可再次发起代金券申请操作。
                      • 发券中:审核通过后,代金券申请会处于发券中状态。对于处于发券中的小程序,开发者将无法撤销申请或更换代金券类型,因此请谨慎申请代金券。
                      • 发券完成:代金券发放完毕后,代金券申请会处于发券完成状态,后续将不会再发放代金券。

                      申请通过后系统会每月定时发放代金券,累计下发 12 个月。除第一次外,每次发放代金券时间一般情况下会在申请时间的基础上提前两天发放。如遇申请时间为 30 或者 31 号,则发放时间是以 29 号为准提前两天。

                      申请通过/拒绝或发放代金券时,系统会通过模版消息通知到申请人,同时通过告警群通知到群成员。

                      申请被拒绝后,如有需要开发者可通过微信开发者工具的云开发控制台中的工单联系我们。

                      特殊代金券

                      当前无可申请的特殊代金券。

                      代金券使用说明

                      以下代金券使用说明同时适用于通用代金券和特殊代金券。

                      开发者可登录微信开发者工具的云开发控制台查看代金券的详细信息。同时,在购买预付费套餐时使用对应代金券。

                      发放的代金券的状态分为待使用、已冻结、已使用、已过期。每种状态的说明如下:

                      • 待使用:未使用且未过期的代金券,可以用于抵扣费用。
                      • 已冻结:显示已确认订单但未支付的代金券。
                      • 已使用:余额已使用完毕的代金券,不可用于抵扣费用。
                      • 已过期:已过有效期的代金券,不可用于抵扣费用。

                      如需了解代金券的具体信息,包括代金券编号、可用金额、总金额、状态、使用门槛、到期时间等,可在云开发控制台费用管理的代金券模块查看。

                      发放的代金券可在支付订单时使用。使用过程中需遵守以下规则:

                      • 一个订单只能使用一张代金券。
                      • 一张代金券仅能用于一个订单。
                      • 基于代金券支付的订单购买时长不得超过 1 个月。
                      • 代金券无金额门槛,可用于购买任意版本的云开发套餐。
                      • 代金券被冻结或已过期时,将无法使用代金券。
                      • 对于使用代金券支付的订单,在发起退费时,代金券将不予以退还。

                      使用代金券


                      兼容性问题

                      云开发能力从基础库 2.2.3 开始支持,现在 2.2.3 或以上的基础库已覆盖绝大部分用户(目前约 99.6% ),不应继续使用旧的兼容性处理方式。如采用了旧的兼容性处理方式,请去除 app.json / game.json 中的字段 "cloud": true。


                      云开发更新日志

                      小程序基础库更新日志(云开发部分)

                      v2.8.3 (2019.09.23)

                      1. A 增加 数据库 8 个查询指令、7 个更新指令、1 个投影操作符 详情

                      v2.8.1 (2019.08.22)

                      1. A 增加 数据库实时数据推送 详情

                      v2.7.3 (2019.07.05)

                      1. A 增加 数据库支持聚合能力 详情

                      v2.6.3 (2019.02.27)

                      1. A 增加 云开发数据库支持地理位置 API

                      v2.4.1 (2018.11.19)

                      1. A 增加 插件支持使用云开发

                      v2.3.2 (2018.10.25)

                      1. A 增加 db.RegExp 及正则查询支持

                      v2.2.3 (2018.08.19)

                      1. A 新增 小程序·云开发 SDK 详情

                      wx-server-sdk 更新日志

                      2.1.1 (2020.06.04)

                      1. A 新增 小游戏虚拟支付沙箱环境接口

                      2.1.0 (2020.06.03)

                      1. A 新增 小游戏虚拟支付能力
                      2. A 新增 数据库更新和删除 API 增加 multi 选项

                      2.0.2 (2020.05.06)

                      1. A 新增 微信支付能力
                      2. A 新增 云函数灰度能力

                      1.8.3 (2020.04.03)

                      1. A 新增 定义文件 index.d.ts

                      1.8.0 (2020.01.03)

                      1. U 更新 云调用 openapi 支持设置不自动转换驼峰命名法和蛇底命名法

                      1.7.0 (2019.12.24)

                      1. A 新增 数据库事务 API
                      2. U 更新 不再支持 node 8 以下运行环境,使用开发者工具本地调试需使用 node 8 或以上

                      1.6.0 (2019.12.12)

                      1. A 新增 定时触发器中支持使用 DYNAMIC_CURRENT_ENV

                      1.5.3 (2019.11.08)

                      1. U 更新 tcb-admin-node 依赖至 1.16.2,修复触发器内使用云调用可能失败的问题

                      1.5.0 (2019.10.23)

                      1. A 新增 logger 方法,支持高级日志

                      1.4.0 (2019.10.21)

                      1. A 新增 新增 not、expr 操作符

                      1.3.1 (2019.10.14)

                      1. F 修复 push 操作符接收数组参数的问题

                      1.3.0 (2019.10.14)

                      1. A 新增 查询操作符:all, elemMatch, exists, size, mod
                      2. A 新增 更新操作符:push, pull, pullAll, addToSet, rename, max, min
                      3. A 新增 聚合流水线阶段:lookup
                      4. A 新增 可用于聚合流水线 lookup 阶段的 pipeline 操作符

                      详询数据库 API 列表

                      1.2.2 (2019.10.11)

                      1. F 修复 使用 DYNAMIC_CURRENT_ENV 时发起云调用会失败的问题

                      1.2.1 (2019.09.16)

                      1. A 新增 数据库多个查询、投影操作符

                      1.1.1 (2019.09.12)

                      1. A 新增 常量 DYNAMIC_CURRENT_ENV

                      v0.8.1 (2019.07.01)

                      1. A 增加 数据库聚合能力 详情

                      0.7.0 (2019.06.28)

                      1. A 新增 getWXContext 新增返回表示云函数最初调用来源的 SOURCE 字段

                      v0.6.0(2019.05.30)

                      1. A 新增 云函数内可通过 getWXContext 获取当前所在环境 详情

                      v0.5.1(2019.05.15)

                      1. F 修复 部分 tmp secret key expired 错误问题
                      2. A 新增 云调用服务端调用 详情
                      3. A 新增 云调用开放数据调用 详情

                      v0.2.2 (2019.03.22)

                      1. A 增加 云开发数据库支持地理位置 API

                      0.0.24(2018.10.29)

                      1. A 新增 数据库支持正则查询

                      0.0.22 (2018.10.24)

                      1. U 更新 callOpenAPI 不需传 event 参数

                      0.0.21 (2018.10.19)

                      1. U 新增 getWXContext API,用于获取微信调用上下文,包括 APPID、OPENID 和 UNIONID

                      0.0.11(2018.08.30)

                      1. U 更新 callFunction 返回 requestID

                      0.0.9(2018.08.19)

                      1. U 更新 getTempFileURL 传入参数更新

                      0.0.7(2018.08.16)

                      1. A 新增 云开发数据库、云函数、文件存储基础能力

                      IDE 云开发 & 云控制台更新日志

                      2019.10.18 (>= 1.02.1910182)

                      1. A 新增 定时触发器支持使用云调用

                      2019.06.25 (>= 1.02.1906252)

                      1. A 新增 云控制台支持云函数接收消息推送配置 详情

                      2019.06.20 (>= 1.02.1906202)

                      1. A 新增 云控制台支持数据库高级查询/CRUD 详情

                      2019.05.30 (>= 1.02.1905302)

                      1. A 新增 IDE Network 面板支持展示云开发请求 详情

                      2019.05.24 (>= 1.02.1905242)

                      1. A 新增 IDE 支持云函数增量上传(上传单文件或目录)
                      2. A 新增 云函数本地调试支持开发数据调用 详情

                      2019.05.17 (>= 1.02.1905172)

                      1. A 新增 控制台支持展示详细配额使用信息

                      2019.03.25 (>= 1.02.1903251)

                      1. A 新增 云控制台支持添加地理位置索引 详情

                      2019.03.21 (>= 1.02.1903211)

                      1. A 新增 IDE 支持云函数本地调试 详情

                      2018.12.18 (>= 1.02.1812180)

                      1. A 新增 插件 plugin.json 支持 cloud: true 详情

                      2018.11.27 (>= 1.02.1811270)

                      1. A 新增 定时触发器 详情

                      2018.11.15 (>= 1.02.1811150)

                      1. A 新增 云数据库索引可以增加唯一性限制 详情
                      2. A 新增 云数据库导出 详情


                      错误码

                      在使用云能力时抛出的异常(fail 回调 / Promise reject)Error 对象中会带有 errCode 和 errMsg,云开发 HTTP API 回包中也会带有errcode和errmsg,这里是 errCode 值的一览表。

                      错误码含义
                      -1通用错误
                      -401001SDK 通用错误:无权限使用 API
                      -401002SDK 通用错误:API 传入参数错误
                      -401003SDK 通用错误:API 传入参数类型错误
                      -402001SDK 数据库错误:检测到循环引用
                      -402002SDK 数据库错误:初始化监听失败
                      -402003SDK 数据库错误:重连 WebSocket 失败
                      -402004SDK 数据库错误:重建监听失败
                      -402005SDK 数据库错误:关闭监听失败
                      -402006SDK 数据库错误:收到服务器错误信息
                      -402007SDK 数据库错误:从服务器收到非法数据
                      -402008SDK 数据库错误:WebSocket 连接异常
                      -402009SDK 数据库错误:WebSocket 连接断开
                      -402010SDK 数据库错误:检查包序失败
                      -402011SDK 数据库错误:未知异常
                      -501001云资源通用错误:云端系统错误
                      -403001SDK 文件存储错误:上传的文件超出大小上限
                      -404001SDK 云函数错误:云函数调用内部失败:空回包
                      -404002SDK 云函数错误:云函数调用内部失败:空 eventid
                      -404003SDK 云函数错误:云函数调用内部失败:空 pollurl
                      -404004SDK 云函数错误:云函数调用内部失败:空 poll 结果 json
                      -404005SDK 云函数错误:云函数调用失败:超出最大正常结果轮询尝试次数
                      -404006SDK 云函数错误:云函数调用内部失败:空 base resp
                      -404007SDK 云函数错误:云函数调用失败:baseresponse.errcode 非 0
                      -404008SDK 云函数错误:云函数调用失败:v1 轮询状态码异常
                      -404009SDK 云函数错误:云函数调用内部失败:轮询处理异常
                      -404010SDK 云函数错误:云函数调用失败:轮询结果已超时过期1
                      -404011SDK 云函数错误:云函数调用失败:函数执行失败
                      -404012SDK 云函数错误:云函数调用失败:超出最大轮询超时后尝试次数2
                      -40400xSDK 云函数错误:云函数调用失败
                      -404011SDK 云函数错误:云函数执行失败
                      -501002云资源通用错误:云端响应超时
                      -501003云资源通用错误:请求次数超出环境配额
                      -501004云资源通用错误:请求并发数超出环境配额
                      -501005云资源通用错误:环境信息异常
                      -501007云资源通用错误:参数错误
                      -501009云资源通用错误:操作的资源对象非法或不存在
                      -501015云资源通用错误:读请求次数配额耗尽
                      -501016云资源通用错误:写请求次数配额耗尽
                      -501017云资源通用错误:磁盘耗尽
                      -501018云资源通用错误:资源不可用
                      -501019云资源通用错误:未授权操作
                      -501020云资源通用错误:未知参数错误
                      -501021云资源通用错误:操作不支持
                      -502001云资源数据库错误:数据库请求失败
                      -502002云资源数据库错误:非法的数据库指令
                      -502003云资源数据库错误:无权限操作数据库
                      -502005云资源数据库错误:集合不存在
                      -502010云资源数据库错误:操作失败
                      -502011云资源数据库错误:操作超时
                      -502012云资源数据库错误:插入失败
                      -502013云资源数据库错误:创建集合失败
                      -502014云资源数据库错误:删除数据失败
                      -502015云资源数据库错误:查询数据失败
                      -503001云资源文件存储错误:云文件请求失败
                      -503002云资源文件存储错误:无权限访问云文件
                      -503003云资源文件存储错误:文件不存在
                      -503003云资源文件存储错误:非法签名
                      -504001云资源云函数错误:云函数调用失败
                      -504002云资源云函数错误:云函数执行失败
                      -601001微信后台通用错误:系统错误
                      -601002微信后台通用错误:系统参数错误
                      -601003微信后台通用错误:系统网络错误
                      -604001微信后台云函数错误:回包大小超过 1M
                      -604100微信后台云函数错误:API 不存在
                      -604101微信后台云函数错误:无权限调用此 API
                      -604102微信后台云函数错误:调用超时
                      -604103微信后台云函数错误:云调用系统错误
                      -604104微信后台云函数错误:非法调用来源
                      -604101微信后台云函数错误:调用系统错误
                      -605101微信后台 HTTP API 错误:查询语句解析失败

                      额外说明

                      1. 常见原因:发起调用后客户端网络异常;发起调用后在函数调用结果返回前切出小程序后台,并在后台函数调用结果缓存超期后才返回小程序前台。
                      2. 常见原因:客户端网络异常。

                      特殊错误说明:

                      • 如果 AppID 没有开通云开发服务,或刚开通云开发但还没有过准备期(十分钟),则调用 cloud.init 时会出现 cloud init error:{ errMsg: "invalid scope" } 的错误,如果是因没有开通云开发,则请先进行开通操作,如果是刚开通,请稍等十分钟再重试。


                      常量

                      DYNAMIC_CURRENT_ENV

                      支持端:云函数 1.1.0

                      标志当前所在环境,注意该值不是当前所在环境 ID 的字符串,其值等价于 Symbol.for('DYNAMIC_CURRENT_ENV'),是用于标志当前所在环境的。如在 init 中如果给 env 参数传该常量值,则后续的 API 请求会自动请求当前所在环境的云资源,如云函数 A 当前所在环境是 test-123,则其接下来请求数据库、文件存储、云函数时都默认请求环境 test-123 的数据库、文件存储、云函数。

                      常量可用于:

                      • cloud.init 的 env 参数
                      • cloud.updateConfig 的 env 参数
                      • 各 API 的 config 参数中的 env 参数

                      注意事项:

                      • 自 1.7.1 起,该变量支持在定时触发器中使用,之前的版本不支持。

                      示例

                      cloud.init: 设置 API 默认环境等于当前所在环境

                      cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})

                      cloud.database: 设置新数据库对象的调用环境等于当前所在环境

                      cloud.init({  env: 'xxx'})// 不同于 init 时设置的环境,db 对象的请求将会去到和当前云函数所在环境相同的环境const db = cloud.database({  env: cloud.DYNAMIC_CURRENT_ENV})

                      cloud.callFunction: 设置调用的同环境的云函数

                      cloud.init({  env: 'xxx'})// 不同于 init 时设置的环境,对云函数 getInfo 的请求将会去到和当前云函数所在环境相同的环境const callResult = await cloud.callFunction({  name: 'getInfo',  config: {    env: cloud.DYNAMIC_CURRENT_ENV  },  data: {    // ...  },})


                      Promise Cloud.callFunction(Object object)

                      支持端:小程序 , 云函数

                      调用云函数

                      参数

                      Object object

                      属性类型默认值必填说明
                      namestring云函数名
                      dataObject传递给云函数的参数,在云函数中可通过 event 参数获取
                      configObject配置
                      successfunction接口调用成功的回调函数
                      failfunction接口调用失败的回调函数
                      completefunction接口调用结束的回调函数(调用成功、失败都会执行)

                      object.config 的结构

                      属性类型默认值必填说明
                      envstring环境 ID,填写后将忽略 init 时指定的环境 ID

                      返回值

                      Promise.<Object>

                      属性类型说明
                      resultany云函数返回的结果
                      requestIDstring云函数执行 ID,可用于日志查询

                      data 参数说明

                      如果 data 中包含大数据字段(建议临界值 256KB),建议使用 wx.cloud.CDN 标记大数据字段,标记后在调用云函数时,该字段的内容将会上传至临时 CDN,然后在云函数中接收到的该字段值将是 CDN url,可在云函数中下载访问。通过这种方式,可以避免大数据传输造成的性能问题、及避免触及调用链路的传输大小限制。

                      如果在 data 中如果传入了 Buffer 类型的数据,数据在 JSON 序列化的过程中会被转成 { "type": "Buffer", data: number[] } 的格式,以小程序端调用为例:

                      // 小程序端调用wx.cloud.callFunction({  // ...  data: {    buf: ArrayBuffer // 此处填入了某种方式获取得到的 Buffer 数据,可以是 request 下来的,可以是读文件读出来的等等  },})// 云函数端收到的 event 参数的结构:{  "type": "Buffer",  "data": [ 17, 371, 255, ... ] // Uint8 Array}

                      因此应当避免传入 Buffer 类型的数据,因为会让数据体积增大,增加传输耗时,如果需要传递 Buffer,有两种替代的建议方式:

                      1. 若 Buffer 较大,可使用 wx.loud.CDN 方法标记字段内容
                      2. 若 Buffer 非常小 (如 < 10k),可将 Buffer 转成 base64 再调用

                      示例代码

                      假设已有一个云函数 add:

                      exports.add = (event, context, cb) => {  return event.x + event.y}

                      在小程序端发起对云函数 add 的调用:

                      wx.cloud.callFunction({  // 要调用的云函数名称  name: 'add',  // 传递给云函数的event参数  data: {    x: 1,    y: 2,  }}).then(res => {  // output: res.result === 3}).catch(err => {  // handle error})

                      在云函数端任意云函数发起对云函数 add 的调用(完整云函数代码示例):

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const res = await cloud.callFunction({    // 要调用的云函数名称    name: 'add',    // 传递给云函数的参数    data: {      x: 1,      y: 2,    }  })  // 3  return res.result}

                      小程序端 callback 风格调用:

                      小程序端同时支持 Callback 风格调用,如上 Promise 风格的调用可以用 Callback 风格改写:

                      wx.cloud.callFunction({  // 要调用的云函数名称  name: 'add',  // 传递给云函数的参数  data: {    x: 1,    y: 2,  },  success: res => {    // output: res.result === 3  },  fail: err => {    // handle error  },  complete: () => {    // ...  }})


                      Cloud.uploadFile()

                      支持端:小程序 , 云函数 , Web

                      将本地资源上传至云存储空间,如果上传至同一路径则是覆盖


                      Cloud.downloadFile()

                      支持端:小程序 , 云函数 , Web

                      从云存储空间下载文件


                      wx.cloud.downloadFile

                      从云存储空间下载文件

                      请求参数

                      字段说明数据类型默认值必填
                      fileID云文件 IDString-Y
                      config配置Object-N
                      success成功回调
                      fail失败回调
                      complete结束回调

                      config 对象定义

                      字段说明数据类型
                      env使用的环境 ID,填写后忽略 init 指定的环境String

                      success 返回参数

                      字段说明数据类型
                      tempFilePath临时文件路径String
                      statusCode服务器返回的 HTTP 状态码Number
                      errMsg成功为 downloadFile:ok,失败为失败原因String

                      fail 返回参数

                      字段说明数据类型
                      errCode错误码 Number
                      errMsg错误信息,格式 downloadFile:fail msgString

                      使用示例

                      Callback 风格

                      wx.cloud.downloadFile({  fileID: 'a7xzcb',  success: res => {    // get temp file path    console.log(res.tempFilePath)  },  fail: err => {    // handle error  }})

                      Promise 风格

                      wx.cloud.downloadFile({  fileID: 'a7xzcb'}).then(res => {  // get temp file path  console.log(res.tempFilePath)}).catch(error => {  // handle error})

                      返回值 如果请求参数中带有 success/fail/complete 回调中的任一个,则会返回一个 downloadTask 对象,通过 downloadTask 对象可监听上传进度变化事件,以及取消上传任务。


                      downloadFile

                      从云存储空间下载文件

                      请求参数

                      字段说明数据类型默认值必填
                      fileID云文件 IDString-Y

                      Promise 返回参数

                      字段说明数据类型
                      fileContent文件内容Buffer
                      statusCode服务器返回的 HTTP 状态码Number

                      错误返回参数

                      字段说明数据类型
                      errCode错误码Number
                      errMsg错误信息,格式 apiName:fail msgString

                      使用示例

                      Promise 风格

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const fileID = 'xxxx'  const res = await cloud.downloadFile({    fileID: fileID,  })  const buffer = res.fileContent  return buffer.toString('utf8')}


                      Cloud.deleteFile(fileList: string[]): Promise<Object>

                      支持端:小程序 , 云函数 , Web

                      从云存储空间删除文件,一次最多 50 个

                      参数

                      fileList: string[]

                      云文件 ID 字符串数组

                      返回值

                      Promise.<Object>

                      属性类型说明
                      fileListObject文件列表

                      fileList 的结构

                      属性类型说明
                      fileIDstring云文件 ID
                      statusnumber状态码,0 为成功
                      errMsgstring成功为 ok,失败为失败原因

                      小程序端示例

                      Promise 风格

                      wx.cloud.deleteFile({  fileList: ['a7xzcb']}).then(res => {  // handle success  console.log(res.fileList)}).catch(error => {  // handle error})

                      Callback 风格

                      wx.cloud.deleteFile({  fileList: ['a7xzcb'],  success: res => {    // handle success    console.log(res.fileList)  },  fail: err => {    // handle error  },  complete: res => {    // ...  }})

                      云函数端示例

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const fileIDs = ['xxx', 'xxx']  const result = await cloud.deleteFile({    fileList: fileIDs,  })  return result.fileList}


                      Cloud.getTempFileURL(fileList: string[]): Promise<Object>

                      支持端:小程序 , 云函数 , Web

                      用云文件 ID 换取真实链接,公有读的文件获取的链接不会过期,私有的文件获取的链接十分钟有效期。一次最多取 50 个。

                      参数

                      fileList: string[]

                      要换取临时链接的云文件 ID 列表

                      返回值

                      Promise.<Object>

                      属性类型说明
                      fileListObject文件列表

                      fileList 的结构

                      属性类型说明
                      fileIDstring云文件 ID
                      tempFileURLstring临时文件路径
                      statusnumber状态码,0 为成功
                      errMsgstring成功为 ok,失败为失败原因

                      小程序端示例

                      Promise 风格

                      wx.cloud.getTempFileURL({  fileList: [{    fileID: 'a7xzcb',    maxAge: 60 * 60, // one hour  }]}).then(res => {  // get temp file URL  console.log(res.fileList)}).catch(error => {  // handle error})

                      Callback 风格

                      wx.cloud.getTempFileURL({  fileList: ['cloud://xxx', 'cloud://yyy'],  success: res => {    // get temp file URL    console.log(res.fileList)  },  fail: err => {    // handle error  }})

                      云函数端示例

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const fileList = ['cloud://xxx', 'cloud://yyy']  const result = await cloud.getTempFileURL({    fileList: fileList,  })  return result.fileList}


                      Cloud.getWXContext(): Object

                      支持端:云函数

                      在云函数中获取微信调用上下文

                      返回值

                      Object

                      wxContext

                      属性类型说明
                      OPENIDstring小程序用户 openid,小程序端调用云函数时有
                      APPIDstring小程序 AppID,小程序端调用云函数时有
                      UNIONIDstring小程序用户 unionid,小程序端调用云函数,并且满足 unionid 获取条件时有
                      ENVstring云函数所在环境的 ID
                      SOURCEstring调用来源(云函数本次运行是被什么触发)
                      CLIENTIPstring小程序客户端 IPv4 地址
                      CLIENTIPV6string小程序客户端 IPv6 地址

                      使用说明

                      SOURCE 值跟随调用链条传递,会表示调用链路情况(用英文逗号分隔),比如小程序调用云函数 A,再在云函数 A 内调用云函数 B,则 A 获得的 SOURCE 为 wx_client, B 内获得的 SOURCE 为 wx_client,scf(微信小程序调用,然后云函数调用)。

                      SOURCE 的枚举类型:

                      SOURCE 值含义
                      wx_devtools微信 IDE 调用
                      wx_client微信小程序调用
                      wx_http微信 HTTP API 调用
                      wx_unknown微信未知来源调用
                      scf云函数调用云函数
                      其他非微信端触发

                      如果在云函数本地调试中,ENV 会为 local,SOURCE 会为 wx_client。

                      注意事项

                      请不要在 exports.main 外使用 getWXContext,此时尚没有调用上下文,无法获取得到信息。

                      示例代码

                      const cloud = require('wx-server-sdk')exports.main = async (event, context) => {  const {    OPENID,    APPID,    UNIONID,    ENV,  } = cloud.getWXContext()  return {    OPENID,    APPID,    UNIONID,    ENV,  }}

                      Cloud.logger(): Object

                      支持端:云函数 1.5.0

                      云函数中使用高级日志能力

                      返回值

                      Object

                      logger

                      属性类型说明
                      logfunction默认等级的日志
                      infofunction普通等级的日志
                      warnfunction警告等级的日志
                      errorfunction错误等级的日志

                      使用说明

                      用于使用高级日志能力。

                      logger 方法返回一个 log 对象,log 对象包含以下方法,每调用一次产生一条日志记录: log:默认等级的日志 info:普通等级的日志 warn:警告等级的日志 error:错误等级的日志

                      所有的方法都接收一个对象,对象的每个 <key, value> 对都会作为日志一条记录的一个可检索的键值对,其中 value 无论类型是什么都会自动转成字符串

                      示例代码

                      // 云函数入口文件const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV,})// 云函数入口函数exports.main = async (event, context) => {  const wxContext = cloud.getWXContext()  const log = cloud.logger()  log.info({    name: 'xx',    cost: 10,    attributes: {      width: 100,      height: 200,    },    colors: ['red', 'blue'],  })  // 输出到日志记录中会有这么一条记录:  // {  //   "level": "info",  //   "name": "xx",  //   "cost": "10",  //   "attributes": "{ width: 100, height: 200 }",  //   "colors": "[ "red", "blue" ]"  //   ..., // 其他系统字段  // }  return {    event,    openid: wxContext.OPENID,    appid: wxContext.APPID,    unionid: wxContext.UNIONID,  }}

                      Cloud.CDN(opt: string|ArrrayBuffer|Object)

                      支持端:小程序 2.12.0

                      小程序端调云函数传递大数据可用的临时 CDN

                      参数

                      opt: string|ArrrayBuffer|Object

                      使用说明

                      标记需要上传到 CDN 的文件/大字符串然后转换成 HTTP URL 的数据,必须在 callFunction 中使用。

                      小程序端调用云函数时,如需传递大数据(建议 128k 以上时),可用此 CDN 方法标记需要传递的数据,即可以是字符串,也可以是临时文件路径。标记之后,在调用云函数时,系统会自动上传相应数据到临时 CDN,最终云函数内接收到的该字段将会是一个 CDN 地址,可在云函数内请求下来。

                      用这个方法可以避免大数据在云函数链路内的传输,提高大数据调用时的性能,同时避免触及调用数据的大小限制。

                      CDN 方法可以接收三种参数类型:

                      • String
                      • ArrayBuffer
                      • 文件路径定义对象

                      当使用文件路径定义对象时,将在调用服务 API 时自动将相应文件路径对应的文件内容上传至 CDN 并转换成 CDN URL,对象定义如下: 入参*

                      接收一个对象,对象下有如下定义的字段:

                      字段名类型必填说明
                      typestring定义对象的类型,必填 filePath
                      filePathstring文件路径

                      示例代码

                      wx.cloud.callFunction({  name: 'test',  data: {    strDemo: wx.cloud.CDN('some large string'),    filePathDemo: wx.cloud.CDN({      type: 'filePath',      filePath: 'xxxxxxxx',    })  },}).then(console.log).catch(console.error)


                      Cloud.openapi

                      云调用 API 对象。


                      Cloud.CloudID(cloudID: string)

                      支持端:小程序 2.7.0

                      声明字符串为 CloudID(开放数据 ID),该接口传入一个字符串,返回一个 CloudID 特殊对象,将该对象传至云函数可以获取其对应的开放数据。详见通过云调用获取开放数据

                      参数

                      cloudID: string

                      通过开放能力在小程序端获取得到的 CloudID

                      示例代码

                      小程序端调用

                      wx.cloud.callFunction({  name: 'myFunction',  data: {    weRunData: wx.cloud.CloudID('xxx'), // 这个 CloudID 值到云函数端会被替换    obj: {      shareInfo: wx.cloud.CloudID('yyy'), // 非顶层字段的 CloudID 不会被替换,会原样字符串展示    }  }})

                      在云函数端接收到的 event 将会包含对应开放数据的对象,其中 event.weRunData 会因为符合规则而包含开放数据,event.shareInfo 则不会,event 结构将如下:

                      {  "weRunData": {    "cloudID": "27_Ih-9vxDaOhIbh48Bdpk90DUkUoNMAPaNtg7OSGM-P2wPEk1NbspjKGoql_g",    "data": {      "stepInfoList": [        {          "step": 9103,          "timestamp": 1571673600        },        {          "step": 9783,          "timestamp": 1571760000        }      ],      "watermark": {        "appid": "wx3d289323f5900f8e",        "timestamp": 1574338655      }    }  },  "obj": {    "shareInfo": "xxx"  }}

                      Cloud.getOpenData(list: string[]): Object

                      支持端:云函数

                      获取 CloudID 对应的开放数据

                      参数

                      list: string[]

                      要获取对应开放数据的 CloudID 列表

                      返回值

                      Object

                      属性类型说明
                      listArray.<Object>开放数据列表,与传入的 CloudID 列表一一对应

                      list 的结构

                      属性类型说明
                      cloudIDstring开放数据 CloudID
                      dataObject开放数据

                      说明

                      详见通过云调用获取开放数据

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const res = await cloud.getOpenData({    list: event.openData.list, // 假设 event.openData.list 是一个 CloudID 字符串列表  })  return res.list}

                      返回的结果结构类似如下(假设 list 长度为 1,其中的 CloudID 是微信运动数据的 CloudID):

                      [{  "cloudID": "27_Ih-9vxDaOhIbh48Bdpk90DUkUoNMAPaNtg7OSGM-P2wPEk1NbspjKGoql_g",  "data": {    "stepInfoList": [      {        "step": 9103,        "timestamp": 1571673600      },      {        "step": 9783,        "timestamp": 1571760000      }    ],    "watermark": {      "appid": "wx3d289323f5900f8e",      "timestamp": 1574338655    }  }

                      Cloud.getVoIPSign(options: Object): Promise<Object>

                      支持端:云函数

                      获取实时语音签名

                      参数

                      options: Object

                      属性类型默认值必填说明
                      groupIdstring游戏房间的标识
                      noncestring随机字符串,长度应小于 128
                      timestampnumber生成这个随机字符串的 UNIX 时间戳(精确到秒)

                      返回值

                      Promise.<Object>

                      属性类型说明
                      signaturestring签名

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const result = await cloud.getVoIPSign({    groupId: 'xxx',    timestamp: 1557056066,    nonce: 'yyy'  })  return result.fileListt}


                      CloudPay.unifiedOrder()

                      支持端:云函数 2.0.2

                      统一下单

                      说明

                      商户在小程序中先调用该接口在微信支付服务后台生成预支付交易单,返回正确的预支付交易后调起支付。

                      关键参数说明

                      云开发相关关键参数说明: 回调函数设置:envId 和 functionName 用来设置接收支付后的异步通知回调的云函数 返回字段 payment:该对象即是在小程序端调用 wx.requestPayment 所需的信息

                      回调云函数返回协议

                      支付结果回调的云函数必须返回如下一个对象,否则会视为回调不成功,云函数会收到重复的支付回调:

                      字段名变量名必填类型描述
                      错误码errcodeNumber0
                      错误信息errmsgString

                      参数说明

                      字段名变量名必填类型示例值描述
                      结果通知回调云函数名functionNameStringpaycallback接收微信支付异步通知回调的云函数名
                      结果通知回调云函数环境envIdStringtest-123接收微信支付异步通知回调的云函数所在的环境 ID
                      子商户号subMchIdString(32)1900000109微信支付分配的子商户号
                      设备号deviceInfoString(32)013467007045764终端设备号(门店号或收银设备ID),注意:PC网页或公众号内支付请传"WEB"
                      随机字符串nonceStrString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
                      商品描述bodyString(128)腾讯充值中心-QQ会员充值商品简单描述,该字段须严格按照规范传递,具体请见参数规定
                      商品详情detailString(6000)商品详细描述,对于使用单品优惠的商户,该字段必须按照规范上传,详见“单品优惠参数说明”
                      附加数据attachString(127)说明附加数据,在查询API和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据
                      商户订单号outTradeNoString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
                      货币类型feeTypeString(16)CNY符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
                      总金额totalFeeInt888订单总金额,只能为整数,详见支付金额
                      终端IPspbillCreateIpString(64)123.12.12.123支持IPV4和IPV6两种格式的IP地址。调用微信支付API的机器IP
                      交易起始时间timeStartString(14)20091225091010订单生成时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则
                      交易结束时间timeExpireString(14)20091227091010订单失效时间,格式为yyyyMMddHHmmss,如2009年12月27日9点10分10秒表示为20091227091010。订单失效时间是针对订单号而言的,由于在请求支付的时候有一个必传参数prepay_id只有两小时的有效期,所以在重入时间超过2小时的时候需要重新请求下单接口获取新的prepay_id。其他详见时间规则。
                      建议:最短失效时间间隔大于1分钟
                      订单优惠标记goodsTagString(32)WXG订单优惠标记,代金券或立减优惠功能的参数,说明详见代金券或立减优惠
                      交易类型tradeTypeString(16)JSAPI小程序取值如下:JSAPI,详细说明见参数规定
                      指定支付方式limitPayString(32)no_creditno_credit--指定不能使用信用卡支付
                      用户标识openidString(128)oUpF8uMuAJO_M2pxb1Q9zNjWeS6otrade_type=JSAPI,此参数必传,用户在商户appid下的唯一标识。openid如何获取,可参考【获取openid】。
                      用户子标识subOpenidString(128)oUpF8uMuAJO_M2pxb1Q9zNjWeS6otrade_type=JSAPI,此参数必传,用户在子商户appid下的唯一标识。openid和sub_openid可以选传其中之一,如果选择传sub_openid,则必须传sub_appid。下单前需要调用【网页授权获取用户信息】接口获取到用户的Openid。
                      电子发票入口开放标识receiptString(8)YY,传入Y时,支付成功消息和支付详情页将出现开票入口。需要在微信支付商户平台或微信公众平台开通电子发票功能,传此字段才可生效
                      场景信息sceneInfoString(256)Y该字段常用于线下活动时的场景信息上报,支持上报实际门店信息,商户也可以按需求自己上报相关信息。该字段为JSON对象数据,对象格式为{"store_info":{"id": "门店ID","name": "名称","area_code": "编码","address": "地址" }}

                      sceneInfo.storeInfo 对象说明*

                      字段名变量名必填类型示例值描述
                      门店ididString(32)SZTX001门店编号,由商户自定义
                      门店名称nameString(64)腾讯大厦腾大餐厅门店名称 ,由商户自定义
                      门店行政区划码area_codeString(6)440305门店所在地行政区划码,详细见《最新县及县以上行政区划代码》
                      门店详细地址addressString(128)科技园中一路腾讯大厦门店详细地址 ,由商户自定义

                      返回值说明

                      字段名变量名必填类型示例值描述
                      返回状态码returnCodeString(16)SUCCESSSUCCESS/FAIL 此字段是通信标识,非交易标识,交易是否成功需要查看result_code来判断
                      返回信息returnMsgString(128)签名失败返回信息,如非空,为错误原因。如 签名失败、参数格式校验错误

                      以下字段在returnCode为SUCCESS的时候有返回

                      字段名变量名必填类型示例值描述
                      小程序中发起支付所需信息paymentObject小程序端调用 wx.requestPayment 所需信息
                      服务商的APPIDappidString(32)wxd678efh567hg6787服务商商户的APPID
                      商户号mch_idString(32)1900000109调用接口提交的商户号
                      小程序的APPIDsub_appidString(32)wx8888888888888888微信分配的小程序ID
                      子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
                      设备号device_infoString(32)013467007045764调用接口提交的终端设备号,
                      随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS微信返回的随机字符串
                      签名signString(64)C380BEC2BFD727A4B6845133519F3AD6微信返回的签名,详见签名算法
                      业务结果result_codeString(16)SUCCESSSUCCESS/FAIL
                      错误代码err_codeString(32)SYSTEMERROR详细参见第6节错误列表
                      错误代码描述err_code_desString(128)系统错误错误返回的信息描述

                      以下字段在returnCode 和result_code都为SUCCESS的时候有返回

                      字段名变量名必填类型示例值描述
                      交易类型trade_typeString(16)JSAPI调用接口提交的交易类型,取值如下:JSAPI,详细说明见参数规定
                      预支付交易会话标识prepay_idString(64)wx201410272009395522657a690389285100微信生成的预支付回话标识,用于后续接口调用中使用,该值有效期为2小时
                      二维码链接code_urlString(64)weixin://wxpay/bizpayurl/up?pr=NwY5Mz9&groupid=00trade_type=NATIVE时有返回,此url用于生成支付二维码,然后提供给用户进行扫码支付。注意:code_url的值并非固定,使用时按照URL格式转成二维码即可

                      错误码

                      名称描述原因解决方案
                      INVALID_REQUEST参数错误参数格式有误或者未按规则上传订单重入时,要求参数值与原请求一致,请确认参数问题
                      NOAUTH商户无此接口权限商户未开通此接口权限请商户前往申请此接口权限
                      NOTENOUGH余额不足用户帐号余额不足用户帐号余额不足,请用户充值或更换支付卡后再支付
                      ORDERPAID商户订单已支付商户订单已支付,无需重复操作商户订单已支付,无需更多操作
                      ORDERCLOSED订单已关闭当前订单已关闭,无法支付当前订单已关闭,请重新下单
                      SYSTEMERROR系统错误系统超时系统异常,请用相同参数重新调用
                      APPID_NOT_EXISTAPPID不存在参数中缺少APPID请检查APPID是否正确
                      MCHID_NOT_EXISTMCHID不存在参数中缺少MCHID请检查MCHID是否正确
                      APPID_MCHID_NOT_MATCHappid和mch_id不匹配appid和mch_id不匹配请确认appid和mch_id是否匹配
                      LACK_PARAMS缺少参数缺少必要的请求参数请检查参数是否齐全
                      OUT_TRADE_NO_USED商户订单号重复同一笔交易不能多次提交请核实商户订单号是否重复提交
                      SIGNERROR签名错误参数签名结果不正确请检查签名参数和方法是否都符合签名算法要求
                      XML_FORMAT_ERRORXML格式错误XML格式错误请检查XML参数格式是否正确
                      REQUIRE_POST_METHOD请使用post方法未使用post传递参数请检查请求参数是否通过post方法提交
                      POST_DATA_EMPTYpost数据为空post数据不能为空请检查post数据是否为空
                      NOT_UTF8编码格式错误未使用指定编码格式请使用UTF-8编码格式

                      示例代码

                      // 云函数代码const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})exports.main = async (event, context) => {  const res = await cloud.cloudPay.unifiedOrder({    "body" : "小秋TIT店-超市",    "outTradeNo" : "1217752501201407033233368018",    "spbillCreateIp" : "127.0.0.1",    "subMchId" : "1900009231",    "totalFee" : 1,    "envId": "test-f0b102",    "functionName": "pay_cb"  })  return res}// 小程序代码wx.cloud.callFunction({  name: '函数名',  data: {    // ...  },  success: res => {    const payment = res.result.payment    wx.requestPayment({      ...payment,      success (res) {        console.log('pay success', res)      },      fail (res) {        console.error('pay fail', err)      }    })  },  fail: console.error,})


                      CloudPay.queryOrder()

                      支持端:云函数 2.0.2

                      查询订单

                      说明

                      该接口提供所有微信支付订单的查询,商户可以通过该接口主动查询订单状态,完成下一步的业务逻辑。

                      需要调用查询接口的情况:

                      ◆ 当商户后台、网络、服务器等出现异常,商户系统最终未接收到支付通知; ◆ 调用支付接口后,返回系统错误或未知交易状态情况; ◆ 调用被扫支付API,返回USERPAYING的状态; ◆ 调用关单或撤销接口API之前,需确认支付状态;

                      参数说明

                      字段名变量名必填类型示例值描述
                      子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
                      微信订单号transaction_id二选一String(32)1009660380201506130728806387微信的订单号,优先使用
                      商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-*@ ,且在同一个商户号下唯一。
                      随机字符串nonce_strString(32)C380BEC2BFD727A4B6845133519F3AD6随机字符串,不长于32位。推荐随机数生成算法

                      返回值说明

                      字段名变量名必填类型示例值描述
                      返回状态码returnCodeString(16)SUCCESSSUCCESS/FAIL 此字段是通信标识,非交易标识,交易是否成功需要查看trade_state来判断
                      返回信息returnMsgString(128)签名失败返回信息,如非空,为错误原因。如 签名失败、参数格式校验错误

                      以下字段在returnCode为SUCCESS的时候有返回

                      字段名变量名必填类型示例值描述
                      服务商的APPIDappidString(32)wxd678efh567hg6787服务商商户的APPID
                      商户号mch_idString(32)1230000109微信支付分配的商户号
                      小程序的APPIDsub_appidString(32)wx8888888888888888微信分配的小程序ID
                      子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
                      随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
                      签名signString(32)C380BEC2BFD727A4B6845133519F3AD6签名,详见签名生成算法
                      业务结果result_codeString(16)SUCCESSSUCCESS/FAIL
                      错误代码err_codeString(32)SYSTEMERROR错误码
                      错误代码描述err_code_desString(128)系统错误结果信息描述

                      以下字段在returnCode 和result_code都为SUCCESS的时候有返回

                      字段名变量名必填类型示例值描述
                      设备号device_infoString(32)013467007045764微信支付分配的终端设备号,
                      用户标识openidString(128)oUpF8uMuAJO_M2pxb1Q9zNjWeS6o用户在商户appid下的唯一标识
                      是否关注公众账号is_subscribeString(1)Y用户是否关注公众账号,Y-关注,N-未关注
                      用户子标识sub_openidString(128)wxd930ea5d5a258f4f用户在子商户appid下的唯一标识
                      是否关注子公众账号sub_is_subscribeString(1)Y用户是否关注子公众账号,Y-关注,N-未关注
                      交易类型trade_typeString(16)JSAPI调用接口提交的交易类型,取值如下:JSAPI,NATIVE,APP,MICROPAY,详细说明见参数规定
                      交易状态trade_stateString(32)SUCCESSSUCCESS—支付成功
                      REFUND—转入退款
                      NOTPAY—未支付
                      CLOSED—已关闭
                      REVOKED—已撤销(刷卡支付)
                      USERPAYING--用户支付中
                      PAYERROR--支付失败(其他原因,如银行返回失败)
                      付款银行bank_typeString(16)CMC银行类型,采用字符串类型的银行标识
                      订单金额total_feeInt100订单总金额,单位为分
                      标价币种fee_typeString(8)CNY货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
                      应结订单金额settlement_total_feeInt100当订单使用了免充值型优惠券后返回该参数,应结订单金额=订单金额-免充值优惠券金额。
                      现金支付金额cash_feeInt100现金支付金额订单现金支付金额,详见支付金额
                      现金支付货币类型cash_fee_typeString(16)CNY货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
                      代金券金额coupon_feeInt100“代金券或立减优惠”金额<=订单总金额,订单总金额-“代金券或立减优惠”金额=现金支付金额,详见支付金额
                      代金券使用数量coupon_countInt1代金券或立减优惠使用数量
                      代金券IDcoupon_id_$nString(20)10000代金券或立减优惠ID, $n为下标,从0开始编号
                      代金券类型coupon_type_$nStringCASHCASH--充值代金券
                      NO_CASH---非充值优惠券
                      开通免充值券功能,并且订单使用了优惠券后有返回(取值:CASH、NO_CASH)。$n为下标,从0开始编号,举例:coupon_type_$0
                      单个代金券金额coupon_fee_$nInt100单个代金券或立减优惠支付金额, $n为下标,从0开始编号
                      微信支付订单号transaction_idString(32)1217752501201407033233368018微信支付订单号
                      商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
                      商家数据包attachString(128)123456商家数据包,原样返回
                      支付完成时间time_endString(14)20141030133525订单支付时间,格式为yyyyMMddHHmmss,如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则
                      交易状态描述trade_state_descString(256)支付失败,请重新下单支付对当前查询订单状态的描述和下一步操作的指引

                      错误码

                      名称描述原因解决方案
                      ORDERNOTEXIST此交易订单号不存在查询系统中不存在此交易订单号该API只能查提交支付交易返回成功的订单,请商户检查需要查询的订单号是否正确
                      SYSTEMERROR系统错误后台系统返回错误系统异常,请再调用发起查询


                      CloudPay.closeOrder()

                      支持端:云函数 2.0.2

                      关闭订单

                      说明

                      以下情况需要调用关单接口:商户订单支付失败需要生成新单号重新发起支付,要对原订单号调用关单,避免重复支付;系统下单后,用户支付超时,系统退出不再受理,避免用户继续,请调用关单接口。 注意:订单生成后不能马上调用关单接口,最短调用时间间隔为5分钟。*

                      参数说明

                      字段名变量名必填类型示例值描述
                      子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
                      商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
                      随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS商户系统内部的订单号,32个字符内、可包含字母, 其他说明见安全规范

                      返回值说明

                      字段名变量名必填类型示例值描述
                      返回状态码returnCodeString(16)SUCCESSSUCCESS/FAIL
                      返回信息returnMsgString(128)签名失败返回信息,如非空,为错误原因。如 签名失败、参数格式校验错误

                      以下字段在returnCode为SUCCESS的时候有返回

                      字段名变量名必填类型示例值描述
                      服务商的APPIDappidString(32)wxd678efh567hg6787服务商商户的APPID
                      商户号mch_idString(32)1230000109微信支付分配的商户号
                      小程序的APPIDsub_appidString(32)wx8888888888888888微信分配的小程序ID
                      子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
                      随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位
                      签名signString(32)C380BEC2BFD727A4B6845133519F3AD6签名,验证签名算法
                      业务结果result_codeString(16)SUCCESSSUCCESS/FAIL
                      业务结果描述result_msgString(32)OK对于业务执行的详细描述
                      错误代码err_codeString(32)SYSTEMERROR详细参见下文错误列表
                      错误代码描述err_code_desString(128)系统错误结果信息描述

                      错误码

                      名称描述原因解决方案
                      ORDERPAID订单已支付订单已支付,不能发起关单订单已支付,不能发起关单,请当作已支付的正常交易
                      SYSTEMERROR系统错误系统错误系统异常,请重新调用该API
                      ORDERCLOSED订单已关闭订单已关闭,无法重复关闭订单已关闭,无需继续调用
                      SIGNERROR签名错误参数签名结果不正确请检查签名参数和方法是否都符合签名算法要求
                      REQUIRE_POST_METHOD请使用post方法未使用post传递参数请检查请求参数是否通过post方法提交
                      XML_FORMAT_ERRORXML格式错误XML格式错误请检查XML参数格式是否正确


                      CloudPay.refund()

                      支持端:云函数 2.0.2

                      申请退款

                      说明

                      当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,微信支付将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家帐号上。

                      注意:

                      1.交易时间超过一年的订单无法提交退款; 2、微信支付退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交,请不要更换退款单号,请使用原商户退款单号。 3、请求频率限制:150qps,即每秒钟正常的申请退款请求次数不超过150次。错误或无效请求频率限制:6qps,即每秒钟异常或错误的退款申请请求不超过6次 4、每个支付订单的部分退款次数不能超过50次

                      参数说明

                      字段名变量名必填类型示例值描述
                      子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
                      随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
                      微信订单号transaction_idString(32)1217752501201407033233368018微信订单号。与商户订单号二选一填入。
                      商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
                      商户退款单号out_refund_noString(64)1.21775E+27商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-
                      订单金额total_feeInt100订单总金额,单位为分,只能为整数,详见支付金额
                      申请退款金额refund_feeInt100退款总金额,单位为分,只能为整数,可部分退款。详见支付金额
                      货币种类refund_fee_typeString(8)CNY货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
                      退款原因refund_descString(80)商品已售完若商户传入,会在下发给用户的退款消息中体现退款原因
                      注意:若订单退款金额≤1元,且属于部分退款,则不会在退款消息中体现退款原因
                      退款资金来源refund_accountString(30)REFUND_SOURCE_RECHARGE_FUNDS仅针对老资金流商户使用
                      REFUND_SOURCE_UNSETTLED_FUNDS---未结算资金退款(默认使用未结算资金退款)
                      REFUND_SOURCE_RECHARGE_FUNDS---可用余额退款

                      返回值说明

                      字段名变量名必填类型示例值描述
                      返回状态码returnCodeString(16)SUCCESSSUCCESS/FAIL
                      返回信息returnMsgString(128)签名失败返回信息,如非空,为错误原因。如 签名失败、参数格式校验错误

                      以下字段在returnCode为SUCCESS的时候有返回

                      字段名变量名必填类型示例值描述
                      业务结果result_codeString(16)SUCCESSSUCCESS/FAIL
                      SUCCESS退款申请接收成功,结果通过退款查询接口查询
                      FAIL 提交业务失败
                      错误代码err_codeString(32)SYSTEMERROR列表详见错误码列表
                      错误代码描述err_code_desString(128)系统超时结果信息描述
                      服务商的APPIDappidString(32)wxd678efh567hg6787服务商商户的APPID
                      商户号mch_idString(32)1230000109微信支付分配的商户号
                      小程序的APPIDsub_appidString(32)wx8888888888888888微信分配的小程序ID
                      子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
                      随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位
                      签名signString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS签名,详见签名算法
                      微信订单号transaction_idString(32)1217752501201407033233368018微信订单号
                      商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
                      商户退款单号out_refund_noString(64)1217752501201407033233368018商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-
                      微信退款单号refund_idString(32)1217752501201407033233368018微信退款单号
                      申请退款金额refund_feeInt100退款总金额,单位为分,可以做部分退款
                      退款金额settlement_refund_feeInt100去掉非充值代金券退款金额后的退款金额,退款金额=申请退款金额-非充值代金券退款金额,退款金额<=申请退款金额
                      订单金额total_feeInt100订单总金额,单位为分,只能为整数,详见支付金额
                      应结订单金额settlement_total_feeInt100应结订单金额=订单金额-免充值代金券金额,应结订单金额<=订单金额。
                      货币种类fee_typeString(8)CNY订单金额货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
                      现金支付金额cash_feeInt100现金支付金额,单位为分,只能为整数,详见支付金额
                      现金退款金额cash_refund_feeInt100现金退款金额,单位为分,只能为整数,详见支付金额
                      代金券退款总金额coupon_refund_feeInt100代金券退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为现金,说明详见代金券或立减优惠
                      退款代金券使用数量coupon_refund_countInt1退款代金券使用数量
                      代金券类型coupon_type_$nString(8)CASHCASH--充值代金券
                      NO_CASH---非充值代金券
                      订单使用代金券时有返回(取值:CASH、NO_CASH)。$n为下标,从0开始编号,举例:coupon_type_0

                      错误码

                      名称描述原因解决方案
                      SYSTEMERROR接口返回错误系统超时请不要更换商户退款单号,请使用相同参数再次调用API。
                      BIZERR_NEED_RETRY退款业务流程错误,需要商户触发重试来解决并发情况下,业务被拒绝,商户重试即可解决请不要更换商户退款单号,请使用相同参数再次调用API。
                      TRADE_OVERDUE订单已经超过退款期限订单已经超过可退款的最大期限(支付后一年内可退款)请选择其他方式自行退款
                      ERROR业务错误申请退款业务发生错误该错误都会返回具体的错误原因,请根据实际返回做相应处理。
                      USER_ACCOUNT_ABNORMAL退款请求失败用户帐号注销此状态代表退款申请失败,商户可自行处理退款。
                      INVALID_REQ_TOO_MUCH无效请求过多连续错误请求数过多被系统短暂屏蔽请检查业务是否正常,确认业务正常后请在1分钟后再来重试
                      NOTENOUGH余额不足商户可用退款余额不足此状态代表退款申请失败,商户可根据具体的错误提示做相应的处理。
                      INVALID_TRANSACTIONID无效transaction_id请求参数未按指引进行填写请求参数错误,检查原交易号是否存在或发起支付交易接口返回失败
                      PARAM_ERROR参数错误请求参数未按指引进行填写请求参数错误,请重新检查再调用退款申请
                      APPID_NOT_EXISTAPPID不存在参数中缺少APPID请检查APPID是否正确
                      MCHID_NOT_EXISTMCHID不存在参数中缺少MCHID请检查MCHID是否正确
                      REQUIRE_POST_METHOD请使用post方法未使用post传递参数请检查请求参数是否通过post方法提交
                      SIGNERROR签名错误参数签名结果不正确请检查签名参数和方法是否都符合签名算法要求
                      XML_FORMAT_ERRORXML格式错误XML格式错误请检查XML参数格式是否正确
                      FREQUENCY_LIMITED频率限制2个月之前的订单申请退款有频率限制该笔退款未受理,请降低频率后重试
                      NOAUTH异常IP请求不予受理请求ip异常如果是动态ip,请登录商户平台后台关闭ip安全配置;
                      如果是静态ip,请确认商户平台配置的请求ip 在不在配的ip列表里


                      CloudPay.queryRefund()

                      支持端:云函数 2.0.2

                      查询退款

                      说明

                      提交退款申请后,通过调用该接口查询退款状态。退款有一定延时,用零钱支付的退款20分钟内到账,银行卡支付的退款3个工作日后重新查询退款状态。 注意:如果单个支付订单部分退款次数超过20次请使用退款单号查询* 分页查询*

                      当一个订单部分退款超过10笔后,商户用微信订单号或商户订单号调退款查询API查询退款时,默认返回前10笔和total_refund_count(退款单总笔数)。商户需要查询同一订单下超过10笔的退款单时,可传入订单号及offset来查询,微信支付会返回offset及后面的10笔,以此类推。当商户传入的offset超过total_refund_count,则系统会返回报错PARAM_ERROR。

                      举例:

                      一笔订单下的退款单有36笔,当商户想查询第25笔时,可传入订单号及offset=24,微信支付平台会返回第25笔到第35笔的退款单信息,或商户可直接传入退款单号查询退款

                      参数说明

                      字段名变量名必填类型示例值描述
                      子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
                      随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
                      微信订单号transaction_id四选一String(28)1217752501201407033233368018微信订单号查询的优先级是: refund_id > out_refund_no > transaction_id > out_trade_no
                      商户订单号out_trade_no四选一String(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
                      商户退款单号out_refund_no四选一String(64)1217752501201407033233368018商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-
                      微信退款单号refund_id四选一String(32)1217752501201407033233368018微信退款单号
                      偏移量offsetInt15偏移量,当部分退款次数超过10次时可使用,表示返回的查询结果从这个偏移量开始取记录

                      refund_id、out_refund_no、out_trade_no、transaction_id四个参数必填一个,如果同时存在优先级为: refund_id>out_refund_no>transaction_id>out_trade_no

                      返回值说明

                      字段名变量名必填类型示例值描述
                      返回状态码returnCodeString(16)SUCCESSSUCCESS/FAIL
                      返回信息returnMsgString(128)签名失败返回信息,如非空,为错误原因。如 签名失败、参数格式校验错误

                      以下字段在returnCode为SUCCESS的时候有返回

                      字段名变量名必填类型示例值描述
                      业务结果result_codeString(16)SUCCESSSUCCESS/FAIL
                      SUCCESS退款申请接收成功,结果通过退款查询接口查询
                      错误码err_codeString(32)SYSTEMERROR错误码详见第6节
                      错误描述err_code_desString(128)系统错误结果信息描述
                      服务商的APPIDappidString(32)wxd678efh567hg6787服务商商户的APPID
                      商户号mch_idString(32)1230000109微信支付分配的商户号
                      小程序的APPIDsub_appidString(32)wx8888888888888888微信分配的小程序ID
                      子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号
                      随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位
                      签名signString(32)C380BEC2BFD727A4B6845133519F3AD6签名,详见签名算法
                      微信订单号transaction_idString(32)1217752501201407033233368018微信订单号
                      商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-
                      订单金额total_feeInt100订单总金额,单位为分,只能为整数,详见支付金额
                      应结订单金额settlement_total_feeInt100当订单使用了免充值型优惠券后返回该参数,应结订单金额=订单金额-免充值优惠券金额。
                      货币种类fee_typeString(8)CNY订单金额货币类型,符合ISO 4217标准的三位字母代码,默认人民币:CNY,其他值列表详见货币类型
                      现金支付金额cash_feeInt100现金支付金额,单位为分,只能为整数,详见支付金额
                      退款笔数refund_countInt1当前返回退款笔数
                      商户退款单号out_refund_no_$nString(64)1217752501201407033233368018商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-
                      微信退款单号refund_id_$nString(32)1217752501201407033233368018微信退款单号
                      退款渠道refund_channel_$nString(16)ORIGINALORIGINAL—原路退款
                      BALANCE—退回到余额
                      OTHER_BALANCE—原账户异常退到其他余额账户
                      OTHER_BANKCARD—原银行卡异常退到其他银行卡
                      订单总退款次数total_refund_countInt35订单总共已发生的部分退款次数,当请求参数传入offset后有返回
                      申请退款金额refund_fee_$nInt100退款总金额,单位为分,可以做部分退款
                      退款金额settlement_refund_fee_$nInt100退款金额=申请退款金额-非充值代金券退款金额,退款金额<=申请退款金额
                      代金券类型coupon_type_$n_$mString(8)CASHCASH--充值代金券
                      NO_CASH---非充值代金券
                      订单使用代金券时有返回(取值:CASH、NO_CASH)。$n为下标,$m为下标,从0开始编号,举例:coupon_type_$0_$1
                      总代金券退款金额coupon_refund_fee_$nInt100代金券退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为现金,说明详见代金券或立减优惠
                      退款代金券使用数量coupon_refund_count_$nInt1退款代金券使用数量 ,$n为下标,从0开始编号
                      退款代金券IDcoupon_refund_id_$n_$mString(20)10000退款代金券ID, $n为下标,$m为下标,从0开始编号
                      单个代金券退款金额coupon_refund_fee_$n_$mInt100单个退款代金券支付金额, $n为下标,$m为下标,从0开始编号
                      退款状态refund_status_$nString(16)SUCCESS退款状态:SUCCESS—退款成功
                      REFUNDCLOSE—退款关闭。
                      PROCESSING—退款处理中
                      CHANGE—退款异常,退款到银行发现用户的卡作废或者冻结了,导致原路退款银行卡失败,可前往商户平台(pay.weixin.qq.com)-交易中心,手动处理此笔退款。$n为下标,从0开始编号。
                      退款资金来源refund_account_$nString(30)REFUND_SOURCE_RECHARGE_FUNDSREFUND_SOURCE_RECHARGE_FUNDS---可用余额退款/基本账户
                      REFUND_SOURCE_UNSETTLED_FUNDS---未结算资金退款
                      $n为下标,从0开始编号。
                      退款入账账户refund_recv_accout_$nString(64)招商银行信用卡0403取当前退款单的退款入账方
                      1)退回银行卡:
                      {银行名称}{卡类型}{卡尾号}
                      2)退回支付用户零钱:
                      支付用户零钱

                      3)退还商户:
                      商户基本账户
                      商户结算银行账户
                      4)退回支付用户零钱通:
                      支付用户零钱通
                      退款成功时间refund_success_time_$nString(20)2016-07-25 15:26:26退款成功时间,当退款状态为退款成功时有返回。$n为下标,从0开始编号。

                      错误码

                      名称描述原因解决方案
                      SYSTEMERROR接口返回错误系统超时请尝试再次掉调用API。
                      REFUNDNOTEXIST退款订单查询失败订单号错误或订单状态不正确请检查订单号是否有误以及订单状态是否正确,如:未支付、已支付未退款
                      INVALID_TRANSACTIONID无效transaction_id请求参数未按指引进行填写请求参数错误,检查原交易号是否存在或发起支付交易接口返回失败
                      PARAM_ERROR参数错误请求参数未按指引进行填写请求参数错误,请检查参数再调用退款申请
                      APPID_NOT_EXISTAPPID不存在参数中缺少APPID请检查APPID是否正确
                      MCHID_NOT_EXISTMCHID不存在参数中缺少MCHID请检查MCHID是否正确
                      REQUIRE_POST_METHOD请使用post方法未使用post传递参数请检查请求参数是否通过post方法提交
                      SIGNERROR签名错误参数签名结果不正确请检查签名参数和方法是否都符合签名算法要求
                      XML_FORMAT_ERRORXML格式错误XML格式错误请检查XML参数格式是否正确


                      CloudPay.downloadBill()

                      支持端:云函数 2.0.2

                      下载对账单

                      说明

                      商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和微信侧数据不一致,通过对账单核对后可校正支付状态。

                      注意:

                      1、微信侧未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中,跟原支付单订单号一致;

                      2、微信在次日9点启动生成前一天的对账单,建议商户10点后再获取;

                      3、对账单中涉及金额的字段单位为“元”。

                      4、对账单接口只能下载三个月以内的账单。

                      5、对账单是以商户号纬度来生成的,如一个商户号与多个appid有绑定关系,则使用其中任何一个appid都可以请求下载对账单。对账单中的appid取自交易时候提交的appid,与请求下载对账单时使用的appid无关。

                      6、小微商户不单独提供对账单下载,如有需要,可在调取【下载对账单】API接口时不传sub_mch_id,获取服务商下全量特约商户(包括小微商户和非小微商户)的对账单。

                      参数说明

                      字段名变量名必填类型示例值描述
                      子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号,如需下载指定的子商户号对账单,则此参数必传。
                      随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
                      签名signString(32)C380BEC2BFD727A4B6845133519F3AD6签名,详见签名生成算法
                      对账单日期bill_dateString(8)20140603下载对账单的日期,格式:20140603
                      账单类型bill_typeString(8)ALLALL,返回当日所有订单信息,默认值
                      SUCCESS,返回当日成功支付的订单
                      REFUND,返回当日退款订单
                      压缩账单tar_typeStringGZIP非必传参数,固定值:GZIP,返回格式为.gzip的压缩包账单。不传则默认为数据流形式。

                      返回值说明

                      失败时,返回以下字段

                      字段名变量名必填类型示例值描述
                      返回状态码returnCodeString(16)FAILFAIL
                      错误码描述returnMsgString(128)签名失败返回信息,如非空,为错误原因,如:签名失败 等。
                      错误码errorCodeString(16)20002失败错误码,详见错误码列表

                      成功时,数据以文本表格的方式返回,第一行为表头,后面各行为对应的字段内容,字段内容跟查询订单或退款结果一致,具体字段说明可查阅相应接口。

                      第一行为表头,根据请求下载的对账单类型不同而不同(由bill_type决定),目前有: 当日所有订单* 交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率 当日成功支付的订单* 交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,商品名称,商户数据包,手续费,费率 当日退款的订单* 交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,退款申请时间,退款成功时间,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率

                      从第二行起,为数据记录,各参数以逗号分隔,参数前增加`符号,为标准键盘1左边键的字符,字段顺序与表头一致。

                      倒数第二行为订单统计标题,最后一行为统计数据

                      总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额

                      举例如下:

                      交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率 2014-11-10 16:33:45,wx2421b1c4370ec43b,10000100,0,1000,1001690740201411100005734289,1415640626,085e9858e3ba5186aafcbaed1,MICROPAY,SUCCESS,OTHERS,CNY,0.01,0.0,0,0,0,0,,,被扫支付测试,订单额外描述,0,0.60% 2014-11-10 16:46:14,wx2421b1c4370ec43b,10000100,0,1000,1002780740201411100005729794,1415635270,085e9858e90ca40c0b5aee463,MICROPAY,SUCCESS,OTHERS,CNY,0.01,0.0,0,0,0,0,,,被扫支付测试,订单额外描述,0,0.60% 总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额 2,0.02,0.0,0.0,`0 结算对账单*

                      普通结算对账单

                      字段名称示例值字段说明
                      交易时间2017-12-14 15:49:06指该笔交易的支付成功时间或发起退款成功时间(注:不是退款成功时间),格式为YYYY-MM-DD HH:MM:SS,如2015-01-01 10:00:00
                      公众账号IDwxab8acb865bb11234发起该笔交易时使用的appid,appid是由微信平台给公众号或app分配的唯一标识、用于区分交易场景
                      商户号1234567890发起该笔交易的微信支付商户号,8~10位数字
                      子商户号0如果是普通受理模式下的交易,展示特约商户的商户号,8~10位数字
                      如果是直连模式交易,则展示成数字0
                      设备号8888该笔交易下单时在device_info字段中传入的信息,没填写则留空
                      微信订单号4200000008201712143733500001微信支付为该笔订单(或该笔退款对应的订单)分配的订单号
                      商户订单号test1商户传入的该笔订单(或该笔退款对应的订单)的商户订单号,对应下单接口里的out_trade_no字段
                      用户标识testxt08c-XB5-QD208X1Aid0Cbs微信平台为支付用户在公众账号(appid)下分配的唯一标识(openid)
                      交易类型NATIVE该笔订单(或该笔退款单对应的订单)的交易类型,使用英文缩写展示,取值和含义: 值:
                      JSAPI-JSAPI支付(或小程序支付)
                      NATIVE-Native支付
                      APP-app支付
                      MWEB-H5支付
                      MICROPAY-付款码支付
                      PAP-委托代扣
                      交易状态SUCCESSSUCCESS—支付成功,说明该行数据为一笔支付成功的订单
                      REFUND—转入退款,说明该行数据为一笔发起退款成功的退款单
                      REVOKED—已撤销,说明该行数据为一笔成功撤销的撤销单
                      付款银行OTHERS银行类型,采用字符串类型的银行标识,如CMC_CREDIT,完整说明见https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=4_2
                      货币种类CNY货币类型,符合ISO 4217标准的三位字母代码,如CNY
                      总金额0.01该笔订单的应结算金额(=订单金额-用户使用的免充值券金额),如果该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位
                      代金券或立减优惠金额0.00该笔订单中使用的微信支付代金券金额(包括充值券和免充值券),如果未使用代金券、或该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位
                      微信退款单号0微信支付为该笔退款分配的退款单号,如果该行数据为订单则展示0
                      商户退款单号0商户发起退款时填入的商户退款单号,如果该行数据为订单则展示0
                      退款金额0.00该笔退款或撤销单的应结算金额(申请退款金额-免充值券退款金额),如果该行数据为订单则展示为0.00,非负数、单位元,保留到小数点后2位
                      代金券或立减优惠退款金额0.00退款金额中包含的充值券退款金额,如果该行数据为订单或没有充值券退款则展示为0.00,非负数、单位元,保留到小数点后2位
                      退款类型ORIGINAL—原路退款
                      BALANCE—转退到用户的微信支付零钱
                      如果该行数据为订单,则留空
                      退款状态生成账单文件时该笔退款的状态、后续不会更新,如果该行数据为订单,则留空
                      SUCCES—退款成功
                      FAIL—退款失败M
                      PROCESSING—退款处理中
                      商品名称中文[body]商户传入的该笔订单(或该笔退款对应的订单)的商品名称,对应下单接口里的body字段
                      商户数据包测试中文[attach]商户传入的该笔订单(或该笔退款对应的订单)的商户数据包,对应下单接口里的attach字段,不传时留空
                      手续费0.00000该笔订单/退款对应的手续费金额,订单对应正数、退款对应负数,单位元,保留小数点后2位
                      费率0.00%该笔交易计费所使用的费率,百分数,如0.60%

                      开通免充值券后的结算对账单

                      字段名称示例值字段说明
                      交易时间2017-12-14 15:49:06指该笔交易的支付成功时间或发起退款成功时间(注:不是退款成功时间),格式为YYYY-MM-DD HH:MM:SS,如2015-01-01 10:00:00
                      公众账号IDwxab8acb865bb11234发起该笔交易时使用的appid,appid是由微信平台给公众号或app分配的唯一标识、用于区分交易场景
                      商户号1234567890发起该笔交易的微信支付商户号,8~10位数字
                      特约商户号0如果是普通受理模式下的交易,展示特约商户的商户号,8~10位数字
                      如果是直连模式交易,则展示成数字0
                      设备号8888该笔交易下单时在device_info字段中传入的信息,没填写则留空
                      微信订单号4200000008201712143733500001微信支付为该笔订单(或该笔退款对应的订单)分配的订单号
                      商户订单号test1商户传入的该笔订单(或该笔退款对应的订单)的商户订单号,对应下单接口里的out_trade_no字段
                      用户标识testxt08c-XB5-QD208X1Aid0Cbs微信平台为支付用户在公众账号(appid)下分配的唯一标识(openid)
                      交易类型NATIVE该笔订单(或该笔退款单对应的订单)的交易类型,使用英文缩写展示,取值和含义: 值:
                      JSAPI-JSAPI支付(或小程序支付)
                      NATIVE-Native支付
                      APP-app支付
                      MWEB-H5支付
                      MICROPAY-付款码支付
                      PAP-委托代扣
                      交易状态SUCCESSSUCCESS—支付成功,说明该行数据为一笔支付成功的订单
                      REFUND—转入退款,说明该行数据为一笔发起退款成功的退款单
                      REVOKED—已撤销,说明该行数据为一笔成功撤销的撤销单
                      付款银行OTHERS银行类型,采用字符串类型的银行标识,如CMC_CREDIT,完整说明见https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=4_2
                      货币种类CNY货币类型,符合ISO 4217标准的三位字母代码,如CNY
                      应结订单金额0.01该笔订单的应结算金额(=订单金额-用户使用的免充值券金额),如果该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位
                      代金券金额0.00该笔订单中使用的微信支付代金券金额(包括充值券和免充值券),如果未使用代金券、或该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位
                      微信退款单号0微信支付为该笔退款分配的退款单号,如果该行数据为订单则展示0
                      商户退款单号0商户发起退款时填入的商户退款单号,如果该行数据为订单则展示0
                      退款金额0.00该笔退款或撤销单的应结算金额(申请退款金额-免充值券退款金额),如果该行数据为订单则展示为0.00,非负数、单位元,保留到小数点后2位
                      充值券退款金额0.00退款金额中包含的充值券退款金额,如果该行数据为订单或没有充值券退款则展示为0.00,非负数、单位元,保留到小数点后2位
                      退款类型ORIGINAL—原路退款
                      BALANCE—转退到用户的微信支付零钱
                      如果该行数据为订单,则留空
                      退款状态生成账单文件时该笔退款的状态、后续不会更新,如果该行数据为订单,则留空
                      SUCCES—退款成功
                      FAIL—退款失败M
                      PROCESSING—退款处理中
                      商品名称中文[body]商户传入的该笔订单(或该笔退款对应的订单)的商品名称,对应下单接口里的body字段
                      商户数据包测试中文[attach]商户传入的该笔订单(或该笔退款对应的订单)的商户数据包,对应下单接口里的attach字段,不传时留空
                      手续费0.00000该笔订单/退款对应的手续费金额,订单对应正数、退款对应负数,单位元,保留小数点后2位
                      费率0.00%该笔交易计费所使用的费率,百分数,如0.60%
                      订单金额0.01该笔订单的金额,包括用户支付金额、充值券金额、免充值券金额,如果该行数据为退款或撤销则填0.00,单位元,保留到小数点后2位
                      申请退款金额0.00商户发起退款的金额,包括退给用户的金额、充值券退款金额、免充值券退款金额,如果该行数据订单则填0.00,单位元,保留到小数点后2位
                      费率备注如果有特殊费率规则时则加以说明,默认留空

                      错误码

                      错误码名称描述原因解决方案
                      20003SYSTEMERROR下载失败系统超时请尝试再次查询。
                      20001sign error签名错误请求参数未按要求进行填写签名错误,请重新检查参数和签名密钥是否正确
                      20001nonce_str too long参数nonce_str错误请求参数未按要求填写参数nonce_str长度超长
                      20001invalid tar_type, Only GZIP supported参数tar_type错误请求参数未按指引进行填写请重新检查参数invalid tar_typ是否正确
                      20001invalid bill_type参数bill_type错误请求参数未按指引进行填写请重新检查参数bill_type是否正确
                      20001invalid bill_date参数bill_date错误请求参数未按指引进行填写请重新检查参数bill_date是否符合要求
                      20001require POST method请求方式错误请求方式不符合要求请求检查参数请求方式是否为post
                      20001empty post data请求报文错误请求报文为空请重新检查请求报文是否正确
                      20001data format error参数格式错误请求参数要求为xml格式请重新检查请求参数格式是否为xml
                      20001missing parameter缺少参数有必传的参数未上传请重新检查是否所有必传参数都上传了,且不为空
                      20001invalid appidappid错误请求参数appid有误请重新检查参数appid是否正确
                      20001invalid parameter参数错误有未知的请求参数请重新检查是否所有参数都与文档相符
                      20001sub_mch not allow特约商户号权限错误无该特约商户账单的下载权限请检查特约商户号是否正确。若是小微商户,可不传sub_mch_id以获取服务商下全量特约商户的账单
                      20002NO Bill Exist账单不存在当前商户号没有已成交的订单,不生成对账单请检查当前商户号在指定日期内是否有成功的交易。
                      20002Bill Creating账单未生成当前商户号没有已成交的订单或对账单尚未生成请先检查当前商户号在指定日期内是否有成功的交易,如指定日期有交易则表示账单正在生成中,请在上午10点以后再下载。
                      20007当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭,请联系微信支付解决
                      20100system error下载失败系统超时请尝试再次查询。


                      Cloud.database(options: Object): Database

                      支持端:小程序 , 云函数 , Web

                      获取数据库实例

                      参数

                      options: Object

                      属性类型默认值必填说明
                      envstring环境 ID,若不填则采用 init 中的值
                      throwOnNotFoundboolean在调用获取记录(doc.get)时,如果获取不到,是否抛出异常,如果不抛出异常,doc.get 返回空。默认 true。云函数 wx-server-sdk 1.7.0 开始支持。

                      返回值

                      Database

                      小程序端示例

                      以下调用获取默认环境的数据库的引用:

                      const db = wx.cloud.database()

                      假设有一个环境名为 test-123,用做测试环境,那么可以如下获取测试环境数据库:

                      const testDB = wx.cloud.database({  env: 'test-123'})

                      云函数端示例

                      env 设置示例*

                      以下调用获取和云函数当前所在环境相同的数据库的引用:

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()

                      假设有一个环境名为 test,用做测试环境,那么可以如下获取测试环境数据库:

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const testDB = cloud.database({  env: 'test'})

                      也可以通过 init 传入默认环境的方式使得获取数据库时默认是默认环境数据库:

                      const cloud = require('wx-server-sdk')cloud.init({  env: 'test'})const testDB = cloud.database()

                      throwOnNotFound 设置示例*

                      以下设置将 doc.get 的行为改为:如果获取不到记录,不抛出异常,而是返回空。

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV,  throwOnNotFound: false})const testDB = cloud.database()


                      Database

                      云开发 SDK 数据库实例

                      属性

                      Command command

                      数据库操作符

                      Geo Geo

                      数据库地理位置结构

                      方法

                      Database.collection(name: string): Collection

                      获取集合的引用。方法接受一个 name 参数,指定需引用的集合名称。

                      Database.createCollection(collectionName: string): Promise<Object>

                      创建集合,如果集合已经存在会创建失败

                      Database.serverDate(options: Object): ServerDate

                      构造一个服务端时间的引用。可用于查询条件、更新字段值或新增记录时的字段值。

                      Database.runTransaction(callback: function, times: number): Promise<any>

                      发起事务。仅可在云函数中使用。

                      Database.startTransaction(): Promise<Transaction>

                      开始事务,另一个同样可以使用的发起事务的 API 是 runTransaction。仅可在云函数中使用。

                      小程序端示例

                      以下调用获取默认环境的数据库的引用:

                      const db = wx.cloud.database()

                      假设有一个环境名为 test-123,用做测试环境,那么可以如下获取测试环境数据库:

                      const testDB = wx.cloud.database({  env: 'test-123'})

                      云函数端示例

                      以下调用获取和云函数当前所在环境相同的数据库的引用:

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()

                      假设有一个环境名为 test,用做测试环境,那么可以如下获取测试环境数据库:

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const testDB = cloud.database({  env: 'test'})

                      也可以通过 init 传入默认环境的方式使得获取数据库时默认是默认环境数据库:

                      const cloud = require('wx-server-sdk')cloud.init({  env: 'test'})const testDB = cloud.database()


                      Database.collection(name: string): Collection

                      支持端:小程序 , 云函数 , Web

                      获取集合的引用。方法接受一个 name 参数,指定需引用的集合名称。

                      参数

                      name: string

                      集合名称

                      返回值

                      Collection

                      示例代码:小程序端

                      const db = wx.cloud.database()const todosCollection = db.collection('todos')

                      示例代码:云函数端

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()const todosCollection = db.collection('todos')


                      Command

                      数据库操作符,通过 db.command 获取

                      属性

                      AggregateCommand aggregate

                      聚合操作符

                      方法

                      Command.addToSet(value: any|Object): Command

                      数组更新操作符。原子操作。给定一个或多个元素,除非数组中已存在该元素,否则添加进数组。

                      Command.all(values: any[]): Command

                      数组查询操作符。用于数组字段的查询筛选条件,要求数组字段中包含给定数组的所有元素。

                      Command.and(expressions: any[]): Command

                      查询操作符,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

                      Command.bit(object: Object): Command

                      更新操作符。对字段进行位运算,可以进行 and/or/xor 运算。

                      Command.elemMatch(condition: Object|Command): Command

                      用于数组字段的查询筛选条件,要求数组中包含至少一个满足 elemMatch 给定的所有条件的元素

                      Command.eq(value: any): Command

                      查询筛选条件,表示字段等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

                      Command.exists(value: boolean): Command

                      判断字段是否存在

                      Command.expr(aggregateExpression: Expression):  Command

                      查询操作符,用于在查询语句中使用聚合表达式,方法接收一个参数,该参数必须为聚合表达式

                      Command.geoIntersects(options: Object): Command

                      找出给定的地理位置图形相交的记录

                      Command.geoNear(options: Object): Command

                      按从近到远的顺序,找出字段值在给定点的附近的记录。

                      Command.geoWithin(options: Object): Command

                      找出字段值在指定区域内的记录,无排序。指定的区域必须是多边形(Polygon)或多边形集合(MultiPolygon)。

                      Command.gt(value: any): Command

                      查询筛选操作符,表示需大于指定值。可以传入 Date 对象用于进行日期比较。

                      Command.gte(value: any): Command

                      查询筛选操作符,表示需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

                      Command.in(value: any[]): Command

                      查询筛选操作符,表示要求值在给定的数组内。

                      Command.inc(value: number): Command

                      更新操作符,原子操作,用于指示字段自增

                      Command.lt(value: any): Command

                      查询筛选操作符,表示需小于指定值。可以传入 Date 对象用于进行日期比较。

                      Command.lte(value: any): Command

                      查询筛选操作符,表示需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

                      Command.max(value: any): Command

                      更新操作符,给定一个值,只有该值大于字段当前值才进行更新。

                      Command.min(value: any): Command

                      更新操作符,给定一个值,只有该值小于字段当前值才进行更新。

                      Command.mod(divisor: number, remainder: number): Command

                      查询筛选操作符,给定除数 divisor 和余数 remainder,要求字段作为被除数时 value % divisor = remainder。

                      Command.mul(value: number): Command

                      更新操作符,原子操作,用于指示字段自乘某个值

                      Command.neq(value: any): Command

                      查询筛选条件,表示字段不等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

                      Command.nin(value: any[]): Command

                      查询筛选操作符,表示要求值不在给定的数组内。

                      Command.nor(expressions: any[]): Command

                      查询操作符,用于表示逻辑 "都不" 的关系,表示需不满足指定的所有条件。如果记录中没有对应的字段,则默认满足条件。

                      Command.not(command: Command): Command

                      查询操作符,用于表示逻辑 "非" 的关系,表示需不满足指定的条件。

                      Command.or(expressions: any[]): Command

                      查询操作符,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

                      Command.pop(): Command

                      数组更新操作符,对一个值为数组的字段,将数组尾部元素删除

                      Command.pull(value: any): Command

                      数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值或查询条件的元素都移除掉。

                      Command.pullAll(value: any): Command

                      数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值的元素都移除掉。跟 pull 的差别在于只能指定常量值、传入的是数组。

                      Command.push(values: Object): Command

                      数组更新操作符。对一个值为数组的字段,往数组添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

                      Command.remove()Command

                      更新操作符,用于表示删除某个字段。

                      Command.rename(value: string): Command

                      更新操作符,字段重命名。如果需要对嵌套深层的字段做重命名,需要用点路径表示法。不能对嵌套在数组里的对象的字段进行重命名。

                      Command.set(value: any): Command

                      更新操作符,用于设定字段等于指定值。

                      Command.shift(): Command

                      数组更新操作符,对一个值为数组的字段,将数组头部元素删除。

                      Command.size(value: string): Command

                      更新操作符,用于数组字段的查询筛选条件,要求数组长度为给定值

                      Command.unshift(values: any[]): Command

                      数组更新操作符,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。


                      Geo

                      数据库地理位置结构集

                      方法

                      Geo.LineString(points: GeoPoint[]): GeoPoint

                      构造一个地理位置的 ”线“。一个线由两个或更多的点有序连接组成。

                      Geo.MultiLineString(lineStrings: GeoLineString[]): GeoMultiLineString

                      构造一个地理位置 ”线“ 集合。一个线集合由多条线组成。

                      Geo.MultiPoint(points: GeoPoint[]): GeoMultiPoint

                      构造一个地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

                      Geo.MultiPolygon(polygons: GeoPolygon[]): GeoMultiPolygon

                      构造一个地理位置 ”多边形“ 集合。一个多边形集合由多个多边形组成。

                      Geo.Point(longitude: number, latitude: number): GeoPoint

                      构造一个地理位置 ”点“。方法接受两个必填参数,第一个是经度(longitude),第二个是纬度(latitude),务必注意顺序。

                      Geo.Polygon(lineStrings: GeoLineString[]): GeoPolygon

                      构造一个地理位置 ”多边形“


                      Database.serverDate(options:Object): ServerDate

                      支持端:小程序 , 云函数 , Web

                      构造一个服务端时间的引用。可用于查询条件、更新字段值或新增记录时的字段值。

                      参数

                      options: Object

                      属性类型默认值必填说明
                      offsetnubmer引用的服务端时间偏移量,毫秒为单位,可以是正数或负数

                      返回值

                      ServerDate

                      示例代码

                      新增记录时设置字段为服务端时间:

                      db.collection('todos').add({  description: 'eat an apple',  createTime: db.serverDate()})

                      更新字段为服务端时间往后一小时:

                      db.collection('todos').doc('my-todo-id').update({  due: db.serverDate({    offset: 60 * 60 * 1000  })})


                      Database.RegExp

                      构造正则表达式,仅需在普通 js 正则表达式无法满足的情况下使用

                      options 参数说明

                      options 支持 i, m, s 这三个 flag,注意 JavaScript 原生正则对象构造时仅支持其中的 i, m 两个 flag,因此需要使用到 s 这个 flag 时必须使用 db.RegExp 构造器构造正则对象。flag 的含义见下表:

                      flag说明
                      i大小写不敏感
                      m跨行匹配;让开始匹配符 ^ 或结束匹配符 $ 时除了匹配字符串的开头和结尾外,还匹配行的开头和结尾
                      s让 . 可以匹配包括换行符在内的所有字符

                      基础用法示例

                      // 原生 JavaScript 对象db.collection('todos').where({  description: /miniprogram/i})// 数据库正则对象db.collection('todos').where({  description: db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})// 用 new 构造也是可以的db.collection('todos').where({  description: new db.RegExp({    regexp: 'miniprogram',    options: 'i',  })})


                      Database.createCollection(collectionName: string): Promise<Object>

                      支持端:云函数

                      创建集合,如果集合已经存在会创建失败

                      参数

                      collectionName: string

                      返回值

                      Promise.<Object>

                      属性类型说明
                      errMsgstring

                      示例

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  return await db.createCollection('todos')}


                      Database.runTransaction(callback: function, times: number): Promise<any>

                      支持端:云函数

                      发起事务。仅可在云函数中使用。

                      参数

                      callback: function

                      事务执行函数,需为 async 异步函数或返回 Promise 的函数

                      times: number

                      事务执行最多次数,默认 3 次,成功后不重复执行,只有事务冲突时会重试,其他异常时不会重试

                      返回值

                      Promise.<any>

                      resolve 的结果为 callback 事务执行函数的返回值,reject 的结果为事务执行过程中抛出的异常或者是 transaction.rollback 传入的值

                      事务执行函数说明

                      事务执行函数由开发者传入,函数接收一个参数 transaction(类型定义见 Transaction),其上提供 collection 方法和 rollback 方法。collection 方法用于取数据库集合记录引用进行操作,rollback 方法用于在不想继续执行事务时终止并回滚事务。

                      事务执行函数必须为 async 异步函数或返回 Promise 的函数,当事务执行函数返回时,SDK 会认为用户逻辑已完成,自动提交(commit)事务,因此务必确保用户事务逻辑完成后才在 async 异步函数中返回或 resolve Promise。

                      事务执行函数可能会被执行多次,在内部发现事务冲突时会自动重复执行,如果超过设定的执行次数上限,会报错退出。

                      在事务执行函数中发生的错误,都会认为事务执行失败而抛错。

                      事务执行函数返回的值会作为 runTransaction 返回的 Promise resolve 的值,在函数中抛出的异常会作为 runTransaction 返回的 Promise reject 的值,如果事务执行函数中调用了 transaction.rollback,则传入 rollback 函数的值会作为 runTransaction 返回的 Promise reject 的值。

                      限制

                      事务现仅支持在云函数 wx-server-sdk 使用。事务操作时为保障效率和并发性,只允许进行单记录操作,不允许进行批量操作,但可以在一个事务中对多个记录进行操作。

                      注意事项

                      开发者提供的事务执行函数正常返回时,SDK 会自动提交(commit)事务,请勿在事务执行函数内调用 transaction.commit 方法,该方法仅在通过 db.startTransaction 进行事务操作时使用。

                      示例代码

                      两个账户之间进行转账的简易示例

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database({  throwOnNotFound: false,})const _ = db.commandexports.main = async (event) => {  try {    const result = await db.runTransaction(async transaction => {      const aaaRes = await transaction.collection('account').doc('aaa').get()      const bbbRes = await transaction.collection('account').doc('bbb').get()      if (aaaRes.data && bbbRes.data) {        const updateAAARes = await transaction.collection('account').doc('aaa').update({          data: {            amount: _.inc(-10)          }        })        const updateBBBRes = await transaction.collection('account').doc('bbb').update({          data: {            amount: _.inc(10)          }        })        console.log(`transaction succeeded`)        // 会作为 runTransaction resolve 的结果返回        return {          aaaAccount: aaaRes.data.amount - 10,        }      } else {        // 会作为 runTransaction reject 的结果出去        await transaction.rollback(-100)      }    })    return {      success: true,      aaaAccount: result.aaaAccount,    }  } catch (e) {    console.error(`transaction error`, e)    return {      success: false,      error: e    }  }}


                      Database.startTransaction():Promise<Transaction>

                      支持端:云函数

                      开始事务,另一个同样可以使用的发起事务的 API 是 runTransaction。仅可在云函数中使用。

                      返回值

                      Promise.<Transaction>

                      resolve 的结果为事务操作对象,其上可通过 collection API 操作数据库,通过 commit 或 rollback 来结束或终止事务。

                      限制

                      事务现仅支持在云函数 wx-server-sdk 使用。事务操作时为保障效率和并发性,只允许进行单记录操作,不允许进行批量操作,但可以在一个事务中对多个记录进行操作。

                      示例代码

                      两个账户之间进行转账的简易示例

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database({  throwOnNotFound: false,})const _ = db.commandexports.main = async (event) => {  try {    const transaction = await db.startTransaction()    const aaaRes = await transaction.collection('account').doc('aaa').get()    const bbbRes = await transaction.collection('account').doc('bbb').get()    if (aaaRes.data && bbbRes.data) {      const updateAAARes = await transaction.collection('account').doc('aaa').update({        data: {          amount: _.inc(-10)        }      })      const updateBBBRes = await transaction.collection('account').doc('bbb').update({        data: {          amount: _.inc(10)        }      })      await transaction.commit()      console.log(`transaction succeeded`)      return {        success: true,        aaaAccount: aaaRes.data.amount - 10,      }    } else {      await transaction.rollback()      return {        success: false,        error: `rollback`,        rollbackCode: -100,      }    }  } catch (e) {    console.error(`transaction error`, e)    return {      success: false,      error: e    }  }}


                      Collection

                      数据库集合引用

                      方法

                      Collection.doc(id: string): Document

                      获取集合中指定记录的引用。方法接受一个 id 参数,指定需引用的记录的 _id。

                      Collection.add(options: Object): Promise<Object>

                      新增记录,如果传入的记录对象没有 _id 字段,则由后台自动生成 _id;若指定了 _id,则不能与已有记录冲突

                      Collection.aggregate(): Aggregate

                      发起聚合操作,定义完聚合流水线阶段之后需调用 end 方法标志结束定义并实际发起聚合操作

                      Collection.count(): Promise<Object>

                      统计匹配查询条件的记录的条数

                      Collection.field(projection: Object): Collection

                      指定返回结果中记录需返回的字段

                      Collection.get(): Promise<Object>

                      获取集合数据,或获取根据查询条件筛选后的集合数据。

                      Collection.limit(value: number): Collection

                      指定查询结果集数量上限

                      Collection.orderBy(fieldPath: string, string: order): Collection

                      指定查询排序条件

                      Collection.remove(): Promise<Object>

                      删除多条记录。注意只支持通过匹配 where 语句来删除,不支持 skip 和 limit。

                      Collection.skip(offset: number): Collection

                      指定查询返回结果时从指定序列后的结果开始返回,常用于分页

                      Collection.update(): Promise<Object>

                      更新多条记录

                      Collection.watch(options: Object): Object

                      监听集合中符合查询条件的数据的更新事件。使用 watch 时,支持 where, orderBy, limit,不支持 field。

                      Collection.where(condition: Object): Collection

                      指定查询条件,返回带新查询条件的新的集合引用


                      Collection.doc(id: string): Document

                      支持端:小程序 , 云函数 , Web

                      获取集合中指定记录的引用。方法接受一个 id 参数,指定需引用的记录的 _id。

                      参数

                      id: string

                      记录 _id

                      返回值

                      Document

                      示例代码

                      const myTodo = db.collection('todos').doc('my-todo-id')


                      Collection.aggregate(): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      发起聚合操作,定义完聚合流水线阶段之后需调用 end 方法标志结束定义并实际发起聚合操作

                      返回值

                      Aggregate

                      示例代码

                      const $ = db.command.aggregatedb.collection('books').aggregate()  .group({    // 按 category 字段分组    _id: '$category',    // 让输出的每组记录有一个 avgSales 字段,其值是组内所有记录的 sales 字段的平均值    avgSales: $.avg('$sales')  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

                      小程序端兼容支持 callback 风格

                      const $ = db.command.aggregatedb.collection('books').aggregate()  .group({    // 按 category 字段分组    _id: '$category',    // 让输出的每组记录有一个 avgSales 字段,其值是组内所有记录的 sales 字段的平均值    avgSales: $.avg('$sales')  })  .end({    success: function(res) {      console.log(res)    },    fail: function(err) {      console.error(err)    }  })


                      Collection.where(condition: Object): Collection

                      支持端:小程序 , 云函数 , Web

                      指定查询条件,返回带新查询条件的新的集合引用

                      参数

                      condition: Object

                      查询条件

                      返回值

                      Collection

                      示例代码

                      const _ = db.commandconst result = await db.collection('todos').where({  price: _.lt(100)}).get()


                      Collection.limit(value: number): Collection

                      支持端:小程序 , 云函数 , Web

                      指定查询结果集数量上限

                      参数

                      value: number

                      返回值

                      Collection

                      说明

                      limit 在小程序端默认及最大上限为 20,在云函数端默认及最大上限为 1000

                      示例代码

                      db.collection('todos').limit(10)  .get()  .then(console.log)  .catch(console.error)

                      Collection.orderBy(fieldPath: string, string: order): Collection

                      支持端:小程序 , 云函数 , Web

                      指定查询排序条件

                      参数

                      fieldPath: string

                      string: order

                      返回值

                      Collection

                      说明

                      方法接受一个必填字符串参数 fieldName 用于定义需要排序的字段,一个字符串参数 order 定义排序顺序。order 只能取 asc 或 desc。

                      如果需要对嵌套字段排序,需要用 "点表示法" 连接嵌套字段,比如 style.color 表示字段 style 里的嵌套字段 color。

                      同时也支持按多个字段排序,多次调用 orderBy 即可,多字段排序时的顺序会按照 orderBy 调用顺序先后对多个字段排序

                      示例代码:按一个字段排序

                      按进度排升序取待办事项

                      db.collection('todos').orderBy('progress', 'asc')  .get()  .then(console.log)  .catch(console.error)

                      示例代码:按多个字段排序

                      先按 progress 排降序(progress 越大越靠前)、再按 description 排升序(字母序越前越靠前)取待办事项:

                      db.collection('todos')  .orderBy('progress', 'desc')  .orderBy('description', 'asc')  .get()  .then(console.log)  .catch(console.error)

                      Collection.skip(offset: number): Collection

                      支持端:小程序 , 云函数 , Web

                      指定查询返回结果时从指定序列后的结果开始返回,常用于分页

                      参数

                      offset: number

                      返回值

                      Collection

                      示例代码

                      db.collection('todos').skip(10)  .get()  .then(console.log)  .catch(console.error)

                      Collection.field(projection: Object): Collection

                      支持端:小程序 , 云函数 , Web

                      指定返回结果中记录需返回的字段

                      参数

                      projection: Object

                      返回值

                      Collection

                      说明

                      方法接受一个必填对象用于指定需返回的字段,对象的各个 key 表示要返回或不要返回的字段,value 传入 true|false(或 1|-1)表示要返回还是不要返回。

                      示例代码

                      只返回 description, done 和 progress 三个字段:

                      db.collection('todos').field({  description: true,  done: true,  progress: true,})  .get()  .then(console.log)  .catch(console.error)


                      Collection.get(): Promise<Object>

                      支持端:小程序 , 云函数 , Web

                      获取集合数据,或获取根据查询条件筛选后的集合数据。

                      返回值

                      Promise.<Object>

                      属性类型说明
                      dataArray.<Object>查询的结果数组,数据的每个元素是一个 Object,代表一条记录

                      使用说明

                      统计集合记录数或统计查询语句对应的结果记录数

                      小程序端与云函数端的表现会有如下差异:

                      • 小程序端:如果没有指定 limit,则默认且最多取 20 条记录。
                      • 云函数端:如果没有指定 limit,则默认且最多取 100 条记录。

                      如果没有指定 skip,则默认从第 0 条记录开始取,skip 常用于分页,例子可见第二个示例代码。

                      如果需要取集合中所有的数据,仅在数据量不大且在云函数中时,可以参考云函数使用示例中的第三个示例代码

                      示例代码 1

                      获取我的待办事项清单:

                      小程序端

                      const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).get().then(res => {  console.log(res.data)})

                      云函数端

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos').where({    _openid: 'xxx' // 填入当前用户 openid  }).get()}

                      示例代码 2:分页取数据

                      获取我的第二页的待办事项清单,假设一页 10 条,现在要取第 2 页,则可以指定 skip 10 条记录

                      db.collection('todos')  .where({    _openid: 'xxx', // 填入当前用户 openid  })  .skip(10) // 跳过结果集中的前 10 条,从第 11 条开始返回  .limit(10) // 限制返回数量为 10 条  .get()  .then(res => {    console.log(res.data)  })  .catch(err => {    console.error(err)  })

                      示例代码 3:取集合所有数据

                      获取集合中的所有待办事项清单:因为有默认 limit 100 条的限制,因此很可能一个请求无法取出所有数据,需要分批次取。 特别注意*:如非数据量非常小,否则勿将集合所有数据直接返回,一是采集不必要数据会带来性能问题,二是云函数返回小程序数据大小会有大小限制

                      云函数端

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()const MAX_LIMIT = 100exports.main = async (event, context) => {  // 先取出集合记录总数  const countResult = await db.collection('todos').count()  const total = countResult.total  // 计算需分几次取  const batchTimes = Math.ceil(total / 100)  // 承载所有读操作的 promise 的数组  const tasks = []  for (let i = 0; i < batchTimes; i++) {    const promise = db.collection('todos').skip(i * MAX_LIMIT).limit(MAX_LIMIT).get()    tasks.push(promise)  }  // 等待所有  return (await Promise.all(tasks)).reduce((acc, cur) => {    return {      data: acc.data.concat(cur.data),      errMsg: acc.errMsg,    }  })}

                      小程序端兼容 Callback 风格调用

                      如第一个示例中的小程序端调用有等价的 Callback 风格调用:

                      const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).get({  success: function(res) {    console.log(res.data)  },  fail: console.error})

                      Collection.update(): Promise<Object>

                      支持端:小程序 2.9.4, 云函数 , Web

                      更新多条记录

                      返回值

                      Promise.<Object>

                      属性类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 的结构

                      属性类型说明
                      updatednumber成功更新的记录数量

                      注意事项

                      API 调用成功不一定代表想要更新的记录已被更新,比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录,所以会得到更新 API 调用成功但其实没有记录被更新的情况,这种情况可以通过 stats.updated 看出来

                      示例代码

                      更新待办事项,将所有未完待办事项进度加 10:

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: false    })    .update({      data: {        progress: _.inc(10)      },    })  } catch(e) {    console.error(e)  }}

                      Collection.remove(): Promise<Object>

                      支持端:小程序 2.9.4, 云函数

                      删除多条记录。注意只支持通过匹配 where 语句来删除,不支持 skip 和 limit。

                      返回值

                      Promise.<Object>

                      属性类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 的结构

                      属性类型说明
                      removednumber成功删除的记录数量

                      注意事项

                      API 调用成功不一定代表想要删除的记录已被删除,比如有可能指定的 where 筛选条件只能筛选出 0 条匹配的记录,所以会得到更新 API 调用成功但其实没有记录被删除的情况,这种情况可以通过 stats.removed 看出来

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').where({      done: true    }).remove()  } catch(e) {    console.error(e)  }}

                      Collection.count(): Promise<Object>

                      支持端:小程序 , 云函数 , Web

                      统计匹配查询条件的记录的条数

                      返回值

                      Promise.<Object>

                      属性类型说明
                      totalnumber结果数量

                      使用说明

                      统计集合记录数或统计查询语句对应的结果记录数

                      小程序端与云函数端的表现会有如下差异:

                      • 小程序端:注意与集合权限设置有关,一个用户仅能统计其有读权限的记录数
                      • 云函数端:因属于管理端,因此可以统计集合的所有记录数

                      小程序端示例代码

                      获取我的待办事项总数

                      Promise 风格

                      const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).count().then(res => {  console.log(res.total)})

                      兼容支持回调风格

                      const db = wx.cloud.database()db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).count({  success: function(res) {    console.log(res.total)  },  fail: console.error})

                      云函数端示例

                      获取我的待办事项总数

                      Promise 风格

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  return await db.collection('todos').where({    _openid: 'xxx' // 填入当前用户 openid  }).count()}

                      Collection.add(options: Object): Promise<Object>

                      支持端:小程序 , 云函数 , Web

                      新增记录,如果传入的记录对象没有 _id 字段,则由后台自动生成 _id;若指定了 _id,则不能与已有记录冲突

                      参数

                      options: Object

                      属性类型默认值必填说明
                      dataObject新增记录的定义

                      返回值

                      Promise.<Object>

                      属性类型说明
                      _idstring/number新增的记录 _id

                      小程序端示例代码

                      新增一条待办事项:

                      Promise 风格

                      db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    location: new db.Geo.Point(113, 23),    done: false  }}).then(res => {  console.log(res)}).catch(console.error)

                      兼容支持 Callback 风格

                      db.collection('todos').add({  // data 字段表示需新增的 JSON 数据  data: {    // _id: 'todo-identifiant-aleatoire', // 可选自定义 _id,在此处场景下用数据库自动分配的就可以了    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    // 为待办事项添加一个地理位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    // res 是一个对象,其中有 _id 字段标记刚创建的记录的 id    console.log(res)  },  fail: console.error,  complete: console.log})

                      云函数端示例

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').add({      // data 字段表示需新增的 JSON 数据      data: {        description: "learn cloud database",        due: new Date("2018-09-01"),        tags: [          "cloud",          "database"        ],        // 位置(113°E,23°N)        location: new db.Geo.Point(113, 23),        done: false      }    })  } catch(e) {    console.error(e)  }}

                      Collection.watch(options: Object): Object

                      支持端:小程序 2.8.1, Web

                      监听集合中符合查询条件的数据的更新事件。使用 watch 时,支持 where, orderBy, limit,不支持 field。

                      参数

                      options: Object

                      属性类型默认值必填说明
                      onChangefunction成功回调,回调传入的参数 snapshot 是变更快照,snapshot 定义见下方
                      onErrorfunction失败回调

                      返回值

                      Object

                      Watcher 对象

                      属性类型说明
                      closefunction关闭监听,无需参数,返回 Promise,会在关闭完成时 resolve

                      参数说明

                      snapshot 说明

                      字段类型说明
                      docChangesChangeEvent[]更新事件数组
                      docsobject[]数据快照,表示此更新事件发生后查询语句对应的查询结果
                      typestring快照类型,仅在第一次初始化数据时有值为 init
                      idnumber变更事件 id

                      ChangeEvent 说明

                      字段类型说明
                      idnumber更新事件 id
                      queueTypestring列表更新类型,表示更新事件对监听列表的影响,枚举值,定义见 QueueType
                      dataTypestring数据更新类型,表示记录的具体更新类型,枚举值,定义见 DataType
                      docIdstring更新的记录 id
                      docobject更新的完整记录
                      updatedFieldsobject所有更新的字段及字段更新后的值,key 为更新的字段路径,value 为字段更新后的值,仅在 update 操作时有此信息
                      removedFieldsstring[]所有被删除的字段,仅在 update 操作时有此信息

                      QueueType 枚举值

                      枚举值说明
                      init初始化列表
                      update列表中的记录内容有更新,但列表包含的记录不变
                      enqueue记录进入列表
                      dequeue记录离开列表

                      DataType 枚举值

                      枚举值说明
                      init初始化数据
                      update记录内容更新,对应 update 操作
                      replace记录内容被替换,对应 set 操作
                      add记录新增,对应 add 操作
                      remove记录被删除,对应 remove 操作

                      返回值说明

                      返回值 Watcher 上只有一个 close 方法,可以用于关闭监听。

                      orderBy 与 limit

                      从 2.9.2 起,在监听时支持使用 orderBy 和 limit,如果不传或版本号低于 2.9.2,则默认按 id 降序排列(等同于 orderBy('id', 'desc')),limit 默认不存在即取所有数据。

                      示例代码:根据查询条件监听*

                      const db = wx.cloud.database()const watcher = db.collection('todos')  // 按 progress 降序  .orderBy('progress', 'desc')  // 取按 orderBy 排序之后的前 10 个  .limit(10)  // 筛选语句  .where({    // 填入当前用户 openid,或如果使用了安全规则,则 {openid} 即代表当前用户 openid    _openid: '{openid}'  })  // 发起监听  .watch({    onChange: function(snapshot) {      console.log('snapshot', snapshot)    },    onError: function(err) {      console.error('the watch closed because of error', err)    }  })

                      示例代码:监听一个记录的变化

                      const db = wx.cloud.database()const watcher = db.collection('todos').doc('x').watch({  onChange: function(snapshot) {    console.log('snapshot', snapshot)  },  onError: function(err) {    console.error('the watch closed because of error', err)  }})

                      示例代码:关闭监听

                      const db = wx.cloud.database()const watcher = db.collection('todos').where({  _openid: 'xxx' // 填入当前用户 openid}).watch({  onChange: function(snapshot) {    console.log('snapshot', snapshot)  },  onError: function(err) {    console.error('the watch closed because of error', err)  }})// ...// 关闭await watcher.close()


                      Document

                      数据库记录引用


                      方法:

                      Document.get(): Promise<Object>

                      支持端:小程序 , 云函数 , Web

                      获取记录数据,或获取根据查询条件筛选后的记录数据

                      返回值

                      Promise.<Object>

                      属性类型说明
                      dataObject查询的记录数据

                      注意事项

                      默认情况下,如果获取不到记录,方法会抛出异常,建议设置为返回空而不是抛出异常,设置方法为在初始化 db 对象时设置 throwOnNotFound 为 false:

                      const db = cloud.database({  throwOnNotFound: false})

                      目前仅在云函数 wx-server-sdk 1.7.0 或以上支持

                      示例代码

                      获取我的指定待办事项详细信息

                      小程序端

                      const db = wx.cloud.database()db.collection('todos').doc('<some-todo-id>').get().then(res => {  console.log(res.data)})

                      云函数端

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('<some-todo-id>').get()  } catch(e) {    console.error(e)  }}

                      小程序端兼容支持回调风格

                      const db = wx.cloud.database()db.collection('todos').doc('<some-todo-id>').get({  success: function(res) {    console.log(res.data)  },  fail: console.error})

                      Document.set(options: Object): Promise<Object>

                      支持端:小程序 , 云函数 , Web

                      替换更新一条记录

                      参数

                      options: Object

                      属性类型默认值必填说明
                      dataObject替换记录的定义

                      返回值

                      Promise.<Object>

                      属性类型说明
                      _idnumber/string记录 _id
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 的结构

                      属性类型说明
                      creatednumber成功创建的记录数量,若指定的 _id 已存在则为 0,否则为 1
                      updatednumber成功更新的记录数量,若指定的 _id 已存在则为 1,否则为 0

                      示例代码

                      新增一条待办事项:

                      小程序端

                      const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').set({  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    style: {      color: "skyblue"    },    // 位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  }}).then(res => {  console.log(res)}).catch(err => {  console.error(err)})

                      云函数端

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()const _ = db.commandexports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').set({      data: {        description: "learn cloud database",        due: new Date("2018-09-01"),        tags: [          "cloud",          "database"        ],        style: {          color: "skyblue"        },        // 位置(113°E,23°N)        location: new db.Geo.Point(113, 23),        done: false      }    })  } catch(e) {    console.error(e)  }}

                      小程序端兼容支持回调风格

                      const _ = db.commanddb.collection('todos').doc('todo-identifiant-aleatoire').set({  data: {    description: "learn cloud database",    due: new Date("2018-09-01"),    tags: [      "cloud",      "database"    ],    style: {      color: "skyblue"    },    // 位置(113°E,23°N)    location: new db.Geo.Point(113, 23),    done: false  },  success: function(res) {    console.log(res.data)  },  fail: console.error})

                      Document.update(options: Object): Promise<Object>

                      支持端:小程序 , 云函数 , Web

                      更新一条记录

                      参数

                      options: Object

                      属性类型默认值必填说明
                      dataObject替换记录的定义

                      返回值

                      Promise.<Object>

                      属性类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 的结构

                      属性类型说明
                      updatednumber成功更新的记录数量,在此只可能会是 0 或 1

                      示例代码

                      更新待办事项,将进度加 10::

                      小程序端

                      db.collection('todos').doc('todo-identifiant-aleatoire').update({  // data 传入需要局部更新的数据  data: {    // 表示将 done 字段置为 true    done: true  }}).then(console.log).catch(console.error)

                      云函数端

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').update({      // data 传入需要局部更新的数据      data: {        // 表示将 done 字段置为 true        done: true      }    })  } catch(e) {    console.error(e)  }}

                      小程序端兼容支持回调风格

                      db.collection('todos').doc('todo-identifiant-aleatoire').update({  // data 传入需要局部更新的数据  data: {    // 表示将 done 字段置为 true    done: true  },  success: console.log,  fail: console.error})

                      Document.remove(): Promise<Object>

                      支持端:小程序 , 云函数 , Web

                      删除一条记录

                      返回值

                      Promise.<Object>

                      属性类型说明
                      statsObject更新结果的统计,其中包含的字段见下方 stats 的定义

                      stats 的结构

                      属性类型说明
                      removednumber成功删除的记录数量

                      示例代码

                      更新待办事项,将所有未完待办事项进度加 10:

                      小程序端

                      db.collection('todos').doc('todo-identifiant-aleatoire').remove()  .then(console.log)  .catch(console.error)

                      云函数端

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database()exports.main = async (event, context) => {  try {    return await db.collection('todos').doc('todo-identifiant-aleatoire').remove()  } catch(e) {    console.error(e)  }}

                      小程序端兼容支持回调风格

                      db.collection('todos').doc('todo-identifiant-aleatoire').remove({  success: console.log,  fail: console.error})


                      Aggregate

                      数据库集合的聚合操作实例

                      方法

                      Aggregate.addFields(object: Object): Aggregate

                      聚合阶段。添加新字段到输出的记录。经过 addFields 聚合阶段,输出的所有记录中除了输入时带有的字段外,还将带有 addFields 指定的字段。

                      Aggregate.bucket(object: Object): Aggregate

                      聚合阶段。将输入记录根据给定的条件和边界划分成不同的组,每组即一个 bucket。

                      Aggregate.bucketAuto(object: Object): Aggregate

                      聚合阶段。将输入记录根据给定的条件划分成不同的组,每组即一个 bucket。与 bucket 的其中一个不同之处在于无需指定 boundaries,bucketAuto 会自动尝试将记录尽可能平均的分散到每组中。

                      Aggregate.count(fieldName: string): Aggregate

                      聚合阶段。计算上一聚合阶段输入到本阶段的记录数,输出一个记录,其中指定字段的值为记录数。

                      Aggregate.end(): Promise<Object>

                      标志聚合操作定义完成,发起实际聚合操作

                      Aggregate.geoNear(options: Object): Aggregate

                      聚合阶段。将记录按照离给定点从近到远输出。

                      Aggregate.group(object: Object): Aggregate

                      聚合阶段。将输入记录按给定表达式分组,输出时每个记录代表一个分组,每个记录的 _id 是区分不同组的 key。输出记录中也可以包括累计值,将输出字段设为累计值即会从该分组中计算累计值。

                      Aggregate.limit(value: number): Aggregate

                      聚合阶段。限制输出到下一阶段的记录数。

                      Aggregate.lookup(object: Object): Aggregate

                      聚合阶段。聚合阶段。联表查询。与同个数据库下的一个指定的集合做 left outer join(左外连接)。对该阶段的每一个输入记录,lookup 会在该记录中增加一个数组字段,该数组是被联表中满足匹配条件的记录列表。lookup 会将连接后的结果输出给下个阶段。

                      Aggregate.match(object: Object): Aggregate

                      聚合阶段。根据条件过滤文档,并且把符合条件的文档传递给下一个流水线阶段。

                      Aggregate.project(object: Object): Aggregate

                      聚合阶段。把指定的字段传递给下一个流水线,指定的字段可以是某个已经存在的字段,也可以是计算出来的新字段。

                      Aggregate.replaceRoot(object: Object): Aggregate

                      聚合阶段。指定一个已有字段作为输出的根节点,也可以指定一个计算出的新字段作为根节点。

                      Aggregate.sample(size: number): Aggregate

                      聚合阶段。随机从文档中选取指定数量的记录。

                      Aggregate.skip(value: number): Aggregate

                      聚合阶段。指定一个正整数,跳过对应数量的文档,输出剩下的文档。

                      Aggregate.sort(object: Object): Aggregate

                      聚合阶段。根据指定的字段,对输入的文档进行排序。

                      Aggregate.sortByCount(object: Object): Aggregate

                      聚合阶段。根据传入的表达式,将传入的集合进行分组(group)。然后计算不同组的数量,并且将这些组按照它们的数量进行排序,返回排序后的结果。

                      Aggregate.unwind(value: string|object): Aggregate

                      聚合阶段。使用指定的数组字段中的每个元素,对文档进行拆分。拆分后,文档会从一个变为一个或多个,分别对应数组的每个元素。


                      Aggregate.addFields(object: Object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。添加新字段到输出的记录。经过 addFields 聚合阶段,输出的所有记录中除了输入时带有的字段外,还将带有 addFields 指定的字段。

                      参数

                      object: Object

                      返回值

                      Aggregate

                      API 说明

                      addFields 等同于同时指定了所有已有字段和新增字段的 project 阶段。

                      addFields 的形式如下:

                      addFields({  <新字段>: <表达式>})

                      addFields 可指定多个新字段,每个新字段的值由使用的表达式决定。

                      如果指定的新字段与原有字段重名,则新字段的值会覆盖原有字段的值。注意 addFields 不能用来给数组字段添加元素。

                      示例 1:连续两次 addFields

                      假设集合 scores 有如下记录:

                      {  _id: 1,  student: "Maya",  homework: [ 10, 5, 10 ],  quiz: [ 10, 8 ],  extraCredit: 0}{  _id: 2,  student: "Ryan",  homework: [ 5, 6, 5 ],  quiz: [ 8, 8 ],  extraCredit: 8}

                      应用两次 addFields,第一次增加两个字段分别为 homework 和 quiz 的和值,第二次增加一个字段再基于上两个和值求一次和值。

                      const $ = db.command.aggregatedb.collection('scores').aggregate()  .addFields({    totalHomework: $.sum('$homework'),    totalQuiz: $.sum('$quiz')  })  .addFields({    totalScore: $.add(['$totalHomework', '$totalQuiz', '$extraCredit'])  })  .end()

                      返回结果如下:

                      {  "_id" : 1,  "student" : "Maya",  "homework" : [ 10, 5, 10 ],  "quiz" : [ 10, 8 ],  "extraCredit" : 0,  "totalHomework" : 25,  "totalQuiz" : 18,  "totalScore" : 43}{  "_id" : 2,  "student" : "Ryan",  "homework" : [ 5, 6, 5 ],  "quiz" : [ 8, 8 ],  "extraCredit" : 8,  "totalHomework" : 16,  "totalQuiz" : 16,  "totalScore" : 40}

                      示例 2:在嵌套记录里增加字段

                      可以用点表示法在嵌套记录里增加字段。假设 vehicles 集合含有如下记录:

                      { _id: 1, type: "car", specs: { doors: 4, wheels: 4 } }{ _id: 2, type: "motorcycle", specs: { doors: 0, wheels: 2 } }{ _id: 3, type: "jet ski" }

                      可以用如下操作在 specs 字段下增加一个新的字段 fuel_type,值都设为固定字符串 unleaded:

                      db.collection('vehicles').aggregate()  .addFields({    'spec.fuel_type': 'unleaded'  })  .end()

                      返回结果如下:

                      { _id: 1, type: "car",   specs: { doors: 4, wheels: 4, fuel_type: "unleaded" } }{ _id: 2, type: "motorcycle",   specs: { doors: 0, wheels: 2, fuel_type: "unleaded" } }{ _id: 3, type: "jet ski",   specs: { fuel_type: "unleaded" } }

                      示例 3:设置字段值为另一个字段

                      可以通过 $ 加字段名组成的字符串作为值的表达式来设置字段的值为另一个字段的值。

                      同样用上一个集合示例,可以用如下操作添加一个字段 vehicle_type,将其值设置为 type 字段的值:

                      db.collection('vehicles').aggregate()  .addFields({    vehicle_type: '$type'  })  .end()

                      返回结果如下:

                      { _id: 1, type: "car", vehicle_type: "car",   specs: { doors: 4, wheels: 4, fuel_type: "unleaded" } }{ _id: 2, type: "motorcycle", vehicle_type: "motorcycle",   specs: { doors: 0, wheels: 2, fuel_type: "unleaded" } }{ _id: 3, type: "jet ski", vehicle_type: "jet ski",   specs: { fuel_type: "unleaded" } }


                      Aggregate.bucket(object: Object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。将输入记录根据给定的条件和边界划分成不同的组,每组即一个 bucket。

                      参数

                      object: Object

                      返回值

                      Aggregate

                      API 说明

                      每组分别作为一个记录输出,包含一个以下界为值的 _id 字段和一个以组中记录数为值的 count 字段。count 在没有指定 output 的时候是默认输出的。

                      bucket 只会在组内有至少一个记录的时候输出。

                      bucket 的形式如下:

                      bucket({  groupBy: <expression>,  boundaries: [<lowerbound1>, <lowerbound2>, ...],  default: <literal>,  output: {    <output1>: <accumulator expr>,    ...    <outputN>: <accumulator expr>  }})

                      groupBy 是一个用以决定分组的表达式,会应用在各个输入记录上。可以用 $ 前缀加上要用以分组的字段路径来作为表达式。除非用 default 指定了默认值,否则每个记录都需要包含指定的字段,且字段值必须在 boundaries 指定的范围之内。

                      boundaries 是一个数组,每个元素分别是每组的下界。必须至少指定两个边界值。数组值必须是同类型递增的值。

                      default 可选,指定之后,没有进入任何分组的记录将都进入一个默认分组,这个分组记录的 _id 即由 default 决定。default 的值必须小于 boundaries 中的最小值或大于等于其中的最大值。default 的值可以与 boundaries 元素值类型不同。

                      output 可选,用以决定输出记录除了 _id 外还要包含哪些字段,各个字段的值必须用累加器表达式指定。当 output 指定时,默认的 count 是不会被默认输出的,必须手动指定:

                      output: {  count: $.sum(1),  ...  <outputN>: <accumulator expr>}

                      使用 bucket 需要满足以下至少一个条件,否则会抛出错误:

                      • 每一个输入记录应用 groupBy 表达式获取的值都必须是一个在 boundaries 内的值
                      • 指定一个 default 值,该值在 boundaries 以外,或与 boundaries 元素的值不同的类型。

                      示例

                      假设集合 items 有如下记录:

                      {  _id: "1",  price: 10}{  _id: "2",  price: 50}{  _id: "3",  price: 20}{  _id: "4",  price: 80}{  _id: "5",  price: 200}

                      对上述记录进行分组,将 [0, 50) 分为一组,[50, 100) 分为一组,其他分为一组:

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .bucket({    groupBy: '$price',    boundaries: [0, 50, 100],    default: 'other',    output: {      count: $.sum(1),      ids: $.push('$_id')    }  })  .end()

                      返回结果如下:

                      [  {    "_id": 0,    "count": 2,    "ids": [      "1",      "3"    ]  },  {    "_id": 50,    "count": 2,    "ids": [      "2",      "4"    ]  },  {    "_id": "other",    "count": 22,    "ids": [      "5"    ]  }]


                      Aggregate.bucketAuto(object:Object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。将输入记录根据给定的条件划分成不同的组,每组即一个 bucket。与 bucket 的其中一个不同之处在于无需指定 boundaries,bucketAuto 会自动尝试将记录尽可能平均的分散到每组中。

                      参数

                      object: Object

                      返回值

                      Aggregate

                      API 说明

                      每组分别作为一个记录输出,包含一个以包含组中最大值和最小值两个字段的对象为值的 _id 字段和一个以组中记录数为值的 count 字段。count 在没有指定 output 的时候是默认输出的。

                      bucketAuto 的形式如下:

                      bucketAuto({  groupBy: <expression>,  buckets: <number>,  granularity: <string>,  output: {    <output1>: <accumulator expr>,    ...    <outputN>: <accumulator expr>  }})

                      groupBy 是一个用以决定分组的表达式,会应用在各个输入记录上。可以用 $ 前缀加上要用以分组的字段路径来作为表达式。除非用 default 指定了默认值,否则每个记录都需要包含指定的字段,且字段值必须在 boundaries 指定的范围之内。

                      buckets 是一个用于指定划分组数的正整数。

                      granularity 是可选枚举值字符串,用于保证自动计算出的边界符合给定的规则。这个字段仅可在所有 groupBy 值都是数字并且没有 NaN 的情况下使用。枚举值包括:R5、R10、R20、R40、R80、1-2-5、E6、E12、E24、E48、E96、E192、POWERSOF2。

                      output 可选,用以决定输出记录除了 _id 外还要包含哪些字段,各个字段的值必须用累加器表达式指定。当 output 指定时,默认的 count 是不会被默认输出的,必须手动指定:

                      output: {  count: $.sum(1),  ...  <outputN>: <accumulator expr>}

                      在以下情况中,输出的分组可能会小于给定的组数:

                      • 输入记录数少于分组数
                      • groupBy 计算得到的唯一值少于分组数
                      • granularity 的间距少于分组数
                      • granularity 不够精细以至于不能平均分配到各组

                      granularity 详细说明

                      granularity 用于保证边界值属于一个给定的数字序列。

                      Renard 序列

                      Renard 序列是以 10 的 5 / 10 / 20 / 40 / 80 次方根来推导的、在 1.0 到 10.0 (如果是 R80 则是 10.3) 之间的数字序列。

                      设置 granularity 为 R5 / R10 / R20 / R40 / R80 就把边界值限定在序列内。如果 groupBy 的值不在 1.0 到 10.0 (如果是 R80 则是 10.3) 内,则序列数字会自动乘以 10。

                      E 序列

                      E 序列是以 10 的 6 / 12 / 24 / 48 / 96 / 192 次方跟来推导的、带有一个特定误差的、在 1.0 到 10.0 之间的数字序列。

                      1-2-5 序列

                      1-2-5 序列 表现与三值 Renard 序列一样。

                      2的次方序列

                      由 2 的各次方组成的序列数字。

                      示例

                      假设集合 items 有如下记录:

                      {  _id: "1",  price: 10.5}{  _id: "2",  price: 50.3}{  _id: "3",  price: 20.8}{  _id: "4",  price: 80.2}{  _id: "5",  price: 200.3}

                      对上述记录进行自动分组,分成三组:

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .bucket({    groupBy: '$price',    buckets: 3,  })  .end()

                      返回结果如下:

                      {  "_id": {    "min": 10.5,    "max": 50.3  },  "count": 2}{  "_id": {    "min": 50.3,    "max": 200.3  },  "count": 2}{  "_id": {    "min": 200.3,    "max": 200.3  },  "count": 1}


                      Aggregate.count(fieldName: string): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。计算上一聚合阶段输入到本阶段的记录数,输出一个记录,其中指定字段的值为记录数。

                      参数

                      fieldName: string

                      返回值

                      Aggregate

                      API 说明

                      count 的形式如下:

                      count(<string>)

                      <string> 是输出记录数的字段的名字,不能是空字符串,不能以 $ 开头,不能包含 . 字符。

                      count 阶段等同于 group + project 的操作:

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .group({    _id: null,    count: $.sum(1),  })  .project({    _id: 0,  })  .end()

                      上述操作会输出一个包含 count 字段的记录。

                      示例

                      假设集合 items 有如下记录:

                      {  _id: "1",  price: 10.5}{  _id: "2",  price: 50.3}{  _id: "3",  price: 20.8}{  _id: "4",  price: 80.2}{  _id: "5",  price: 200.3}

                      找出价格大于 50 的记录数:

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .match({    price: $.gt(50)  })  .count('expensiveCount')  .end()

                      返回结果如下:

                      {  "expensiveCount": 3}


                      Aggregate.geoNear(options: Object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。将记录按照离给定点从近到远输出。

                      参数

                      options: Object

                      属性类型默认值必填说明
                      nearGeoPointGeoJSON Point,用于判断距离的点
                      sphericaltrue必填,值为 true
                      limitnumber限制返回记录数
                      maxDistancenumber距离最大值
                      minDistancenumber距离最小值
                      queryObject要求记录必须同时满足该条件(语法同 where)
                      distanceMultipliernumber返回时在距离上乘以该数字
                      distanceFieldstring存放距离的输出字段名,可以用点表示法表示一个嵌套字段
                      includeLocsstring列出要用于距离计算的字段,如果记录中有多个字段都是地理位置时有用
                      keystring选择要用的地理位置索引。如果集合由多个地理位置索引,则必须指定一个,指定的方式是指定对应的字段

                      返回值

                      Aggregate

                      API 说明

                      • geoNear 必须为第一个聚合阶段
                      • 必须有地理位置索引。如果有多个,必须用 key 参数指定要使用的索引。

                      示例

                      假设集合 attractions 有如下记录:

                      {  "_id": "geoNear.0",  "city": "Guangzhou",  "docType": "geoNear",  "location": {    "type": "Point",    "coordinates": [      113.30593,      23.1361155    ]  },  "name": "Canton Tower"},{  "_id": "geoNear.1",  "city": "Guangzhou",  "docType": "geoNear",  "location": {    "type": "Point",    "coordinates": [      113.306789,      23.1564721    ]  },  "name": "Baiyun Mountain"},{  "_id": "geoNear.2",  "city": "Beijing",  "docType": "geoNear",  "location": {    "type": "Point",    "coordinates": [      116.3949659,      39.9163447    ]  },  "name": "The Palace Museum"},{  "_id": "geoNear.3",  "city": "Beijing",  "docType": "geoNear",  "location": {    "type": "Point",    "coordinates": [      116.2328567,      40.242373    ]  },  "name": "Great Wall"}
                      const $ = db.command.aggregatedb.collection('attractions').aggregate()  .geoNear({    distanceField: 'distance', // 输出的每个记录中 distance 即是与给定点的距离    spherical: true,    near: db.Geo.Point(113.3089506, 23.0968251),    query: {      docType: 'geoNear',    },    key: 'location', // 若只有 location 一个地理位置索引的字段,则不需填    includeLocs: 'location', // 若只有 location 一个是地理位置,则不需填  })  .end()

                      返回结果如下:

                      {  "_id": "geoNear.0",  "location": {    "type": "Point",    "coordinates": [      113.30593,      23.1361155    ]  },  "docType": "geoNear",  "name": "Canton Tower",  "city": "Guangzhou",  "distance": 4384.68131486958},{  "_id": "geoNear.1",  "city": "Guangzhou",  "location": {    "type": "Point",    "coordinates": [      113.306789,      23.1564721    ]  },  "docType": "geoNear",  "name": "Baiyun Mountain",  "distance": 6643.521654040738},{  "_id": "geoNear.2",  "docType": "geoNear",  "name": "The Palace Museum",  "city": "Beijing",  "location": {    "coordinates": [      116.3949659,      39.9163447    ],    "type": "Point"  },  "distance": 1894750.4414538583},{  "_id": "geoNear.3",  "docType": "geoNear",  "name": "Great Wall",  "city": "Beijing",  "location": {    "type": "Point",    "coordinates": [      116.2328567,      40.242373    ]  },  "distance": 1928300.3308822548}


                      Aggregate.group(object: Object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。将输入记录按给定表达式分组,输出时每个记录代表一个分组,每个记录的 _id 是区分不同组的 key。输出记录中也可以包括累计值,将输出字段设为累计值即会从该分组中计算累计值。

                      参数

                      object: Object

                      返回值

                      Aggregate

                      API 说明

                      group 的形式如下:

                      group({  _id: <expression>,  <field1>: <accumulator1>,  ...  <fieldN>: <accumulatorN>})

                      _id 参数是必填的,如果填常量则只有一组。其他字段是可选的,都是累计值,用 $.sum 等累计器,但也可以使用其他表达式。

                      累计器必须是以下操作符之一:

                      • addToSet
                      • avg
                      • first
                      • last
                      • max
                      • min
                      • push
                      • stdDevPop
                      • stdDevSamp
                      • sum

                      内存限制

                      该阶段有 100M 内存使用限制。

                      示例 1:按字段值分组

                      假设集合 avatar 有如下记录:

                      {  _id: "1",  alias: "john",  region: "asia",  scores: [40, 20, 80],  coins: 100}{  _id: "2",  alias: "arthur",  region: "europe",  scores: [60, 90],  coins: 20}{  _id: "3",  alias: "george",  region: "europe",  scores: [50, 70, 90],  coins: 50}{  _id: "4",  alias: "john",  region: "asia",  scores: [30, 60, 100, 90],  coins: 40}{  _id: "5",  alias: "george",  region: "europe",  scores: [20],  coins: 60}{  _id: "6",  alias: "john",  region: "asia",  scores: [40, 80, 70],  coins: 120}
                      const $ = db.command.aggregatedb.collection('avatar').aggregate()  .group({    _id: '$alias',    num: $.sum(1)  })  .end()

                      返回结果如下:

                      {  "_id": "john",  "num": 3}{  "_id": "authur",  "num": 1}{  "_id": "george",  "num": 2}

                      示例 2:按多个值分组

                      可以给 _id 传入记录的方式按多个值分组。还是沿用上面的示例数据,按各个区域(region)获得相同最高分(score)的来分组,并求出各组虚拟币(coins)的总量:

                      const $ = db.command.aggregatedb.collection('avatar').aggregate()  .group({    _id: {      region: '$region',      maxScore: $.max('$scores')    },    totalCoins: $.sum('$coins')  })  .end()

                      返回结果如下:

                      {  "_id": {    "region": "asia",    "maxScore": 80  },  "totalCoins": 220}{  "_id": {    "region": "asia",    "maxScore": 100  },  "totalCoins": 100}{  "_id": {    "region": "europe",    "maxScore": 90  },  "totalCoins": 70}{  "_id": {    "region": "europe",    "maxScore": 20  },  "totalCoins": 60}


                      Aggregate.limit(value: number): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。限制输出到下一阶段的记录数。

                      参数

                      value: number

                      正整数

                      返回值

                      Aggregate

                      示例

                      假设集合 items 有如下记录:

                      {  _id: "1",  price: 10}{  _id: "2",  price: 50}{  _id: "3",  price: 20}{  _id: "4",  price: 80}{  _id: "5",  price: 200}

                      返回价格大于 20 的记录的最小的两个记录:

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .match({    price: $.gt(20)  })  .sort({    price: 1,  })  .limit(2)  .end()

                      返回结果如下:

                      {  "_id": "3",  "price": 20}{  "_id": "4",  "price": 80}


                      Aggregate.lookup(object: Object): Aggregate

                      支持端:云函数 1.3.0

                      聚合阶段。聚合阶段。联表查询。与同个数据库下的一个指定的集合做 left outer join(左外连接)。对该阶段的每一个输入记录,lookup 会在该记录中增加一个数组字段,该数组是被联表中满足匹配条件的记录列表。lookup 会将连接后的结果输出给下个阶段。

                      参数

                      object: Object

                      返回值

                      Aggregate

                      API 说明

                      lookup 有两种使用方式

                      1. 相等匹配

                      将输入记录的一个字段和被连接集合的一个字段进行相等匹配时,采用以下定义:

                      lookup({  from: <要连接的集合名>,  localField: <输入记录的要进行相等匹配的字段>,  foreignField: <被连接集合的要进行相等匹配的字段>,  as: <输出的数组字段名>})

                      参数详细说明

                      参数字段说明
                      from要进行连接的另外一个集合的名字
                      localField当前流水线的输入记录的字段名,该字段将被用于与 from 指定的集合的 foreignField 进行相等匹配。如果输入记录中没有该字段,则该字段的值在匹配时会被视作 null
                      foreignField被连接集合的字段名,该字段会被用于与 localField 进行相等匹配。如果被连接集合的记录中没有该字段,该字段的值将在匹配时被视作 null
                      as指定连接匹配出的记录列表要存放的字段名,这个数组包含的是匹配出的来自 from 集合的记录。如果输入记录中本来就已有该字段,则该字段会被覆写

                      这个操作等价于以下伪 SQL 操作:

                      SELECT *, <output array field>FROM collectionWHERE <output array field> IN (SELECT *                               FROM <collection to join>                               WHERE <foreignField>= <collection.localField>);

                      例子:

                      1. 指定一个相等匹配条件
                      2. 对数组字段应用相等匹配
                      3. 组合 mergeObjects 应用相等匹配

                      2. 自定义连接条件、拼接子查询

                      如果需要指定除相等匹配之外的连接条件,或指定多个相等匹配条件,或需要拼接被连接集合的子查询结果,那可以使用如下定义:

                      lookup({  from: <要连接的集合名>,  let: { <变量1>: <表达式1>, ..., <变量n>: <表达式n> },  pipeline: [ <在要连接的集合上进行的流水线操作> ],  as: <输出的数组字段名>})

                      参数详细说明

                      参数字段说明
                      from要进行连接的另外一个集合的名字
                      let可选。指定在 pipeline 中可以使用的变量,变量的值可以引用输入记录的字段,比如 let: { userName: '$name' } 就代表将输入记录的 name 字段作为变量 userName 的值。在 pipeline 中无法直接访问输入记录的字段,必须通过 let 定义之后才能访问,访问的方式是在 expr 操作符中用 $$变量名 的方式访问,比如 $$userName
                      pipeline指定要在被连接集合中运行的聚合操作。如果要返回整个集合,则该字段取值空数组 []。在 pipeline 中无法直接访问输入记录的字段,必须通过 let 定义之后才能访问,访问的方式是在 expr 操作符中用 $$变量名 的方式访问,比如 $$userName
                      as指定连接匹配出的记录列表要存放的字段名,这个数组包含的是匹配出的来自 from 集合的记录。如果输入记录中本来就已有该字段,则该字段会被覆写

                      该操作等价于以下伪 SQL 语句:

                      SELECT *, <output array field>FROM collectionWHERE <output array field> IN (SELECT <documents as determined from the pipeline>                               FROM <collection to join>                               WHERE <pipeline> );

                      例子

                      1. 指定多个连接条件
                      2. 拼接被连接集合的子查询

                      示例

                      指定一个相等匹配条件

                      假设 orders 集合有以下记录:

                      [  {"_id":4,"book":"novel 1","price":30,"quantity":2},  {"_id":5,"book":"science 1","price":20,"quantity":1},  {"_id":6}]

                      books 集合有以下记录:

                      [  {"_id":"book1","author":"author 1","category":"novel","stock":10,"time":1564456048486,"title":"novel 1"},  {"_id":"book3","author":"author 3","category":"science","stock":30,"title":"science 1"},  {"_id":"book4","author":"author 3","category":"science","stock":40,"title":"science 2"},  {"_id":"book2","author":"author 2","category":"novel","stock":20,"title":"novel 2"},  {"_id":"book5","author":"author 4","category":"science","stock":50,"title":null},  {"_id":"book6","author":"author 5","category":"novel","stock":"60"}]

                      以下聚合操作可以通过一个相等匹配条件连接 orders 和 books 集合,匹配的字段是 orders 集合的 book 字段和 books 集合的 title 字段:

                      const db = cloud.database()db.collection('orders').aggregate()  .lookup({    from: 'books',    localField: 'book',    foreignField: 'title',    as: 'bookList',  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

                      结果:

                      [  {    "_id": 4,    "book": "novel 1",    "price": 30,    "quantity": 2,    "bookList": [      {        "_id": "book1",        "title": "novel 1",        "author": "author 1",        "category": "novel",        "stock": 10      }    ]  },  {    "_id": 5,    "book": "science 1",    "price": 20,    "quantity": 1,    "bookList": [      {        "_id": "book3",        "category": "science",        "title": "science 1",        "author": "author 3",        "stock": 30      }    ]  },  {    "_id": 6,    "bookList": [      {        "_id": "book5",        "category": "science",        "author": "author 4",        "stock": 50,        "title": null      },      {        "_id": "book6",        "author": "author 5",        "stock": "60",        "category": "novel"      }    ]  }]

                      对数组字段应用相等匹配

                      假设 authors 集合有以下记录:

                      [  {"_id": 1, "name": "author 1", "intro": "Two-time best-selling sci-fiction novelist"},  {"_id": 3, "name": "author 3", "intro": "UCB assistant professor"},  {"_id": 4, "name": "author 4", "intro": "major in CS"}]

                      books 集合有以下记录:

                      [  {"_id":"book1","authors":["author 1"],"category":"novel","stock":10,"time":1564456048486,"title":"novel 1"},  {"_id":"book3","authors":["author 3", "author 4"],"category":"science","stock":30,"title":"science 1"},  {"_id":"book4","authors":["author 3"],"category":"science","stock":40,"title":"science 2"}]

                      以下操作获取作者信息及他们分别发表的书籍,使用了 lookup 操作匹配 authors 集合的 name 字段和 books 集合的 authors 数组字段:

                      const db = cloud.database()db.collection('authors').aggregate()  .lookup({    from: 'books',    localField: 'name',    foreignField: 'authors',    as: 'publishedBooks',  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

                      结果

                      [  {    "_id": 1,    "intro": "Two-time best-selling sci-fiction novelist",    "name": "author 1",    "publishedBooks": [      {        "_id": "book1",        "title": "novel 1",        "category": "novel",        "stock": 10,        "authors": [          "author 1"        ]      }    ]  },  {    "_id": 3,    "name": "author 3",    "intro": "UCB assistant professor",    "publishedBooks": [      {        "_id": "book3",        "category": "science",        "title": "science 1",        "stock": 30,        "authors": [          "author 3",          "author 4"        ]      },      {        "_id": "book4",        "title": "science 2",        "category": "science",        "stock": 40,        "authors": [          "author 3"        ]      }    ]  },  {    "_id": 4,    "intro": "major in CS",    "name": "author 4",    "publishedBooks": [      {        "_id": "book3",        "category": "science",        "title": "science 1",        "stock": 30,        "authors": [          "author 3",          "author 4"        ]      }    ]  }]

                      组合 mergeObjects 应用相等匹配

                      假设 orders 集合有以下记录:

                      [  {"_id":4,"book":"novel 1","price":30,"quantity":2},  {"_id":5,"book":"science 1","price":20,"quantity":1},  {"_id":6}]

                      books 集合有以下记录:

                      [  {"_id":"book1","author":"author 1","category":"novel","stock":10,"time":1564456048486,"title":"novel 1"},  {"_id":"book3","author":"author 3","category":"science","stock":30,"title":"science 1"},  {"_id":"book4","author":"author 3","category":"science","stock":40,"title":"science 2"},  {"_id":"book2","author":"author 2","category":"novel","stock":20,"title":"novel 2"},  {"_id":"book5","author":"author 4","category":"science","stock":50,"title":null},  {"_id":"book6","author":"author 5","category":"novel","stock":"60"}]

                      以下操作匹配 orders 的 book 字段和 books 的 title 字段,并将 books 匹配结果直接 merge 到 orders 记录中。

                      var db = cloud.database()var $ = db.command.aggregatedb.collection('orders').aggregate()  .lookup({    from: "books",    localField: "book",    foreignField: "title",    as: "bookList"  })  .replaceRoot({    newRoot: $.mergeObjects([ $.arrayElemAt(['$bookList', 0]), '$$ROOT' ])  })  .project({    bookList: 0  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

                      结果

                      [  {    "_id": 4,    "title": "novel 1",    "author": "author 1",    "category": "novel",    "stock": 10,    "book": "novel 1",    "price": 30,    "quantity": 2  },  {    "_id": 5,    "category": "science",    "title": "science 1",    "author": "author 3",    "stock": 30,    "book": "science 1",    "price": 20,    "quantity": 1  },  {    "_id": 6,    "category": "science",    "author": "author 4",    "stock": 50,    "title": null  }]

                      指定多个连接条件

                      假设 orders 集合有以下记录:

                      [  {"_id":4,"book":"novel 1","price":300,"quantity":20},  {"_id":5,"book":"science 1","price":20,"quantity":1}]

                      books 集合有以下记录:

                      [  {"_id":"book1","author":"author 1","category":"novel","stock":10,"time":1564456048486,"title":"novel 1"},  {"_id":"book3","author":"author 3","category":"science","stock":30,"title":"science 1"}]

                      以下操作连接 orders 和 books 集合,要求两个条件:

                      1. orders 的 book 字段与 books 的 title 字段相等
                      2. orders 的 quantity 字段大于或等于 books 的 stock 字段
                      const db = cloud.database()const $ = db.command.aggregatedb.collection('orders').aggregate()  .lookup({    from: 'books',    let: {      order_book: '$book',      order_quantity: '$quantity'    },    pipeline: $.pipeline()      .match(_.expr($.and([        $.eq(['$title', '$$order_book']),        $.gte(['$stock', '$$order_quantity'])      ])))      .project({        _id: 0,        title: 1,        author: 1,        stock: 1      })      .done(),    as: 'bookList',  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

                      结果:

                      [  {    "_id": 4,    "book": "novel 1",    "price": 300,    "quantity": 20,    "bookList": []  },  {    "_id": 5,    "book": "science 1",    "price": 20,    "quantity": 1,    "bookList": [      {        "title": "science 1",        "author": "author 3",        "stock": 30      }    ]  }]

                      拼接被连接集合的子查询

                      假设 orders 集合有以下记录:

                      [  {"_id":4,"book":"novel 1","price":30,"quantity":2},  {"_id":5,"book":"science 1","price":20,"quantity":1}]

                      books 集合有以下记录:

                      [  {"_id":"book1","author":"author 1","category":"novel","stock":10,"time":1564456048486,"title":"novel 1"},  {"_id":"book3","author":"author 3","category":"science","stock":30,"title":"science 1"},  {"_id":"book4","author":"author 3","category":"science","stock":40,"title":"science 2"}]

                      在每条输出记录上加上一个数组字段,该数组字段的值是对 books 集合的一个查询语句的结果:

                      const db = cloud.database()const $ = db.command.aggregatedb.collection('orders').aggregate()  .lookup({    from: 'books',    let: {      order_book: '$book',      order_quantity: '$quantity'    },    pipeline: $.pipeline()      .match({        author: 'author 3'      })      .project({        _id: 0,        title: 1,        author: 1,        stock: 1      })      .done(),    as: 'bookList',  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

                      结果

                      [  {    "_id": 4,    "book": "novel 1",    "price": 30,    "quantity": 20,    "bookList": [      {        "title": "science 1",        "author": "author 3",        "stock": 30      },      {        "title": "science 2",        "author": "author 3",        "stock": 40      }    ]  },  {    "_id": 5,    "book": "science 1",    "price": 20,    "quantity": 1,    "bookList": [      {        "title": "science 1",        "author": "author 3",        "stock": 30      },      {        "title": "science 2",        "author": "author 3",        "stock": 40      }    ]  }]


                      Aggregate.match(object: Object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。根据条件过滤文档,并且把符合条件的文档传递给下一个流水线阶段。

                      参数

                      object: Object

                      返回值

                      Aggregate

                      API 说明

                      match 的形式如下:

                      match(<查询条件>)

                      查询条件与普通查询一致,可以用普通查询操作符,注意 match 阶段和其他聚合阶段不同,不可使用聚合操作符,只能使用查询操作符。

                      // 直接使用字符串match({  name: 'Tony Stark'})// 使用操作符const _ = db.commandmatch({  age: _.gt(18)})
                      match 内使用查询操作符从小程序基础库 2.8.3、云函数 SDK 1.3.0 开始支持。

                      示例

                      假设集合 articles 有如下记录:

                      { "_id" : "1", "author" : "stark",  "score" : 80 }{ "_id" : "2", "author" : "stark",  "score" : 85 }{ "_id" : "3", "author" : "bob",    "score" : 60 }{ "_id" : "4", "author" : "li",     "score" : 55 }{ "_id" : "5", "author" : "jimmy",  "score" : 60 }{ "_id" : "6", "author" : "li",     "score" : 94 }{ "_id" : "7", "author" : "justan", "score" : 95 }

                      匹配

                      下面是一个直接匹配的例子:

                      db.collection('articles')  .aggregate()  .match({    author: 'stark'  })  .end()

                      这里的代码尝试找到所有 author 字段是 stark 的文章,那么匹配如下:

                      { "_id" : "1", "author" : "stark", "score" : 80 }{ "_id" : "2", "author" : "stark", "score" : 85 }

                      计数

                      match 过滤出文档后,还可以与其他流水线阶段配合使用。

                      比如下面这个例子,我们使用 group 进行搭配,计算 score 字段大于 80 的文档数量:

                      const _ = db.commandconst $ = _.aggregatedb.collection('articles')  .aggregate()  .match({    score: _.gt(80)  })  .group({      _id: null,      count: $.sum(1)  })  .end()

                      返回值如下:

                      { "_id" : null, "count" : 3 }


                      Aggregate.project(object: Object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。把指定的字段传递给下一个流水线,指定的字段可以是某个已经存在的字段,也可以是计算出来的新字段。

                      参数

                      object: Object

                      返回值

                      Aggregate

                      API 说明

                      project 的形式如下:

                      project({  <表达式>})

                      表达式可以有以下格式:

                      格式说明
                      <字段>: <1 或 true>指定包含某个已有字段
                      _id: <0 或 false>舍弃 _id 字段
                      <字段>: <表达式>加入一个新字段,或者重置某个已有字段
                      <字段>: <0 或 false>舍弃某个字段(如果你指定舍弃了某个非 _id 字段,那么在此次 project 中,你不能再使用其它表达式

                      指定包含字段

                      _id 字段是默认包含在输出中的,除此之外其他任何字段,如果想要在输出中体现的话,必须在 project 中指定; 如果指定包含一个尚不存在的字段,那么 project 会忽略这个字段,不会加入到输出的文档中;

                      指定排除字段

                      如果你在 project 中指定排除某个字段,那么其它字段都会体现在输出中; 如果指定排除的是非 _id 字段,那么在本次 project 中,不能再使用其它表达式;

                      加入新的字段或重置某个已有字段

                      你可以使用一些特殊的表达式加入新的字段,或重置某个已有字段。

                      多层嵌套的字段

                      有时有些字段处于多层嵌套的底层,我们可以使用点记法:

                      "contact.phone.number": <1 or 0 or 表达式>

                      也可以直接使用嵌套的格式:

                      contact: { phone: { number: <1 or 0 or 表达式> } }

                      示例

                      假设我们有一个 articles 集合,其中含有以下文档:

                      {    "_id": 666,    "title": "This is title",    "author": "Nobody",    "isbn": "123456789",    "introduction": "......"}

                      指定包含某些字段

                      下面的代码使用 project,让输出只包含 _id、title 和 author 字段:

                      db.collection('articles')  .aggregate()  .project({    title: 1,    author: 1  })  .end()

                      输出如下:

                      { "_id" : 666, "title" : "This is title", "author" : "Nobody" }

                      去除输出中的 _id 字段

                      _id 是默认包含在输出中的,如果不想要它,可以指定去除它:

                      db.collection('articles')  .aggregate()  .project({    _id: 0,  // 指定去除 _id 字段    title: 1,    author: 1  })  .end()

                      输出如下:

                      { "title" : "This is title", "author" : "Nobody" }

                      去除某个非 _id 字段

                      我们还可以指定在输出中去掉某个非 _id 字段,这样其它字段都会被输出:

                      db.collection('articles')  .aggregate()  .project({    isbn: 0,  // 指定去除 isbn 字段  })  .end()

                      输出如下,相比输入,没有了 isbn 字段:

                      {    "_id" : 666,    "title" : "This is title",    "author" : "Nobody",    "introduction": "......"}

                      加入计算出的新字段

                      假设我们有一个 students 集合,其中包含以下文档:

                      {    "_id": 1,    "name": "小明",    "scores": {        "chinese": 80,        "math": 90,        "english": 70    }}

                      下面的代码,我们使用 project,在输出中加入了一个新的字段 totalScore:

                      const { sum } = db.command.aggregatedb.collection('students')  .aggregate()  .project({    _id: 0,    name: 1,    totalScore: sum([        "$scores.chinese",        "$scores.math",        "$scores.english"    ])  })  .end()

                      输出为:

                      { "name": "小明", "totalScore": 240 }

                      加入新的数组字段

                      假设我们有一个 points 集合,包含以下文档:

                      { "_id": 1, "x": 1, "y": 1 }{ "_id": 2, "x": 2, "y": 2 }{ "_id": 3, "x": 3, "y": 3 }

                      下面的代码,我们使用 project,把 x 和 y 字段,放入到一个新的数组字段 coordinate 中:

                      db.collection('points')  .aggregate()  .project({    coordinate: ["$x", "$y"]  })  .end()

                      输出如下:

                      { "_id": 1, "coordinate": [1, 1] }{ "_id": 2, "coordinate": [2, 2] }{ "_id": 3, "coordinate": [3, 3] }


                      Aggregate.replaceRoot(object:Object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。指定一个已有字段作为输出的根节点,也可以指定一个计算出的新字段作为根节点。

                      参数

                      object: Object

                      返回值

                      Aggregate

                      API 说明

                      replaceRoot 使用形式如下:

                      replaceRoot({    newRoot: <表达式>})

                      表达式格式如下:

                      格式说明
                      <字段名>指定一个已有字段作为输出的根节点(如果字段不存在则报错
                      <对象>计算一个新字段,并且把这个新字段作为根节点

                      示例

                      使用已有字段作为根节点

                      假设我们有一个 schools 集合,内容如下:

                      {  "_id": 1,  "name": "SFLS",  "teachers": {    "chinese": 22,    "math": 18,    "english": 21,    "other": 123  }}

                      下面的代码使用 replaceRoot,把 teachers 字段作为根节点输出:

                      db.collection('schools')  .aggregate()  .replaceRoot({    newRoot: '$teachers'  })  .end()

                      输出如下:

                      {  "chinese": 22,  "math": 18,  "english": 21,  "other": 123}

                      使用计算出的新字段作为根节点

                      假设我们有一个 roles 集合,内容如下:

                      { "_id": 1, "first_name": "四郎", "last_name": "黄" }{ "_id": 2, "first_name": "邦德", "last_name": "马" }{ "_id": 3, "first_name": "牧之", "last_name": "张" }

                      下面的代码使用 replaceRoot,把 first_name 和 last_name 拼在一起:

                      const { concat } = db.command.aggregatedb.collection('roles')  .aggregate()  .replaceRoot({    newRoot: {      full_name: concat(['$last_name', '$first_name'])    }  })  .end()

                      输出如下:

                      { "full_name": "黄四郎" }{ "full_name": "马邦德" }{ "full_name": "张牧之" }


                      Aggregate.sample(size: number): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。随机从文档中选取指定数量的记录。

                      参数

                      size: number

                      返回值

                      Aggregate

                      API 说明

                      sample 的形式如下:

                      sample({    size: <正整数>})

                      请注意:size 是正整数,否则会出错。

                      示例

                      假设文档 users 有以下记录:

                      { "name": "a" }{ "name": "b" }

                      随机选取

                      如果现在进行抽奖活动,需要选出一名幸运用户。那么 sample 的调用方式如下:

                      db.collection('users')  .aggregate()  .sample({    size: 1  })  .end()

                      返回了随机选中的一个用户对应的记录,结果如下:

                      { "_id": "696529e4-7e82-4e7f-812e-5144714edff6", "name": "b" }


                      Aggregate.skip(value: number): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。指定一个正整数,跳过对应数量的文档,输出剩下的文档。

                      参数

                      value: number

                      返回值

                      Aggregate

                      示例

                      db.collection('users')  .aggregate()  .skip(5)  .end()

                      这段代码会跳过查找到的前 5 个文档,并且把剩余的文档输出。


                      Aggregate.sort(object: Object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。根据指定的字段,对输入的文档进行排序。

                      参数

                      object: Object

                      返回值

                      Aggregate

                      API 说明

                      形式如下:

                      sort({    <字段名1>: <排序规则>,    <字段名2>: <排序规则>,})

                      <排序规则>可以是以下取值:

                      • 1 代表升序排列(从小到大);
                      • -1 代表降序排列(从大到小);

                      示例

                      升序/降序排列

                      假设我们有集合 articles,其中包含数据如下:

                      { "_id": "1", "author": "stark",  "score": 80, "age": 18 }{ "_id": "2", "author": "bob",    "score": 60, "age": 18 }{ "_id": "3", "author": "li",     "score": 55, "age": 19 }{ "_id": "4", "author": "jimmy",  "score": 60, "age": 22 }{ "_id": "5", "author": "justan", "score": 95, "age": 33 }
                      db.collection('articles')  .aggregate()  .sort({      age: -1,      score: -1  })  .end()

                      上面的代码在 students 集合中进行聚合搜索,并且将结果排序,首先根据 age 字段降序排列,然后再根据 score 字段进行降序排列。

                      输出结果如下:

                      { "_id": "5", "author": "justan", "score": 95, "age": 33 }{ "_id": "4", "author": "jimmy",  "score": 60, "age": 22 }{ "_id": "3", "author": "li",     "score": 55, "age": 19 }{ "_id": "1", "author": "stark",  "score": 80, "age": 18 }{ "_id": "2", "author": "bob",    "score": 60, "age": 18 }


                      Aggregate.sortByCount(object:Object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。根据传入的表达式,将传入的集合进行分组(group)。然后计算不同组的数量,并且将这些组按照它们的数量进行排序,返回排序后的结果。

                      参数

                      object: Object

                      返回值

                      Aggregate

                      API 说明

                      sortByCount 的调用方式如下:

                      sortByCount(<表达式>)

                      表达式的形式是:$ + 指定字段。请注意:不要漏写 $ 符号。

                      示例

                      统计基础类型

                      假设集合 passages 的记录如下:

                      { "category": "Web" }{ "category": "Web" }{ "category": "Life" }

                      下面的代码就可以统计文章的分类信息,并且计算每个分类的数量。即对 category 字段执行 sortByCount 聚合操作。

                      db.collection('passages')  .aggregate()  .sortByCount('$category')  .end()

                      返回的结果如下所示:Web 分类下有2篇文章,Life 分类下有1篇文章。

                      { "_id": "Web", "count": 2 }{ "_id": "Life", "count": 1 }

                      解构数组类型

                      假设集合 passages 的记录如下:tags 字段对应的值是数组类型。

                      { "tags": [ "JavaScript", "C#" ] }{ "tags": [ "Go", "C#" ] }{ "tags": [ "Go", "Python", "JavaScript" ] }

                      如何统计文章的标签信息,并且计算每个标签的数量?因为 tags 字段对应的数组,所以需要借助 unwind 操作解构 tags 字段,然后再调用 sortByCount。

                      下面的代码实现了这个功能:

                      db.collection('passages')  .aggregate()  .unwind(`$tags`)  .sortByCount(`$tags`)  .end()

                      返回的结果如下所示:

                      { "_id": "Go", "count": 2 }{ "_id": "C#", "count": 2 }{ "_id": "JavaScript", "count": 2 }{ "_id": "Python", "count": 1 }


                      Aggregate.unwind(value:string|object): Aggregate

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合阶段。使用指定的数组字段中的每个元素,对文档进行拆分。拆分后,文档会从一个变为一个或多个,分别对应数组的每个元素。

                      参数

                      value: string|object

                      返回值

                      Aggregate

                      API 说明

                      使用指定的数组字段中的每个元素,对文档进行拆分。拆分后,文档会从一个变为一个或多个,分别对应数组的每个元素。

                      unwind 有两种使用形式:

                      1. 参数是一个字段名
                      unwind(<字段名>)
                      1. 参数是一个对象
                      unwind({    path: <字段名>,    includeArrayIndex: <string>,    preserveNullAndEmptyArrays: <boolean>})
                      字段类型说明
                      pathstring想要拆分的数组的字段名,需要以 $ 开头。
                      includeArrayIndexstring可选项,传入一个新的字段名,数组索引会保存在这个新的字段上。新的字段名不能以 $ 开头。
                      preserveNullAndEmptyArraysboolean如果为 true,那么在 path 对应的字段为 null、空数组或者这个字段不存在时,依然会输出这个文档;如果为 falseunwind 将不会输出这些文档。默认为 false

                      示例

                      拆分数组

                      假设我们有一个 products 集合,包含数据如下:

                      { "_id": "1", "product": "tshirt", "size": ["S", "M", "L"] }{ "_id": "2", "product": "pants", "size": [] }{ "_id": "3", "product": "socks", "size": null }{ "_id": "4", "product": "trousers", "size": ["S"] }{ "_id": "5", "product": "sweater", "size": ["M", "L"] }

                      我们根据 size 字段对这些文档进行拆分

                      db.collection('products')  .aggregate()  .unwind('$size')  .end()

                      输出如下:

                      { "_id": "1", "product": "tshirt", "size": "S" }{ "_id": "1", "product": "tshirt", "size": "M" }{ "_id": "1", "product": "tshirt", "size": "L" }{ "_id": "4", "product": "trousers", "size": "S" }{ "_id": "5", "product": "sweater", "size": "M" }{ "_id": "5", "product": "sweater", "size": "L" }

                      拆分后,保留原数组的索引

                      我们根据 size 字段对文档进行拆分后,想要保留原数组索引在新的 index 字段中。

                      db.collection('products')  .aggregate()  .unwind({      path: '$size',      includeArrayIndex: 'index'  })  .end()

                      输出如下:

                      { "_id": "1", "product": "tshirt", "size": "S", "index": 0 }{ "_id": "1", "product": "tshirt", "size": "M", "index": 1 }{ "_id": "1", "product": "tshirt", "size": "L", "index": 2 }{ "_id": "4", "product": "trousers", "size": "S", "index": 0 }{ "_id": "5", "product": "sweater", "size": "M", "index": 0 }{ "_id": "5", "product": "sweater", "size": "L", "index": 1 }

                      保留字段为空的文档

                      注意到我们的集合中有两行特殊的空值数据:

                      ...{ "_id": "2", "product": "pants", "size": [] }{ "_id": "3", "product": "socks", "size": null }...

                      如果想要在输出中保留 size 为空数组、null,或者 size 字段不存在的文档,可以使用 preserveNullAndEmptyArrays 参数

                      db.collection('products')  .aggregate()  .unwind({      path: '$size',      preserveNullAndEmptyArrays: true  })  .end()

                      输出如下:

                      { "_id": "1", "product": "tshirt", "size": "S" }{ "_id": "1", "product": "tshirt", "size": "M" }{ "_id": "1", "product": "tshirt", "size": "L" }{ "_id": "2", "product": "pants", "size": null }{ "_id": "3", "product": "socks", "size": null }{ "_id": "4", "product": "trousers", "size": "S" }{ "_id": "5", "product": "sweater", "size": "M" }{ "_id": "5", "product": "sweater", "size": "L" }


                      Aggregate.end(): Promise<Object>

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      标志聚合操作定义完成,发起实际聚合操作

                      返回值

                      Promise.<Object>

                      属性类型说明
                      listArray.<any>聚合结果列表

                      示例代码

                      const $ = db.command.aggregatedb.collection('books').aggregate()  .group({    // 按 category 字段分组    _id: '$category',    // 让输出的每组记录有一个 avgSales 字段,其值是组内所有记录的 sales 字段的平均值    avgSales: $.avg('$sales')  })  .end()  .then(res => console.log(res))  .catch(err => console.error(err))

                      小程序端兼容支持 callback 风格

                      const $ = db.command.aggregatedb.collection('books').aggregate()  .group({    // 按 category 字段分组    _id: '$category',    // 让输出的每组记录有一个 avgSales 字段,其值是组内所有记录的 sales 字段的平均值    avgSales: $.avg('$sales')  })  .end({    success: function(res) {      console.log(res)    },    fail: function(err) {      console.error(err)    }  })


                      Geo

                      数据库地理位置结构集


                      方法:

                      Geo.Point(longitude: number, latitude: number): GeoPoint

                      支持端:小程序 , 云函数 , Web

                      构造一个地理位置 ”点“。方法接受两个必填参数,第一个是经度(longitude),第二个是纬度(latitude),务必注意顺序。

                      参数

                      longitude: number

                      经度

                      latitude: number

                      纬度

                      返回值

                      GeoPoint

                      索引

                      如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: db.Geo.Point(113, 23)  }}).then(console.log).catch(console.error)

                      除了使用接口构造一个点外,也可以使用等价的 GeoJSON 的 点 (Point) 的 JSON 表示,其格式如下:

                      {  "type": "Point",  "coordinates": [longitude, latitude] // 数字数组:[经度, 纬度]}

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'Point',      coordinates: [113, 23]    }  }}).then(console.log).catch(console.error)


                      Geo.LineString(points: GeoPoint[]): GeoPoint

                      支持端:小程序 2.6.3, 云函数

                      构造一个地理位置的 ”线“。一个线由两个或更多的点有序连接组成。

                      参数

                      points: GeoPoint[]

                      “点” 数组

                      返回值

                      GeoPoint

                      索引

                      如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: db.Geo.LineString([      db.Geo.Point(113, 23),      db.Geo.Point(120, 50),      // ... 可选更多点    ])  }}).then(console.log).catch(console.error)

                      除了使用接口构造一条 LineString 外,也可以使用等价的 GeoJSON 的 线 (LineString) 的 JSON 表示,其格式如下:

                      {  "type": "LineString",  "coordinates": [    [p1_lng, p1_lat],    [p2_lng, p2_lng]    // ... 可选更多点  ]}

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'LineString',      coordinates: [        [113, 23],        [120, 50]      ]    }  }}).then(console.log).catch(console.error)


                      Geo.Polygon(lineStrings: GeoLineString[]): GeoPolygon

                      支持端:小程序 2.6.3, 云函数

                      构造一个地理位置 ”多边形“

                      参数

                      lineStrings: GeoLineString[]

                      “线” 数组

                      返回值

                      GeoPolygon

                      索引

                      如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

                      说明

                      一个多边形由一个或多个线性环(Linear Ring)组成,一个线性环即一个闭合的线段。一个闭合线段至少由四个点组成,其中最后一个点和第一个点的坐标必须相同,以此表示环的起点和终点。如果一个多边形由多个线性环组成,则第一个线性环表示外环(外边界),接下来的所有线性环表示内环(即外环中的洞,不计在此多边形中的区域)。如果一个多边形只有一个线性环组成,则这个环就是外环。

                      多边形构造规则:

                      1. 第一个线性环必须是外环
                      2. 外环不能自交
                      3. 所有内环必须完全在外环内
                      4. 各个内环间不能相交或重叠,也不能有共同的边
                      5. 外环应为逆时针,内环应为顺时针

                      示例代码

                      示例代码:单环多边形

                      const { Polygon, LineString, Point } = db.Geodb.collection('todos').add({  data: {    description: 'eat an apple',    location: Polygon([      LineString([        Point(0, 0),        Point(3, 2),        Point(2, 3),        Point(0, 0)      ])    ])  }}).then(console.log).catch(console.error)

                      示例代码:含一个外环和一个内环的多边形

                      const { Polygon, LineString, Point } = db.Geodb.collection('todos').add({  data: {    description: 'eat an apple',    location: Polygon([      // 外环      LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),      // 内环      LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])    ])  }}).then(console.log).catch(console.error)

                      除了使用接口构造一个 Polygon 外,也可以使用等价的 GeoJSON 的 多边形 (Polygon) 的 JSON 表示,其格式如下:

                      {  "type": "Polygon",  "coordinates": [    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 外环    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 可选内环 1    ...    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ], // 可选内环 n  ]}

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'Polygon',      coordinates: [        [ [0, 0], [30, 20], [20, 30], [0, 0] ],        [ [10, 10], [16, 14], [14, 16], [10, 10]]      ]    }  }}).then(console.log).catch(console.error)


                      Geo.MultiPoint(points: GeoPoint[]): GeoMultiPoint

                      支持端:小程序 2.6.3, 云函数

                      构造一个地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

                      参数

                      points: GeoPoint[]

                      “点” 数组

                      返回值

                      GeoMultiPoint

                      索引

                      如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: db.Geo.MultiPoint([      db.Geo.Point(113, 23),      db.Geo.Point(120, 50),      // ... 可选更多点    ])  }}).then(console.log).catch(console.error)

                      除了使用接口构造 MultiPoint 外,也可以使用等价的 GeoJSON 的 点集合 (MultiPoint) 的 JSON 表示,其格式如下:

                      {  "type": "MultiPoint",  "coordinates": [    [p1_lng, p1_lat],    [p2_lng, p2_lng]    // ... 可选更多点  ]}

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'MultiPoint',      coordinates: [        [113, 23],        [120, 50]      ]    }  }}).then(console.log).catch(console.error)


                      Geo.MultiPoint(points: GeoPoint[]): GeoMultiPoint

                      支持端:小程序 2.6.3, 云函数

                      构造一个地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

                      参数

                      points: GeoPoint[]

                      “点” 数组

                      返回值

                      GeoMultiPoint

                      索引

                      如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: db.Geo.MultiPoint([      db.Geo.Point(113, 23),      db.Geo.Point(120, 50),      // ... 可选更多点    ])  }}).then(console.log).catch(console.error)

                      除了使用接口构造 MultiPoint 外,也可以使用等价的 GeoJSON 的 点集合 (MultiPoint) 的 JSON 表示,其格式如下:

                      {  "type": "MultiPoint",  "coordinates": [    [p1_lng, p1_lat],    [p2_lng, p2_lng]    // ... 可选更多点  ]}

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'MultiPoint',      coordinates: [        [113, 23],        [120, 50]      ]    }  }}).then(console.log).catch(console.error)


                      Geo.MultiLineString(lineStrings: GeoLineString[]): GeoMultiLineString

                      支持端:小程序 2.6.3, 云函数

                      构造一个地理位置 ”线“ 集合。一个线集合由多条线组成。

                      参数

                      lineStrings: GeoLineString[]

                      “线” 数组

                      返回值

                      GeoMultiLineString

                      索引

                      如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

                      示例代码

                      const { LineString, MultiLineString, Point } = db.Geodb.collection('todos').add({  data: {    description: 'eat an apple',    location: MultiLineString([      LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),      LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])    ])  }}).then(console.log).catch(console.error)

                      除了使用接口构造一个 MultiLineString 外,也可以使用等价的 GeoJSON 的 线集合 (MultiLineString) 的 JSON 表示,其格式如下:

                      {  "type": "MultiLineString",  "coordinates": [    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],    ...    [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]  ]}

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'MultiLineString',      coordinates: [        [ [0, 0], [3, 3] ],        [ [5, 10], [20, 30] ]      ]    }  }}).then(console.log).catch(console.error)


                      Geo.MultiPolygon(polygons: GeoPolygon[]): GeoMultiPolygon

                      支持端:小程序 2.6.3, 云函数

                      构造一个地理位置 ”多边形“ 集合。一个多边形集合由多个多边形组成。

                      参数

                      polygons: GeoPolygon[]

                      “多边形” 数组

                      返回值

                      GeoMultiPolygon

                      索引

                      如存储地理位置信息的字段有被查询的需求,务必对字段建立地理位置索引

                      说明

                      多边形集合由多个多边形组成。一个多边形由一个或多个线性环(Linear Ring)组成,一个线性环即一个闭合的线段。一个闭合线段至少由四个点组成,其中最后一个点和第一个点的坐标必须相同,以此表示环的起点和终点。如果一个多边形由多个线性环组成,则第一个线性环表示外环(外边界),接下来的所有线性环表示内环(即外环中的洞,不计在此多边形中的区域)。如果一个多边形只有一个线性环组成,则这个环就是外环。

                      多边形构造规则:

                      1. 第一个线性环必须是外环
                      2. 外环不能自交
                      3. 所有内环必须完全在外环内
                      4. 各个内环间不能相交或重叠,也不能有共同的边
                      5. 外环应为逆时针,内环应为顺时针

                      示例代码

                      示例代码

                      const { MultiPolygon, Polygon, LineString, Point } = db.Geodb.collection('todos').add({  data: {    description: 'eat an apple',    location: MultiPolygon([      Polygon([        LineString([ Point(50, 50), Point(60, 80), Point(80, 60), Point(50, 50) ]),      ]),      Polygon([        LineString([ Point(0, 0), Point(30, 20), Point(20, 30), Point(0, 0) ]),        LineString([ Point(10, 10), Point(16, 14), Point(14, 16), Point(10, 10) ])      ]),    ])  }}).then(console.log).catch(console.error)

                      除了使用接口构造一个 MultiPolygon 外,也可以使用等价的 GeoJSON 的 多边形 (MultiPolygon) 的 JSON 表示,其格式如下:

                      {  "type": "MultiPolygon",  "coordinates": [    // polygon 1    [      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],      ...      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]    ],    ...    // polygon n    [      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ],      ...      [ [lng, lat], [lng, lat], [lng, lat], ..., [lng, lat] ]    ],  ]}

                      示例代码

                      db.collection('todos').add({  data: {    description: 'eat an apple',    location: {      type: 'MultiPolygon',      coordinates: [        [          [ [50, 50], [60, 80], [80, 60], [50, 50] ]        ],        [          [ [0, 0], [30, 20], [20, 30], [0, 0] ],          [ [10, 10], [16, 14], [14, 16], [10, 10]]        ]      ]    }  }}).then(console.log).catch(console.error)



                      类型:

                      GeoPoint

                      地理位置 “点”

                      属性

                      longitude: number

                      经度

                      latitude: number

                      纬度

                      方法

                      GeoPoint.toJSON(): Object

                      返回相应的 GeoJSON 结构的对象


                      GeoLineString

                      地理位置的 ”线“。一个线由两个或更多的点有序连接组成。

                      属性

                      points: GeoPoint[]

                      “点” 数组

                      方法

                      GeoLineString.toJSON(): Object

                      返回相应的 GeoJSON 结构的对象


                      GeoPolygon

                      地理位置 ”多边形“

                      属性

                      lines: GeoLineString[]

                      “线” 数组

                      方法

                      GeoPolygon.toJSON(): Object

                      返回相应的 GeoJSON 结构的对象


                      GeoMultiPoint

                      地理位置的 ”点“ 的集合。一个点集合由一个或更多的点组成。

                      属性

                      points: GeoPoint[]

                      “点” 数组

                      方法

                      GeoMultiPoint.toJSON(): Object

                      返回相应的 GeoJSON 结构的对象


                      GeoMultiLineString

                      地理位置 ”线“ 集合。一个线集合由多条线组成。

                      属性

                      lines: GeoLineString[]

                      “线” 数组

                      方法

                      GeoMultiLineString.toJSON(): Object

                      返回相应的 GeoJSON 结构的对象


                      GeoMultiPolygon

                      地理位置 ”多边形“ 集合。一个多边形集合由多个多边形组成。

                      属性

                      polygons: GeoPolygon[]

                      “多边形” 数组

                      方法

                      GeoMultiPolygon.toJSON(): Object

                      返回相应的 GeoJSON 结构的对象




                      Transaction

                      数据库事务操作对象


                      方法:

                      Transaction.collection(name: string): Collection

                      支持端:云函数

                      事务中获取集合的引用。方法接受一个 name 参数,指定需引用的集合名称。

                      参数

                      name: string

                      集合名称

                      返回值

                      Collection

                      集合引用

                      注意事项

                      在事务中仅能进行单记录操作,也就是不能使用 where、aggregate 接口,可以使用的接口如下:

                      collection       获取集合引用|-- add          新增记录|-- doc          获取记录引用    |-- get      获取记录内容    |-- update   更新记录内容    |-- set      替换记录内容    |-- remove   删除记录



                      Transaction.rollback(reason: any): Promise<void>

                      支持端:云函数

                      终止并回滚事务

                      参数

                      reason: any

                      终止后,希望在 runTransaction 返回的 Promise reject 时接收到的值。

                      返回值

                      Promise.<void>

                      终止完成

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database({  throwOnNotFound: false,})const _ = db.commandtry {  const result = await db.runTransaction(async transaction => {    const aaaRes = await transaction.collection('account').doc('aaa').get()    // ...    // 终止事务    await transaction.rollback(-100)  })} catch (e) {  // e === -100  console.error(`transaction error`, e)}


                      Transaction.commit(reason: any): Promise<void>

                      支持端:云函数

                      提交事务

                      参数

                      reason: any

                      终止后,希望在 runTransaction 返回的 Promise reject 时接收到的值。

                      返回值

                      Promise.<void>

                      提交完成

                      示例代码

                      const cloud = require('wx-server-sdk')cloud.init({  env: cloud.DYNAMIC_CURRENT_ENV})const db = cloud.database({  throwOnNotFound: false,})const _ = db.commandexports.main = async (event) => {  try {    const transaction = await db.startTransaction()    // ...    await transaction.collection('account').doc('aaa').update({      data: {        amount: 100      }    })    // 提交事务    await transaction.commit()    return {      success: true,    }  } catch (e) {    console.error(`transaction error`, e)    return {      success: false,      error: e,    }  }}

                      API 列表:

                      transaction|-- collection       获取集合引用|   |-- doc          获取记录引用|   |   |-- get      获取记录内容|   |   |-- update   更新记录内容|   |   |-- set      替换记录内容|   |   |-- remove   删除记录|   |-- add          新增记录|-- rollback         终止事务并回滚|-- commit           提交事务(仅在使用 startTransaction 时可调用)


                      Command

                      数据库操作符,通过 db.command 获取

                      属性

                      AggregateCommand aggregate

                      聚合操作符

                      方法

                      Command.addToSet(value: any|Object): Command

                      数组更新操作符。原子操作。给定一个或多个元素,除非数组中已存在该元素,否则添加进数组。

                      Command.all(values: any[]): Command

                      数组查询操作符。用于数组字段的查询筛选条件,要求数组字段中包含给定数组的所有元素。

                      Command.and(expressions: any[]): Command

                      查询操作符,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

                      Command.bit(object: Object): Command

                      更新操作符。对字段进行位运算,可以进行 and/or/xor 运算。

                      Command.elemMatch(condition: Object|Command): Command

                      用于数组字段的查询筛选条件,要求数组中包含至少一个满足 elemMatch 给定的所有条件的元素

                      Command.eq(value: any): Command

                      查询筛选条件,表示字段等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

                      Command.exists(value: boolean): Command

                      判断字段是否存在

                      Command.expr(aggregateExpression: Expression): Command

                      查询操作符,用于在查询语句中使用聚合表达式,方法接收一个参数,该参数必须为聚合表达式

                      Command.geoIntersects(options: Object): Command

                      找出给定的地理位置图形相交的记录

                      Command.geoNear(options: Object): Command

                      按从近到远的顺序,找出字段值在给定点的附近的记录。

                      Command.geoWithin(options: Object): Command

                      找出字段值在指定区域内的记录,无排序。指定的区域必须是多边形(Polygon)或多边形集合(MultiPolygon)。

                      Command.gt(value: any): Command

                      查询筛选操作符,表示需大于指定值。可以传入 Date 对象用于进行日期比较。

                      Command.gte(value: any): Command

                      查询筛选操作符,表示需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

                      Command.in(value: any[]): Command

                      查询筛选操作符,表示要求值在给定的数组内。

                      Command.inc(value: number): Command

                      更新操作符,原子操作,用于指示字段自增

                      Command.lt(value: any): Command

                      查询筛选操作符,表示需小于指定值。可以传入 Date 对象用于进行日期比较。

                      Command.lte(value: any): Command

                      查询筛选操作符,表示需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

                      Command.max(value: any): Command

                      更新操作符,给定一个值,只有该值大于字段当前值才进行更新。

                      Command.min(value: any): Command

                      更新操作符,给定一个值,只有该值小于字段当前值才进行更新。

                      Command.mod(divisor: number, remainder: number): Command

                      查询筛选操作符,给定除数 divisor 和余数 remainder,要求字段作为被除数时 value % divisor = remainder。

                      Command.mul(value: number): Command

                      更新操作符,原子操作,用于指示字段自乘某个值

                      Command.neq(value: any): Command

                      查询筛选条件,表示字段不等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

                      Command.nin(value: any[]): Command

                      查询筛选操作符,表示要求值不在给定的数组内。

                      Command.nor(expressions: any[]): Command

                      查询操作符,用于表示逻辑 "都不" 的关系,表示需不满足指定的所有条件。如果记录中没有对应的字段,则默认满足条件。

                      Command.not(command: Command): Command

                      查询操作符,用于表示逻辑 "非" 的关系,表示需不满足指定的条件。

                      Command.or(expressions: any[]): Command

                      查询操作符,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

                      Command.pop(): Command

                      数组更新操作符,对一个值为数组的字段,将数组尾部元素删除

                      Command.pull(value: any): Command

                      数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值或查询条件的元素都移除掉。

                      Command.pullAll(value: any): Command

                      数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值的元素都移除掉。跟 pull 的差别在于只能指定常量值、传入的是数组。

                      Command.push(values: Object): Command

                      数组更新操作符。对一个值为数组的字段,往数组添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

                      Command.remove(): Command

                      更新操作符,用于表示删除某个字段。

                      Command.rename(value: string): Command

                      更新操作符,字段重命名。如果需要对嵌套深层的字段做重命名,需要用点路径表示法。不能对嵌套在数组里的对象的字段进行重命名。

                      Command.set(value: any): Command

                      更新操作符,用于设定字段等于指定值。

                      Command.shift(): Command

                      数组更新操作符,对一个值为数组的字段,将数组头部元素删除。

                      Command.size(value: string): Command

                      更新操作符,用于数组字段的查询筛选条件,要求数组长度为给定值

                      Command.unshift(values: any[]): Command

                      数组更新操作符,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。


                      Command.and(expressions: any[]): Command

                      支持端:小程序 , 云函数 , Web

                      查询操作符,用于表示逻辑 "与" 的关系,表示需同时满足多个查询筛选条件

                      参数

                      expressions: any[]

                      返回值

                      Command

                      使用说明

                      and 有两种使用情况:

                      1. 用在根查询条件

                      此时需传入多个查询条件,表示需同时满足提供的多个完整查询条件

                      const _ = db.commanddb.collection('todo').where(_.and([  {    progress: _.gt(50)  },  {    tags: 'cloud'  }])).get()

                      但以上用 and 组成的查询条件是不必要的,因为传入的对象的各字段隐式组成了 “与” 的关系,上述条件等价于下方更简洁的写法:

                      const _ = db.commanddb.collection('todo').where({  progress: _.gt(50),  tags: 'cloud'}).get()

                      通常需要显示使用 and 是用在有跨字段或操作的时候,如以下表示 “progress 字段大于 50 或 tags 字段等于 cloud 或 tags 数组字段(如果 tags 是数组)中含有 cloud”:

                      const _ = db.commanddb.collection('todo').where(_.and([  _.or({    progress: _.gt(50)  }),  _.or({    tags: 'cloud'  })])).get()

                      2. 用在字段查询条件

                      需传入多个查询操作符或常量,表示字段需满足或匹配给定的条件。

                      如以下用前置写法的方式表示 "progress 字段值大于 50 且小于 100"

                      const _ = db.commanddb.collection('todo').where({  progress: _.and(_.gt(50), _.lt(100))})

                      还可以用后置写法的方式表示同样的条件:

                      const _ = db.commanddb.collection('todo').where({  progress: _.gt(50).and(_.lt(100))})

                      注意 Command 默认也可以直接链式调用其他 Command,默认表示多个 Command 的与操作,因此上述代码还可以精简为:

                      const _ = db.commanddb.collection('todo').where({  progress: _.gt(50).lt(100)})

                      调用风格

                      方法接收两种传参方式,一是传入一个数组参数,二是传入多个参数,效果一样。

                      // 传入数组function and(expressions: Expression[]): Command// 传入多参数function and(...expressions: Expression[]): Command



                      Command.or(expressions: any[]): Command

                      支持端:小程序 , 云函数 , Web

                      查询操作符,用于表示逻辑 "或" 的关系,表示需同时满足多个查询筛选条件。或指令有两种用法,一是可以进行字段值的 “或” 操作,二是也可以进行跨字段的 “或” 操作。

                      参数

                      expressions: any[]

                      返回值

                      Command

                      字段值的或操作

                      字段值的 “或” 操作指的是指定一个字段值为多个值之一即可。

                      如筛选出进度大于 80 或小于 20 的 todo:

                      流式写法:

                      const _ = db.commanddb.collection('todo').where({  progress: _.gt(80).or(_.lt(20))})

                      前置写法:

                      const _ = db.commanddb.collection('todo').where({  progress: _.or(_.gt(80), _.lt(20))})

                      前置写法也可接收一个数组:

                      const _ = db.commanddb.collection('todo').where({  progress: _.or([_.gt(80), _.lt(20)])})

                      跨字段的或操作

                      跨字段的 “或” 操作指条件 “或”,相当于可以传入多个 where 语句,满足其中一个即可。

                      如筛选出进度大于 80 或已标为已完成的 todo:

                      const _ = db.commanddb.collection('todo').where(_.or([  {    progress: _.gt(80)  },  {    done: true  }]))

                      调用风格

                      方法接收两种传参方式,一是传入一个数组参数,二是传入多个参数,效果一样。

                      // 传入数组function or(expressions: Expression[]): Command// 传入多参数function or(...expressions: Expression[]): Command

                      Command.not(command: Command): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      查询操作符,用于表示逻辑 "非" 的关系,表示需不满足指定的条件。

                      参数

                      command: Command

                      返回值

                      Command

                      示例

                      如筛选出进度不等于100的 todo:

                      const _ = db.commanddb.collection('todo').where({  progress: _.not(_.eq(100))})

                      not 也可搭配其他逻辑指令使用,包括 and, or, nor, not,如 or:

                      const _ = db.commanddb.collection('todo').where({  progress: _.not(_.or([_.lt(50), _.eq(100)]))})

                      Command.nor(expressions: any[]): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      查询操作符,用于表示逻辑 "都不" 的关系,表示需不满足指定的所有条件。如果记录中没有对应的字段,则默认满足条件。

                      参数

                      expressions: any[]

                      返回值

                      Command

                      示例 1

                      筛选出进度既不小于20又不大于80的 todo :

                      const _ = db.commanddb.collection('todo').where({  progress: _.nor([_.lt(20), _.gt(80)])})

                      以上同时会筛选出不存在 progress 字段的记录,如果要要求 progress 字段存在,可以用 exists 指令:

                      const _ = db.commanddb.collection('todo').where({  progress: _.exists().nor([_.lt(20), _.gt(80)])  // 等价于以下非链式调用的写法:  // progress: _.exists().and(_.nor([_.lt(20), _.gt(80)]))}).get()

                      示例 2

                      筛选出 progress 不小于 20 且 tags 数组不包含 miniprogram 字符串的记录:

                      const _ = db.commanddb.collection('todo').where(_.nor([{  progress: _.lt(20),}, {  tags: 'miniprogram',}])).get()

                      以上会筛选出满足以下条件之一的记录:

                      1. progress 不小于 20 且 tags 数组不包含 miniprogram 字符串
                      2. progress 不小于 20 且 tags 字段不存在
                      3. progress 字段不存在 且 tags 数组不包含 miniprogram 字符串
                      4. progress 不小于 20 且 tags 字段不存在

                      如果要求 progress 和 tags 字段存在,可以用 exists 指令:

                      const _ = db.commanddb.collection('todo').where(  _.nor([{    progress: _.lt(20),  }, {    tags: 'miniprogram',  }])  .and({    progress: _.exists(true),    tags: _.exists(true),  }))

                      调用风格

                      方法接收两种传参方式,一是传入一个数组参数,二是传入多个参数,效果一样。

                      // 传入数组function nor(expressions: Expression[]): Command// 传入多参数function nor(...expressions: Expression[]): Command


                      Command.eq(value: any): Command

                      支持端:小程序 , 云函数 , Web

                      查询筛选条件,表示字段等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

                      参数

                      value: any

                      返回值

                      Command

                      使用说明

                      比如筛选出所有自己发表的文章,除了用传对象的方式:

                      const openID = 'xxx'db.collection('articles').where({  _openid: openID})

                      还可以用指令:

                      const _ = db.commandconst openID = 'xxx'db.collection('articles').where({  _openid: _.eq(openid)})

                      注意 eq 指令比对象的方式有更大的灵活性,可以用于表示字段等于某个对象的情况,比如:

                      // 这种写法表示匹配 stat.publishYear == 2018 且 stat.language == 'zh-CN'db.collection('articles').where({  stat: {    publishYear: 2018,    language: 'zh-CN'  }})// 这种写法表示 stat 对象等于 { publishYear: 2018, language: 'zh-CN' }const _ = db.commanddb.collection('articles').where({  stat: _.eq({    publishYear: 2018,    language: 'zh-CN'  })})

                      Command.neq(value: any): Command

                      支持端:小程序 , 云函数 , Web

                      查询筛选条件,表示字段不等于某个值。eq 指令接受一个字面量 (literal),可以是 number, boolean, string, object, array, Date。

                      参数

                      value: any

                      返回值

                      Command

                      使用说明

                      表示字段不等于某个值,和 eq 相反


                      Command.lt(value: any): Command

                      支持端:小程序 , 云函数 , Web

                      查询筛选操作符,表示需小于指定值。可以传入 Date 对象用于进行日期比较。

                      参数

                      value: any

                      返回值

                      Command

                      示例代码

                      找出进度小于 50 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.lt(50)}).get({  success: console.log,  fail: console.error})

                      Command.lte(value: any): Command

                      支持端:小程序 , 云函数 , Web

                      查询筛选操作符,表示需小于或等于指定值。可以传入 Date 对象用于进行日期比较。

                      参数

                      value: any

                      返回值

                      Command

                      示例代码

                      找出进度小于或等于 50 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.lte(50)}).get({  success: console.log,  fail: console.error})

                      Command.gt(value: any): Command

                      支持端:小程序 , 云函数 , Web

                      查询筛选操作符,表示需大于指定值。可以传入 Date 对象用于进行日期比较。

                      参数

                      value: any

                      返回值

                      Command

                      示例代码

                      找出进度大于 50 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.gt(50)}).get({  success: console.log,  fail: console.error})

                      Command.gte(value: any): Command

                      支持端:小程序 , 云函数 , Web

                      查询筛选操作符,表示需大于或等于指定值。可以传入 Date 对象用于进行日期比较。

                      参数

                      value: any

                      返回值

                      Command

                      示例代码

                      找出进度大于或等于 50 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.gte(50)}).get({  success: console.log,  fail: console.error})

                      Command.in(value: any[]): Command

                      支持端:小程序 , 云函数 , Web

                      查询筛选操作符,表示要求值在给定的数组内。

                      参数

                      value: any[]

                      返回值

                      Command

                      示例代码

                      找出进度为 0 或 100 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.in([0, 100])}).get({  success: console.log,  fail: console.error})

                      Command.nin(value: any[]): Command

                      支持端:小程序 , 云函数 , Web

                      查询筛选操作符,表示要求值不在给定的数组内。

                      参数

                      value: any[]

                      返回值

                      Command

                      示例代码

                      找出进度不是 0 或 100 的 todo

                      const _ = db.commanddb.collection('todos').where({  progress: _.nin([0, 100])}).get({  success: console.log,  fail: console.error})


                      Command.exists(value: boolean): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      判断字段是否存在

                      参数

                      value: boolean

                      返回值

                      Command

                      示例代码

                      找出存在 tags 字段的记录

                      const _ = db.commanddb.collection('todos').where({  tags: _.exists(true)}).get({  success: console.log,  fail: console.error})

                      Command.mod(divisor: number, remainder: number): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      查询筛选操作符,给定除数 divisor 和余数 remainder,要求字段作为被除数时 value % divisor = remainder。

                      参数

                      divisor: number

                      remainder: number

                      返回值

                      Command

                      示例代码

                      找出进度为 10 的倍数的字段的记录

                      const _ = db.commanddb.collection('todos').where({  progress: _.mod(10, 0)}).get({  success: console.log,  fail: console.error})


                      Command.all(values: any[]): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      数组查询操作符。用于数组字段的查询筛选条件,要求数组字段中包含给定数组的所有元素。

                      参数

                      values: any[]

                      返回值

                      Command

                      示例代码 1:普通数组

                      找出 tags 数组字段同时包含 cloud 和 database 的记录

                      const _ = db.commanddb.collection('todos').where({  tags: _.all(['cloud', 'database'])}).get({  success: console.log,  fail: console.error})

                      示例代码 2:对象数组

                      如果数组元素是对象,则可以用 _.elemMatch 匹配对象的部分字段

                      假设有字段 places 定义如下:

                      {  "type": string  "area": number  "age": number}

                      找出数组字段中至少同时包含一个满足 “area 大于 100 且 age 小于 2” 的元素和一个满足 “type 为 mall 且 age 大于 5” 的元素

                      const _ = db.commanddb.collection('todos').where({  places: _.all([    _.elemMatch({      area: _.gt(100),      age: _.lt(2),    }),    _.elemMatch({      name: 'mall',      age: _.gt(5),    }),  ]),}).get({  success: console.log,  fail: console.error,})




                      Command.elemMatch(condition: Object|Command): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      用于数组字段的查询筛选条件,要求数组中包含至少一个满足 elemMatch 给定的所有条件的元素

                      参数

                      condition: Object|Command

                      匹配条件

                      返回值

                      Command

                      示例代码:数组是对象数组的情况

                      假设集合示例数据如下:

                      {  "_id": "a0",  "city": "x0",  "places": [{    "type": "garden",    "area": 300,    "age": 1  }, {    "type": "theatre",    "area": 50,    "age": 15  }]}

                      找出 places 数组字段中至少同时包含一个满足 “area 大于 100 且 age 小于 2” 的元素

                      const _ = db.commanddb.collection('todos').where({  places: _.elemMatch({    area: _.gt(100),    age: _.lt(2),  })}).get()

                      注意*:如果不使用 elemMatch 而直接如下指定条件,则表示的是 places 数组字段中至少有一个元素的 area 字段大于 100 且 places 数组字段中至少有一个元素的 age 字段小于 2:

                      const _ = db.commanddb.collection('todos').where({  places: {    area: _.gt(100),    age: _.lt(2),  }}).get()

                      示例代码:数组元素都是普通数据类型的情况

                      假设集合示例数据如下:

                      {  "_id": "a0",  "scores": [60, 80, 90]}

                      找出 scores 数组字段中至少同时包含一个满足 “大于 80 且小于 100” 的元素

                      const _ = db.commanddb.collection('todos').where({  places: _.elemMatch(_.gt(80).lt(100))}).get()

                      Command.size(value: string): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      更新操作符,用于数组字段的查询筛选条件,要求数组长度为给定值

                      参数

                      value: string

                      返回值

                      Command

                      示例

                      找出 tags 数组字段长度为 2 的所有记录

                      const _ = db.commanddb.collection('todos').where({  places: _.size(2)}).get({  success: console.log,  fail: console.error,})


                      Command.geoNear(options: Object): Command

                      支持端:小程序 , 云函数 , Web

                      按从近到远的顺序,找出字段值在给定点的附近的记录。

                      参数

                      options: Object

                      属性类型默认值必填说明
                      geometryGeoPoint地理位置点 (Point)
                      maxDistancenumber选填,最大距离,单位为米
                      minDistancenumber选填,最小距离,单位为米

                      返回值

                      Command

                      索引要求

                      需对查询字段建立地理位置索引

                      示例代码

                      找出离给定位置 1 公里到 5 公里范围内的记录

                      const _ = db.commanddb.collection('restaurants').where({  location: _.geoNear({    geometry: db.Geo.Point(113.323809, 23.097732),    minDistance: 1000,    maxDistance: 5000,  })}).get()

                      Command.geoWithin(options: Object): Command

                      支持端:小程序 , 云函数 , Web

                      找出字段值在指定区域内的记录,无排序。指定的区域必须是多边形(Polygon)或多边形集合(MultiPolygon)。

                      参数

                      options: Object

                      属性类型默认值必填说明
                      geometryObject地理信息结构,Polygon,MultiPolygon,或 { centerSphere }

                      返回值

                      Command

                      索引要求

                      需对查询字段建立地理位置索引

                      示例代码 1:给定多边形

                      const _ = db.commandconst { Point, LineString, Polygon } = db.Geodb.collection('restaurants').where({  location: _.geoWithin({    geometry: Polygon([      LineString([        Point(0, 0),        Point(3, 2),        Point(2, 3),        Point(0, 0)      ])    ]),  })})

                      示例代码 2:给定圆形

                      可以不用 geometry 而用 centerSphere 构建一个圆形。

                      centerShpere 从公共库 2.8.3 开始支持

                      centerSphere 对应的值的定义是:[ [经度, 纬度], 半径 ]

                      半径需以弧度计,比如需要 10km 的半径,则用距离除以地球半径 6378.1km 得出的数字。

                      const _ = db.commanddb.collection('restaurants').where({  location: _.geoWithin({    centerSphere: [      [-88, 30],      10 / 6378.1,    ]  })})

                      Command.geoIntersects(options: Object): Command

                      支持端:小程序 , 云函数 , Web

                      找出给定的地理位置图形相交的记录

                      参数

                      options: Object

                      属性类型默认值必填说明
                      geometryObject地理信息结构,Point

                      返回值

                      Command

                      索引要求

                      需对查询字段建立地理位置索引

                      示例代码:找出和一个多边形相交的记录

                      const _ = db.commandconst { Point, LineString, Polygon } = db.Geodb.collection('restaurants').where({  location: _.geoIntersects({    geometry: Polygon([      LineString([        Point(0, 0),        Point(3, 2),        Point(2, 3),        Point(0, 0)      ])    ]),  })})


                      Command.expr(aggregateExpression: Expression): Command

                      支持端:云函数 1.4.0

                      查询操作符,用于在查询语句中使用聚合表达式,方法接收一个参数,该参数必须为聚合表达式

                      参数

                      aggregateExpression: Expression

                      要添加进数组的一个或多个元素

                      返回值

                      Command

                      使用说明

                      1. expr 可用于在聚合 match 流水线阶段中引入聚合表达式
                      2. 如果聚合 match 阶段是在 lookup 阶段内,此时的 expr 表达式内可使用 lookup 中使用 let 参数定义的变量,具体示例可见 lookup 的 指定多个连接条件 例子
                      3. expr 可用在普通查询语句(where)中引入聚合表达式

                      示例代码 1:比较同一个记录中的两个字段

                      假设 items 集合的数据结构如下:

                      {  "_id": string,  "inStock": number, // 库存量  "ordered": number  // 被订量}

                      找出被订量大于库存量的记录:

                      const _ = db.commandconst $ = _.aggregatedb.collection('items').where(_.expr($.gt('$ordered', '$inStock'))).get()

                      示例代码 2:与条件语句组合使用

                      假设 items 集合的数据结构如下:

                      {  "_id": string,  "price": number}

                      假设加个小于等于 10 的打 8 折,大于 10 的打 5 折,让数据库查询返回打折后价格小于等于 8 的记录:

                      const _ = db.commandconst $ = _.aggregatedb.collection('items').where(_.expr(  $.lt(    $.cond({      if: $.gte('$price', 10),      then: $.multiply(['$price', '0.5']),      else: $.multiply(['$price', '0.8']),    })    ,    8  )).get()


                      Command.set(value: any): Command

                      支持端:小程序 , 云函数 , Web

                      更新操作符,用于设定字段等于指定值。

                      参数

                      value: any

                      返回值

                      Command

                      使用说明

                      这种方法相比传入纯 JS 对象的好处是能够指定字段等于一个对象

                      示例

                      // 以下方法只会更新 style.color 为 red,而不是将 style 更新为 { color: 'red' },即不影响 style 中的其他字段db.collection('todos').doc('doc-id').update({  data: {    style: {      color: 'red'    }  }})// 以下方法更新 style 为 { color: 'red', size: 'large' }db.collection('todos').doc('doc-id').update({  data: {    style: _.set({      color: 'red',      size: 'large'    })  }})

                      Command.remove(): Command

                      支持端:小程序 , 云函数 , Web

                      更新操作符,用于表示删除某个字段。

                      返回值

                      Command

                      示例代码

                      删除 style 字段:

                      const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    style: _.remove()  }})

                      Command.inc(value: number): Command

                      支持端:小程序 , 云函数 , Web

                      更新操作符,原子操作,用于指示字段自增

                      参数

                      value: number

                      自增量,可正可负

                      返回值

                      Command

                      原子自增

                      多个用户同时写,对数据库来说都是将字段自增,不会有后来者覆写前者的情况

                      示例代码

                      将一个 todo 的进度自增 10:

                      const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    progress: _.inc(10)  }})

                      Command.mul(value: number): Command

                      支持端:小程序 , 云函数 , Web

                      更新操作符,原子操作,用于指示字段自乘某个值

                      参数

                      value: number

                      自乘量,可正可负

                      返回值

                      Command

                      原子自乘

                      多个用户同时写,对数据库来说都是将字段自乘,不会有后来者覆写前者的情况

                      示例代码

                      将一个 todo 的进度自乘 10:

                      const _ = db.commanddb.collection('todos').doc('todo-id').update({  data: {    progress: _.mul(10)  }})

                      Command.min(value: any): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      更新操作符,给定一个值,只有该值小于字段当前值才进行更新。

                      参数

                      value: any

                      返回值

                      Command

                      示例代码

                      如果字段 progress > 50,则更新到 50

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    progress: _.min(50)  }})

                      Command.max(value: any): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      更新操作符,给定一个值,只有该值大于字段当前值才进行更新。

                      参数

                      value: any

                      返回值

                      Command

                      示例代码

                      如果字段 progress < 50,则更新到 50

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    progress: _.max(50)  }})

                      Command.rename(value: string): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      更新操作符,字段重命名。如果需要对嵌套深层的字段做重命名,需要用点路径表示法。不能对嵌套在数组里的对象的字段进行重命名。

                      参数

                      value: string

                      返回值

                      Command

                      示例 1:重命名顶层字段

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    progress: _.rename('totalProgress')  }})

                      示例 2:重命名嵌套字段

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    someObject: {      someField: _.rename('someObject.renamedField')    }  }})

                      或:

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    'someObject.someField': _.rename('someObject.renamedField')  }})

                      Command.bit(object: Object): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      更新操作符。对字段进行位运算,可以进行 and/or/xor 运算。

                      参数

                      object: Object

                      属性类型默认值必填说明
                      andnumber进行位与运算的整形
                      ornumber进行位或运算的整形
                      xornumber进行位异或运算的整形

                      返回值

                      Command

                      使用说明

                      and/or/xor 只能选其一

                      示例代码

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    // 假设原来是 2,则运算后是 3    progress: _.bit({      or: 1    })  }})


                      Command.push(values: Object): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      数组更新操作符。对一个值为数组的字段,往数组添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

                      参数

                      values: Object

                      属性类型默认值必填说明
                      eachArray.<any>要插入的所有元素
                      positionnumber从哪个位置开始插入,不填则是尾部
                      sortnumber对结果数组排序
                      slicenumber限制结果数组长度

                      返回值

                      Command

                      参数说明

                      position 说明

                      要求必须同时有 each 参数存在。

                      非负数代表从数组开始位置数的位置,从 0 开始计。如果数值大于等于数组长度,则视为在尾部添加。负数代表从数组尾部倒数的位置,比如 -1 就代表倒数第二个元素的位置。如果负数数值的绝对值大于等于数组长度,则视为从数组头部添加。

                      sort 说明

                      要求必须同时有 each 参数存在。给定 1 代表升序,-1 代表降序。

                      如果数组元素是记录,则用 { <字段>: 1 | -1 } 的格式表示根据记录中的什么字段做升降序排序。

                      slice** 说明

                      要求必须同时有 each 参数存在

                      说明
                      0将字段更新为空数组
                      正数数组只保留前 n 个元素
                      负数数组只保留后 n 个元素

                      升级说明

                      以上定义是从小程序 2.8.3 / 云函数 SDK 1.2.1 起支持,对于之前的版本,使用的是如下函数签名,新版中对旧版签名有兼容。

                      旧版签名:传入一个数组,该数组的每个元素会被追加到字段数组的尾部

                      function push(values: any[]): Command

                      示例 1:尾部添加元素

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push(['mini-program', 'cloud'])  }})

                      示例 2:从第二个位置开始插入

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: ['mini-program', 'cloud'],      position: 1,    })  }})

                      示例 3:排序

                      插入后对整个数组做排序

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: ['mini-program', 'cloud'],      sort: 1,    })  }})

                      不插入,只对数组做排序

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: [],      sort: 1,    })  }})

                      如果字段是对象数组,可以如下根据元素对象里的字段进行排序:

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: [        { name: 'miniprogram', weight: 8 },        { name: 'cloud', weight: 6 },      ],      sort: {        weight: 1,      },    })  }})

                      示例 4:截断保留

                      插入后只保留后 2 个元素

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: ['mini-program', 'cloud'],      slice: -2,    })  }})

                      示例 5:在指定位置插入、然后排序、最后只保留前 2 个元素

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.push({      each: ['mini-program', 'cloud'],      position: 1,      slice: 2,      sort: 1,    })  }})

                      Command.pop(): Command

                      支持端:小程序 , 云函数 , Web

                      数组更新操作符,对一个值为数组的字段,将数组尾部元素删除

                      返回值

                      Command

                      示例代码

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.pop()  }})

                      Command.unshift(values: any[]): Command

                      支持端:小程序 , 云函数 , Web

                      数组更新操作符,对一个值为数组的字段,往数组头部添加一个或多个值。或字段原为空,则创建该字段并设数组为传入值。

                      参数

                      values: any[]

                      返回值

                      Command

                      示例代码

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.unshift(['mini-program', 'cloud'])  }})

                      Command.shift(): Command

                      支持端:小程序 , 云函数 , Web

                      数组更新操作符,对一个值为数组的字段,将数组头部元素删除。

                      返回值

                      Command

                      示例代码

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.shift()  }})

                      Command.pull(value: any): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值或查询条件的元素都移除掉。

                      参数

                      value: any

                      值或查询条件

                      返回值

                      Command

                      示例代码 1:根据常量匹配移除

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.pull('database')  }})

                      示例代码 2:根据查询条件匹配移除

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.pull(_.in(['database', 'cloud']))  }})

                      示例代码 3:对象数组时,根据查询条件匹配移除

                      假设有字段 places 数组中的元素结构如下

                      {  "type": string  "area": number  "age": number}
                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    places: _.pull({      area: _.gt(100),      age: _.lt(2),    })  }})

                      示例代码 4:有嵌套对象的对象数组时,根据查询条件匹配移除

                      假设有字段 cities 数组中的元素结构如下

                      {  "name": string  "places": Place[]}

                      Place 结构如下:

                      {  "type": string  "area": number  "age": number}

                      可用 elemMatch 匹配嵌套在对象数组里面的对象数组字段 places

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    cities: _.pull({      places: _.elemMatch({        area: _.gt(100),        age: _.lt(2),      })    })  }})

                      Command.pullAll(value: any): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      数组更新操作符。给定一个值或一个查询条件,将数组中所有匹配给定值的元素都移除掉。跟 pull 的差别在于只能指定常量值、传入的是数组。

                      参数

                      value: any

                      值或查询条件

                      返回值

                      Command

                      示例代码:根据常量匹配移除

                      从 tags 中移除所有 database 和 cloud 字符串

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.pullAll(['database', 'cloud'])  }})

                      Command.addToSet(value: any|Object): Command

                      支持端:小程序 2.8.3, 云函数 1.2.1, Web

                      数组更新操作符。原子操作。给定一个或多个元素,除非数组中已存在该元素,否则添加进数组。

                      参数

                      value: any|Object

                      要添加进数组的一个或多个元素

                      属性类型默认值必填说明
                      eachArray.<any>数组,用于同时指定多个要插入数组的元素

                      返回值

                      Command

                      示例代码 1:添加一个元素

                      如果 tags 数组中不包含 database,添加进去

                      const _ = db.commanddb.collection('todos').doc('doc-id').update({  data: {    tags: _.addToSet('database')  }})

                      示例代码 2:添加多个元素

                      需传入一个对象,其中有一个字段 each,其值为数组,每个元素就是要添加的元素

                        const _ = db.command  db.collection('todos').doc('doc-id').update({    data: {      tags: _.addToSet({        each: ['database', 'cloud']      })    }  })


                      AggregateCommand

                      数据库聚合操作符,通过 db.command.aggregate 获取

                      方法

                      AggregateCommand.abs(value: Expression<number>): Object

                      聚合操作符。返回一个数字的绝对值。

                      AggregateCommand.add(value: Expression[]): Object

                      聚合操作符。将数字相加或将数字加在日期上。如果数组中的其中一个值是日期,那么其他值将被视为毫秒数加在该日期上。

                      AggregateCommand.addToSet(value: Expression): Object

                      聚合操作符。聚合运算符。向数组中添加值,如果数组中已存在该值,不执行任何操作。它只能在 group stage 中使用。

                      AggregateCommand.allElementsTrue(value: Expression[]): Object

                      聚合操作符。输入一个数组,或者数组字段的表达式。如果数组中所有元素均为真值,那么返回 true,否则返回 false。空数组永远返回 true。

                      AggregateCommand.and(value: Expression[]): Object

                      聚合操作符。给定多个表达式,and 仅在所有表达式都返回 true 时返回 true,否则返回 false。

                      AggregateCommand.anyElementTrue(value: Expression[]): Object

                      聚合操作符。输入一个数组,或者数组字段的表达式。如果数组中任意一个元素为真值,那么返回 true,否则返回 false。空数组永远返回 false。

                      AggregateCommand.arrayElemAt(value: Expression[]): Object

                      聚合操作符。返回在指定数组下标的元素。

                      AggregateCommand.arrayToObject(value: any): Object

                      聚合操作符。将一个数组转换为对象。

                      AggregateCommand.avg(value: Expression<number>): Object

                      聚合操作符。返回一组集合中,指定字段对应数据的平均值。

                      AggregateCommand.ceil(value: Expression<number>): Object

                      聚合操作符。向上取整,返回大于或等于给定数字的最小整数。

                      AggregateCommand.cmp(value: Expression[]): Object

                      聚合操作符。给定两个值,返回其比较值:

                      AggregateCommand.concat(value: Expression[]): Object

                      聚合操作符。连接字符串,返回拼接后的字符串。

                      AggregateCommand.concatArrays(value: Expression[]): Object

                      聚合操作符。将多个数组拼接成一个数组。

                      AggregateCommand.cond(value: any): Object

                      聚合操作符。计算布尔表达式,返回指定的两个值其中之一。

                      AggregateCommand.dateFromParts(value: any): Object

                      聚合操作符。给定日期的相关信息,构建并返回一个日期对象。

                      AggregateCommand.dateFromString(value: any): Object

                      聚合操作符。将一个日期/时间字符串转换为日期对象

                      AggregateCommand.dateToString(value: any): Object

                      聚合操作符。根据指定的表达式将日期对象格式化为符合要求的字符串。

                      AggregateCommand.dayOfMonth(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的天数(一个月中的哪一天),是一个介于 1 至 31 之间的数字。

                      AggregateCommand.dayOfWeek(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的天数(一周中的第几天),是一个介于 1(周日)到 7(周六)之间的整数。

                      AggregateCommand.dayOfYear(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的天数(一年中的第几天),是一个介于 1 到 366 之间的整数。

                      AggregateCommand.divide(value: Expression[]): Object

                      聚合操作符。传入被除数和除数,求商。

                      AggregateCommand.eq(value: Expression[]): Object

                      聚合操作符。匹配两个值,如果相等则返回 true,否则返回 false。

                      AggregateCommand.exp(value: Expression<number>): Object

                      聚合操作符。取 e(自然对数的底数,欧拉数) 的 n 次方。

                      AggregateCommand.filter(value: any): Object

                      聚合操作符。根据给定条件返回满足条件的数组的子集。

                      AggregateCommand.first(value: Expression): Object

                      聚合操作符。返回指定字段在一组集合的第一条记录对应的值。仅当这组集合是按照某种定义排序( sort )后,此操作才有意义。

                      AggregateCommand.floor(value: Expression<number>): Object

                      聚合操作符。向下取整,返回大于或等于给定数字的最小整数。

                      AggregateCommand.gt(value: Expression[]): Object

                      聚合操作符。匹配两个值,如果前者大于后者则返回 true,否则返回 false。

                      AggregateCommand.gte(value: Expression[]): Object

                      聚合操作符。匹配两个值,如果前者大于或等于后者则返回 true,否则返回 false。

                      AggregateCommand.hour(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的小时数,是一个介于 0 到 23 之间的整数。

                      AggregateCommand.ifNull(value: Expression[]): Object

                      聚合操作符。计算给定的表达式,如果表达式结果为 null、undefined 或者不存在,那么返回一个替代值;否则返回原值。

                      AggregateCommand.in(value: Expression[]): Object

                      聚合操作符。给定一个值和一个数组,如果值在数组中则返回 true,否则返回 false。

                      AggregateCommand.indexOfArray(value: Expression[]): Object

                      聚合操作符。在数组中找出等于给定值的第一个元素的下标,如果找不到则返回 -1。

                      AggregateCommand.indexOfBytes(value: Expression[]): Object

                      聚合操作符。在目标字符串中查找子字符串,并返回第一次出现的 UTF-8 的字节索引(从0开始)。如果不存在子字符串,返回 -1。

                      AggregateCommand.indexOfCP(value: Expression[]): Object

                      聚合操作符。在目标字符串中查找子字符串,并返回第一次出现的 UTF-8 的 code point 索引(从0开始)。如果不存在子字符串,返回 -1。

                      AggregateCommand.isArray(value: Expression): Object

                      聚合操作符。判断给定表达式是否是数组,返回布尔值。

                      AggregateCommand.isoDayOfWeek(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的 ISO 8601 标准的天数(一周中的第几天),是一个介于 1(周一)到 7(周日)之间的整数。

                      AggregateCommand.isoWeek(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的 ISO 8601 标准的周数(一年中的第几周),是一个介于 1 到 53 之间的整数。

                      AggregateCommand.isoWeekYear(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的 ISO 8601 标准的天数(一年中的第几天)。

                      AggregateCommand.last(value: Expression): Object

                      聚合操作符。返回指定字段在一组集合的最后一条记录对应的值。仅当这组集合是按照某种定义排序( sort )后,此操作才有意义。

                      AggregateCommand.let(value: any): Object

                      聚合操作符。自定义变量,并且在指定表达式中使用,返回的结果是表达式的结果。

                      AggregateCommand.literal(value: any): Object

                      聚合操作符。直接返回一个值的字面量,不经过任何解析和处理。

                      AggregateCommand.ln(value: Expression<number>): Object

                      聚合操作符。计算给定数字在自然对数值。

                      AggregateCommand.log(value: Expression[]): Object

                      聚合操作符。计算给定数字在给定对数底下的 log 值。

                      AggregateCommand.log10(value: Expression<number>): Object

                      聚合操作符。计算给定数字在对数底为 10 下的 log 值。

                      AggregateCommand.lt(value: Expression[]): Object

                      聚合操作符。匹配两个值,如果前者小于后者则返回 true,否则返回 false。

                      AggregateCommand.lte(value: Expression[]): Object

                      聚合操作符。匹配两个值,如果前者小于或等于后者则返回 true,否则返回 false。

                      AggregateCommand.map(value: any): Object

                      聚合操作符。类似 JavaScript Array 上的 map 方法,将给定数组的每个元素按给定转换方法转换后得出新的数组。

                      AggregateCommand.max(value: Expression): Object

                      聚合操作符。返回一组数值的最大值。

                      AggregateCommand.mergeObjects(value: Expression<document>): Object

                      聚合操作符。将多个文档合并为单个文档。

                      AggregateCommand.millisecond(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的毫秒数,是一个介于 0 到 999 之间的整数。

                      AggregateCommand.min(value: Expression): Object

                      聚合操作符。返回一组数值的最小值。

                      AggregateCommand.minute(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的分钟数,是一个介于 0 到 59 之间的整数。

                      AggregateCommand.mod(value: Expression[]): Object

                      聚合操作符。取模运算,取数字取模后的值。

                      AggregateCommand.month(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的月份,是一个介于 1 到 12 之间的整数。

                      AggregateCommand.multiply(value: Expression[]): Object

                      聚合操作符。取传入的数字参数相乘的结果。

                      AggregateCommand.neq(value: Expression[]): Object

                      聚合操作符。匹配两个值,如果不相等则返回 true,否则返回 false。

                      AggregateCommand.not(value: Expression): Object

                      聚合操作符。给定一个表达式,如果表达式返回 true,则 not 返回 false,否则返回 true。注意表达式不能为逻辑表达式(and、or、nor、not)。

                      AggregateCommand.objectToArray(value: Expression<object>): Object

                      聚合操作符。将一个对象转换为数组。方法把对象的每个键值对都变成输出数组的一个元素,元素形如 { k: <key>, v: <value> }。

                      AggregateCommand.or(value: Expression[]): Object

                      聚合操作符。给定多个表达式,如果任意一个表达式返回 true,则 or 返回 true,否则返回 false。

                      AggregateCommand.pow(value: Expression[]): Object

                      聚合操作符。求给定基数的指数次幂。

                      AggregateCommand.push(value: any): Object

                      聚合操作符。在 group 阶段,返回一组中表达式指定列与对应的值,一起组成的数组。

                      AggregateCommand.range(value: Expression[]): Object

                      聚合操作符。返回一组生成的序列数字。给定开始值、结束值、非零的步长,range 会返回从开始值开始逐步增长、步长为给定步长、但不包括结束值的序列。

                      AggregateCommand.reduce(value: any): Object

                      聚合操作符。类似 JavaScript 的 reduce 方法,应用一个表达式于数组各个元素然后归一成一个元素。

                      AggregateCommand.reverseArray(value: Expression<any[]>): Object

                      聚合操作符。返回给定数组的倒序形式。

                      AggregateCommand.second(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的秒数,是一个介于 0 到 59 之间的整数,在特殊情况下(闰秒)可能等于 60。

                      AggregateCommand.setDifference(value: Expression[]): Object

                      聚合操作符,输入两个集合,输出只存在于第一个集合中的元素。

                      AggregateCommand.setEquals(value: Expression[]): Object

                      聚合操作符,输入两个集合,判断两个集合中包含的元素是否相同(不考虑顺序、去重)。

                      AggregateCommand.setIntersection(value: Expression[]): Object

                      聚合操作符,输入两个集合,输出两个集合的交集。

                      AggregateCommand.setIsSubset(value: Expression[]): Object

                      聚合操作符,输入两个集合,判断第一个集合是否是第二个集合的子集。

                      AggregateCommand.setUnion(value: Expression[]): Object

                      聚合操作符,输入两个集合,输出两个集合的并集。

                      AggregateCommand.size(value: Expression<any[]>): Object

                      聚合操作符。返回数组长度。

                      AggregateCommand.slice(value: Expression[]): Object

                      聚合操作符。类似 JavaScritp 的 slice 方法。返回给定数组的指定子集。

                      AggregateCommand.split(value: Expression[]): Object

                      聚合操作符。按照分隔符分隔数组,并且删除分隔符,返回子字符串组成的数组。如果字符串无法找到分隔符进行分隔,返回原字符串作为数组的唯一元素。

                      AggregateCommand.sqrt(value: Expression[]): Object

                      聚合操作符。求平方根。

                      AggregateCommand.stdDevPop(value: Expression): Object

                      聚合操作符。返回一组字段对应值的标准差。

                      AggregateCommand.stdDevSamp(value: Expression): Object

                      聚合操作符。计算输入值的样本标准偏差。如果输入值代表数据总体,或者不概括更多的数据,请改用 db.command.aggregate.stdDevPop。

                      AggregateCommand.strLenBytes(value: Expression): Object

                      聚合操作符。计算并返回指定字符串中 utf-8 编码的字节数量。

                      AggregateCommand.strLenCP(value: Expression): Object

                      聚合操作符。计算并返回指定字符串的UTF-8 code points 数量。

                      AggregateCommand.strcasecmp(value: Expression[]): Object

                      聚合操作符。对两个字符串在不区分大小写的情况下进行大小比较,并返回比较的结果。

                      AggregateCommand.substr(value: Expression[]): Object

                      聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。它是 db.command.aggregate.substrBytes 的别名,更推荐使用后者。

                      AggregateCommand.substrBytes(value: Expression[]): Object

                      聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。子字符串是由字符串中指定的 UTF-8 字节索引的字符开始,长度为指定的字节数。

                      AggregateCommand.substrCP(value: Expression[]): Object

                      聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。子字符串是由字符串中指定的 UTF-8 字节索引的字符开始,长度为指定的字节数。

                      AggregateCommand.subtract(value: Expression[]): Object

                      聚合操作符。将两个数字相减然后返回差值,或将两个日期相减然后返回相差的毫秒数,或将一个日期减去一个数字返回结果的日期。

                      AggregateCommand.sum(value: Expression): Object

                      聚合操作符。计算并且返回一组字段所有数值的总和。

                      AggregateCommand.switch(value: any): Object

                      聚合操作符。根据给定的 switch-case-default 计算返回值、

                      AggregateCommand.toLower(value: any): Object

                      聚合操作符。将字符串转化为小写并返回。

                      AggregateCommand.toUpper(value: any): Object

                      聚合操作符。将字符串转化为大写并返回。

                      AggregateCommand.trunc(value: Expression<number>): Object

                      聚合操作符。将数字截断为整形。

                      AggregateCommand.week(value: Expression<string>): Object

                      聚合操作符。返回日期字段对应的周数(一年中的第几周),是一个介于 0 到 53 之间的整数。

                      Expression

                      聚合表达式

                      说明

                      表达式可以是字段路径、常量、或聚合操作符。表达式可以嵌套表达式。

                      字段路径

                      表达式用字段路径表示法来指定记录中的字段。字段路径的表示由一个 $ 符号加上字段名或嵌套字段名。嵌套字段名用点将嵌套的各级字段连接起来。如 $profile 就表示 profile 的字段路径,$profile.name 就表示 profile.name 的字段路径(profile 字段中嵌套的 name 字段)。

                      常量

                      常量可以是任意类型。默认情况下 $ 开头的字符串都会被当做字段路径处理,如果想要避免这种行为,使用 AggregateCommand.literal 声明为常量。

                      聚合操作符

                      AggregateCommand


                      AggregateCommand.abs(value: Expression<number>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回一个数字的绝对值。

                      参数

                      value: Expression<number>

                      number

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.abs(<number>)

                      abs 传入的值除了数字常量外,也可以是任何最终解析成一个数字的表达式。

                      如果表达式解析为 null 或者指向一个不存在的字段,则 abs 的结果是 null。如果值解析为 NaN,则结果是 NaN。

                      示例代码

                      假设集合 ratings 有如下记录:

                      { _id: 1, start: 5, end: 8 }{ _id: 2, start: 4, end: 4 }{ _id: 3, start: 9, end: 7 }{ _id: 4, start: 6, end: 7 }

                      ··· 可以用如下方式求得各个记录的 start 和 end 之间的绝对差异大小:

                      const $ = db.command.aggregatedb.collection('ratings').aggregate()  .project({    delta: $.abs($.subtract(['$start', '$end']))  })  .end()

                      返回结果如下:

                      { "_id" : 1, "delta" : 3 }{ "_id" : 2, "delta" : 0 }{ "_id" : 3, "delta" : 2 }{ "_id" : 4, "delta" : 1 }

                      AggregateCommand.add(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将数字相加或将数字加在日期上。如果数组中的其中一个值是日期,那么其他值将被视为毫秒数加在该日期上。

                      参数

                      value: Expression[]

                      [<表达式1>, <表达式2>, ...]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.add([<表达式1>, <表达式2>, ...])

                      表达式可以是形如 $ + 指定字段,也可以是普通字符串。只要能够被解析成字符串即可。

                      示例代码

                      假设集合 staff 有如下记录:

                      { _id: 1, department: "x", sales: 5, engineer: 10, lastUpdate: ISODate("2019-05-01T00:00:00Z") }{ _id: 2, department: "y", sales: 10, engineer: 20, lastUpdate: ISODate("2019-05-01T02:00:00Z") }{ _id: 3, department: "z", sales: 20, engineer: 5, lastUpdate: ISODate("2019-05-02T03:00:00Z") }

                      数字求和

                      可以用如下方式求得各个记录人数总数:

                      const $ = db.command.aggregatedb.collection('staff').aggregate()  .project({    department: 1,    total: $.add(['$sales', '$engineer'])  })  .end()

                      返回结果如下:

                      { _id: 1, department: "x", total: 15 }{ _id: 2, department: "y", total: 30 }{ _id: 3, department: "z", total: 25 }

                      增加日期值

                      如下操作可以获取各个记录的 lastUpdate 加一个小时之后的值:

                      const $ = db.command.aggregatedb.collection('staff').aggregate()  .project({    department: 1,    lastUpdate: $.add(['$lastUpdate', 60*60*1000])  })  .end()

                      返回结果如下:

                      { _id: 1, department: "x", lastUpdate: ISODate("2019-05-01T01:00:00Z") }{ _id: 2, department: "y", lastUpdate: ISODate("2019-05-01T03:00:00Z") }{ _id: 3, department: "z", lastUpdate: ISODate("2019-05-02T04:00:00Z") }

                      AggregateCommand.ceil(value: Expression<number>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。向上取整,返回大于或等于给定数字的最小整数。

                      参数

                      value: Expression<number>

                      number

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.ceil(<number>)

                      <number> 可以是任意解析为数字的表达式。如果表达式解析为 null 或指向一个不存在的字段,则返回 null,如果解析为 NaN,则返回 NaN。

                      示例代码

                      假设集合 sales 有如下记录:

                      { _id: 1, sales: 5.2 }{ _id: 2, sales: 1.32 }{ _id: 3, sales: -3.2 }

                      可以用如下方式取各个数字的向上取整值:

                      const $ = db.command.aggregatedb.collection('sales').aggregate()  .project({    sales: $.ceil('$sales')  })  .end()

                      返回结果如下:

                      { _id: 1, sales: 6 }{ _id: 2, sales: 2 }{ _id: 3, sales: -3 }

                      AggregateCommand.divide(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。传入被除数和除数,求商。

                      参数

                      value: Expression[]

                      [<被除数表达式>, <除数表达式>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.divide([<被除数表达式>, <除数表达式>])

                      表达式可以是任意解析为数字的表达式。

                      示例代码

                      假设集合 railroads 有如下记录:

                      { _id: 1, meters: 5300 }{ _id: 2, meters: 64000 }{ _id: 3, meters: 130 }

                      可以用如下方式取各个数字转换为千米之后的值:

                      const $ = db.command.aggregatedb.collection('railroads').aggregate()  .project({    km: $.divide(['$meters', 1000])  })  .end()

                      返回结果如下:

                      { _id: 1, km: 5.3 }{ _id: 2, km: 64 }{ _id: 3, km: 0.13 }

                      AggregateCommand.exp(value: Expression<number>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。取 e(自然对数的底数,欧拉数) 的 n 次方。

                      参数

                      value: Expression<number>

                      exponent

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.exp(<exponent>)

                      <exponent> 可以是任意解析为数字的表达式。如果表达式解析为 null 或指向一个不存在的字段,则返回 null,如果解析为 NaN,则返回 NaN。

                      示例代码

                      假设集合 math 有如下记录:

                      { _id: 1, exp: 0 }{ _id: 2, exp: 1 }{ _id: 3, exp: 2 }
                      const $ = db.command.aggregatedb.collection('math').aggregate()  .project({    result: $.exp('$exp')  })  .end()

                      返回结果如下:

                      { _id: 1, result: 1 }{ _id: 2, result: 2.71828182845905 }{ _id: 3, result: 7.38905609893065 }

                      AggregateCommand.floor(value: Expression<number>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。向下取整,返回大于或等于给定数字的最小整数。

                      参数

                      value: Expression<number>

                      number

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.floor(<number>)

                      <number> 可以是任意解析为数字的表达式。如果表达式解析为 null 或指向一个不存在的字段,则返回 null,如果解析为 NaN,则返回 NaN。

                      示例代码

                      假设集合 sales 有如下记录:

                      { _id: 1, sales: 5.2 }{ _id: 2, sales: 1.32 }{ _id: 3, sales: -3.2 }

                      可以用如下方式取各个数字的向下取整值:

                      const $ = db.command.aggregatedb.collection('sales').aggregate()  .project({    sales: $.floor('$sales')  })  .end()

                      返回结果如下:

                      { _id: 1, sales: 5 }{ _id: 2, sales: 1 }{ _id: 3, sales: -6 }

                      AggregateCommand.ln(value: Expression<number>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。计算给定数字在自然对数值。

                      参数

                      value: Expression<number>

                      number

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.ln(<number>)

                      <number> 可以是任意解析为非负数字的表达式。

                      ln 等价于 log([<number>, Math.E]),其中 Math.E 是 JavaScript 获取 e 的值的方法。

                      示例代码

                      db.command.aggregate.ln

                      聚合操作符。计算给定数字在自然对数值。

                      语法如下:

                      db.command.aggregate.ln(<number>)

                      <number> 可以是任意解析为非负数字的表达式。

                      ln 等价于 log([<number>, Math.E]),其中 Math.E 是 JavaScript 获取 e 的值的方法。


                      AggregateCommand.log(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。计算给定数字在给定对数底下的 log 值。

                      参数

                      value: Expression[]

                      [<number>, <base>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.log([<number>, <base>])

                      <number> 可以是任意解析为非负数字的表达式。<base> 可以是任意解析为大于 1 的数字的表达式。

                      如果任一参数解析为 null 或指向任意一个不存在的字段,log 返回 null。如果任一参数解析为 NaN,log 返回 NaN。

                      示例代码

                      假设集合 curve 有如下记录:

                      { _id: 1, x: 1 }{ _id: 2, x: 2 }{ _id: 3, x: 3 }

                      计算 log2(x) 的值:

                      const $ = db.command.aggregatedb.collection('staff').aggregate()  .project({    log: $.log(['$x', 2])  })  .end()

                      返回结果如下:

                      { _id: 1, log: 0 }{ _id: 2, log: 1 }{ _id: 3, log: 1.58496250072 }

                      AggregateCommand.log10(value: Expression<number>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。计算给定数字在对数底为 10 下的 log 值。

                      参数

                      value: Expression<number>

                      number

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.log(<number>)

                      <number> 可以是任意解析为非负数字的表达式。

                      log10 等同于 log 方法的第二个参数固定为 10。

                      示例代码

                      db.command.aggregate.log10

                      聚合操作符。计算给定数字在对数底为 10 下的 log 值。

                      语法如下:

                      db.command.aggregate.log(<number>)

                      <number> 可以是任意解析为非负数字的表达式。

                      log10 等同于 log 方法的第二个参数固定为 10。


                      AggregateCommand.mod(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。取模运算,取数字取模后的值。

                      参数

                      value: Expression[]

                      [<dividend>, <divisor>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.mod([<dividend>, <divisor>])

                      第一个数字是被除数,第二个数字是除数。参数可以是任意解析为数字的表达式。

                      示例代码

                      假设集合 shopping 有如下记录:

                      { _id: 1, bags: 3, items: 5 }{ _id: 2, bags: 2, items: 8 }{ _id: 3, bags: 5, items: 16 }

                      各记录取 items 除以 bags 的余数(items % bags):

                      const $ = db.command.aggregatedb.collection('shopping').aggregate()  .project({    overflow: $.mod(['$items', '$bags'])  })  .end()

                      返回结果如下:

                      { _id: 1, log: 2 }{ _id: 2, log: 0 }{ _id: 3, log: 1 }

                      AggregateCommand.multiply(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。取传入的数字参数相乘的结果。

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>, ...]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.multiply([<expression1>, <expression2>, ...])

                      参数可以是任意解析为数字的表达式。

                      示例代码

                      假设集合 fruits 有如下记录:

                      { "_id": 1, "name": "apple", "price": 10, "quantity": 100 }{ "_id": 2, "name": "orange", "price": 15, "quantity": 50 }{ "_id": 3, "name": "lemon", "price": 5, "quantity": 20 }

                      求各个水果的的总价值:

                      const $ = db.command.aggregatedb.collection('fruits').aggregate()  .project({    name: 1,    total: $.multiply(['$price', '$quantity']),  })  .end()

                      返回结果如下:

                      { "_id": 1, "name": "apple", "total": 1000 }{ "_id": 2, "name": "orange", "total": 750 }{ "_id": 3, "name": "lemo", "total": 100 }

                      AggregateCommand.pow(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。求给定基数的指数次幂。

                      参数

                      value: Expression[]

                      [<base>, <exponent>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.pow([<base>, <exponent>])

                      参数可以是任意解析为数字的表达式。

                      示例代码

                      假设集合 stats 有如下记录:

                      { "_id": 1, "x": 2, "y": 3 }{ "_id": 2, "x": 5, "y": 7 }{ "_id": 3, "x": 10, "y": 20 }

                      求 x 和 y 的平方和:

                      const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    sumOfSquares: $.add([$.pow(['$x', 2]), $.pow(['$y', 2])]),  })  .end()

                      返回结果如下:

                      { "_id": 1, "sumOfSquares": 13 }{ "_id": 2, "sumOfSquares": 74 }{ "_id": 3, "sumOfSquares": 500 }

                      AggregateCommand.sqrt(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。求平方根。

                      参数

                      value: Expression[]

                      [<number>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.sqrt([<number>])

                      参数可以是任意解析为非负数字的表达式。

                      示例代码

                      假设直角三角形集合 triangle 有如下记录:

                      { "_id": 1, "x": 2, "y": 3 }{ "_id": 2, "x": 5, "y": 7 }{ "_id": 3, "x": 10, "y": 20 }

                      假设 x 和 y 分别为两直角边,则求斜边长:

                      const $ = db.command.aggregatedb.collection('triangle').aggregate()  .project({    len: $.sqrt([$.add([$.pow(['$x', 2]), $.pow(['$y', 2])])]),  })  .end()

                      返回结果如下:

                      { "_id": 1, "len": 3.605551275463989 }{ "_id": 2, "len": 8.602325267042627 }{ "_id": 3, "len": 22.360679774997898 }

                      AggregateCommand.subtract(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将两个数字相减然后返回差值,或将两个日期相减然后返回相差的毫秒数,或将一个日期减去一个数字返回结果的日期。

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.subtract([<expression1>, <expression2>])

                      参数可以是任意解析为数字或日期的表达式。

                      示例代码

                      假设集合 scores 有如下记录:

                      { "_id": 1, "max": 10, "min": 1 }{ "_id": 2, "max": 7, "min": 5 }{ "_id": 3, "max": 6, "min": 6 }

                      求各个记录的 max 和 min 的差值。:

                      const $ = db.command.aggregatedb.collection('scores').aggregate()  .project({    diff: $.subtract(['$max', '$min'])  })  .end()

                      返回结果如下:

                      { "_id": 1, "diff": 9 }{ "_id": 2, "diff": 2 }{ "_id": 3, "diff": 0 }

                      AggregateCommand.trunc(value: Expression<number>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将数字截断为整形。

                      参数

                      value: Expression<number>

                      number

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.trunc(<number>)

                      参数可以是任意解析为数字的表达式。

                      示例代码

                      假设集合 scores 有如下记录:

                      { "_id": 1, "value": 1.21 }{ "_id": 2, "value": 3.83 }{ "_id": 3, "value": -4.94 }
                      const $ = db.command.aggregatedb.collection('scores').aggregate()  .project({    int: $.trunc('$value')  })  .end()

                      返回结果如下:

                      { "_id": 1, "value": 1 }{ "_id": 2, "value": 3 }{ "_id": 3, "value": -4 }


                      AggregateCommand.arrayElemAt(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回在指定数组下标的元素。

                      参数

                      value: Expression[]

                      [<array>, <index>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.arrayElemAt([<array>, <index>])

                      <array> 可以是任意解析为数字的表达式。

                      <index> 可以是任意解析为整形的表达式。如果是正数,arrayElemAt 返回在 index 位置的元素,如果是负数,arrayElemAt 返回从数组尾部算起的 index 位置的元素。

                      示例代码

                      假设集合 exams 有如下记录:

                      { "_id": 1, "scores": [80, 60, 65, 90] }{ "_id": 2, "scores": [78] }{ "_id": 3, "scores": [95, 88, 92] }

                      求各个第一次考试的分数和和最后一次的分数:

                      const $ = db.command.aggregatedb.collection('exams').aggregate()  .project({    first: $.arrayElemAt(['$scores', 0]),    last: $.arrayElemAt(['$scores', -1]),  })  .end()

                      返回结果如下:

                      { "_id": 1, "first": 80, "last": 90 }{ "_id": 2, "first": 78, "last": 78 }{ "_id": 3, "first": 95, "last": 92 }

                      AggregateCommand.arrayToObject(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将一个数组转换为对象。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      语法可以取两种:

                      第一种:传入一个二维数组,第二维的数组长度必须为 2,其第一个值为字段名,第二个值为字段值

                      db.command.aggregate.arrayToObject([  [<key1>, <value1>],  [<key2>, <value2>],  ...])

                      第二种:传入一个对象数组,各个对象必须包含字段 k 和 v,分别指定字段名和字段值

                      db.command.aggregate.arrayToObject([  { "k": <key1>, "v": <value1> },  { "k": <key2>, "v": <value2> },  ...])

                      传入 arrayToObject 的参数只要可以解析为上述两种表示法之一即可。

                      示例代码

                      假设集合 shops 有如下记录:

                      { "_id": 1, "sales": [ ["max", 100], ["min", 50] ] }{ "_id": 2, "sales": [ ["max", 70], ["min", 60] ] }{ "_id": 3, "sales": [ { "k": "max", "v": 50 }, { "k": "min", "v": 30 } ] }

                      求各个第一次考试的分数和和最后一次的分数:

                      const $ = db.command.aggregatedb.collection('shops').aggregate()  .project({    sales: $.arrayToObject('$sales'),  })  .end()

                      返回结果如下:

                      { "_id": 1, "sales": { "max": 100, "min": 50 } }{ "_id": 2, "sales": { "max": 70, "min": 60 } }{ "_id": 3, "sales": { "max": 50, "min": 30 } }

                      AggregateCommand.concatArrays(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将多个数组拼接成一个数组。

                      参数

                      value: Expression[]

                      [ <array1>, <array2>, ... ]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.arrayToObject([ <array1>, <array2>, ... ])

                      参数可以是任意解析为数组的表达式。

                      示例代码

                      假设集合 items 有如下记录:

                      { "_id": 1, "fruits": [ "apple" ], "vegetables": [ "carrot" ] }{ "_id": 2, "fruits": [ "orange", "lemon" ], "vegetables": [ "cabbage" ] }{ "_id": 3, "fruits": [ "strawberry" ], "vegetables": [ "spinach" ] }
                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    list: $.concatArrays(['$fruits', '$vegetables']),  })  .end()

                      返回结果如下:

                      { "_id": 1, "list": [ "apple", "carrot" ] }{ "_id": 2, "list": [ "orange", "lemon", "cabbage" ] }{ "_id": 3, "list": [ "strawberry", "spinach" ] }

                      AggregateCommand.filter(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。根据给定条件返回满足条件的数组的子集。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.filter({  input: <array>,  as: <string>,  cond: <expression>})
                      字段说明
                      input一个可以解析为数组的表达式
                      as可选,用于表示数组各个元素的变量,默认为 this
                      cond一个可以解析为布尔值的表达式,用于判断各个元素是否满足条件,各个元素的名字由 as 参数决定(参数名需加 $$ 前缀,如 $$this

                      参数可以是任意解析为数组的表达式。

                      示例代码

                      假设集合 fruits 有如下记录:

                      {  "_id": 1,  "stock": [    { "name": "apple", "price": 10 },    { "name": "orange", "price": 20 }  ],}{  "_id": 2,  "stock": [    { "name": "lemon", "price": 15 },  ],}
                      const _ = db.commandconst $ = db.command.aggregatedb.collection('fruits').aggregate()  .project({    stock: $.filter({      input: '$stock',      as: 'item',      cond: $.gte(['$$item.price', 15])    })  })  .end()

                      返回结果如下:

                      { "_id": 1, "stock": [ { "name": "orange", "price": 20} ] }{ "_id": 2, "stock": [ { "name": "lemon", "price": 15 } ] }

                      AggregateCommand.in(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。给定一个值和一个数组,如果值在数组中则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value>, <array>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.in([<value>, <array>])

                      <value> 可以是任意表达式。

                      <array> 可以是任意解析为数组的表达式。

                      示例代码

                      假设集合 shops 有如下记录:

                      { "_id": 1, "topsellers": ["bread", "ice cream", "butter"] }{ "_id": 2, "topsellers": ["ice cream", "cheese", "yagurt"] }{ "_id": 3, "topsellers": ["croissant", "cucumber", "coconut"] }

                      标记销量最高的商品包含 ice cream 的记录。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    included: $.in(['ice cream', '$topsellers'])  })  .end()

                      返回结果如下:

                      { "_id": 1, "included": true }{ "_id": 2, "included": true }{ "_id": 3, "included": false }

                      AggregateCommand.indexOfArray(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。在数组中找出等于给定值的第一个元素的下标,如果找不到则返回 -1。

                      参数

                      value: Expression[]

                      [ <array expression>, <search expression>, <start>, <end> ]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.indexOfArray([ <array expression>, <search expression>, <start>, <end> ])
                      字段类型说明
                      <array>string一个可以解析为数组的表达式,如果解析为 null,则 indexOfArray 返回 null
                      <search>string对数据各个元素应用的条件匹配表达式
                      <start>integer可选,用于指定搜索的开始下标,必须是非负整数
                      <end>integer可选,用于指定搜索的结束下标,必须是非负整数,指定了 <end> 时也应指定 <start>,否则 <end> 默认当做 <start>

                      参数可以是任意解析为数组的表达式。

                      示例代码

                      假设集合 stats 有如下记录:

                      {  "_id": 1,  "sales": [ 1, 6, 2, 2, 5 ]}{  "_id": 2,  "sales": [ 4, 2, 1, 5, 2 ]}{  "_id": 3,  "sales": [ 2, 5, 3, 3, 1 ]}
                      const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    index: $.indexOfArray(['$sales', 2, 2])  })  .end()

                      返回结果如下:

                      { "_id": 1, "index": 2 }{ "_id": 2, "index": 4 }{ "_id": 3, "index": -1 }

                      AggregateCommand.isArray(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。判断给定表达式是否是数组,返回布尔值。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.isArray(<expression>)

                      参数可以是任意表达式。

                      示例代码

                      假设集合 stats 有如下记录:

                      {  "_id": 1,  "base": 10,  "sales": [ 1, 6, 2, 2, 5 ]}{  "_id": 2,  "base": 1,  "sales": 100}

                      计算总销量,如果 sales 是数字,则求 sales * base,如果 sales 是数组,则求数组元素之和与 base 的乘积。

                      const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    sum: $.cond({      if: $.isArray('$sales'),      then: $.multiply([$.sum(['$sales']), '$base']),      else: $.multiply(['$sales', '$base']),    })  })  .end()

                      返回结果如下:

                      { "_id": 1, "index": 160 }{ "_id": 2, "index": 100 }

                      AggregateCommand.map(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。类似 JavaScript Array 上的 map 方法,将给定数组的每个元素按给定转换方法转换后得出新的数组。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.map({  input: <expression>,  as: <string>,  in: <expression>})
                      字段说明
                      input一个可以解析为数组的表达式
                      as可选,用于表示数组各个元素的变量,默认为 this
                      in一个可以应用在给定数组的各个元素上的表达式,各个元素的名字由 as 参数决定(参数名需加 $$ 前缀,如 $$this

                      示例代码

                      假设集合 stats 有如下记录:

                      {  "_id": 1,  "sales": [ 1.32, 6.93, 2.48, 2.82, 5.74 ]}{  "_id": 2,  "sales": [ 2.97, 7.13, 1.58, 6.37, 3.69 ]}

                      将各个数字截断为整形,然后求和

                      const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    truncated: $.map({      input: '$sales',      as: 'num',      in: $.trunc('$$num'),    })  })  .project({    total: $.sum('$truncated')  })  .end()

                      返回结果如下:

                      { "_id": 1, "index": 16 }{ "_id": 2, "index": 19 }

                      AggregateCommand.objectToArray(value: Expression<object>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将一个对象转换为数组。方法把对象的每个键值对都变成输出数组的一个元素,元素形如 { k: &lt;key&gt;, v: &lt;value&gt; }。

                      参数

                      value: Expression<object>

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.objectToArray(<object>)

                      示例代码

                      假设集合 items 有如下记录:

                      { "_id": 1, "attributes": { "color": "red", "price": 150 } }{ "_id": 2, "attributes": { "color": "blue", "price": 50 } }{ "_id": 3, "attributes": { "color": "yellow", "price": 10 } }
                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    array: $.objectToArray('$attributes')  })  .end()

                      返回结果如下:

                      { "_id": 1, "array": [{ "k": "color", "v": "red" }, { "k": "price", "v": 150 }] }{ "_id": 2, "array": [{ "k": "color", "v": "blue" }, { "k": "price", "v": 50 }] }{ "_id": 3, "array": [{ "k": "color", "v": "yellow" }, { "k": "price", "v": 10 }] }

                      AggregateCommand.range(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回一组生成的序列数字。给定开始值、结束值、非零的步长,range 会返回从开始值开始逐步增长、步长为给定步长、但不包括结束值的序列。

                      参数

                      value: Expression[]

                      [<start>, <end>, <non-zero step>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.range([<start>, <end>, <non-zero step>])
                      字段说明
                      start开始值,一个可以解析为整形的表达式
                      end结束值,一个可以解析为整形的表达式
                      non-zero step可选,步长,一个可以解析为非零整形的表达式,默认为 1

                      示例代码

                      假设集合 stats 有如下记录:

                      { "_id": 1, "max": 52 }{ "_id": 2, "max": 38 }
                      const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    points: $.range([0, '$max', 10])  })  .end()

                      返回结果如下:

                      { "_id": 1, "points": [0, 10, 20, 30, 40, 50] }{ "_id": 2, "points": [0, 10, 20] }

                      AggregateCommand.reduce(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。类似 JavaScript 的 reduce 方法,应用一个表达式于数组各个元素然后归一成一个元素。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.reduce({  input: <array>  initialValue: <expression>,  in: <expression>})
                      字段说明
                      input输入数组,可以是任意解析为数组的表达式
                      initialValue初始值
                      in用来作用于每个元素的表达式,在 in 中有两个可用变量,value 是表示累计值的变量,this 是表示当前数组元素的变量

                      示例代码

                      简易字符串拼接

                      假设集合 player 有如下记录:

                      { "_id": 1, "fullname": [ "Stephen", "Curry" ] }{ "_id": 2, "fullname": [ "Klay", "Thompsom" ] }

                      获取各个球员的全名,并加 Player: 前缀:

                      const $ = db.command.aggregatedb.collection('player').aggregate()  .project({    info: $.reduce({      input: '$fullname',      initialValue: 'Player:',      in: $.concat(['$$value', ' ', '$$this']),    })  })  .end()

                      返回结果如下:

                      { "_id": 1, "info": "Player: Stephen Curry" }{ "_id": 2, "info": "Player: Klay Thompson" }

                      获取各个球员的全名,不加前缀:

                      const $ = db.command.aggregatedb.collection('player').aggregate()  .project({    name: $.reduce({      input: '$fullname',      initialValue: '',      in: $.concat([        '$$value',        $.cond({          if: $.eq(['$$value', '']),          then: '',          else: ' ',        }),        '$$this',      ]),    })  })  .end()

                      返回结果如下:

                      { "_id": 1, "name": "Stephen Curry" }{ "_id": 2, "name": "Klay Thompson" }

                      AggregateCommand.reverseArray(value: Expression<any[]>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回给定数组的倒序形式。

                      参数

                      value: Expression<any[]>

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.reverseArray(<array>)

                      参数可以是任意解析为数组表达式。

                      示例代码

                      假设集合 stats 有如下记录:

                      {  "_id": 1,  "sales": [ 1, 2, 3, 4, 5 ]}

                      取 sales 倒序:

                      const $ = db.command.aggregatedb.collection('stats').aggregate()  .project({    reversed: $.reverseArray('$sales'),  })  .end()

                      返回结果如下:

                      { "_id": 1, "reversed": [5, 4, 3, 2, 1] }

                      AggregateCommand.size(value: Expression<any[]>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回数组长度。

                      参数

                      value: Expression<any[]>

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.size(<array>)

                      <array> 可以是任意解析为数组的表达式。

                      示例代码

                      假设集合 shops 有如下记录:

                      { "_id": 1, "staff": [ "John", "Middleton", "George" ] }{ "_id": 2, "staff": [ "Steph", "Jack" ] }

                      计算各个商店的雇员数量:

                      const $ = db.command.aggregatedb.collection('staff').aggregate()  .project({    totalStaff: $.size('$staff')  })  .end()

                      返回结果如下:

                      { "_id": 1, "totalStaff": 3 }{ "_id": 2, "totalStaff": 2 }

                      AggregateCommand.slice(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。类似 JavaScritp 的 slice 方法。返回给定数组的指定子集。

                      参数

                      value: Expression[]

                      [<array>, <n>]

                      返回值

                      Object

                      API 说明

                      语法有两种:

                      返回从开头或结尾开始的 n 个元素:

                      db.command.aggregate.slice([<array>, <n>])

                      返回从指定位置算作数组开头、再向后或向前的 n 个元素:

                      db.command.aggregate.slice([<array>, <position>, <n>])

                      <array> 可以是任意解析为数组的表达式。

                      <position> 可以是任意解析为整形的表达式。如果是正数,则将数组的第 <position> 个元素作为数组开始;如果 <position> 比数组长度更长,slice 返回空数组。如果是负数,则将数组倒数第 <position> 个元素作为数组开始;如果 <position> 的绝对值大于数组长度,则开始位置即为数组开始位置。

                      <n> 可以是任意解析为整形的表达式。如果 <position> 有提供,则 <n> 必须为正整数。如果是正数,slice 返回前 n 个元素。如果是负数,slice 返回后 n 个元素。

                      示例代码

                      假设集合 people 有如下记录:

                      { "_id": 1, "hobbies": [ "basketball", "football", "tennis", "badminton" ] }{ "_id": 2, "hobbies": [ "golf", "handball" ] }{ "_id": 3, "hobbies": [ "table tennis", "swimming", "rowing" ] }

                      统一返回前两个爱好:

                      const $ = db.command.aggregatedb.collection('fruits').aggregate()  .project({    hobbies: $.slice(['$hobbies', 2]),  })  .end()

                      返回结果如下:

                      { "_id": 1, "hobbies": [ "basketball", "football" ] }{ "_id": 2, "hobbies": [ "golf", "handball" ] }{ "_id": 3, "hobbies": [ "table tennis", "swimming" ] }

                      AggregateCommand.zip(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。把二维数组的第二维数组中的相同序号的元素分别拼装成一个新的数组进而组装成一个新的二维数组。如可将 [ [ 1, 2, 3 ], [ &#34;a&#34;, &#34;b&#34;, &#34;c&#34; ] ] 转换成 [ [ 1, &#34;a&#34; ], [ 2, &#34;b&#34; ], [ 3, &#34;c&#34; ] ]。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.zip({  inputs: [<array1>, <array2>, ...],  useLongestLength: <boolean>,  defaults: <array>})

                      inputs 是一个二维数组(inputs 不可以是字段引用),其中每个元素的表达式(这个可以是字段引用)都可以解析为数组。如果其中任意一个表达式返回 null,<inputs> 也返回 null。如果其中任意一个表达式不是指向一个合法的字段 / 解析为数组 / 解析为 null,则返回错误。

                      useLongestLength 决定输出数组的长度是否采用输入数组中的最长数组的长度。默认为 false,即输入数组中的最短的数组的长度即是输出数组的各个元素的长度。

                      defaults 是一个数组,用于指定在输入数组长度不一的情况下时采用的数组各元素默认值。指定这个字段则必须指定 useLongestLength,否则返回错误。如果 useLongestLength 是 true 但是 defaults 是空或没有指定,则 zip 用 null 做数组元素的缺省默认值。指定各元素默认值时 defaults 数组的长度必须是输入数组最大的长度。

                      示例代码

                      假设集合 stats 有如下记录:

                      { "_id": 1, "zip1": [1, 2], "zip2": [3, 4], "zip3": [5, 6] ] }{ "_id": 2, "zip1": [1, 2], "zip2": [3], "zip3": [4, 5, 6] ] }{ "_id": 3, "zip1": [1, 2], "zip2": [3] ] }

                      只传 inputs

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    zip: $.zip({      inputs: [        '$zip1', // 字段引用        '$zip2',        '$zip3',      ],    })  })  .end()

                      返回结果如下:

                      { "_id": 1, "zip": [ [1, 3, 5], [2, 4, 6] ] }{ "_id": 2, "zip": [ [1, 3, 4] ] }{ "_id": 3, "zip": null }

                      设置 useLongestLength

                      如果设 useLongestLength 为 true:

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    zip: $.zip({      inputs: [        '$zip1', // 字段引用        '$zip2',        '$zip3',      ],      useLongestLength: true,    })  })  .end()

                      返回结果如下:

                      { "_id": 1, "zip": [ [1, 3, 5], [2, 4, 6] ] }{ "_id": 2, "zip": [ [1, 3, 4], [2, null, 5], [null, null, 6] ] }{ "_id": 3, "zip": null }

                      设置 defaults

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    zip: $.zip({      inputs: [        '$zip1', // 字段引用        '$zip2',        '$zip3',      ],      useLongestLength: true,      defaults: [-300, -200, -100],    })  })  .end()

                      返回结果如下:

                      { "_id": 1, "zip": [ [1, 3, 5], [2, 4, 6] ] }{ "_id": 2, "zip": [ [1, 3, 4], [2, -200, 5], [-300, -200, 6] ] }{ "_id": 3, "zip": null }


                      AggregateCommand.and(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。给定多个表达式,and 仅在所有表达式都返回 true 时返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>, ...]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.and([<expression1>, <expression2>, ...])

                      如果表达式返回 false、null、0、或 undefined,表达式会解析为 false,否则对其他返回值都认为是 true。

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "min": 10, "max": 100 }{ "_id": 2, "min": 60, "max": 80 }{ "_id": 3, "min": 30, "max": 50 }

                      求 min 大于等于 30 且 max 小于等于 80 的记录。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    fullfilled: $.and([$.gte(['$min', 30]), $.lte(['$max', 80])])  })  .end()

                      返回结果如下:

                      { "_id": 1, "fullfilled": false }{ "_id": 2, "fullfilled": true }{ "_id": 3, "fullfilled": true }

                      AggregateCommand.not(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。给定一个表达式,如果表达式返回 true,则 not 返回 false,否则返回 true。注意表达式不能为逻辑表达式(and、or、nor、not)。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.not(<expression>)

                      如果表达式返回 false、null、0、或 undefined,表达式会解析为 false,否则对其他返回值都认为是 true。

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "min": 10, "max": 100 }{ "_id": 2, "min": 60, "max": 80 }{ "_id": 3, "min": 30, "max": 50 }

                      求 min 不大于 40 的记录。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    fullfilled: $.not($.gt(['$min', 40]))  })  .end()

                      返回结果如下:

                      { "_id": 1, "fullfilled": true }{ "_id": 2, "fullfilled": false }{ "_id": 3, "fullfilled": true }

                      AggregateCommand.or(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。给定多个表达式,如果任意一个表达式返回 true,则 or 返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>, ...]

                      返回值

                      Objectu

                      API 说明

                      语法如下:

                      db.command.aggregate.or([<expression1>, <expression2>, ...])

                      如果表达式返回 false、null、0、或 undefined,表达式会解析为 false,否则对其他返回值都认为是 true。

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "min": 10, "max": 100 }{ "_id": 2, "min": 60, "max": 80 }{ "_id": 3, "min": 30, "max": 50 }

                      求 min 小于 40 且 max 大于 60 的记录。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    fullfilled: $.or([$.lt(['$min', 30]), $.gt(['$max', 60])])  })  .end()

                      返回结果如下:

                      { "_id": 1, "fullfilled": true }{ "_id": 2, "fullfilled": false }{ "_id": 3, "fullfilled": true }


                      AggregateCommand.cmp(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。给定两个值,返回其比较值:

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>]

                      返回值

                      Object

                      API 说明

                      如果第一个值小于第二个值,返回 -1 如果第一个值大于第二个值,返回 1 如果两个值相等,返回 0

                      语法如下:

                      db.command.aggregate.cmp([<expression1>, <expression2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "shop1": 10, "shop2": 100 }{ "_id": 2, "shop1": 80, "shop2": 20 }{ "_id": 3, "shop1": 50, "shop2": 50 }

                      求 shop1 和 shop2 的各个物品的价格对比。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    compare: $.cmp(['$shop1', '$shop2']))  })  .end()

                      返回结果如下:

                      { "_id": 1, "compare": -1 }{ "_id": 2, "compare": 1 }{ "_id": 3, "compare": 0 }

                      AggregateCommand.eq(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果相等则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.eq([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      求 value 等于 50 的记录。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.eq(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": false }{ "_id": 2, "matched": false }{ "_id": 3, "matched": true }

                      AggregateCommand.gt(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果前者大于后者则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.gt([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      判断 value 是否大于 50。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.gt(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": false }{ "_id": 2, "matched": true }{ "_id": 3, "matched": false }

                      AggregateCommand.gte(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果前者大于或等于后者则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.gte([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      判断 value 是否大于或等于 50。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.gte(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": false }{ "_id": 2, "matched": true }{ "_id": 3, "matched": true }

                      AggregateCommand.lt(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果前者小于后者则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.lt([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      判断 value 是否小于 50。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.lt(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": true }{ "_id": 2, "matched": false }{ "_id": 3, "matched": false }

                      AggregateCommand.lte(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果前者小于或等于后者则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.lte([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      判断 value 是否小于 50。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.lte(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": true }{ "_id": 2, "matched": false }{ "_id": 3, "matched": true }

                      AggregateCommand.neq(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果不相等则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.neq([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      求 value 不等于 50 的记录。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.neq(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": true }{ "_id": 2, "matched": true }{ "_id": 3, "matched": false }


                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。给定两个值,返回其比较值:

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>]

                      返回值

                      Object

                      API 说明

                      如果第一个值小于第二个值,返回 -1 如果第一个值大于第二个值,返回 1 如果两个值相等,返回 0

                      语法如下:

                      db.command.aggregate.cmp([<expression1>, <expression2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "shop1": 10, "shop2": 100 }{ "_id": 2, "shop1": 80, "shop2": 20 }{ "_id": 3, "shop1": 50, "shop2": 50 }

                      求 shop1 和 shop2 的各个物品的价格对比。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    compare: $.cmp(['$shop1', '$shop2']))  })  .end()

                      返回结果如下:

                      { "_id": 1, "compare": -1 }{ "_id": 2, "compare": 1 }{ "_id": 3, "compare": 0 }

                      AggregateCommand.eq(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果相等则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.eq([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      求 value 等于 50 的记录。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.eq(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": false }{ "_id": 2, "matched": false }{ "_id": 3, "matched": true }

                      AggregateCommand.gt(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果前者大于后者则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.gt([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      判断 value 是否大于 50。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.gt(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": false }{ "_id": 2, "matched": true }{ "_id": 3, "matched": false }

                      AggregateCommand.gte(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果前者大于或等于后者则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.gte([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      判断 value 是否大于或等于 50。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.gte(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": false }{ "_id": 2, "matched": true }{ "_id": 3, "matched": true }

                      AggregateCommand.lt(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果前者小于后者则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.lt([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      判断 value 是否小于 50。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.lt(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": true }{ "_id": 2, "matched": false }{ "_id": 3, "matched": false }

                      AggregateCommand.lte(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果前者小于或等于后者则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.lte([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      判断 value 是否小于 50。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.lte(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": true }{ "_id": 2, "matched": false }{ "_id": 3, "matched": true }

                      AggregateCommand.neq(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。匹配两个值,如果不相等则返回 true,否则返回 false。

                      参数

                      value: Expression[]

                      [<value1>, <value2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.neq([<value1>, <value2>])

                      示例代码

                      假设集合 price 有如下记录:

                      { "_id": 1, "value": 10 }{ "_id": 2, "value": 80 }{ "_id": 3, "value": 50 }

                      求 value 不等于 50 的记录。

                      const $ = db.command.aggregatedb.collection('price').aggregate()  .project({    matched: $.neq(['$value', 50])  })  .end()

                      返回结果如下:

                      { "_id": 1, "matched": true }{ "_id": 2, "matched": true }{ "_id": 3, "matched": false }


                      AggregateCommand.cond(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。计算布尔表达式,返回指定的两个值其中之一。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      cond 的使用形式如下:

                      cond({ if: <布尔表达式>, then: <真值>, else: <假值>  })

                      或者:

                      cond([ <布尔表达式>, <真值>, <假值> ])

                      两种形式中,三个参数(if、then、else)都是必须的。

                      如果布尔表达式为真,那么 $cond 将会返回 <真值>,否则会返回 <假值>

                      示例代码

                      假设集合 items 的记录如下:

                      { "_id": "0", "name": "item-a", "amount": 100 }{ "_id": "1", "name": "item-b", "amount": 200 }{ "_id": "2", "name": "item-c", "amount": 300 }

                      我们可以使用 cond,根据 amount 字段,来生成新的字段 discount:

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    name: 1,    discount: $.cond({        if: $.gte(['$amount', 200]),        then: 0.7,        else: 0.9    })  })  .end()

                      输出如下:

                      { "_id": "0", "name": "item-a", "discount": 0.9 }{ "_id": "1", "name": "item-b", "discount": 0.7 }{ "_id": "2", "name": "item-c", "discount": 0.7 }

                      AggregateCommand.ifNull(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。计算给定的表达式,如果表达式结果为 null、undefined 或者不存在,那么返回一个替代值;否则返回原值。

                      参数

                      value: Expression[]

                      [ <表达式>, <替代值> ]

                      返回值

                      Object

                      API 说明

                      ifNull 的使用形式如下:

                      ifNull([ <表达式>, <替代值> ])

                      示例代码

                      假设集合 items 的记录如下:

                      { "_id": "0", "name": "A", "description": "这是商品A" }{ "_id": "1", "name": "B", "description": null }{ "_id": "2", "name": "C" }

                      我们可以使用 ifNull,对不存在 desc 字段的文档,或者 desc 字段为 null 的文档,补充一个替代值。

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    _id: 0,    name: 1,    description: $.ifNull(['$description', '商品描述空缺'])  })  .end()

                      输出如下:

                      { "name": "A", "description": "这是商品A" }{ "name": "B", "description": "商品描述空缺" }{ "name": "C", "description": "商品描述空缺" }

                      AggregateCommand.switch(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。根据给定的 switch-case-default 计算返回值、

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      switch 的使用形式如下:

                      switch({    branches: [        case: <表达式>, then: <表达式>,        case: <表达式>, then: <表达式>,        ...    ],    default: <表达式>})

                      示例代码

                      假设集合 items 的记录如下:

                      { "_id": "0", "name": "item-a", "amount": 100 }{ "_id": "1", "name": "item-b", "amount": 200 }{ "_id": "2", "name": "item-c", "amount": 300 }

                      我们可以使用 switch,根据 amount 字段,来生成新的字段 discount:

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    name: 1,    discount: $.switch({        branches: [            { case: $.gt(['$amount', 250]), then: 0.8 },            { case: $.gt(['$amount', 150]), then: 0.9 }        ],        default: 1    })  })  .end()

                      输出如下:

                      { "_id": "0", "name": "item-a", "discount": 1 }{ "_id": "1", "name": "item-b", "discount": 0.9 }{ "_id": "2", "name": "item-c", "discount": 0.8 }


                      AggregateCommand.dateFromParts(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。给定日期的相关信息,构建并返回一个日期对象。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.dateFromParts({    year: <year>,    month: <month>,    day: <day>,    hour: <hour>,    minute: <minute>,    second: <second>,    millisecond: <ms>,    timezone: <tzExpression>})

                      你也可以使用 ISO 8601 的标准:

                      db.command.aggregate.dateFromParts({    isoWeekYear: <year>,    isoWeek: <week>,    isoDayOfWeek: <day>,    hour: <hour>,    minute: <minute>,    second: <second>,    millisecond: <ms>,    timezone: <tzExpression>})

                      示例代码

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    date: $.dateFromParts({        year: 2017,        month: 2,        day: 8,        hour: 12,        timezone: 'America/New_York'    }),  })  .end()

                      输出如下:

                      {    "date": ISODate("2017-02-08T17:00:00.000Z")}

                      AggregateCommand.dateFromString(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将一个日期/时间字符串转换为日期对象

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.dateFromString({    dateString: <dateStringExpression>,    timezone: <tzExpression>})

                      示例代码

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    date: $.dateFromString({        dateString: "2019-05-14T09:38:51.686Z"    })  })  .end()

                      输出如下:

                      {    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      AggregateCommand.dateToString(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。根据指定的表达式将日期对象格式化为符合要求的字符串。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      dateToString 的调用形式如下:

                      db.command.aggregate.dateToString({  date: <日期表达式>,  format: <格式化表达式>,  timezone: <时区表达式>,  onNull: <空值表达式>})

                      下面是四种表达式的详细说明:

                      名称描述
                      日期表达式必选。指定字段值应该是能转化为字符串的日期。
                      格式化表达式可选。它可以是任何包含“格式说明符”的有效字符串。
                      时区表达式可选。指明运算结果的时区。它可以解析格式为 UTC Offset 或者 Olson Timezone Identifier 的字符串。
                      空值表达式可选。当 <日期表达式> 返回空或者不存在的时候,会返回此表达式指明的值。

                      下面是格式说明符的详细说明:

                      说明符描述合法值
                      %d月份的日期(2位数,0填充)01 - 31
                      %GISO 8601 格式的年份0000 - 9999
                      %H小时(2位数,0填充,24小时制)00 - 23
                      %j一年中的一天(3位数,0填充)001 - 366
                      %L毫秒(3位数,0填充)000 - 999
                      %m月份(2位数,0填充)01 - 12
                      %M分钟(2位数,0填充)00 - 59
                      %S秒(2位数,0填充)00 - 60
                      %w星期几1 - 7
                      %uISO 8601 格式的星期几1 - 7
                      %U一年中的一周(2位数,0填充)00 - 53
                      %VISO 8601 格式的一年中的一周1 - 53
                      %Y年份(4位数,0填充)0000 - 9999
                      %z与 UTC 的时区偏移量+/-[hh][mm]
                      %Z以分钟为单位,与 UTC 的时区偏移量+/-mmm
                      %%百分号作为字符%

                      示例代码

                      假设集合 students 有如下记录:

                      { "date": "1999-12-11T16:00:00.000Z", "firstName": "Yuanxin", "lastName": "Dong" }{ "date": "1998-11-10T16:00:00.000Z", "firstName": "Weijia", "lastName": "Wang" }{ "date": "1997-10-09T16:00:00.000Z", "firstName": "Chengxi", "lastName": "Li" }

                      格式化日期

                      下面是将 date 字段的值,格式化成形如 年份-月份-日期 的字符串:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$date',      format: '%Y-%m-%d'    })  })  .end()

                      返回的结果如下:

                      { "formatDate": "1999-12-11" }{ "formatDate": "1998-11-10" }{ "formatDate": "1997-10-09" }

                      时区时间

                      下面是将 date 字段值格式化为上海时区时间的例子:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$date',      format: '%H:%M:%S',      timezone: 'Asia/Shanghai'    })  })  .end()

                      返回的结果如下:

                      { "formatDate": "00:00:00" }{ "formatDate": "00:00:00" }{ "formatDate": "00:00:00" }

                      缺失情况的默认值

                      当指定的 <日期表达式> 返回空或者不存在的时候,可以设置缺失情况下的默认值:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$empty',      onNull: 'null'    })  })  .end()

                      返回的结果如下:

                      { "formatDate": "null" }{ "formatDate": "null" }{ "formatDate": "null" }

                      AggregateCommand.dayOfMonth(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的天数(一个月中的哪一天),是一个介于 1 至 31 之间的数字。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.dayOfMonth(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 dayOfMonth() 对 date 字段进行投影,获取对应的日期:

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    dayOfMonth: $.dayOfMonth('$date')  })  .end()

                      输出如下:

                      {    "dayOfMonth": 14}

                      AggregateCommand.dayOfWeek(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的天数(一周中的第几天),是一个介于 1(周日)到 7(周六)之间的整数。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      注意:周日是每周的第 1 天*

                      语法如下:

                      db.command.aggregate.dayOfWeek(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 dayOfWeek() 对 date 字段进行投影,获取对应的天数(一周中的第几天):

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    dayOfWeek: $.dayOfWeek('$date')  })  .end()

                      输出如下:

                      {    "dayOfWeek": 3}

                      AggregateCommand.dayOfYear(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的天数(一年中的第几天),是一个介于 1 到 366 之间的整数。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.dayOfYear(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 dayOfYear() 对 date 字段进行投影,获取对应的天数(一年中的第几天):

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    dayOfYear: $.dayOfYear('$date')  })  .end()

                      输出如下:

                      {    "dayOfYear": 134}

                      AggregateCommand.hour(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的小时数,是一个介于 0 到 23 之间的整数。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.hour(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 hour() 对 date 字段进行投影,获取对应的小时数:

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    hour: $.hour('$date')  })  .end()

                      输出如下:

                      {    "hour": 9}

                      AggregateCommand.isoDayOfWeek(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的 ISO 8601 标准的天数(一周中的第几天),是一个介于 1(周一)到 7(周日)之间的整数。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.month(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 month() 对 date 字段进行投影,获取对应的 ISO 8601 标准的天数(一周中的第几天):

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    isoDayOfWeek: $.isoDayOfWeek('$date')  })  .end()

                      输出如下:

                      {    "isoDayOfWeek": 2}

                      AggregateCommand.isoWeek(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的 ISO 8601 标准的周数(一年中的第几周),是一个介于 1 到 53 之间的整数。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      根据 ISO 8601 标准,周一到周日视为一周,本年度第一个周四所在的那周,视为本年度的第 1 周。

                      例如:2016 年 1 月 7 日是那年的第一个周四,那么 2016.01.04(周一)到 2016.01.10(周日) 即为第 1 周。同理,2016 年 1 月 1 日的周数为 53。

                      语法如下:

                      db.command.aggregate.isoWeek(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 isoWeek() 对 date 字段进行投影,获取对应的 ISO 8601 标准的周数(一年中的第几周):

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    isoWeek: $.isoWeek('$date')  })  .end()

                      输出如下:

                      {    "isoWeek": 20}

                      AggregateCommand.isoWeekYear(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的 ISO 8601 标准的天数(一年中的第几天)。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      此处的“年”以第一周的周一为开始,以最后一周的周日为结束。

                      语法如下:

                      db.command.aggregate.isoWeekYear(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 isoWeekYear() 对 date 字段进行投影,获取对应的 ISO 8601 标准的天数(一年中的第几天):

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    isoWeekYear: $.isoWeekYear('$date')  })  .end()

                      输出如下:

                      {    "isoWeekYear": 2019}

                      AggregateCommand.millisecond(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的毫秒数,是一个介于 0 到 999 之间的整数。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.millisecond(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 millisecond() 对 date 字段进行投影,获取对应的毫秒数:

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    millisecond: $.millisecond('$date'),  })  .end()

                      输出如下:

                      {    "millisecond": 686}

                      AggregateCommand.minute(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的分钟数,是一个介于 0 到 59 之间的整数。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.minute(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 minute() 对 date 字段进行投影,获取对应的分钟数:

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    minute: $.minute('$date')  })  .end()

                      输出如下:

                      {    "minute": 38}

                      AggregateCommand.month(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的月份,是一个介于 1 到 12 之间的整数。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.month(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 month() 对 date 字段进行投影,获取对应的月份:

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    month: $.month('$date')  })  .end()

                      输出如下:

                      {    "month": 5}

                      AggregateCommand.second(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的秒数,是一个介于 0 到 59 之间的整数,在特殊情况下(闰秒)可能等于 60。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.second(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 second() 对 date 字段进行投影,获取对应的秒数:

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    second: $.second('$date')  })  .end()

                      输出如下:

                      {    "second": 51}

                      AggregateCommand.week(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的周数(一年中的第几周),是一个介于 0 到 53 之间的整数。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      每周以周日为开头,每年的第一个周日即为 week 1 的开始,这天之前是 week 0。

                      语法如下:

                      db.command.aggregate.week(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 week() 对 date 字段进行投影,获取对应的周数(一年中的第几周):

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    week: $.week('$date')  })  .end()

                      输出如下:

                      {    "week": 19}

                      AggregateCommand.year(value: Expression<string>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回日期字段对应的年份。

                      参数

                      value: Expression<string>

                      日期字段

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.year(<日期字段>)

                      示例代码

                      假设集合 dates 有以下文档:

                      {    "_id": 1,    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      我们使用 year() 对 date 字段进行投影,获取对应的年份:

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    year: $.year('$date')  })  .end()

                      输出如下:

                      {    "year": 2019}

                      AggregateCommand.subtract(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将两个数字相减然后返回差值,或将两个日期相减然后返回相差的毫秒数,或将一个日期减去一个数字返回结果的日期。

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.subtract([<expression1>, <expression2>])

                      参数可以是任意解析为数字或日期的表达式。

                      示例代码

                      假设集合 scores 有如下记录:

                      { "_id": 1, "max": 10, "min": 1 }{ "_id": 2, "max": 7, "min": 5 }{ "_id": 3, "max": 6, "min": 6 }

                      求各个记录的 max 和 min 的差值。:

                      const $ = db.command.aggregatedb.collection('scores').aggregate()  .project({    diff: $.subtract(['$max', '$min'])  })  .end()

                      返回结果如下:

                      { "_id": 1, "diff": 9 }{ "_id": 2, "diff": 2 }{ "_id": 3, "diff": 0 }


                      AggregateCommand.literal(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。直接返回一个值的字面量,不经过任何解析和处理。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      literal 使用形式如下:

                      literal(<值>)

                      如果 <值> 是一个表达式,那么 literal 不会解析或者计算这个表达式,而是直接返回这个表达式。

                      示例代码

                      比如我们有一个 items 集合,其中数据如下:

                      { "_id": "0", "price": "$1" }{ "_id": "1", "price": "$5.60" }{ "_id": "2", "price": "$8.90" }

                      以字面量的形式使用 $

                      下面的代码使用 literal,生成了一个新的字段 isOneDollar,表示 price 字段是否严格等于 "$1"。

                      注意:我们这里无法使用 eq(['$price', '$1']),因为 "$1" 是一个表达式,代表 "1" 字段对应的值,而不是字符串字面量 "$1"。

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    isOneDollar: $.eq(['$price', $.literal('$1')])  })  .end()

                      输出如下:

                      { "_id": "0", "isOneDollar": true }{ "_id": "1", "isOneDollar": false }{ "_id": "2", "isOneDollar": false }

                      投影一个字段,对应的值为 1

                      下面的代码使用 literal,投影了一个新的字段 amount,其值为 1。

                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    price: 1,    amount: $.literal(1)  })  .end()

                      输出如下:

                      { "_id": "0", "price": "$1", "amount": 1 }{ "_id": "1", "price": "$5.60", "amount": 1 }{ "_id": "2", "price": "$8.90", "amount": 1 }


                      AggregateCommand.mergeObjects(value: Expression<document>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将多个文档合并为单个文档。

                      参数

                      value: Expression<document>

                      Document 表达式

                      返回值

                      Object

                      API 说明

                      使用形式如下: 在 group() 中使用时:

                      mergeObjects(<document>)

                      在其它表达式中使用时:

                      mergeObjects([<document1>, <document2>, ...])

                      示例代码

                      搭配 group() 使用

                      假设集合 sales 存在以下文档:

                      { "_id": 1, "year": 2018, "name": "A", "volume": { "2018Q1": 500, "2018Q2": 500 } }{ "_id": 2, "year": 2017, "name": "A", "volume": { "2017Q1": 400, "2017Q2": 300, "2017Q3": 0, "2017Q4": 0 } }{ "_id": 3, "year": 2018, "name": "B", "volume": { "2018Q1": 100 } }{ "_id": 4, "year": 2017, "name": "B", "volume": { "2017Q3": 100, "2017Q4": 250 } }

                      下面的代码使用 mergeObjects(),将用相同 name 的文档合并:

                      const $ = db.command.aggregatedb.collection('sales').aggregate()  .group({    _id: '$name',    mergedVolume: $.mergeObjects('$volume')  })  .end()

                      输出如下:

                      { "_id": "A", "mergedVolume": { "2017Q1": 400, "2017Q2": 300, "2017Q3": 0, "2017Q4": 0, "2018Q1": 500, "2018Q2": 500 } }{ "_id": "B", "mergedVolume": { "2017Q3": 100, "2017Q4": 250, "2018Q1": 100 } }

                      一般用法

                      假设集合 test 存在以下文档:

                      { "_id": 1, "foo": { "a": 1 }, "bar": { "b": 2 } }{ "_id": 2, "foo": { "c": 1 }, "bar": { "d": 2 } }{ "_id": 3, "foo": { "e": 1 }, "bar": { "f": 2 } }

                      下面的代码使用 mergeObjects(),将文档中的 foo 和 bar 字段合并为 foobar:

                      const $ = db.command.aggregatedb.collection('sales').aggregate()  .project({    foobar: $.mergeObjects(['$foo', '$bar'])  })  .end()

                      输出结果如下:

                      { "_id": 1, "foobar": { "a": 1, "b": 2 } }{ "_id": 2, "foobar": { "c": 1, "d": 2 } }{ "_id": 3, "foobar": { "e": 1, "f": 2 } }

                      AggregateCommand.objectToArray(value: Expression<object>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将一个对象转换为数组。方法把对象的每个键值对都变成输出数组的一个元素,元素形如 { k: &lt;key&gt;, v: &lt;value&gt; }。

                      参数

                      value: Expression<object>

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.objectToArray(<object>)

                      示例代码

                      假设集合 items 有如下记录:

                      { "_id": 1, "attributes": { "color": "red", "price": 150 } }{ "_id": 2, "attributes": { "color": "blue", "price": 50 } }{ "_id": 3, "attributes": { "color": "yellow", "price": 10 } }
                      const $ = db.command.aggregatedb.collection('items').aggregate()  .project({    array: $.objectToArray('$attributes')  })  .end()

                      返回结果如下:

                      { "_id": 1, "array": [{ "k": "color", "v": "red" }, { "k": "price", "v": 150 }] }{ "_id": 2, "array": [{ "k": "color", "v": "blue" }, { "k": "price", "v": 50 }] }{ "_id": 3, "array": [{ "k": "color", "v": "yellow" }, { "k": "price", "v": 10 }] }


                      AggregateCommand.allElementsTrue(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。输入一个数组,或者数组字段的表达式。如果数组中所有元素均为真值,那么返回 true,否则返回 false。空数组永远返回 true。

                      参数

                      value: Expression[]

                      [<expression>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      allElementsTrue([<expression>])

                      示例代码

                      假设集合 test 有如下记录:

                      { "_id": 1, "array": [ true ] }{ "_id": 2, "array": [ ] }{ "_id": 3, "array": [ false ] }{ "_id": 4, "array": [ true, false ] }{ "_id": 5, "array": [ 0 ] }{ "_id": 6, "array": [ "stark" ] }

                      下面的代码使用 allElementsTrue(),判断 array 字段中是否均为真值:

                      const $ = db.command.aggregatedb.collection('price')  .aggregate()  .project({    isAllTrue: $.allElementsTrue(['$array'])  })  .end()

                      返回结果如下:

                      { "_id": 1, "isAllTrue": true }{ "_id": 2, "isAllTrue": true }{ "_id": 3, "isAllTrue": false }{ "_id": 4, "isAllTrue": false }{ "_id": 5, "isAllTrue": false }{ "_id": 6, "isAllTrue": true }

                      AggregateCommand.anyElementTrue(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。输入一个数组,或者数组字段的表达式。如果数组中任意一个元素为真值,那么返回 true,否则返回 false。空数组永远返回 false。

                      参数

                      value: Expression[]

                      [<expression>]

                      返回值

                      Object

                      API 说明

                      语法如下:

                      anyElementTrue([<expression>])

                      示例代码

                      假设集合 test 有如下记录:

                      { "_id": 1, "array": [ true ] }{ "_id": 2, "array": [ ] }{ "_id": 3, "array": [ false ] }{ "_id": 4, "array": [ true, false ] }{ "_id": 5, "array": [ 0 ] }{ "_id": 6, "array": [ "stark" ] }

                      下面的代码使用 anyElementTrue(),判断 array 字段中是否含有真值:

                      const $ = db.command.aggregatedb.collection('price')  .aggregate()  .project({    isAnyTrue: $.anyElementTrue(['$array'])  })  .end()

                      返回结果如下:

                      { "_id": 1, "isAnyTrue": true }{ "_id": 2, "isAnyTrue": false }{ "_id": 3, "isAnyTrue": false }{ "_id": 4, "isAnyTrue": true }{ "_id": 5, "isAnyTrue": false }{ "_id": 6, "isAnyTrue": true }

                      AggregateCommand.setDifference(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符,输入两个集合,输出只存在于第一个集合中的元素。

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>]

                      返回值

                      Object

                      API 说明

                      使用形式如下:

                      setDifference([<expression1>, <expression2>])

                      示例代码

                      假设集合 test 存在以下数据:

                      { "_id": 1, "A": [ 1, 2 ], "B": [ 1, 2 ] }{ "_id": 2, "A": [ 1, 2 ], "B": [ 2, 1, 2 ] }{ "_id": 3, "A": [ 1, 2 ], "B": [ 1, 2, 3 ] }{ "_id": 4, "A": [ 1, 2 ], "B": [ 3, 1 ] }{ "_id": 5, "A": [ 1, 2 ], "B": [ ] }{ "_id": 6, "A": [ 1, 2 ], "B": [ {}, [] ] }{ "_id": 7, "A": [ ], "B": [ ] }{ "_id": 8, "A": [ ], "B": [ 1 ] }

                      下面的代码使用 setDifference,找到只存在于 B 中的数字:

                      db.collection('test')  .aggregate()  .project({    isBOnly: $.setDifference(['$B', '$A'])  })  .end()
                      { "_id": 1, "isBOnly": [] }{ "_id": 2, "isBOnly": [3] }{ "_id": 3, "isBOnly": [3] }{ "_id": 4, "isBOnly": [5] }{ "_id": 5, "isBOnly": [] }{ "_id": 6, "isBOnly": [{}, []] }{ "_id": 7, "isBOnly": [] }{ "_id": 8, "isBOnly": [1] }

                      AggregateCommand.setEquals(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符,输入两个集合,判断两个集合中包含的元素是否相同(不考虑顺序、去重)。

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>]

                      返回值

                      Object

                      API 说明

                      使用形式如下:

                      setEquals([<expression1>, <expression2>])

                      示例代码

                      假设集合 test 存在以下数据:

                      { "_id": 1, "A": [ 1, 2 ], "B": [ 1, 2 ] }{ "_id": 2, "A": [ 1, 2 ], "B": [ 2, 1, 2 ] }{ "_id": 3, "A": [ 1, 2 ], "B": [ 1, 2, 3 ] }{ "_id": 4, "A": [ 1, 2 ], "B": [ 3, 1 ] }{ "_id": 5, "A": [ 1, 2 ], "B": [ ] }{ "_id": 6, "A": [ 1, 2 ], "B": [ {}, [] ] }{ "_id": 7, "A": [ ], "B": [ ] }{ "_id": 8, "A": [ ], "B": [ 1 ] }

                      下面的代码使用 setEquals,判断两个集合中包含的元素是否相同:

                      db.collection('test')  .aggregate()  .project({    sameElements: $.setEquals(['$A', '$B'])  })  .end()
                      { "_id": 1, "sameElements": true }{ "_id": 2, "sameElements": true }{ "_id": 3, "sameElements": false }{ "_id": 4, "sameElements": false }{ "_id": 5, "sameElements": false }{ "_id": 6, "sameElements": false }{ "_id": 7, "sameElements": true }{ "_id": 8, "sameElements": false }

                      AggregateCommand.setIntersection(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符,输入两个集合,输出两个集合的交集。

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>]

                      返回值

                      Object

                      API 说明

                      使用形式如下:

                      setIntersection([<expression1>, <expression2>])

                      示例代码

                      假设集合 test 存在以下数据:

                      { "_id": 1, "A": [ 1, 2 ], "B": [ 1, 2 ] }{ "_id": 2, "A": [ 1, 2 ], "B": [ 2, 1, 2 ] }{ "_id": 3, "A": [ 1, 2 ], "B": [ 1, 2, 3 ] }{ "_id": 4, "A": [ 1, 2 ], "B": [ 3, 1 ] }{ "_id": 5, "A": [ 1, 2 ], "B": [ ] }{ "_id": 6, "A": [ 1, 2 ], "B": [ {}, [] ] }{ "_id": 7, "A": [ ], "B": [ ] }{ "_id": 8, "A": [ ], "B": [ 1 ] }

                      下面的代码使用 setIntersection,输出两个集合的交集:

                      db.collection('test')  .aggregate()  .project({    commonToBoth: $.setIntersection(['$A', '$B'])  })  .end()

                      输出如下:

                      { "_id": 1, "commonToBoth": [ 1, 2 ] }{ "_id": 2, "commonToBoth": [ 1, 2 ] }{ "_id": 3, "commonToBoth": [ 1, 2 ] }{ "_id": 4, "commonToBoth": [ 1 ] }{ "_id": 5, "commonToBoth": [ ] }{ "_id": 6, "commonToBoth": [ ] }{ "_id": 7, "commonToBoth": [ ] }{ "_id": 8, "commonToBoth": [ ] }

                      AggregateCommand.setIsSubset(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符,输入两个集合,判断第一个集合是否是第二个集合的子集。

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>]

                      返回值

                      Object

                      API 说明

                      使用形式如下:

                      setIsSubset([<expression1>, <expression2>])

                      示例代码

                      假设集合 test 存在以下数据:

                      { "_id": 1, "A": [ 1, 2 ], "B": [ 1, 2 ] }{ "_id": 2, "A": [ 1, 2 ], "B": [ 2, 1, 2 ] }{ "_id": 3, "A": [ 1, 2 ], "B": [ 1, 2, 3 ] }{ "_id": 4, "A": [ 1, 2 ], "B": [ 3, 1 ] }{ "_id": 5, "A": [ 1, 2 ], "B": [ ] }{ "_id": 6, "A": [ 1, 2 ], "B": [ {}, [] ] }{ "_id": 7, "A": [ ], "B": [ ] }{ "_id": 8, "A": [ ], "B": [ 1 ] }

                      下面的代码使用 setIsSubset,判断第一个集合是否是第二个集合的子集:

                      db.collection('test')  .aggregate()  .project({    AisSubsetOfB: $.setIsSubset(['$A', '$B'])  })  .end()
                      { "_id": 1, "AisSubsetOfB": true }{ "_id": 2, "AisSubsetOfB": true }{ "_id": 3, "AisSubsetOfB": true }{ "_id": 4, "AisSubsetOfB": false }{ "_id": 5, "AisSubsetOfB": false }{ "_id": 6, "AisSubsetOfB": false }{ "_id": 7, "AisSubsetOfB": true }{ "_id": 8, "AisSubsetOfB": true }

                      AggregateCommand.setUnion(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符,输入两个集合,输出两个集合的并集。

                      参数

                      value: Expression[]

                      [<expression1>, <expression2>]

                      返回值

                      Object

                      API 说明

                      使用形式如下:

                      setUnion([<expression1>, <expression2>])

                      示例代码

                      假设集合 test 存在以下数据:

                      { "_id": 1, "A": [ 1, 2 ], "B": [ 1, 2 ] }{ "_id": 2, "A": [ 1, 2 ], "B": [ 2, 1, 2 ] }{ "_id": 3, "A": [ 1, 2 ], "B": [ 1, 2, 3 ] }{ "_id": 4, "A": [ 1, 2 ], "B": [ 3, 1 ] }{ "_id": 5, "A": [ 1, 2 ], "B": [ ] }{ "_id": 6, "A": [ 1, 2 ], "B": [ {}, [] ] }{ "_id": 7, "A": [ ], "B": [ ] }{ "_id": 8, "A": [ ], "B": [ 1 ] }

                      下面的代码使用 setUnion,输出两个集合的并集:

                      db.collection('test')  .aggregate()  .project({    AB: $.setUnion(['$A', '$B'])  })  .end()

                      输出如下:

                      { "_id": 1, "AB": [ 1, 2 ] }{ "_id": 2, "AB": [ 1, 2 ] }{ "_id": 3, "AB": [ 1, 2, 3 ] }{ "_id": 4, "AB": [ 1, 2, 3 ] }{ "_id": 5, "AB": [ 1, 2 ] }{ "_id": 6, "AB": [ 1, 2, {}, [] ] }{ "_id": 7, "AB": [ ] }{ "_id": 8, "AB": [ 1 ] }


                      AggregateCommand.concat(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。连接字符串,返回拼接后的字符串。

                      参数

                      value: Expression[]

                      [<表达式1>, <表达式2>, ...]

                      返回值

                      Object

                      API 说明

                      concat 的语法如下:

                      db.command.aggregate.concat([<表达式1>, <表达式2>, ...])

                      表达式可以是形如 $ + 指定字段,也可以是普通字符串。只要能够被解析成字符串即可。

                      示例代码

                      假设集合 students 的记录如下:

                      { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

                      借助 concat 可以拼接 lastName 和 firstName 字段,得到每位学生的名字全称:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    fullName: $.concat(['$firstName', ' ', '$lastName'])  })  .end()

                      返回的结果如下:

                      { "fullName": "Yuanxin Dong" }{ "fullName": "Weijia Wang" }{ "fullName": "Chengxi Li" }

                      AggregateCommand.dateFromString(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将一个日期/时间字符串转换为日期对象

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      语法如下:

                      db.command.aggregate.dateFromString({    dateString: <dateStringExpression>,    timezone: <tzExpression>})

                      示例代码

                      const $ = db.command.aggregatedb  .collection('dates')  .aggregate()  .project({    _id: 0,    date: $.dateFromString({        dateString: "2019-05-14T09:38:51.686Z"    })  })  .end()

                      输出如下:

                      {    "date": ISODate("2019-05-14T09:38:51.686Z")}

                      AggregateCommand.dateToString(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。根据指定的表达式将日期对象格式化为符合要求的字符串。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      dateToString 的调用形式如下:

                      db.command.aggregate.dateToString({  date: <日期表达式>,  format: <格式化表达式>,  timezone: <时区表达式>,  onNull: <空值表达式>})

                      下面是四种表达式的详细说明:

                      名称描述
                      日期表达式必选。指定字段值应该是能转化为字符串的日期。
                      格式化表达式可选。它可以是任何包含“格式说明符”的有效字符串。
                      时区表达式可选。指明运算结果的时区。它可以解析格式为 UTC Offset 或者 Olson Timezone Identifier 的字符串。
                      空值表达式可选。当 <日期表达式> 返回空或者不存在的时候,会返回此表达式指明的值。

                      下面是格式说明符的详细说明:

                      说明符描述合法值
                      %d月份的日期(2位数,0填充)01 - 31
                      %GISO 8601 格式的年份0000 - 9999
                      %H小时(2位数,0填充,24小时制)00 - 23
                      %j一年中的一天(3位数,0填充)001 - 366
                      %L毫秒(3位数,0填充)000 - 999
                      %m月份(2位数,0填充)01 - 12
                      %M分钟(2位数,0填充)00 - 59
                      %S秒(2位数,0填充)00 - 60
                      %w星期几1 - 7
                      %uISO 8601 格式的星期几1 - 7
                      %U一年中的一周(2位数,0填充)00 - 53
                      %VISO 8601 格式的一年中的一周1 - 53
                      %Y年份(4位数,0填充)0000 - 9999
                      %z与 UTC 的时区偏移量+/-[hh][mm]
                      %Z以分钟为单位,与 UTC 的时区偏移量+/-mmm
                      %%百分号作为字符%

                      示例代码

                      假设集合 students 有如下记录:

                      { "date": "1999-12-11T16:00:00.000Z", "firstName": "Yuanxin", "lastName": "Dong" }{ "date": "1998-11-10T16:00:00.000Z", "firstName": "Weijia", "lastName": "Wang" }{ "date": "1997-10-09T16:00:00.000Z", "firstName": "Chengxi", "lastName": "Li" }

                      格式化日期

                      下面是将 date 字段的值,格式化成形如 年份-月份-日期 的字符串:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$date',      format: '%Y-%m-%d'    })  })  .end()

                      返回的结果如下:

                      { "formatDate": "1999-12-11" }{ "formatDate": "1998-11-10" }{ "formatDate": "1997-10-09" }

                      时区时间

                      下面是将 date 字段值格式化为上海时区时间的例子:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$date',      format: '%H:%M:%S',      timezone: 'Asia/Shanghai'    })  })  .end()

                      返回的结果如下:

                      { "formatDate": "00:00:00" }{ "formatDate": "00:00:00" }{ "formatDate": "00:00:00" }

                      缺失情况的默认值

                      当指定的 <日期表达式> 返回空或者不存在的时候,可以设置缺失情况下的默认值:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    formatDate: $.dateToString({      date: '$empty',      onNull: 'null'    })  })  .end()

                      返回的结果如下:

                      { "formatDate": "null" }{ "formatDate": "null" }{ "formatDate": "null" }

                      AggregateCommand.indexOfBytes(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。在目标字符串中查找子字符串,并返回第一次出现的 UTF-8 的字节索引(从0开始)。如果不存在子字符串,返回 -1。

                      参数

                      value: Expression[]

                      [<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>]

                      返回值

                      Object

                      API 说明

                      indexOfBytes 的语法如下:

                      db.command.aggregate.indexOfBytes([<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>])

                      下面是 4 种表达式的详细描述:

                      表达式描述
                      目标字符串表达式任何可以被解析为字符串的表达式
                      子字符串表达式任何可以被解析为字符串的表达式
                      开始位置表达式任何可以被解析为非负整数的表达式
                      结束位置表达式任何可以被解析为非负整数的表达式

                      示例代码

                      假设集合 students 的记录如下:

                      { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

                      借助 indexOfBytes 查找字符 "a" 在字段 firstName 中的位置:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    aStrIndex: $.indexOfBytes(['$firstName', 'a'])  })  .end()

                      返回的结果如下:

                      { "aStrIndex": 2 }{ "aStrIndex": 5 }{ "aStrIndex": -1 }

                      AggregateCommand.indexOfCP(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。在目标字符串中查找子字符串,并返回第一次出现的 UTF-8 的 code point 索引(从0开始)。如果不存在子字符串,返回 -1。

                      参数

                      value: Expression[]

                      [<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>]

                      返回值

                      Object

                      API 说明

                      code point 是“码位”,又名“编码位置”。这里特指 Unicode 包中的码位,范围是从0(16进制)到10FFFF(16进制)。

                      indexOfCP 的语法如下:

                      db.command.aggregate.indexOfCP([<目标字符串表达式>, <子字符串表达式>, <开始位置表达式>, <结束位置表达式>])

                      下面是 4 种表达式的详细描述:

                      表达式描述
                      目标字符串表达式任何可以被解析为字符串的表达式
                      子字符串表达式任何可以被解析为字符串的表达式
                      开始位置表达式任何可以被解析为非负整数的表达式
                      结束位置表达式任何可以被解析为非负整数的表达式

                      示例代码

                      假设集合 students 的记录如下:

                      { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

                      借助 indexOfCP 查找字符 "a" 在字段 firstName 中的位置:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    aStrIndex: $.indexOfCP(['$firstName', 'a'])  })  .end()

                      返回的结果如下:

                      { "aStrIndex": 2 }{ "aStrIndex": 5 }{ "aStrIndex": -1 }

                      AggregateCommand.split(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。按照分隔符分隔数组,并且删除分隔符,返回子字符串组成的数组。如果字符串无法找到分隔符进行分隔,返回原字符串作为数组的唯一元素。

                      参数

                      value: Expression[]

                      [<字符串表达式>, <分隔符表达式>]

                      返回值

                      Object

                      API 说明

                      split 的语法如下:

                      db.command.aggregate.split([<字符串表达式>, <分隔符表达式>])

                      字符串表达式和分隔符表达式可以是任意形式的表达式,只要它可以被解析为字符串即可。

                      示例代码

                      假设集合 students 的记录如下:

                      { "birthday": "1999/12/12" }{ "birthday": "1998/11/11" }{ "birthday": "1997/10/10" }

                      通过 split 将每条记录中的 birthday 字段对应值分隔成数组,每个数组分别由代表年、月、日的3个元素组成:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    birthday: $.split(['$birthday', '/'])  })  .end()

                      返回的结果如下:

                      { "birthday": [ "1999", "12", "12" ] }{ "birthday": [ "1998", "11", "11" ] }{ "birthday": [ "1997", "10", "10" ] }

                      AggregateCommand.strLenBytes(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。计算并返回指定字符串中 utf-8 编码的字节数量。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      strLenBytes 的语法如下:

                      db.command.aggregate.strLenBytes(<表达式>)

                      只要表达式可以被解析成字符串,那么它就是有效表达式。

                      示例代码

                      假设集合 students 的记录如下:

                      { "name": "dongyuanxin", "nickname": "心谭" }

                      借助 strLenBytes 计算 name 字段和 nickname 字段对应值的字节长度:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    nameLength: $.strLenBytes('$name'),    nicknameLength: $.strLenBytes('$nickname')  })  .end()

                      返回结果如下:

                      { "nameLength": 11, "nicknameLength": 6 }

                      AggregateCommand.strLenCP(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。计算并返回指定字符串的UTF-8 code points 数量。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      strLenCP 的语法如下:

                      db.command.aggregate.strLenCP(<表达式>)

                      只要表达式可以被解析成字符串,那么它就是有效表达式。

                      示例代码

                      假设集合 students 的记录如下:

                      { "name": "dongyuanxin", "nickname": "心谭" }

                      借助 strLenCP 计算 name 字段和 nickname 字段对应值的UTF-8 code points的数量:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    nameLength: $.strLenCP('$name'),    nicknameLength: $.strLenCP('$nickname')  })  .end()

                      返回结果如下:

                      { "nameLength": 11, "nicknameLength": 2 }

                      AggregateCommand.strcasecmp(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。对两个字符串在不区分大小写的情况下进行大小比较,并返回比较的结果。

                      参数

                      value: Expression[]

                      [<表达式1>, <表达式2>]

                      返回值

                      Object

                      API 说明

                      strcasecmp 的语法如下:

                      db.command.aggregate.strcasecmp([<表达式1>, <表达式2>])

                      只要 表达式1和 表达式2 可以被解析成字符串,那么它们就是有效的。

                      返回的比较结果有1,0和-1三种:

                      • 1:表达式1 解析的字符串 > 表达式2 解析的字符串
                      • 0:表达式1 解析的字符串 = 表达式2 解析的字符串
                      • -1:表达式1 解析的字符串 < 表达式2 解析的字符串

                      示例代码

                      假设集合 students 的记录如下:

                      { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

                      借助 strcasecmp 比较 firstName 字段值和 lastName 字段值的大小:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    result: $.strcasecmp(['$firstName', '$lastName']),  })  .end()

                      返回结果如下:

                      { "result": 1 }{ "result": 1 }{ "result": -1 }

                      AggregateCommand.substr(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。它是 db.command.aggregate.substrBytes 的别名,更推荐使用后者。

                      参数

                      value: Expression[]

                      [<表达式1>, <表达式2>, <表达式3>]

                      返回值

                      Object

                      API 说明

                      substr 的语法如下:

                      db.command.aggregate.substr([<表达式1>, <表达式2>, <表达式3>])

                      表达式1 是任何可以解析为字符串的有效表达式,表达式2 和 表达式3 是任何可以解析为数字的有效表达式。

                      如果 表达式2 是负数,返回的结果为 ""。

                      如果 表达式3 是负数,返回的结果为从 表达式2 指定的开始位置以及之后其余部分的子字符串。

                      示例代码

                      假设集合 students 的记录如下:

                      { "birthday": "1999/12/12", "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "birthday": "1998/11/11", "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "birthday": "1997/10/10", "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

                      借助 substr 可以提取 birthday 中的年、月、日信息,代码如下:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    year: $.substr(['$birthday', 0, 4]),    month: $.substr(['$birthday', 5, 2]),    day: $.substr(['$birthday', 8, -1])  })  .end()

                      返回的结果如下:

                      { "day": "12", "month": "12", "year": "1999" }{ "day": "11", "month": "11", "year": "1998" }{ "day": "10", "month": "10", "year": "1997" }

                      AggregateCommand.substrBytes(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。子字符串是由字符串中指定的 UTF-8 字节索引的字符开始,长度为指定的字节数。

                      参数

                      value: Expression[]

                      [<表达式1>, <表达式2>, <表达式3>]

                      返回值

                      Object

                      API 说明

                      substrBytes 的语法如下:

                      db.command.aggregate.substrBytes([<表达式1>, <表达式2>, <表达式3>])

                      表达式1 是任何可以解析为字符串的有效表达式,表达式2 和 表达式3 是任何可以解析为数字的有效表达式。

                      如果 表达式2 是负数,返回的结果为 ""。

                      如果 表达式3 是负数,返回的结果为从 表达式2 指定的开始位置以及之后其余部分的子字符串。

                      示例代码

                      假设集合 students 的记录如下:

                      { "birthday": "1999/12/12", "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "birthday": "1998/11/11", "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "birthday": "1997/10/10", "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

                      借助 substrBytes 可以提取 birthday 中的年、月、日信息,代码如下:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    year: $.substrBytes(['$birthday', 0, 4]),    month: $.substrBytes(['$birthday', 5, 2]),    day: $.substrBytes(['$birthday', 8, -1])  })  .end()

                      返回的结果如下:

                      { "day": "12", "month": "12", "year": "1999" }{ "day": "11", "month": "11", "year": "1998" }{ "day": "10", "month": "10", "year": "1997" }

                      AggregateCommand.substrCP(value: Expression[]): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回字符串从指定位置开始的指定长度的子字符串。子字符串是由字符串中指定的 UTF-8 字节索引的字符开始,长度为指定的字节数。

                      参数

                      value: Expression[]

                      [<表达式1>, <表达式2>, <表达式3>]

                      返回值

                      Object

                      API 说明

                      substrCP 的语法如下:

                      db.command.aggregate.substrCP([<表达式1>, <表达式2>, <表达式3>])

                      表达式1 是任何可以解析为字符串的有效表达式,表达式2 和 表达式3 是任何可以解析为数字的有效表达式。

                      如果 表达式2 是负数,返回的结果为 ""。

                      如果 表达式3 是负数,返回的结果为从 表达式2 指定的开始位置以及之后其余部分的子字符串。

                      示例代码

                      假设集合 students 的记录如下:

                      { "name": "dongyuanxin", "nickname": "心谭" }

                      借助 substrCP 可以提取 nickname 字段值的第一个汉字:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    firstCh: $.substrCP(['$nickname', 0, 1])  })  .end()

                      返回的结果如下:

                      { "firstCh": "心" }

                      AggregateCommand.toLower(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将字符串转化为小写并返回。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      toLower 的语法如下:

                      db.command.aggregate.toLower(表达式)

                      只要表达式可以被解析成字符串,那么它就是有效表达式。例如:$ + 指定字段。

                      示例代码

                      假设集合 students 的记录如下:

                      { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

                      借助 toLower 将 firstName 的字段值转化为小写:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    result: $.toLower('$firstName'),  })  .end()

                      返回的结果如下:

                      { "result": "yuanxin" }{ "result": "weijia" }{ "result": "chengxi" }

                      AggregateCommand.toUpper(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将字符串转化为大写并返回。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      toUpper 的语法如下:

                      db.command.aggregate.toUpper(表达式)

                      只要表达式可以被解析成字符串,那么它就是有效表达式。例如:$ + 指定字段。

                      示例代码

                      假设集合 students 的记录如下:

                      { "firstName": "Yuanxin", "group": "a", "lastName": "Dong", "score": 84 }{ "firstName": "Weijia", "group": "a", "lastName": "Wang", "score": 96 }{ "firstName": "Chengxi", "group": "b", "lastName": "Li", "score": 80 }

                      借助 toUpper 将 lastName 的字段值转化为大写:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .project({    _id: 0,    result: $.toUpper('$lastName'),  })  .end()

                      返回的结果如下:

                      { "result": "DONG" }{ "result": "WANG" }{ "result": "LI" }


                      AggregateCommand.addToSet(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。聚合运算符。向数组中添加值,如果数组中已存在该值,不执行任何操作。它只能在 group stage 中使用。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      addToSet 语法如下:

                      db.command.aggregate.addToSet(<表达式>)

                      表达式是形如 $ + 指定字段 的字符串。如果指定字段的值是数组,那么整个数组会被当作一个元素。

                      示例代码

                      假设集合 passages 的记录如下:

                      { "category": "web", "tags": [ "JavaScript", "CSS" ], "title": "title1" }{ "category": "System", "tags": [ "C++", "C" ], "title": "title2" }

                      非数组字段

                      每条记录的 category 对应值的类型是非数组,利用 addToSet 统计所有分类:

                      const $ = db.command.aggregatedb  .collection('passages')  .aggregate()  .group({    _id: null,    categories: $.addToSet('$category')  })  .end()

                      返回的结果如下:

                      { "_id": null, "categories": [ "System", "web" ] }

                      数组字段

                      每条记录的 tags 对应值的类型是数组,数组不会被自动展开:

                      const $ = db.command.aggregatedb  .collection('passages')  .aggregate()  .group({    _id: null,    tagsList: $.addToSet('$tags')  })  .end()

                      返回的结果如下:

                      { "_id": null, "tagsList": [ [ "C++", "C" ], [ "JavaScript", "CSS" ] ] }

                      AggregateCommand.avg(value: Expression<number>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回一组集合中,指定字段对应数据的平均值。

                      参数

                      value: Expression<number>

                      number

                      返回值

                      Object

                      API 说明

                      avg 的语法如下:

                      db.command.aggregate.avg(<number>)

                      avg 传入的值除了数字常量外,也可以是任何最终解析成一个数字的表达式。它会忽略非数字值。

                      示例代码

                      假设集合 students 的记录如下:

                      { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

                      借助 avg 可以计算所有记录的 score 的平均值:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .group({    _id: null,    average: $.avg('$score')  })  .end()

                      返回的结果如下:

                      { "_id": null, "average": 90 }

                      AggregateCommand.first(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回指定字段在一组集合的第一条记录对应的值。仅当这组集合是按照某种定义排序( sort )后,此操作才有意义。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      first 的语法如下:

                      db.command.aggregate.first(<表达式>)

                      表达式是形如 $ + 指定字段 的字符串。

                      first 只能在 group 阶段被使用,并且需要配合 sort 才有意义。

                      示例代码

                      假设集合 students 的记录如下:

                      { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

                      如果需要得到所有记录中 score 的最小值,可以先将所有记录按照 score 排序,然后取出第一条记录的 first。

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .sort({    score: 1  })  .group({    _id: null,    min: $.first('$score')  })  .end()

                      返回的数据结果如下:

                      { "_id": null, "min": 80 }

                      AggregateCommand.last(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回指定字段在一组集合的最后一条记录对应的值。仅当这组集合是按照某种定义排序( sort )后,此操作才有意义。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      last 的语法如下:

                      db.command.aggregate.last(<表达式>)

                      表达式是形如 $ + 指定字段 的字符串。

                      last 只能在 group 阶段被使用,并且需要配合 sort 才有意义。

                      示例代码

                      假设集合 students 的记录如下:

                      { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

                      如果需要得到所有记录中 score 的最大值,可以先将所有记录按照 score 排序,然后取出最后一条记录的 last。

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .sort({    score: 1  })  .group({    _id: null,    max: $.last('$score')  })  .end()

                      返回的数据结果如下:

                      { "_id": null, "max": 100 }

                      AggregateCommand.max(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回一组数值的最大值。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      max 的语法如下:

                      db.command.aggregate.max(<表达式>)

                      表达式是形如 $ + 指定字段 的字符串。

                      示例代码

                      假设集合 students 的记录如下:

                      { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

                      借助 max 可以统计不同组( group )中成绩的最高值,代码如下:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .group({    _id: '$group',    maxScore: $.max('$score')  })  .end()

                      返回的数据结果如下:

                      { "_id": "b", "maxScore": 100 }{ "_id": "a", "maxScore": 96 }```.

                      AggregateCommand.mergeObjects(value: Expression<document>): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。将多个文档合并为单个文档。

                      参数

                      value: Expression<document>

                      Document 表达式

                      返回值

                      Object

                      API 说明

                      使用形式如下: 在 group() 中使用时:

                      mergeObjects(<document>)

                      在其它表达式中使用时:

                      mergeObjects([<document1>, <document2>, ...])

                      示例代码

                      搭配 group() 使用

                      假设集合 sales 存在以下文档:

                      { "_id": 1, "year": 2018, "name": "A", "volume": { "2018Q1": 500, "2018Q2": 500 } }{ "_id": 2, "year": 2017, "name": "A", "volume": { "2017Q1": 400, "2017Q2": 300, "2017Q3": 0, "2017Q4": 0 } }{ "_id": 3, "year": 2018, "name": "B", "volume": { "2018Q1": 100 } }{ "_id": 4, "year": 2017, "name": "B", "volume": { "2017Q3": 100, "2017Q4": 250 } }

                      下面的代码使用 mergeObjects(),将用相同 name 的文档合并:

                      const $ = db.command.aggregatedb.collection('sales').aggregate()  .group({    _id: '$name',    mergedVolume: $.mergeObjects('$volume')  })  .end()

                      输出如下:

                      { "_id": "A", "mergedVolume": { "2017Q1": 400, "2017Q2": 300, "2017Q3": 0, "2017Q4": 0, "2018Q1": 500, "2018Q2": 500 } }{ "_id": "B", "mergedVolume": { "2017Q3": 100, "2017Q4": 250, "2018Q1": 100 } }

                      一般用法

                      假设集合 test 存在以下文档:

                      { "_id": 1, "foo": { "a": 1 }, "bar": { "b": 2 } }{ "_id": 2, "foo": { "c": 1 }, "bar": { "d": 2 } }{ "_id": 3, "foo": { "e": 1 }, "bar": { "f": 2 } }

                      下面的代码使用 mergeObjects(),将文档中的 foo 和 bar 字段合并为 foobar:

                      const $ = db.command.aggregatedb.collection('sales').aggregate()  .project({    foobar: $.mergeObjects(['$foo', '$bar'])  })  .end()

                      输出结果如下:

                      { "_id": 1, "foobar": { "a": 1, "b": 2 } }{ "_id": 2, "foobar": { "c": 1, "d": 2 } }{ "_id": 3, "foobar": { "e": 1, "f": 2 } }

                      AggregateCommand.min(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回一组数值的最小值。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      min 的语法如下:

                      db.command.aggregate.min(<表达式>)

                      表达式是形如 $ + 指定字段 的字符串。

                      示例代码

                      假设集合 students 的记录如下:

                      { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

                      借助 min 可以统计不同组( group )中成绩的最低值,代码如下:

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .group({    _id: '$group',    minScore: $.min('$score')  })  .end()

                      返回的数据结果如下:

                      { "_id": "b", "minScore": 80 }{ "_id": "a", "minScore": 84 }

                      AggregateCommand.push(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。在 group 阶段,返回一组中表达式指定列与对应的值,一起组成的数组。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      push 语法如下:

                      db.command.aggregate.push({  <字段名1>: <指定字段1>,  <字段名2>: <指定字段2>,  ...})

                      示例代码

                      假设集合 students 的记录如下:

                      { "group": "a", "name": "stu1", "score": 84 }{ "group": "a", "name": "stu2", "score": 96 }{ "group": "b", "name": "stu3", "score": 80 }{ "group": "b", "name": "stu4", "score": 100 }

                      借助 push 操作,对不同分组( group )的所有记录,聚合所有数据并且将其放入一个新的字段中,进一步结构化和语义化数据。

                      const $ = db.command.aggregatedb  .collection('students')  .aggregate()  .group({    _id: '$group',    students: $.push({      name: '$name',      score: '$score'    })  })  .end()

                      输出结果如下:

                      { "_id": "b", "students": [{ "name": "stu3", "score": 80 }, { "name": "stu4", "score": 100 }] }{ "_id": "a", "students": [{ "name": "stu1", "score": 84 }, { "name": "stu2", "score": 96 }] }

                      AggregateCommand.stdDevPop(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。返回一组字段对应值的标准差。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      stdDevPop 的使用形式如下:

                      db.command.aggregate.stdDevPop(<表达式>)

                      表达式传入的是指定字段,指定字段对应的值的数据类型必须是 number ,否则结果会返回 null。

                      示例代码

                      假设集合 students 的记录如下:a 组同学的成绩分别是84和96,b组同学的成绩分别是80和100。

                      { "group":"a", "score":84 }{ "group":"a", "score":96 }{ "group":"b", "score":80 }{ "group":"b", "score":100 }

                      可以用 stdDevPop 来分别计算 a 和 b 两组同学成绩的标准差,以此来比较哪一组同学的成绩更稳定。代码如下:

                      const $ = db.command.aggregatedb.collection('students').aggregate()  .group({    _id: '$group',    stdDev: $.stdDevPop('$score')  })  .end()

                      返回的数据结果如下:

                      { "_id": "b", "stdDev": 10 }{ "_id": "a", "stdDev": 6 }

                      AggregateCommand.stdDevSamp(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。计算输入值的样本标准偏差。如果输入值代表数据总体,或者不概括更多的数据,请改用 db.command.aggregate.stdDevPop。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      stdDevSamp 的使用形式如下:

                      db.command.aggregate.stdDevSamp(<表达式>)

                      表达式传入的是指定字段,stdDevSamp 会自动忽略非数字值。如果指定字段所有的值均是非数字,那么结果返回 null。

                      示例代码

                      假设集合 students 的记录如下:

                      { "score": 80 }{ "score": 100 }

                      可以用 stdDevSamp 来计算成绩的标准样本偏差。代码如下:

                      const $ = db.command.aggregatedb.collection('students').aggregate()  .group({    _id: null,    ageStdDev: $.stdDevSamp('$score')  })  .end()

                      返回的数据结果如下:

                      { "_id": null, "ageStdDev": 14.142135623730951 }

                      如果向集合 students 添加一条新记录,它的 score 字段类型是 string:

                      { "score": "aa" }

                      用上面代码计算标准样本偏差时,stdDevSamp 会自动忽略类型不为 number 的记录,返回结果保持不变。


                      AggregateCommand.sum(value: Expression): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。计算并且返回一组字段所有数值的总和。

                      参数

                      value: Expression

                      表达式

                      返回值

                      Object

                      API 说明

                      sum 的使用形式如下:

                      db.command.aggregate.sum(<表达式>)

                      表达式可以传入指定字段,也可以传入指定字段组成的列表。sum 会自动忽略非数字值。如果字段下的所有值均是非数字,那么结果返回 0。若传入数字常量,则当做所有记录该字段的值都给给定常量,在聚合时相加,最终值为输入记录数乘以常量。

                      示例代码

                      假设代表商品的集合 goods 的记录如下:price 代表商品销售额,cost 代表商品成本

                      { "cost": -10, "price": 100 }{ "cost": -15, "price": 1 }{ "cost": -10, "price": 10 }

                      单独字段

                      借助 sum 可以计算所有商品的销售总和,代码如下:

                      const $ = db.command.aggregatedb  .collection('goods')  .aggregate()  .group({    _id: null,    totalPrice: $.sum('$price')  })  .end()

                      返回的数据结果如下:销售额是 111

                      { "_id": null, "totalPrice": 111 }

                      字段列表

                      如果需要计算所有商品的利润总额,那么需要将每条记录的 cost 和 price 相加得到此记录对应商品的利润。最后再计算所有商品的利润总额。

                      借助 sum,代码如下:

                      const $ = db.command.aggregatedb  .collection('goods')  .aggregate()  .group({    _id: null,    totalProfit: $.sum(      $.sum(['$price', '$cost'])    )  })  .end()

                      返回的数据结果如下:利润总额为 76

                      { "_id": null, "totalProfit": 76 }


                      AggregateCommand.let(value: any): Object

                      支持端:小程序 2.7.4, 云函数 0.8.1, Web

                      聚合操作符。自定义变量,并且在指定表达式中使用,返回的结果是表达式的结果。

                      参数

                      value: any

                      返回值

                      Object

                      API 说明

                      let 的语法如下:

                      db.command.aggregate.let({  vars: {    <变量1>: <变量表达式>,    <变量2>: <变量表达式>,    ...  },  in: <结果表达式>})

                      vars 中可以定义多个变量,变量的值由 变量表达式 计算而来,并且被定义的变量只有在 in 中的 结果表达式 才可以访问。

                      在 in 的结果表达式中访问自定义变量时候,请在变量名前加上双美元符号( $$ )并用引号括起来。

                      示例代码

                      假设代表商品的集合 goods 的记录如下:price 代表商品价格,discount 代表商品折扣率,cost 代表商品成本

                      { "cost": -10, "discount": 0.95, "price": 100 }{ "cost": -15, "discount": 0.98, "price": 1 }{ "cost": -10, "discount": 1, "price": 10 }

                      借助 let 可以定义并计算每件商品实际的销售价格,并将其赋值给自定义变量 priceTotal。最后再将 priceTotal 与 cost 进行取和( sum )运算,得到每件商品的利润。

                      代码如下:

                      const $ = db.command.aggregatedb  .collection('goods')  .aggregate()  .project({    profit: $.let({      vars: {        priceTotal: $.multiply(['$price', '$discount'])      },      in: $.sum(['$$priceTotal', '$cost'])    })  })  .end()

                      返回的数据结果如下:

                      { "profit": 85 }{ "profit": -14.02 }{ "profit": 0 }


                      云函数

                      注意: HTTP API 途径触发云函数不包含用户信息



                      云开发 HTTP API 提供了以下云函数调用 API:

                      触发云函数:

                      invokeCloudFunction

                      本接口应在服务器端调用,详细说明参见服务端API。

                      触发云函数。注意:HTTP API 途径触发云函数不包含用户信息。

                      请求地址

                      POST https://api.weixin.qq.com/tcb/invokecloudfunction?access_token=ACCESS_TOKEN&env=ENV&name=FUNCTION_NAME

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云开发环境ID
                      namestring云函数名称
                      POSTBODYstring云函数的传入参数,具体结构由开发者定义。

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      resp_datastring云函数返回的buffer

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      示例代码

                      curl -d '{}' 'https://api.weixin.qq.com/tcb/invokecloudfunction?access_token=ACCESS_TOKEN&env=ENV&name=login'

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "resp_data": "{"event":{"userInfo":{"appId":"SAMPLE_APPID"}},"appid":"SAMPLE_APPID"}"}

                      Tips

                      1. 使用本API触发云函数,在云函数中无法获取OpenID等用户相关信息,无法使用涉及用户登录态的其他API。
                      2. 注意 POST BODY 部分会传递给云函数作为输入参数。
                      3. 由 HTTP API 触发的云函数可以使用云调用。
                      4. 由 HTTP API 触发云函数的超时时间为5s,请注意云函数的执行时间不能过长。


                      databaseMigrateImport

                      本接口应在服务器端调用,详细说明参见服务端API。

                      数据库导入

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databasemigrateimport?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      collection_namestring导入collection名
                      file_pathstring导入文件路径(导入文件需先上传到同环境的存储中,可使用开发者工具或 HTTP API的上传文件 API上传)
                      file_typenumber导入文件类型,文件格式参考数据库导入指引中的文件格式部分
                      stop_on_errorbool是否在遇到错误时停止导入
                      conflict_modenumber冲突处理模式

                      file_type 的合法值

                      说明最低版本
                      1JSON
                      2CSV

                      conflict_mode 的合法值

                      说明最低版本
                      1INSERT
                      2UPSERT

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      job_idnumber导入任务ID,可使用数据库迁移进度查询 API 查询导入进度及结果

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {	"env": "qbasetest-a5c40e",	"collection_name": "test1",	"file_path":"test_import",	"file_type":1,	"stop_on_error": false,	"conflict_mode": 2}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "job_id": 100074947}


                      databaseMigrateExport

                      本接口应在服务器端调用,详细说明参见服务端API。

                      数据库导出

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databasemigrateexport?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      file_pathstring导出文件路径(文件会导出到同环境的云存储中,可使用获取下载链接 API 获取下载链接)
                      file_typenumber导出文件类型,文件格式参考数据库导入指引中的文件格式部分
                      querystring导出条件

                      file_type 的合法值

                      说明最低版本
                      1JSON
                      2CSV

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      job_idnumber导出任务ID,使用数据库迁移进度查询 API 查询导出结果,获取文件下载链接。

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {    "env":"test2-4a89da",    "file_path":"test_export",    "file_type":1,    "query":"const Point = db.Geo.Point;db.collection('geo').where({name: 'x',age: _.gt(10).and(_.lt(20)),loc: new Point(113,23),array: [1,2]}).limit(10).skip(1).orderBy('age','asc').orderBy('name', 'desc').field({ name: true }).get()"}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "job_id": 100074947}

                      导出条件说明

                      查询语句语法与数据库 API相同


                      databaseMigrateQueryInfo

                      本接口应在服务器端调用,详细说明参见服务端API。

                      数据库迁移状态查询

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databasemigratequeryinfo?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      job_idnumber迁移任务ID

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      statusstring导出状态
                      record_successnumber导出成功记录数
                      record_failnumber导出失败记录数
                      err_msgstring导出错误信息
                      file_urlstring导出文件下载地址

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {	"env": "test2-4a89da",	"job_id": 100071736}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "status": "success",    "record_success": 3,    "record_fail": 0,    "error_msg": "导出完成.",    "file_url": "https://tcb-mongodb-data-1254135806.cos.ap-shanghai.myqcloud.com/..."


                      updateIndex

                      本接口应在服务器端调用,详细说明参见服务端API。

                      变更数据库索引

                      请求地址

                      POST https://api.weixin.qq.com/tcb/updateindex?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      collection_namestring集合名称
                      create_indexesArray.<Object>新增索引
                      drop_indexesArray.<Object>删除索引

                      create_indexes 的结构

                      属性类型默认值必填说明
                      namestring索引名
                      uniqueboolean是否唯一
                      keysArray.<Object>索引字段

                      keys 的结构

                      属性类型默认值必填说明
                      namestring字段名
                      directionstring字段排序

                      direction 的合法值

                      说明最低版本
                      "1"升序
                      "-1"降序
                      "2dsphere"地理位置

                      drop_indexes 的结构

                      属性类型默认值必填说明
                      namestring索引名

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {  "env": "test2-4a89da",  "collection_name": "counters",  "create_indexes": [    {      "name":"add_index",      "unique": true,      "keys": [        {          "name": "test",          "direction": "2dsphere"        }        ]    }    ],  "drop_indexes": [    {      "name":"del_index"    }    ]}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",}


                      databaseCollectionAdd

                      本接口应在服务器端调用,详细说明参见服务端API。

                      新增集合

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databasecollectionadd?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      collection_namestring集合名称

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {  "env":"test2-4a89da",  "collection_name": "test_add_collection"}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",}


                      databaseCollectionDelete

                      本接口应在服务器端调用,详细说明参见服务端API。

                      删除集合

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databasecollectiondelete?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      collection_namestring集合名称

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {  "env":"test2-4a89da",  "collection_name": "test_delete_collection"}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",}


                      databaseCollectionGet

                      本接口应在服务器端调用,详细说明参见服务端API。

                      获取特定云环境下集合信息

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databasecollectionget?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      limitnumber10获取数量限制
                      offsetnumber0偏移量

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      pagerObject分页信息
                      collectionsArray.<Object>集合信息

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      pager 的结构

                      属性类型说明
                      Offsetnumber偏移
                      Limitnumber单次查询限制
                      Totalnumber符合查询条件的记录总数

                      collections 的结构

                      属性类型说明
                      namestring集合名
                      countnumber表中文档数量
                      sizenumber表的大小(即表中文档总大小),单位:字节
                      index_countnumber索引数量
                      index_sizenumber索引占用大小,单位:字节

                      请求数据示例

                      {  "env":"test2-4a89da",  "limit": 10,  "offset": 0}

                      返回数据示例

                      {  "errcode": 0,  "errmsg": "ok",  "collections": [      {          "name": "geo",          "count": 13,          "size": 2469,          "index_count": 1,          "index_size": 36864      },      {          "name": "test_collection",          "count": 1,          "size": 67,          "index_count": 1,          "index_size": 16384      }  ],  "pager": {      "Offset": 0,      "Limit": 10,      "Total": 2  }}


                      databaseAdd

                      本接口应在服务器端调用,详细说明参见服务端API。

                      数据库插入记录

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databaseadd?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      querystring数据库操作语句

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      id_listArray.<string>插入成功的数据集合主键_id。

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {    "env":"test2-4a89da",    "query": "db.collection("geo").add({      data: [{        description: "item1",        due: new Date("2019-09-09"),        tags: [          "cloud",          "database"        ],        location: new db.Geo.Point(113, 23),        done: false      },      {        description: "item2",        due: new Date("2019-09-09"),        tags: [          "cloud",          "database"        ],        location: new db.Geo.Point(113, 23),        done: false      }      ]    })"}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "id_list": [        "be62d9c4-43ec-4dc6-8ca1-30b206eeed24",        "0f4b8add5cdd728a003bf5c83ed99dff"    ]}

                      数据库操作语句说明

                      数据库操作语句语法与数据库 API相同


                      databaseDelete

                      本接口应在服务器端调用,详细说明参见服务端API。

                      数据库删除记录

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databasedelete?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      querystring数据库操作语句

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      deletednumber删除记录数量

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例1: 操作集合

                      {  "env":"test2-4a89da",  "query": "db.collection("geo").where({done:false}).remove()"}

                      返回数据示例1: 操作集合

                      {    "errcode": 0,    "errmsg": "ok",    "deleted": 2}

                      请求数据示例2: 操作记录

                      {  "env":"test2-4a89da",  "query": "db.collection("geo").doc("be62d9c4-43ec-4dc6-8ca1-30b206eeed24").remove()"}

                      返回数据示例2: 操作记录

                      {    "errcode": 0,    "errmsg": "ok",    "deleted": 1}

                      数据库操作语句说明

                      数据库操作语句语法与数据库 API相同


                      databaseUpdate

                      本接口应在服务器端调用,详细说明参见服务端API。

                      数据库更新记录

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databaseupdate?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      querystring数据库操作语句

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      matchednumber更新条件匹配到的结果数
                      modifiednumber修改的记录数,注意:使用set操作新插入的数据不计入修改数目
                      idstring新插入记录的id,注意:只有使用set操作新插入数据时这个字段会有值

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例1: 操作集合

                      {  "env":"test2-4a89da",  "query": "db.collection("geo").where({age:14}).update({data:{age: _.inc(1)}})"}

                      返回数据示例1: 操作集合

                      {    "errcode": 0,    "errmsg": "ok",    "matched": 1,    "modified": 1,    "id": ""}

                      请求数据示例2: 更新一条记录

                      {  "env":"test2-4a89da",  "query": "db.collection("geo").doc("56abd6d5-9daf-4fc7-af05-eca13933f1aa").update({data:{age: 10}})"}

                      返回数据示例2: 更新一条记录

                      {    "errcode": 0,    "errmsg": "ok",    "matched": 1,    "modified": 1,    "id": ""}

                      请求数据示例3: 更新替换一条记录

                      {  "env":"test2-4a89da",  "query": "db.collection("geo").doc("be62d9c4-43ec-4dc6-8ca1-30b206eeed24").set({data: {        description: "set",        done: true      }})"}

                      返回数据示例3: 更新替换一条记录

                      {    "errcode": 0,    "errmsg": "ok",    "matched": 0,    "modified": 0,    "id": "be62d9c4-43ec-4dc6-8ca1-30b206eeed24"}

                      数据库操作语句说明

                      数据库操作语句语法与数据库 API相同


                      databaseQuery

                      本接口应在服务器端调用,详细说明参见服务端API。

                      数据库查询记录

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databasequery?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      querystring数据库操作语句

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      pagerObject分页信息
                      dataArray.<string>记录数组

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      pager 的结构

                      属性类型说明
                      Offsetnumber偏移
                      Limitnumber单次查询限制
                      Totalnumber符合查询条件的记录总数

                      Tips

                      query中应使用limit()限制单次拉取的数量,默认10条。

                      请求数据示例

                      {  "env":"test2-4a89da",  "query": "db.collection("geo").where({done:true}).limit(10).skip(1).get()"}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "pager": {        "Offset": 1,        "Limit": 10,        "Total": 2    },    "data": [        "{"_id":"b15498af-1a5a-40b4-a4e7-b3fc4a1df482","done":true,"name":"test"}"    ]}

                      数据库操作语句说明

                      数据库操作语句语法与数据库 API相同


                      databaseAggregate

                      本接口应在服务器端调用,详细说明参见服务端API。

                      数据库聚合

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databaseaggregate?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      Querystring数据库操作语句

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      dataArray.<string>记录数组

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {  "env":"test2-4a89da",  "query": "db.collection("test_collection").aggregate().match({tags:"cloud"}).limit(10).end()"}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "data": [    "{"_id":"f77e039f-f1cf-4aa8-bd59-16cbaa91e6ea","location":{"type":"Point","coordinates":[{"$numberDouble":"113.0"},{"$numberDouble":"23.0"}]},"done":false,"description":"learn cloud database","due":"2019-09-09","tags":["cloud","database"]}",        "{"_id":"6bb88938-49ea-42b6-a6f5-ce408970cfc6","due":"2019-09-09","tags":["cloud","database"],"location":{"type":"Point","coordinates":[{"$numberDouble":"113.0"},{"$numberDouble":"23.0"}]},"done":false,"description":"学习 cloud database"}",        "{"_id":"51f4f67e-a6a1-4c3e-a50f-827380b8da86","description":"学习 cloud database","due":"2019-09-09","tags":["cloud","database"],"location":{"coordinates":[{"$numberDouble":"113.0"},{"$numberDouble":"23.0"}],"type":"Point"},"done":false}",        "{"_id":"ee1d69da-b7ec-4e7a-bc1f-2fae31da4ce0","tags":["cloud","database"],"location":{"type":"Point","coordinates":[{"$numberDouble":"113.0"},{"$numberDouble":"23.0"}]},"done":false,"description":"学习 cloud database","due":"2019-09-09"}"    ]}

                      数据库操作语句说明

                      数据库操作语句语法与数据库 API相同, 聚合操作参考聚合文档


                      databaseCount

                      本接口应在服务器端调用,详细说明参见服务端API。

                      统计集合记录数或统计查询语句对应的结果记录数

                      请求地址

                      POST https://api.weixin.qq.com/tcb/databasecount?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      querystring数据库操作语句

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      countnumber记录数量

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {  "env":"test2-4a89da",  "query": "db.collection("geo").where({done:true}).count()"}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "count": 3}

                      数据库操作语句说明

                      数据库操作语句语法与数据库 API相同


                      存储

                      云开发 HTTP API 提供了以下存储相关 API:


                      uploadFile

                      本接口应在服务器端调用,详细说明参见服务端API。

                      获取文件上传链接

                      请求地址

                      POST https://api.weixin.qq.com/tcb/uploadfile?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      pathstring上传路径

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      urlstring上传url
                      tokenstringtoken
                      authorizationstringauthorization
                      file_idstring文件ID
                      cos_file_idstringcos文件ID

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {	"env": "test2-4a89da",	"path": "this/is/a/example/file.path"}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "url": "https://cos.ap-shanghai.myqcloud.com/7465-test2-4a89da-1258717764/testupload",    "token": "Cukha70zkXIBqkh1OhUIFqjUmXLXeSWq7dff61099221bb270522b8e0cf21d72e0aWCfGXEIDT5bKVJgykFFr9_MeQ-ExrsZ8oiFdMwyYag8h0r-EJq_EaO94KzksxH6bAeb4Y7SwZjJqoy_4g1Na797F1IEG9Dnstm_rz02AgaP5HbJwt1P-XHT4Xjw_lafla079gtQKAP-EPbE5Tc8BRXIm32esjGDDDuDyml7IJqbsPolYZ4-CHQsisdx488loGAN4f7YRMkrrP1Pgi5XOm0-iG5HbWd3tHtuE2pzsGkTobO_fyz2PfSPaeUt_735ll38yIWpAFESAsZnBj2DcRSPBT2FJ_s5mOZACS53q6-tWXPO0AR3-EhOCQpiDKsldVsCxz00Uwhgm1T6Ozw777fJEFkUIngUdZ5yajy3LA84Mpfu6CLkFjfiBtz3wpmcCQxhijo_CrVHkmaMc2JBQ",    "authorization": "q-sign-algorithm=sha1&q-ak=AKID98EDB528Sfqerp0Z_7l23we-u4Avrx04te9VvlzGihMTseysMgu7iSdh_hxEnoAy&q-sign-time=1557307130;1557308030&q-key-time=1557307130;1557308030&q-header-list=&q-url-param-list=&q-signature=ac95227b67a04157bb5e49b435c6ac3ce88e03f2",    "file_id": "cloud://test2-4a89da.7465-test2-4a89da-1258717764/testupload",    "cos_file_id": "HDze32/qZENCwWi5N5akgoXSv3U8DsccKaqCxTMGs0zFgvlD28j484/VYFPJ1l2QDh0Qy8wNbQCpxs5zEsLJln1lIY9RGYn1LzRQQQYFQm+Xwvw6S4YEZN1AIwY906mwIBgiI3gKGkU2K1+1ZEnEYEM4Uh/C1JxB4Q=="}

                      上传链接使用说明

                      用户获取到返回数据后,需拼装一个 HTTP POST 请求,其中 url 为返回包的 url 字段,Body 部分格式为 multipart/form-data,具体内容如下:

                      keyvalue说明
                      keythis/is/a/example/file.path请求包中的 path 字段
                      Signatureq-sign-algorithm=sha1&q-ak=AKID9...返回数据的 authorization 字段
                      x-cos-security-tokenCukha70zkXIBqkh1Oh...返回数据的 token 字段
                      x-cos-meta-fileidHDze32/qZENCwWi5...返回数据的 cos_file_id 字段
                      file文件内容文件的二进制内容

                      batchDownloadFile

                      本接口应在服务器端调用,详细说明参见服务端API。

                      获取文件下载链接

                      请求地址

                      POST https://api.weixin.qq.com/tcb/batchdownloadfile?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      file_listArray.<Object>文件列表

                      file_list 的结构

                      属性类型默认值必填说明
                      fileidstring文件ID
                      max_agenumber下载链接有效期

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      file_listArray.<Object>文件列表

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      file_list 的结构

                      属性类型说明
                      fileidstring文件ID
                      download_urlstring下载链接
                      statusnumber状态码
                      errmsgstring该文件错误信息

                      请求数据示例

                      {	"env": "test2-4a89da",	"file_list": [		{			"fileid":"cloud://test2-4a89da.7465-test2-4a89da/A.png",			"max_age":7200		}		]}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "file_list": [        {            "fileid": "cloud://test2-4a89da.7465-test2-4a89da/A.png",            "download_url": "https://7465-test2-4a89da-1258717764.tcb.qcloud.la/A.png",            "status": 0,            "errmsg": "ok"        }    ]}

                      batchDeleteFile

                      本接口应在服务器端调用,详细说明参见服务端API。

                      删除文件

                      请求地址

                      POST https://api.weixin.qq.com/tcb/batchdeletefile?access_token=ACCESS_TOKEN

                      请求参数

                      属性类型默认值必填说明
                      access_tokenstring接口调用凭证
                      envstring云环境ID
                      fileid_listArray.<string>文件ID列表

                      返回值

                      Object

                      返回的 JSON 数据包

                      属性类型说明
                      errcodenumber错误码
                      errmsgstring错误信息
                      delete_listArray.<string>文件列表

                      errcode 的合法值

                      说明最低版本
                      0请求成功
                      -1系统错误
                      -1000系统错误
                      40014AccessToken 不合法
                      40097请求参数错误
                      40101缺少必填参数
                      41001缺少AccessToken
                      42001AccessToken过期
                      43002HTTP METHOD 错误
                      44002POST BODY 为空
                      47001POST BODY 格式错误
                      85088该APP未开通云开发
                      其他错误码云开发错误码

                      请求数据示例

                      {	"env": "test2-4a89da",	"fileid_list": [		"cloud://test2-4a89da.7465-test2-4a89da/A.png"	]}

                      返回数据示例

                      {    "errcode": 0,    "errmsg": "ok",    "delete_list": [        {            "fileid": "cloud://test2-4a89da.7465-test2-4a89da/A.png",            "status": 0,            "errmsg": "ok"        }    ]}


                      快速上手

                      使用之前

                      扩展组件库基于小程序自定义组件构建,在使用扩展组件库之前,建议先阅读熟悉小程序自定义组件。

                      引入组件

                      1. 通过 useExtendedLib 扩展库 的方式引入,这种方式引入的组件将不会计入代码包大小。
                      2. 可以通过npm方式下载构建,npm包名为weui-miniprogram

                      如何使用

                      首先要在 app.wxss 里面引入 weui.wxss,如果是通过 npm 引入,需要先构建 npm(“工具”菜单 --> “构建 npm”)

                      通过 useExtendedLib 扩展库 的方式引入,可省略 import 步骤

                      @import '/miniprogram_npm/weui-miniprogram/weui-wxss/dist/style/weui.wxss';

                      然后可以在页面中引入 dialog 弹窗组件

                      1. 首先在页面的 json 文件加入 usingComponents 配置字段
                      {  "usingComponents": {    "mp-dialog": "/miniprogram_npm/weui-miniprogram/dialog/dialog"  }}
                      1. 然后可以在对应页面的 wxml 中直接使用该组件
                      <mp-dialog title="test" show="{{true}}" bindbuttontap="tapDialogButton" buttons="{{[{text: '取消'}, {text: '确认'}]}}">    <view>test content</view></mp-dialog>

                      完整的组件的使用文档请参考具体的组件的文档。

                      修改组件内部样式

                      每个组件可以设置ext-class这个属性,该属性提供设置在组件WXML顶部元素的class,组件的addGlobalClass的options都设置为true,所以可以在页面设置wxss样式来覆盖组件的内部样式。需要注意的是,如果要覆盖组件内部样式,必须wxss的样式选择器的优先级比组件内部样式优先级高。 addGlobalClass在基础库2.2.3开始支持。

                      适配 DarkMode

                      在根结点(或组件的外层结点)增加属性 data-weui-theme="dark",即可把 WeUI 组件切换到 DarkMode 的表现,如:

                      <view data-weui-theme="dark">    ...</view>

                      也可以参考库中提供的 Demo。


                      Badge徽章

                      出现在按钮、图标附近的数字或者状态标记。

                      示例代码:

                      {  "usingComponents": {    "mp-cells": "../components/cells/cells",    "mp-cell": "../components/cell/cell",    "mp-badge": "../components/badge/badge"  }}

                      Gallery画廊

                      用于多张图片展示,类似原生的wx.previewImage的展示。

                      示例代码:

                      {  "usingComponents": {    "mp-gallery": "../components/gallery/gallery"  }}

                      Loading加载

                      加载数据时的 loading 效果

                      示例代码:

                      {    "usingComponents": {        "mp-loading": "../components/loading/loading"    },    "navigationBarTitleText": "UI组件库"}

                      Icon

                      图标

                      代码引入

                      在 page.json 中引入组件

                      {  "usingComponents": {    "mp-icon": "../../components/icon/icon"  }}

                      示例代码

                      <!--WXML示例代码--><mp-icon type="field" icon="add" color="black" size="{{25}}"></mp-icon><mp-icon icon="add" color="black" size="{{25}}"></mp-icon>

                      效果展示

                      属性列表

                      属性类型默认值说明
                      extClassstring组件类名
                      typestringoutlineIcon类型,可选值 outline(描边),field(填充)
                      iconstringIcon名字
                      sizenumber20Icon的大小,单位 px
                      colorstringblackIcon的颜色,默认黑色

                      Icon 列表

                       


                      Form

                      Form表单组件,结合Cell、Checkbox-group、Checkbox组件等做表单校验。

                      示例代码:

                      {  "component": true,  "usingComponents": {    "mp-toptips": "../components/toptips/toptips",    "mp-cells": "../components/cells/cells",    "mp-cell": "../components/cell/cell",    "mp-checkbox": "../components/checkbox/checkbox",    "mp-checkbox-group": "../components/checkbox-group/checkbox-group",    "mp-form": "../components/form/form"  }}
                      <mp-toptips msg="{{error}}" type="error" show="{{error}}"></mp-toptips><view class="page" xmlns:wx="http://www.w3.org/1999/xhtml">    <view class="page__hd">        <view class="page__title">Form</view>        <view class="page__desc">表单输入</view>    </view>    <view class="page__bd">        <mp-form id="form" rules="{{rules}}" models="{{formData}}">            <mp-cells title="单选列表项">                <mp-checkbox-group prop="radio" multi="{{false}}" bindchange="radioChange">                    <mp-checkbox wx:for="{{radioItems}}" wx:key="value" label="{{item.name}}" value="{{item.value}}" checked="{{item.checked}}"></mp-checkbox>                </mp-checkbox-group>            </mp-cells>            <mp-cells title="复选列表项">                <mp-checkbox-group prop="checkbox" multi="{{true}}" bindchange="checkboxChange">                    <mp-checkbox wx:for="{{checkboxItems}}" wx:key="value" label="{{item.name}}" value="{{item.value}}" checked="{{item.checked}}"></mp-checkbox>                </mp-checkbox-group>            </mp-cells>            <mp-cells title="表单" footer="底部说明文字底部说明文字">                <mp-cell prop="qq" title="qq" ext-class="">                    <input bindinput="formInputChange" data-field="qq" class="weui-input" placeholder="请输入qq"/>                </mp-cell>                <mp-cell prop="mobile" title="手机号" ext-class=" weui-cell_vcode">                    <input bindinput="formInputChange" data-field="mobile" class="weui-input" placeholder="请输入手机号"/>                    <view slot="footer" class="weui-vcode-btn">获取验证码</view>                </mp-cell>                <mp-cell prop="date" title="日期" ext-class="">                    <picker data-field="date" mode="date" value="{{date}}" start="2015-09-01" end="2017-09-01" bindchange="bindDateChange">                        <view class="weui-input">{{date}}</view>                    </picker>                </mp-cell>                <mp-cell prop="vcode" title="验证码" ext-class=" weui-cell_vcode">                    <input bindinput="formInputChange" data-field="vcode" class="weui-input" placeholder="请输入验证码"/>                    <image slot="footer" class="weui-vcode-img" src="../images/vcode.jpg" style="width: 108px"></image>                </mp-cell>            </mp-cells>            <mp-cells title="提交后表单项报错">                <mp-cell show-error prop="idcard" title="卡号" ext-class="">                    <input bindinput="formInputChange" data-field="idcard" class="weui-input" placeholder="请输入卡号"/>                </mp-cell>            </mp-cells>        </mp-form>        <view class="weui-cells__title">开关</view>        <view class="weui-cells weui-cells_after-title">            <view class="weui-cell weui-cell_switch">                <view class="weui-cell__bd">标题文字</view>                <view class="weui-cell__ft">                    <switch checked />                </view>            </view>        </view>        <view class="weui-cells__title">文本框</view>        <view class="weui-cells weui-cells_after-title">            <view class="weui-cell">                <view class="weui-cell__bd">                    <input class="weui-input" placeholder="请输入文本" />                </view>            </view>        </view>        <view class="weui-cells__title">文本域</view>        <view class="weui-cells weui-cells_after-title">            <view class="weui-cell">                <view class="weui-cell__bd">                    <textarea class="weui-textarea" placeholder="请输入文本" style="height: 3.3em" />                    <view class="weui-textarea-counter">0/200</view>                </view>            </view>        </view>        <view class="weui-cells__title">选择</view>        <view class="weui-cells weui-cells_after-title">            <view class="weui-cell weui-cell_select">                <view class="weui-cell__hd" style="width: 105px">                    <picker bindchange="bindCountryCodeChange" value="{{countryCodeIndex}}" range="{{countryCodes}}">                        <view class="weui-select">{{countryCodes[countryCodeIndex]}}</view>                    </picker>                </view>                <view class="weui-cell__bd weui-cell__bd_in-select-before">                    <input class="weui-input" placeholder="请输入号码" />                </view>            </view>        </view>        <view class="weui-cells__title">选择</view>        <view class="weui-cells weui-cells_after-title">            <view class="weui-cell weui-cell_select">                <view class="weui-cell__bd">                    <picker bindchange="bindAccountChange" value="{{accountIndex}}" range="{{accounts}}">                        <view class="weui-select">{{accounts[accountIndex]}}</view>                    </picker>                </view>            </view>            <view class="weui-cell weui-cell_select">                <view class="weui-cell__hd weui-cell__hd_in-select-after">                    <view class="weui-label">国家/地区</view>                </view>                <view class="weui-cell__bd">                    <picker bindchange="bindCountryChange" value="{{countryIndex}}" range="{{countries}}">                        <view class="weui-select weui-select_in-select-after">{{countries[countryIndex]}}</view>                    </picker>                </view>            </view>        </view>        <checkbox-group bindchange="bindAgreeChange">            <label class="weui-agree" for="weuiAgree">                <view class="weui-agree__text">                    <checkbox class="weui-agree__checkbox" id="weuiAgree" value="agree" checked="{{isAgree}}" />                    <view class="weui-agree__checkbox-icon">                        <icon class="weui-agree__checkbox-icon-check" type="success_no_circle" size="9" wx:if="{{isAgree}}"></icon>                    </view>                    阅读并同意<navigator url="" class="weui-agree__link">《相关条款》</navigator>                </view>            </label>        </checkbox-group>        <view class="weui-btn-area">            <button class="weui-btn" type="primary" bindtap="submitForm">确定</button>        </view>    </view></view>
                      Component({    data: {        showTopTips: false,        radioItems: [            {name: 'cell standard', value: '0', checked: true},            {name: 'cell standard', value: '1'}        ],        checkboxItems: [            {name: 'standard is dealt for u.', value: '0', checked: true},            {name: 'standard is dealicient for u.', value: '1'}        ],        items: [            {name: 'USA', value: '美国'},            {name: 'CHN', value: '中国', checked: 'true'},            {name: 'BRA', value: '巴西'},            {name: 'JPN', value: '日本'},            {name: 'ENG', value: '英国'},            {name: 'TUR', value: '法国'},        ],        date: "2016-09-01",        time: "12:01",        countryCodes: ["+86", "+80", "+84", "+87"],        countryCodeIndex: 0,        countries: ["中国", "美国", "英国"],        countryIndex: 0,        accounts: ["微信号", "QQ", "Email"],        accountIndex: 0,        isAgree: false,        formData: {        },        rules: [{            name: 'radio',            rules: {required: true, message: '单选列表是必选项'},        }, {            name: 'checkbox',            rules: {required: true, message: '多选列表是必选项'},        }, {            name: 'qq',            rules: {required: true, message: 'qq必填'},        }, {            name: 'mobile',            rules: [{required: true, message: 'mobile必填'}, {mobile: true, message: 'mobile格式不对'}],        }, {            name: 'vcode',            rules: {required: true, message: '验证码必填'},        }, {            name: 'idcard',            rules: {required: true, message: 'idcard必填'},        }]    },    methods: {        radioChange: function (e) {            console.log('radio发生change事件,携带value值为:', e.detail.value);                var radioItems = this.data.radioItems;            for (var i = 0, len = radioItems.length; i < len; ++i) {                radioItems[i].checked = radioItems[i].value == e.detail.value;            }                this.setData({                radioItems: radioItems,                [`formData.radio`]: e.detail.value            });        },        checkboxChange: function (e) {            console.log('checkbox发生change事件,携带value值为:', e.detail.value);                var checkboxItems = this.data.checkboxItems, values = e.detail.value;            for (var i = 0, lenI = checkboxItems.length; i < lenI; ++i) {                checkboxItems[i].checked = false;                    for (var j = 0, lenJ = values.length; j < lenJ; ++j) {                    if(checkboxItems[i].value == values[j]){                        checkboxItems[i].checked = true;                        break;                    }                }            }                this.setData({                checkboxItems: checkboxItems,                [`formData.checkbox`]: e.detail.value            });        },        bindDateChange: function (e) {            this.setData({                date: e.detail.value,                [`formData.date`]: e.detail.value            })        },        formInputChange(e) {            const {field} = e.currentTarget.dataset            this.setData({                [`formData.${field}`]: e.detail.value            })        },        bindTimeChange: function (e) {            this.setData({                time: e.detail.value            })        },        bindCountryCodeChange: function(e){            console.log('picker country code 发生选择改变,携带值为', e.detail.value);                this.setData({                countryCodeIndex: e.detail.value            })        },        bindCountryChange: function(e) {            console.log('picker country 发生选择改变,携带值为', e.detail.value);                this.setData({                countryIndex: e.detail.value            })        },        bindAccountChange: function(e) {            console.log('picker account 发生选择改变,携带值为', e.detail.value);                this.setData({                accountIndex: e.detail.value            })        },        bindAgreeChange: function (e) {            this.setData({                isAgree: !!e.detail.value.length            });        },        submitForm() {            this.selectComponent('#form').validate((valid, errors) => {                console.log('valid', valid, errors)                if (!valid) {                    const firstError = Object.keys(errors)                    if (firstError.length) {                        this.setData({                            error: errors[firstError[0]].message                        })                        }                } else {                    wx.showToast({                        title: '校验通过'                    })                }            })        }    }});

                      FormPage

                      表单页面,规定了标准表单的顶部的标题和底部的按钮提示等区域的规范

                      代码引入

                      在 page.json 中引入组件

                      {  "usingComponents": {    "mp-form-page": "../../components/form-page/form-page",    "mp-form": "../../components/form/form"  }}

                      示例代码

                      <!--WXML示例代码--><mp-form-page title="表单结构" subtitle="展示表单页面的信息结构样式, 分别由头部区域/控件区域/提示区域/操作区域和底部信息区域组成。">    <mp-form id="form" rules="{{rules}}" models="{{formData}}">    </mp-form>    <checkbox-group slot="tips" bindchange="bindAgreeChange">        <label class="weui-agree" for="weuiAgree">            <view class="weui-agree__text">                <checkbox class="weui-agree__checkbox" id="weuiAgree" value="agree" checked="{{isAgree}}" />                <view class="weui-agree__checkbox-icon">                    <icon class="weui-agree__checkbox-icon-check" type="success_no_circle" size="9" wx:if="{{isAgree}}"></icon>                </view>                阅读并同意<navigator url="" class="weui-agree__link">《相关条款》</navigator>            </view>        </label>    </checkbox-group>    <view slot="button">        <button class="weui-btn" type="primary" bindtap="submitForm">确定</button>    </view></mp-form-page>

                      效果展示

                      属性列表

                      属性类型默认值必填说明
                      titlestring标题
                      subtitleboolean副标题

                      Slot

                      名称描述
                      title标题区域slot和title属性互斥
                      tips底部确认按钮前面的提示区域
                      button底部提交按钮区域
                      suffixtips提交按钮下面的提示区域
                      footer页脚的内容区域


                      Cell

                      Cell是列表或者是表单的一项,常用于设置页的展示,或者用在表单中,作为表单的每一个要填写的项,Cell必须要放在Cells组件的下面。

                      示例代码:

                      {  "usingComponents": {    "mp-cells": "../components/cells/cells",    "mp-cell": "../components/cell/cell",    "mp-slideview": "../components/slideview/slideview"  }}
                      <view class="page">    <view class="page__hd">        <view class="page__title">Cell</view>        <view class="page__desc">列表</view>    </view>    <view class="page__bd">        <mp-cells ext-class="my-cells" title="带说明的列表项">            <mp-cell value="标题文字" footer="说明文字"></mp-cell>            <mp-cell>                <view>标题文字(使用slot)</view>                <view slot="footer">说明文字</view>            </mp-cell>            <mp-slideview buttons="{{slideButtons}}" bindbuttontap="slideButtonTap">                <mp-cell value="左滑可以删除" footer="说明文字"></mp-cell>            </mp-slideview>        </mp-cells>        <mp-cells title="带图标、说明的列表项" footer="底部说明文字">            <mp-cell value="标题文字" footer="说明文字">                <image slot="icon" src="{{icon}}" style="margin-right: 16px;vertical-align: middle;width:20px; height: 20px;"></image>            </mp-cell>            <mp-cell value="标题文字" footer="说明文字">                <image slot="icon" src="{{icon}}" style="margin-right: 16px;vertical-align: middle;width:20px; height: 20px;"></image>            </mp-cell>        </mp-cells>        <mp-cells title="带跳转的列表项">            <mp-cell link hover value="有hover效果" footer="说明文字">                <image slot="title" src="{{icon}}" style="margin-right: 16px;vertical-align: middle;width:20px; height: 20px;"></image>            </mp-cell>            <mp-cell link value="无hover效果" footer="说明文字">                <image slot="icon" src="{{icon}}" style="margin-right: 16px;vertical-align: middle;width:20px; height: 20px;"></image>            </mp-cell>            <mp-cell link url="../index" value="无hover效果,带跳转URL" footer="说明文字">                <image slot="icon" src="{{icon}}" style="margin-right: 16px;vertical-align: middle;width:20px; height: 20px;"></image>            </mp-cell>        </mp-cells>    </view></view>
                      var base64 = require("../images/base64");Page({    onLoad: function(){        this.setData({            icon: base64.icon20,            slideButtons: [{              text: '普通',              src: '/page/weui/cell/icon_love.svg', // icon的路径            },{              text: '普通',              extClass: 'test',                src: '/page/weui/cell/icon_star.svg', // icon的路径            },{              type: 'warn',              text: '警示',              extClass: 'test',                src: '/page/weui/cell/icon_del.svg', // icon的路径            }],        });    },    slideButtonTap(e) {        console.log('slide button tap', e.detail)    }});


                      属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      iconstringCell的最左侧的icon,是本地图片的路径,icon和名为icon的slot互斥
                      titlestringCell最左侧的标题,一般用在Form表单组件里面,icon和title二选一,title和名为title的slot互斥
                      hoverbooleanfalse是否有hover效果
                      linkbooleanfalse右侧是有跳转的箭头,v1.0后的版本,link: true 会自带 hover 效果
                      valuestringCell的值,和默认的slot互斥
                      show-errorbooleanfalse用在Form表单组件里面,在表单校验出错的时候是否把Cell标为warn状态
                      propstring用在Form表单组件里面,需要校验的表单的字段名
                      footerstringCell右侧区域的内容,和名为footer的slot互斥
                      inlineboolean用在Form表单组件里面,表示表单项是左右显示还是上下显示

                      Slot

                      名称描述
                      icon左侧图标slot
                      title标题slot
                      默认内容slot
                      footer右侧区域slot


                      Cells

                      Cells是列表分组,常用于嵌套一组Cell或者Checkbox,注意,Checkbox-group和Cell组件都必须放在Cells组件下面,Cells效果如下图所示。

                      引入组件

                      在 page.json 中引入组件

                      {  "usingComponents": {    "mp-cell": "../../components/cell/cell",    "mp-cells": "../../components/cells/cells"  }}

                      示例代码

                      <!--WXML示例代码--><mp-cells ext-class="my-cells" title="带说明的列表项">    <mp-cell value="标题文字" footer="说明文字"></mp-cell>    <mp-cell>        <view>标题文字(使用slot)</view>        <view slot="footer">说明文字</view>    </mp-cell></mp-cells>
                      // page.js示例代码Page({});

                      属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      titlestringCells的标题
                      footerstringCells底部的文字

                      Slot

                      名称描述
                      默认内容slot


                      Checkbox-group和Checkbox

                      Checkbox-group是由一组单选或者多选Checkbox组件组成,效果如下图所示。

                      引入组件

                      在 page.json 中引入组件

                      {  "usingComponents": {    "mp-checkbox-group": "../../components/checkbox-group/checkbox-group",    "mp-checkbox": "../../components/checkbox/checkbox",    "mp-cells": "../../components/cells/cells"  }}

                      示例代码

                      <!--WXML示例代码--><mp-cells title="单选列表项">    <mp-checkbox-group prop="radio" multi="{{false}}" bindchange="radioChange">        <mp-checkbox wx:for="{{radioItems}}" wx:key="value" label="{{item.name}}" value="{{item.value}}" checked="{{item.checked}}"></mp-checkbox>    </mp-checkbox-group></mp-cells><mp-cells title="复选列表项">    <mp-checkbox-group prop="checkbox" multi="{{true}}" bindchange="checkboxChange">        <mp-checkbox wx:for="{{checkboxItems}}" wx:key="value" label="{{item.name}}" value="{{item.value}}" checked="{{item.checked}}"></mp-checkbox>    </mp-checkbox-group></mp-cells>
                      // page.js示例代码Page({    data: {        radioItems: [            {name: 'cell standard', value: '0', checked: true},            {name: 'cell standard', value: '1'}        ],        checkboxItems: [            {name: 'standard is dealt for u.', value: '0', checked: true},            {name: 'standard is dealicient for u.', value: '1'}        ],    },    radioChange: function (e) {        console.log('radio发生change事件,携带value值为:', e.detail.value);        var radioItems = this.data.radioItems;        for (var i = 0, len = radioItems.length; i < len; ++i) {            radioItems[i].checked = radioItems[i].value == e.detail.value;        }        this.setData({            radioItems: radioItems,            [`formData.radio`]: e.detail.value        });    },    checkboxChange: function (e) {        console.log('checkbox发生change事件,携带value值为:', e.detail.value);        var checkboxItems = this.data.checkboxItems, values = e.detail.value;        for (var i = 0, lenI = checkboxItems.length; i < lenI; ++i) {            checkboxItems[i].checked = false;            for (var j = 0, lenJ = values.length; j < lenJ; ++j) {                if(checkboxItems[i].value == values[j]){                    checkboxItems[i].checked = true;                    break;                }            }        }        this.setData({            checkboxItems: checkboxItems,            [`formData.checkbox`]: e.detail.value        });    },});

                      checkbox-group组件属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      multibooleantrue单选还是多选
                      propstringForm表单组件校验的字段名
                      bindchangeeventhandlerCheckbox-group发生改变时候触发的事件,detail为{value},单选的value为checkbox的值,多选的value为选中的checkbox的值组成的数组

                      checkbox-group的Slot

                      名称描述
                      默认内容slot

                      checkbox组件属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      multibooleantrue单选还是多选
                      checkedboolean是否选中
                      valuestringcheckbox的值
                      bindchangeeventhandlerCheckbox发生改变时候触发的事件,detail为{value},value为checkbox的值


                      Slideview

                      左滑删除组件,基础库 2.4.4 开始支持。

                      示例代码:

                      {  "usingComponents": {    "mp-cells": "../components/cells/cells",    "mp-cell": "../components/cell/cell",    "mp-slideview": "../components/slideview/slideview"  }}
                      <view class="page">    <view class="page__hd">        <view class="page__title">Slideview</view>        <view class="page__desc">左滑操作</view>    </view>    <view class="page__bd">      <view class="weui-cells">          <mp-slideview buttons="{{slideButtons}}" bindbuttontap="slideButtonTap">              <mp-cell value="左滑可以删除" footer="说明文字"></mp-cell>          </mp-slideview>      </view>      <view class="weui-slidecells">        <mp-slideview buttons="{{slideButtons}}" icon="{{true}}" bindbuttontap="slideButtonTap">          <view class="weui-slidecell">            左滑可以删除(图标Button)          </view>        </mp-slideview>      </view>    </view></view>
                      var base64 = require("../images/base64");Page({    onLoad: function(){        this.setData({            icon: base64.icon20,            slideButtons: [{              text: '普通',              src: '/page/weui/cell/icon_love.svg', // icon的路径            },{              text: '普通',              extClass: 'test',              src: '/page/weui/cell/icon_star.svg', // icon的路径            },{              type: 'warn',              text: '警示',              extClass: 'test',                src: '/page/weui/cell/icon_del.svg', // icon的路径            }],        });    },    slideButtonTap(e) {        console.log('slide button tap', e.detail)    }});



                      属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      disablebooleanfalse是否禁用slideview
                      buttonsarray<object>[]左滑的按钮组,建议最多3个按钮
                      iconbooleanfalse按钮是否是icon
                      showboolean是否显示slideview,可以控制隐藏显示
                      durationboolean350slideview显示隐藏的动画的时长
                      throttlenumber40手指移动距离超过该值的时候,触发slideview的显示隐藏
                      bindbuttontapeventhandlerbuttons按钮组点击时触发的事件,detail为{index, data},data是按钮的配置项传入的data参数
                      bindhideeventhandler隐藏时触发的事件
                      bindshoweventhandler显示时触发的事件

                      buttons提供按钮组配置,每一项表示一个按钮,每一项的属性为

                      属性类型默认值必填说明
                      extClassstring按钮的额外的class,可用于修改组件内部的样式
                      typestringdefault按钮的类型,取值default和warn,warn是红色按钮
                      textstring按钮的文本
                      srcstring如果icon为true,此属性有效
                      dataany触发bindbuttontap回传的数据


                      图片上传Uploader组件。

                      示例代码:

                      {  "usingComponents": {    "mp-uploader": "../components/uploader/uploader",    "mp-cells": "../components/cells/cells",    "mp-cell": "../components/cell/cell"  },  "navigationBarTitleText": "UI组件库"}
                      <view class="page">    <view class="page__hd">        <view class="page__title">Uploader</view>        <view class="page__desc">上传组件</view>    </view>    <view class="page__bd">        <mp-cells>            <mp-cell>                <mp-uploader bindfail="uploadError" bindsuccess="uploadSuccess" select="{{selectFile}}" upload="{{uplaodFile}}" files="{{files}}" max-count="5" title="图片上传" tips="图片上传提示"></mp-uploader>            </mp-cell>        </mp-cells>    </view></view>
                      Page({    data: {        files: [{            url: 'http://mmbiz.qpic.cn/mmbiz_png/VUIF3v9blLsicfV8ysC76e9fZzWgy8YJ2bQO58p43Lib8ncGXmuyibLY7O3hia8sWv25KCibQb7MbJW3Q7xibNzfRN7A/0',        }, {            loading: true        }, {            error: true        }]    },    onLoad() {        this.setData({            selectFile: this.selectFile.bind(this),            uplaodFile: this.uplaodFile.bind(this)        })    },    chooseImage: function (e) {        var that = this;        wx.chooseImage({            sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图,默认二者都有            sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机,默认二者都有            success: function (res) {                // 返回选定照片的本地文件路径列表,tempFilePath可以作为img标签的src属性显示图片                that.setData({                    files: that.data.files.concat(res.tempFilePaths)                });            }        })    },    previewImage: function(e){        wx.previewImage({            current: e.currentTarget.id, // 当前显示图片的http链接            urls: this.data.files // 需要预览的图片http链接列表        })    },    selectFile(files) {        console.log('files', files)        // 返回false可以阻止某次文件上传    },    uplaodFile(files) {        console.log('upload files', files)        // 文件上传的函数,返回一个promise        return new Promise((resolve, reject) => {            setTimeout(() => {                reject('some error')            }, 1000)        })    },    uploadError(e) {        console.log('upload error', e.detail)    },    uploadSuccess(e) {        console.log('upload success', e.detail)    }});


                      属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      titlestring组件标题
                      tipsstring组件的提示
                      deleteboolean是否显示删除按钮
                      size-typearray和chooseImage的sizeType参数一样
                      source-typearray和chooseImage的sourceType参数一样
                      max-sizenumber5 * 1024 * 1024图片上传的最大文件限制,默认是5M
                      max-countnumber1图片上传的个数限制
                      filesarray<object>当前的图片列表
                      selectfunction选择图片时的过滤函数,返回true表示图片有效
                      uploadfunction图片上传的函数,返回Promise,Promise的callback里面必须resolve({urls})表示成功,否则表示失败
                      bindselecteventhandler图片选择触发的事件,detail为{tempFilePaths, tempFiles, contents},其中tempFiles和tempFilePaths是chooseImage返回的字段,contents表示所选的图片的二进制Buffer列表
                      bindcanceleventhandler取消图片选择的事件,detail为{}
                      bindsuccesseventhandler图片上传成功的事件,detail为{urls},urls为upload函数上传成功返回的urls参数
                      bindfaileventhandler图片上传失败的事件,detail为{type, errMsg},type为1表示图片超过大小限制,type为2表示选择图片失败,type为3表示图片上传失败。
                      binddeleteeventhandler删除图片触发的事件,detail为{index, item},index表示删除的图片的下标,item为图片对象。

                      files表示当前的图片列表,每一项的定义为

                      属性类型默认值必填说明
                      urlstring图片链接
                      loadingboolean图片上传中
                      errorboolean图片上传失败


                      Dialog

                      Dialog弹窗组件。

                      示例代码:

                      {  "usingComponents": {    "mp-dialog": "../components/dialog/dialog"  }}

                      <view class="page">    <view class="page__hd">        <view class="page__title">Dialog</view>        <view class="page__desc">对话框</view>    </view>    <view class="page__bd">        <view class="weui-btn-area">            <button class="weui-btn" type="default" bindtap="openConfirm">确认取消按钮</button>            <button class="weui-btn" type="default" bindtap="tapOneDialogButton">只有确认按钮</button>        </view>    </view>    <mp-dialog title="test" show="{{dialogShow}}" bindbuttontap="tapDialogButton" buttons="{{buttons}}">        <view>test content</view>    </mp-dialog>    <mp-dialog title="test1" show="{{showOneButtonDialog}}" bindbuttontap="tapDialogButton" buttons="{{oneButton}}">        <view>test content1</view>    </mp-dialog></view>

                      Page({    data: {        dialogShow: false,        showOneButtonDialog: false,        buttons: [{text: '取消'}, {text: '确定'}],        oneButton: [{text: '确定'}],    },    openConfirm: function () {        this.setData({            dialogShow: true        })    },    tapDialogButton(e) {        this.setData({            dialogShow: false,            showOneButtonDialog: false        })    },    tapOneDialogButton(e) {        this.setData({            showOneButtonDialog: true        })    }});


                      属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      titlestring弹窗的标题
                      buttonsarray<object>[]底部的按钮组,建议最多提供两个按钮
                      maskboolean是否显示蒙层
                      mask-closableboolean点击蒙层是否可以关闭
                      showbooleanfalse是否显示弹窗
                      bindcloseeventhandler弹窗关闭的时候触发的事件
                      bindbuttontapeventhandlerbuttons按钮组点击时触发的事件,detail为{index, item},item是按钮的配置项

                      buttons提供按钮组配置,每一项表示一个按钮,每一项的属性为

                      属性类型默认值必填说明
                      extClassstring按钮的额外的class,可用于修改组件内部的样式
                      textstring按钮的文本

                      Slot

                      弹窗组件只有一个默认slot用于显示弹窗的内容


                      Msg

                      Msg组件提供操作确认页或操作成功或失败的标准的确认页的样式。

                      示例代码:

                      {  "usingComponents": {    "mp-msg": "../components/msg/msg"  },  "navigationBarTitleText": "UI组件库"}
                      <view class="page">    <mp-msg type="success" title="操作成功">        <view slot="desc">内容详情,可根据实际需要安排,如果换行则不超过规定长度,居中展现<navigator url="" class="weui-msg__link">文字链接</navigator></view>        <view slot="extend">            <view>1. 说明1</view>            <view>2. 说明2</view>        </view>        <view slot="handle">            <button class="weui-btn" type="primary">主要操作</button>            <button class="weui-btn" type="default">辅助操作</button>        </view>        <view slot="footer">            <view class="weui-footer__links">                <navigator url="" class="weui-footer__link">底部链接文本</navigator>            </view>            <view class="weui-footer__text">Copyright © 2008-2016 weui.io</view>        </view>    </mp-msg> </view>


                      属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      typestring顶部图标的样式,和icon组件的type属性用法一样
                      sizenumber64type不为空的时候有效,和icon组件的size属性用法一样
                      iconstringtype为空的时候,icon的值是顶部图标的路径
                      titlestring标题
                      descstring描述内容,和desc的slot显示在相同的位置

                      Slot

                      名称描述
                      desc描述内容slot
                      extenddesc下面的说明区域的slot
                      handle操作按钮区域slot
                      footer底部slot


                      Toptips

                      Toptips顶部错误提示组件,常用于表单校验或提交请求到后台成功或失败的错误提示,如下图所示。

                      引入组件

                      在 page.json 中引入组件

                      {  "usingComponents": {    "mp-toptips": "../../components/toptips/toptips"  }}

                      示例代码

                      <!--WXML示例代码--><mp-toptips msg="{{error}}" type="error" show="{{error}}"></mp-toptips>
                      // page.js示例代码Page({    data: {        error: ''    },    onShow() {        this.setData({            error: '这是一个错误提示'        })    }});

                      属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      typestring提示类型,可以为info、error、success,表示三种提示颜色
                      showbooleanfalse是否显示Toptips
                      msgstring提示内容
                      delaynumber2000提示内容显示后隐藏的ms值
                      bindhideeventhandler顶部提示隐藏的时候触发的事件


                      Half Screen Dialog

                      半屏弹窗,辅助完成当前页面任务时;提醒用户并引导用户的下一步操作;用户主动发起的任务时。

                      代码引入

                      在 page.json 中引入组件

                      {  "usingComponents": {    "mp-halfScreenDialog": "../../components/half-screen-dialog/half-screen-dialog"  }}

                      示例代码

                      <!--WXML示例代码--><mp-halfScreenDialog   bindbuttontap="buttontap"  show="{{show}}"  maskClosable="{{false}}"   title="测试标题B"   subTitle="测试标题B的副标题"  desc="辅助描述内容,可根据实际需要安排"  tips="辅助提示内容,可根据实际需要安排"  buttons="{{buttons}}"></mp-halfScreenDialog><button class="weui-btn" type="primary" bindtap="open">Open</button>
                      // page.js示例代码Page({    data: {        show: false,        buttons: [            {                type: 'default',                className: '',                text: '辅助操作',                value: 0            },            {                type: 'primary',                className: '',                text: '主操作',                value: 1            }        ]    },    open: function () {        this.setData({            show: true        })    },    buttontap(e) {        console.log(e.detail)    }});

                      效果展示

                      属性列表

                      属性类型默认值说明
                      extClassstring组件类名
                      closabledbooleantrue是否展示关闭按钮
                      titlestring组件标题,可通过slot自定义
                      subTitlestring组件副标题,可通过slot自定义
                      descstring辅助操作描述内容
                      tipsstring辅助操作提示内容
                      maskClosablebooleantrue点击遮罩是否关闭改组件
                      maskbooleantrue是否需要遮罩层
                      showbooleantrue是否开启弹窗
                      buttonsarray[]辅助操作按钮列表

                      自定义事件

                      事件名称说明回调参数
                      buttontap点击辅助操作按钮时触发e.detail = { index, item }
                      close组件关闭时候触发

                      Slot

                      名称描述
                      title组件自定义标题栏
                      desc组件自定义操作描述
                      footer操作按钮区域slot


                      ActionSheet

                      底部弹起的操作按钮组件

                      代码引入

                      在 page.json 中引入组件

                      {  "usingComponents": {    "mp-actionSheet": "../../components/actionsheet/actionsheet"  }}

                      示例代码

                      <!--WXML示例代码--><mp-actionSheet bindactiontap="btnClick" show="{{showActionsheet}}" actions="{{groups}}" title="这是一个标题,可以为一行或者两行。"></mp-actionSheet>
                      Page({    data: {        showActionsheet: false,        groups: [            { text: '示例菜单', value: 1 },            { text: '示例菜单', value: 2 },            { text: '负向菜单', type: 'warn', value: 3 }        ]    },    close: function () {        this.setData({            showActionsheet: false        })    },    btnClick(e) {        console.log(e)        this.close()    }})

                      效果展示

                      属性列表

                      属性类型默认值必填说明
                      titlestring标题
                      show-cancelbooleantrue是否显示取消按钮
                      cancel-textstring取消按钮的文本
                      mask-classstring背景蒙层的class
                      ext-classstringActionSheet额外的class
                      mask-closablebooleantrue点击背景蒙层是否可以关闭ActionSheet
                      maskbooleantrue是否显示背景蒙层
                      showbooleanfalse是否显示ActionSheet
                      actionsArrayfalseActionSheet的按钮项的配置,每一项是包含text、value、type的Object,type的取值为warn和default,表示两种样式
                      bindcloseeventhandler点击背后的mask关闭掉ActionSheet触发的事件
                      bindactiontapeventhandler点击ActionSheet的按钮项触发的事件,detail为{ value, index }

                      Slot

                      名称描述
                      title标题区域slot


                      Navigation

                      Navigation是小程序的顶部导航组件,当页面配置navigationStyle设置为custom的时候可以使用此组件替代原生导航栏。

                      示例代码:

                      {    "usingComponents": {        "mp-navigation-bar": "../components/navigation-bar/navigation-bar"    },    "navigationStyle": "custom",    "navigationBarTitleText": "UI组件库"}

                      <mp-navigation-bar loading="{{loading}}" show="{{show}}" animated="{{animated}}" color="{{color}}" background="{{background}}" title="UI组件库" back="{{true}}"></mp-navigation-bar><view class="page">    <view class="page__hd">        <view class="page__title">Navigation</view>        <view class="page__desc">小程序自定义导航栏</view>    </view>    <view class="page__bd page__bd_spacing">        <button class="weui-btn" type="primary" bindtap="toggleLoading">触发loading</button>        <button class="weui-btn" type="primary" bindtap="changeColor">修改文字颜色</button>        <button class="weui-btn" type="primary" bindtap="changeBgColor">修改背景颜色</button>        <button class="weui-btn" type="primary" bindtap="toggleShow">显示 / 隐藏</button>        <button class="weui-btn" type="primary" bindtap="toggleAnimated">设置显示 / 隐藏opacity动画</button>    </view></view>

                      Page({  data: {    loading: false,    color: '#000',    background: '#f8f8f8',    show: true,    animated: false  },  toggleLoading() {    this.setData({      loading: !this.data.loading    })  },  changeColor() {    this.setData({      color: '#07C160'    })  },  changeBgColor() {    this.setData({      background: '#ededed'    })  },  toggleShow() {    this.setData({      show: !this.data.show    })  },  toggleAnimated() {    this.setData({      animated: !this.data.animated,      show: !this.data.show    })  }})


                      属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      titlestring导航标题,如果不提供,则名为center的slot有效
                      backbooleantrue是否显示返回按钮,默认点击按钮会执行navigateBack,如果为false,则名为left的slot有效
                      deltanumber1当back为true的时候有效,表示navigateBack的delta参数
                      backgroundstring#f8f8f8导航背景色
                      colorstring导航颜色
                      loadingboolean是否显示标题左侧的loading
                      showboolean显示隐藏导航,隐藏的时候navigation的高度占位还在
                      animatedboolean显示隐藏导航的时候是有opacity过渡动画
                      bindbackeventhandler在back为true时,点击back按钮触发此事件,detail包含delta

                      Slot

                      名称描述
                      left左侧slot,在back按钮位置显示,当back为false的时候有效
                      center标题slot,在标题位置显示,当title为空的时候有效
                      right在导航的右侧显示

                      Tabbar

                      Tabbar组件,也可以用来作为小程序的自定义Tabbar使用

                      示例代码:

                      {  "usingComponents": {    "mp-tabbar": "../components/tabbar/tabbar"  },  "navigationBarTitleText": "UI组件库"}

                      <view class="page">    <view class="page__hd">        <view class="page__title">Tabbar</view>        <view class="page__desc">类似小程序原生tabbar的组件,可用于自定义tabbar</view>    </view>    <mp-tabbar style="position:fixed;bottom:0;width:100%;left:0;right:0;" list="{{list}}" bindchange="tabChange"></mp-tabbar></view>

                      Page({    data: {        list: [{            "text": "对话",            "iconPath": "../../images/tabbar_icon_chat_default.png",          "selectedIconPath": "../../images/tabbar_icon_chat_active.png",            dot: true        },        {            "text": "设置",          "iconPath": "../../images/tabbar_icon_setting_default.png",          "selectedIconPath": "../../images/tabbar_icon_setting_active.png",            badge: 'New'        }]    },    tabChange(e) {        console.log('tab change', e)    }});


                      属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      listarray<object>Tabbar的项的数组,按照规范,至少要有2个Tabbar项
                      currentnumber0当前选中的Tabbar项的下标
                      bindchangeeventhandlerTabbar项发生改成的时候触发此事件,detail为{index, item},index是Tabbar下标,item是对应的Tabbar项的配置

                      list属性是对象数组,每一项表示一个Tabbar项,其字段含义为

                      字段名类型默认值必填说明
                      textstringTabbar项的标题
                      iconPathstringTabbar项的icon图片路径,建议使用绝对路径,相对路径要相对于组件所在目录的。
                      selectedIconPathstringTabbar项选中时的icon,建议使用绝对路径,相对路径要相对于组件所在目录的。
                      badgestring是否显示Tabbar的右上角的Badge


                      Searchbar

                      搜索组件Searchbar提供搜索的功能,并展示搜索的结果。

                      示例代码:

                      {  "usingComponents": {    "mp-searchbar": "../components/searchbar/searchbar"  },  "navigationBarTitleText": "UI组件库"}
                      <view class="page">    <view class="page__hd">        <view class="page__title">SearchBar</view>        <view class="page__desc">搜索栏</view>    </view>    <view class="page__bd">        <mp-searchbar bindselectresult="selectResult" search="{{search}}"></mp-searchbar>    </view></view>
                      Page({    data: {        inputShowed: false,        inputVal: ""    },    onLoad() {        this.setData({            search: this.search.bind(this)        })    },    search: function (value) {        return new Promise((resolve, reject) => {            setTimeout(() => {                resolve([{text: '搜索结果', value: 1}, {text: '搜索结果2', value: 2}])            }, 200)        })    },    selectResult: function (e) {        console.log('select result', e.detail)    },});


                      属性列表

                      属性类型默认值必填说明
                      ext-classstring添加在组件内部结构的class,可用于修改组件内部的样式
                      focusbooleanfalse是否在组件开始创建的时候focus搜索输入框
                      placeholderstring搜索搜索输入框的placeholder
                      valuestring搜索输入框的默认值
                      searchfunction输入过程不断调用此函数得到新的搜索结果,参数是输入框的值value,返回Promise实例
                      throttlenumber500调用search函数的间隔,单位ms
                      cancelTextstring取消取消按钮的文本
                      cancelbooleantrue是否显示取消按钮
                      bindfocuseventhandle在输入框focus的时候触发事件
                      bindblureventhandle在输入框blur的时候触发事件
                      bindcleareventhandle在clear按钮点击的时候触发事件
                      bindinputeventhandle在输入框输入过程中触发事件
                      bindselectresulteventhandle在选择搜索结果的时候触发事件


                      其他组件

                      出于性能考虑,weui-miniprogram 并没有对所有 WeUI 组件进行封装(如:flex布局组件),可以直接使用 WeUI 中定义的组件结构(参考 Demo)。

                      示例代码

                      在引入 weui.wxss 后,可以直接使用 weui-wxss 中定义的 class 自定义样式,以 flex 组件为例:

                      <view class="page__hd">    <view class="page__title">Flex</view>    <view class="page__desc">Flex布局</view></view><view class="page__bd page__bd_spacing">    <view class="weui-flex">        <view class="weui-flex__item"><view class="placeholder">weui</view></view>    </view>    <view class="weui-flex">        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>    </view>    <view class="weui-flex">        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>    </view>    <view class="weui-flex">        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>    </view>    <view class="weui-flex">        <view><view class="placeholder">weui</view></view>        <view class="weui-flex__item"><view class="placeholder">weui</view></view>        <view><view class="placeholder">weui</view></view>    </view></view>

                      渲染到页面上会得到以下结果:

                      flex布局

                      其他组件可以参考库中提供的 Demo


                      emoji

                      仿微信表情组件。使用前需将文档下方提供的表情雪碧图上传 CDN,再传入表情组件。为提升首次加载表情图片的性能,可通过 image 组件提前触发雪碧图的下载,利用浏览器的缓存机制。在不使用表情面板的页面,可将 emoji 组件隐藏或移出屏幕外,仅使用 parseEmoji 的功能。

                      属性列表

                      属性类型默认值必填说明
                      sourcestring表情雪碧图地址
                      heightnumber300表情盘高度
                      background-colorstring#EDEDED表情盘背景色
                      show-sendbooleantrue是否显示发送按钮
                      show-delbooleantrue是否显示删除按钮
                      show-historybooleantrue是否显示最近使用
                      bindinsertemojieventhandle插入表情,e.detail={emotionName}
                      binddelemojieventhandle点击删除按钮
                      bindsendeventhandle点击发送按钮

                      示例代码:

                      {  "disableScroll": true,  "navigationBarTitleText": "",  "usingComponents": {    "mp-emoji": "../components/emoji/emoji"  }}

                      <scroll-view scroll-y style="height: {{layoutHeight}}px" scroll-into-view="{{historyList[historyList.length - 1].id}}">  <block wx:for="{{historyList}}" wx:for-index="idx" wx:for-item="historyItem">    <view class="record" hidden="{{historyItem.length === 0}}" id="{{historyItem.id}}">      <view class="avator"></view>      <view class="comment">        <block wx:for="{{historyItem.emoji}}" wx:key="*this">          <block wx:if="{{item.type === 1}}">{{item.content}}</block>          <view             wx:if="{{item.type === 2}}"             style="display: inline-block; width: {{lineHeight}}px; height: {{lineHeight}}px">            <view               class="{{item.imageClass}}"              style="background-image: url({{emojiSource}});transform-origin: 0 0; transform: scale({{lineHeight / 64}});"></view>          </view>        </block>      </view>    </view>  </block></scroll-view>      <view class="reply_wrp" style="bottom: {{keyboardHeight}}px">      <view class="reply_tool">        <view hover-class="active" class="reply_button replay_quick_button">          <image src="./images/reply_tool_keyboard.svg" mode='aspectFit' class="reply_tool_pic"></image>        </view>        <view class="reply_form_wrp">          <label for="" class="reply_label">            <input               class="reply_input"               cursor-spacing="8px"               confirm-type="send"               adjust-position="{{false}}"               confirm-hold value="{{comment}}"               cursor="{{cursor}}"               focus="{{focus}}"               bindblur="onBlur"               bindfocus="onFocus"               bindinput="onInput"               bindconfirm="onConfirm"               bindkeyboardheightchange="onkeyboardHeightChange"            />          </label>        </view>        <view hover-class="active" class="reply_button replay_emotion_button" bindtap="showEmoji">          <image src="./images/reply_tool_emoji.svg" mode='aspectFit' class="reply_tool_pic"></image>        </view>        <view hover-class="active" class="reply_button replay_media_button" bindtap="showFunction">          <image src="./images/reply_tool_add.png" mode='aspectFit' class="reply_tool_pic"></image>        </view>      </view>      <view class="reply_panel_wrp" style="height: {{emojiShow ? 300 : 200}}px;" hidden="{{!emojiShow && !functionShow}}">        <view class="reply_panel {{emojiShow ? 'show': ''}}" hidden="{{!emojiShow}}">          <mp-emoji source="{{emojiSource}}" class="mp-emoji" bindinsertemoji="insertEmoji" binddelemoji="deleteEmoji" bindsend="onsend"></mp-emoji>        </view>        <view class="reply_panel {{functionShow ? 'show': ''}}" hidden="{{!functionShow}}">          <swiper indicator-dots="{{true}}" indicator-color="#bbbbbb" indicator-active-color="#8c8c8c">            <swiper-item>              <view class="function_list">                <view class="function_item" bindtap="chooseImage">                  <image src="./images/reply_function_image.svg" class="reply_function_pic"></image>                </view>              </view>            </swiper-item>          </swiper>        </view>      </view>    </view>


                      使用方式

                      点击表情图标将会获得对应的中文含义,例如????->[微笑]。在实际输入过程中,我们通常仅展示中文含义即可。

                      对文字和表情混合的评论需要解析后才能展示,组件内提供了 parseEmoji 解析函数,获取方式如下:

                      // .mp-emoji 为表情组件的选择器const emojiInstance = this.selectComponent('.mp-emoji')const emojiNames = emojiInstance.getEmojiNames()const parseEmoji = emojiInstance.parseEmojiconst comment = '测试[得意][偷笑]文本'const parsedCommnet = parseEmoji(comment)

                      解析后的评论结构如下,文字和表情分割构成的数组,type=1 为纯文本,type=2 为表情 icon,imageClass 记录了表情在雪碧图上的位置。需注意的是组件开启了 styleIsolation: 'page-shared',组件内样式与页面共享。

                      [  {type: 1, content: '测试'},  {type: 2, content: '[得意]', imageClass: 'smiley_4'},  {type: 2, content: '[偷笑]', imageClass: 'smiley_20'},  {type: 1, content: '文本'},]

                      由于表情 icon 采用雪碧图生成,展示时可采用如下的结构。需要注意的是每个 icon 的实际大小为 64px,因此在段落中通过 scale 进行缩放,缩放的比例为 行高 / 64。

                      <view class="comment">  <block wx:for="{{parsedComment}}" wx:key="*this">    <block wx:if="{{item.type === 1}}">{{item.content}}</block>    <view wx:if="{{item.type === 2}}" style="display: inline-block; width: {{lineHeight}}px; height: {{lineHeight}}px">      <view         class="{{item.imageClass}}"        style="background-image: url({{emojiSource}});transform-origin: 0 0; transform: scale({{lineHeight / 64}});">      </view>    </view>  </block></view>
                      .comment {  font-size: 18px;  display: flex;  align-items: center;  flex-wrap: wrap;  line-height: 24px;}

                      如何与 input 结合使用,参考示例代码。

                      表情雪碧图

                      emoji-sprite


                      video-swiper

                      视频滑动切换组件,可实现类似微视无限视频列表效果。

                      使用说明

                      video-list 的长度应当不低于 3 个,当滚动到首项或者尾项后,会进入循环。通过 setData 更改 video-list,会直接追加到之前的视频源中。可监听 bindchange 事件获取当前滚动到那一个视频,activeId 为视频源的唯一 id。

                      属性列表

                      属性类型默认值必填说明
                      durationnumber500滑动动画时长
                      easing-functionstringdefault切换缓动动画类型
                      loopbooleantrue是否循环播放
                      video-listArray VideoSwiperItem[]true视频源
                      bindchangeeventhandle滑动切换完成时触发, e.detail={activeId}
                      bindplayeventhandle开始/继续播放时触发, e.detail={activeId}
                      bindpauseeventhandle暂停播放时触发, e.detail={activeId}
                      bindendedeventhandle播放到末尾时触发, e.detail={activeId}
                      bindtimeupdateeventhandle播放进度变化时触发,event.detail = {currentTime, duration, activeId}
                      bindwaitingeventhandle视频出现缓冲时触发, e.detail={activeId}
                      binderroreventhandle视频播放出错时触发, e.detail={activeId}
                      bindprogresseventhandle加载进度变化时触发,只支持一段加载。event.detail={buffered, activeId}
                      bindloadedmetadataeventhandle视频元数据加载完成时触发。event.detail={width, height, duration, activeId}

                      VideoSwiperItem 属性列表

                      属性说明
                      id每个视频源的唯一 id
                      url视频播放地址
                      objectFit当视频大小与 video 容器大小不一致时,视频的表现形式

                      objectFit 的合法值

                      属性说明
                      contain包含
                      fill填充
                      cover覆盖

                      easing-function 的合法值

                      属性说明
                      default默认缓动函数
                      linear线性动画
                      easeInCubic缓入动画
                      easeOutCubic缓出动画
                      easeInOutCubic缓入缓出动画


                      recycle-view

                      小程序长列表组件

                      使用此组件需要依赖小程序基础库 2.2.2 版本,同时依赖开发者工具的 npm 构建。具体详情可查阅官方 npm 文档。

                      背景

                      ​目前小程序会有不少的应用场景里会用到无限长列表的交互,当一个页面展示很多信息的时候,会造成小程序页面的卡顿以及白屏。原因有如下几点:

                      1. 列表数据很大,首次 setData 的时候耗时高
                      2. 渲染出来的列表 DOM 结构多,每次 setData 都需要创建新的虚拟树、和旧树 diff 操作耗时都比较高
                      3. 渲染出来的列表 DOM 结构多,占用的内存高,造成页面被系统回收的概率变大。

                      因此就有长列表组件来解决这些问题。

                      实现思路

                      ​核心的思路是只渲染显示在屏幕的数据,基本实现就是监听 scroll 事件,并且重新计算需要渲染的数据,不需要渲染的数据留一个空的 div 占位元素。

                      假设列表数据有100个 item,知道了滚动的位置,怎么知道哪些 item 必须显示在页面?因为 item 还没渲染出来,不能通过 getComputedStyle 等 DOM 操作得到每个 item 的位置,所以无法知道哪些 item 需要渲染。为了解决这个问题,需要每个 item 固定宽高。item 的宽高的定义见下面的 API 的createRecycleContext()的参数 itemSize 的介绍。

                      滚动过程中,重新渲染数据的同时,需要设置当前数据的前后的 div 占位元素高度,同时是指在同一个渲染周期内。页面渲染是通过 setData 触发的,列表数据和 div 占位高度在2个组件内进行 setData 的,为了把这2个 setData 放在同一个渲染周期,用了一个 hack 方法,所以定义 recycle-view 的 batch 属性固定为 batch="{{batchSetRecycleData}}"。

                      在滚动过程中,为了避免频繁出现白屏,会多渲染当前屏幕的前后2个屏幕的内容。

                      包结构

                      长列表组件由2个自定义组件 recycle-view、recycle-item 和一组 API 组成,对应的代码结构如下

                      ├── miniprogram-recycle-view/    └── recycle-view 组件    └── recycle-item 组件    └── index.js

                      包结构详细描述如下:

                      目录/文件描述
                      recycle-view 组件长列表组件
                      recycle-item 组件长列表每一项 item 组件
                      index.js提供操作长列表数据的API

                      使用方法:

                      1.安装组件

                      npm install --save miniprogram-recycle-view

                      2.在页面的 json 配置文件中添加 recycle-view 和 recycle-item 自定义组件的配置

                      {  "usingComponents": {    "recycle-view": "miniprogram-recycle-view/recycle-view",    "recycle-item": "miniprogram-recycle-view/recycle-item"  }}

                      3.WXML 文件中引用 recycle-view

                      <recycle-view batch="{{batchSetRecycleData}}" id="recycleId">  <view slot="before">长列表前面的内容</view>  <recycle-item wx:for="{{recycleList}}" wx:key="id">    <view>        <image style='width:80px;height:80px;float:left;' src="{{item.image_url}}"></image>      {{item.idx+1}}. {{item.title}}    </view>  </recycle-item>  <view slot="after">长列表后面的内容</view></recycle-view>

                      recycle-view 的属性介绍如下:

                      字段名类型必填描述
                      idStringid必须是页面唯一的字符串
                      batchBoolean必须设置为{{batchSetRecycleData}}才能生效
                      heightNumber设置recycle-view的高度,默认为页面高度
                      widthNumber设置recycle-view的宽度,默认是页面的宽度
                      enable-back-to-topBoolean默认为false,同scroll-view同名字段
                      scroll-topNumber默认为false,同scroll-view同名字段
                      scroll-yNumber默认为true,同scroll-view同名字段
                      scroll-to-indexNumber设置滚动到长列表的项
                      placeholder-imageString默认占位背景图片,在渲染不及时的时候显示,不建议使用大图作为占位。建议传入SVG的Base64格式,可使用工具将SVG代码转为Base64格式。支持SVG中设置rpx。
                      scroll-with-animationBoolean默认为false,同scroll-view的同名字段
                      lower-thresholdNumber默认为false,同scroll-view同名字段
                      upper-thresholdNumber默认为false,同scroll-view同名字段
                      bindscroll事件同scroll-view同名字段
                      bindscrolltolower事件同scroll-view同名字段
                      bindscrolltoupper事件同scroll-view同名字段

                      recycle-view 包含3个 slot,具体介绍如下:

                      名称描述
                      before默认 slot 的前面的非回收区域
                      默认 slot长列表的列表展示区域,recycle-item 必须定义在默认 slot 中
                      after默认 slot 的后面的非回收区域

                      长列表的内容实际是在一个 scroll-view 滚动区域里面的,当长列表里面的内容,不止是单独的一个列表的时候,例如我们页面底部都会有一个 copyright 的声明,我们就可以把这部分的内容放在 before 和 after 这2个 slot 里面。

                      recycle-item 的介绍如下:

                      需要注意的是,recycle-item 中必须定义 wx:for 列表循环,不应该通过 setData 来设置 wx:for 绑定的变量,而是通过createRecycleContext方法创建RecycleContext对象来管理数据,createRecycleContext在 index.js 文件里面定义。建议同时设置 wx:key,以提升列表的渲染性能。

                      4.页面 JS 管理 recycle-view 的数据

                      const createRecycleContext = require('miniprogram-recycle-view')Page({    onReady: function() {        var ctx = createRecycleContext({          id: 'recycleId',          dataKey: 'recycleList',          page: this,          itemSize: { // 这个参数也可以直接传下面定义的this.itemSizeFunc函数            width: 162,            height: 182          }        })        ctx.append(newList)        // ctx.update(beginIndex, list)        // ctx.destroy()    },    itemSizeFunc: function (item, idx) {        return {            width: 162,            height: 182        }    }})

                      页面必须通过 Component 构造器定义,页面引入了miniprogram-recycle-view包之后,会在 wx 对象下面新增接口createRecycleContext函数创建RecycleContext对象来管理 recycle-view 定义的的数据,createRecycleContext接收类型为1个 Object 的参数,Object 参数的每一个 key 的介绍如下:

                      参数名类型描述
                      idString对应 recycle-view 的 id 属性的值
                      dataKeyString对应 recycle-item 的 wx:for 属性设置的绑定变量名
                      pagePage/Componentrecycle-view 所在的页面或者组件的实例,页面或者组件内可以直接传 this
                      itemSizeObject/Function此参数用来生成recycle-item的宽和高,前面提到过,要知道当前需要渲染哪些item,必须知道item的宽高才能进行计算
                      Object必须包含{width, height}两个属性,Function的话接收item, index这2个参数,返回一个包含{width, height}的Object
                      itemSize如果是函数,函数里面this指向RecycleContext
                      如果样式使用了rpx,可以通过transformRpx来转化为px。
                      为Object类型的时候,还有另外一种用法,详细情况见下面的itemSize章节的介绍。
                      useInPageBoolean是否整个页面只有recycle-view。Page的定义里面必须至少加空的onPageScroll函数,主要是用在页面级别的长列表,并且需要用到onPullDownRefresh的效果。切必须设置root参数为当前页面对象
                      rootPage当前页面对象,可以通过getCurrentPages获取, 当useInPage为true必须提供

                      RecycleContext 对象提供的方法有:

                      方法参数说明
                      appendlist, callback在当前的长列表数据上追加list数据,callback是渲染完成的回调函数
                      splicebegin, count, list, callback插入/删除长列表数据,参数同Array的splice函数,callback是渲染完成的回调函数
                      updatebegin, list, callback更新长列表的数据,从索引参数begin开始,更新为参数list,参数callback同splice。
                      destroy销毁RecycleContext对象,在recycle-view销毁的时候调用此方法
                      forceUpdatecallback, reinitSlot重新渲染recycle-view。callback是渲染完成的回调函数,当before和after这2个slot的高度发生变化时候调用此函数,reinitSlot设置为true。当item的宽高发生变化的时候也需要调用此方法。
                      getBoundingClientRectindex获取某个数据项的在长列表中的位置,返回{left, top, width, height}的Object。
                      getScrollTop获取长列表的当前的滚动位置。
                      transformRpxrpx将rpx转化为px,返回转化后的px整数。itemSize返回的宽高单位是px,可以在这里调用此函数将rpx转化为px,参数是Number,例如ctx.transformRpx(140),返回70。注意,transformRpx会进行四舍五入,所以transformRpx(20) + transformRpx(90)不一定等于transformRpx(110)
                      getViewportItemsinViewportPx获取在视窗内的数据项,用于判断某个项是否出现在视窗内。用于曝光数据上报,菜品和类别的联动效果实现。参数inViewportPx表示距离屏幕多少像素为出现在屏幕内,可以为负值。

                      其中 itemSize 的使用

                      itemSize可以为包含{width, height}的Object,所有数据只有一种宽高信息。如果有多种,则可以提供一个函数,长列表组件会调用这个函数生成每条数据的宽高信息,如下所示:

                      function(item, index) {    return {        width: 195,        height: item.azFirst ? 130 : 120    }}

                      提示:

                      1. recycle-view设置batch属性的值必须为{{batchSetRecycleData}}。
                      2. recycle-item的宽高必须和itemSize设置的宽高一致,否则会出现跳动的bug。
                      3. recycle-view设置的高度必须和其style里面设置的样式一致。
                      4. createRecycleContext(options)的id参数必须和recycle-view的id属性一致,dataKey参数必须和recycle-item的wx:for绑定的变量名一致。
                      5. 不能在recycle-item里面使用wx:for的index变量作为索引值的,请使用{{item._index_}}替代。
                      6. 不要通过setData设置recycle-item的wx:for的变量值,建议recycle-item设置wx:key属性。
                      7. 如果长列表里面包含图片,必须保证图片资源是有HTTP缓存的,否则在滚动过程中会发起很多的图片请求。
                      8. 有些数据不一定会渲染出来,使用wx.createSelectorQuery的时候有可能会失效,可使用RecycleContext的getBoundingClientRect来替代。
                      9. 当使用了useInPage参数的时候,必须在Page里面定义onPageScroll事件。
                      10. transformRpx会进行四舍五入,所以transformRpx(20) + transformRpx(90)不一定等于transformRpx(110)
                      11. 如果一个页面有多个长列表,必须多设置batch-key属性,每个的batch-key的值和batch属性的变量必须不一致。例如
                      <recycle-view batch="{{batchSetRecycleData}}" batch-key="batchSetRecycleData"></recycle-view><recycle-view batch="{{batchSetRecycleData1}}" batch-key="batchSetRecycleData1"></recycle-view>


                      sticky

                      粘性布局组件。Sticky 组件与 CSS 中 position: sticky 属性实现的效果一致,当组件在屏幕范围内时,会按照正常的布局排列,当组件滚出屏幕范围时,始终会固定在屏幕顶部。

                      属性列表

                      属性类型默认值必填说明
                      offset-topNumber0吸顶时与顶部的距离,单位px
                      z-indexNumber99吸顶时的 z-index
                      containerfunctionnull一个函数,返回容器对应的 NodesRef 节点
                      disabledBooleanfalse是否禁用
                      bindscrolleventhandle滚动时触发,{scrollTop: 距离顶部位置, isFixed: 是否吸顶 }

                      代码演示

                      吸顶距离

                      通过 offset-top 属性可以设置组件在吸顶时与顶部的距离

                      <mp-sticky offset-top="32">  <button size="mini" type="primary" style="margin-left: 115px; background-color: #1989fa">吸顶距离</button></mp-sticky>

                      指定容器

                      通过 container 属性可以指定组件的容器,页面滚动时,组件会始终保持在容器范围内,当组件即将超出容器底部时,会返回原位置。

                      <view id="container" style="height: 250px; background-color: #E0E0E0;">  <view style="height: 100px; background-color: #FFFF99;"></view>  <mp-sticky container="{{container}}" offset-top="64">    <button size="mini" type="primary" style="margin-left: 215px; background-color: #ff976a">指定容器</button>  </mp-sticky></view>
                      Page({  data: {    container: null  },  onReady() {    this.setData({      container: () => wx.createSelectorQuery().select('#container')    })  }})


                      tabs

                      选项卡组件。

                      <view class="page">  <mp-tabs     tabs="{{tabs}}"     activeTab="{{activeTab}}"     swiperClass="weui-tabs-swiper"    bindtabclick="onTabClick"    bindchange="onChange"    activeClass="tab-bar-title__selected">    <block wx:for="{{tabs}}" wx:key="title">      <view class="tab-content" data-set="{{item}}" slot="tab-content-{{index}}" bind:tap="handleClick" >        <image src="{{item.img}}" mode="widthFix"></image>        <view class="item-title">          {{item.title2}}        </view>        <view class="item-desc">          {{item.desc}}        </view>      </view>    </block>  </mp-tabs>  </view>
                      Page({  onShareAppMessage() {    return {      title: 'tabs',      path: 'page/weui/example/tabs/tabs'    }  },  data: {    tabs: [],    activeTab: 0,  },  onLoad() {    const tabs = [      {        title: '技术开发',        title2: '小程序开发进阶',        img: 'http://mmbiz.qpic.cn/sz_mmbiz_jpg/GEWVeJPFkSEV5QjxLDJaL6ibHLSZ02TIcve0ocPXrdTVqGGbqAmh5Mw9V7504dlEiatSvnyibibHCrVQO2GEYsJicPA/0?wx_fmt=jpeg',        desc: '本视频系列课程,由腾讯课堂NEXT学院与微信团队联合出品,通过实战案例,深入浅出地进行讲解。',      },      {        title: '产品解析',        title2: '微信小程序直播',        img: 'http://mmbiz.qpic.cn/sz_mmbiz_png/GEWVeJPFkSHALb0g5rCc4Jf5IqDfdwhWJ43I1IvriaV5uFr9fLAuv3uxHR7DQstbIxhNXFoQEcxGzWwzQUDBd6Q/0?wx_fmt=png',        desc: '微信小程序直播系列课程持续更新中,帮助大家更好地理解、应用微信小程序直播功能。',      },      {        title: '运营规范',        title2: '常见问题和解决方案',        img: 'http://mmbiz.qpic.cn/sz_mmbiz_jpg/GEWVeJPFkSGqys4ibO2a8L9nnIgH0ibjNXfbicNbZQQYfxxUpmicQglAEYQ2btVXjOhY9gRtSTCxKvAlKFek7sRUFA/0?wx_fmt=jpeg',        desc: '提高审核质量',      },      {        title: '营销经验',        title2: '流量主小程序',        img: 'http://mmbiz.qpic.cn/sz_mmbiz_jpg/GEWVeJPFkSH2Eic4Lt0HkZeEN08pWXTticVRgyNGgBVHMJwMtRhmB0hE4m4alSuwsBk3uBBOhdCr91bZlSFbYhFg/0?wx_fmt=jpeg',        desc: '本课程共四节,将分阶段为开发者展示如何开通流量主功能、如何接入广告组件、不同类型小程序接入的建议,以及如何通过工具调优小程序变现效率。',      },      {        title: '高校大赛',        title2:'2020中国高校计算机大赛',        img: 'http://mmbiz.qpic.cn/mmbiz_jpg/TcDuyasB5T3Eg34AYwjMw7xbEK2n01ekiaicPiaMInEMTkOQtuv1yke5KziaYF4MLia4IAbxlm0m5NxkibicFg4IZ92EA/0?wx_fmt=jpeg',        desc: '微信小程序应用开发赛',      },    ]    this.setData({ tabs })  },  onTabClick(e) {    const index = e.detail.index    this.setData({       activeTab: index     })  },  onChange(e) {    const index = e.detail.index    this.setData({       activeTab: index     })  },  handleClick(e) {    wx.navigateTo({      url: './webview',    })  }})


                      属性列表

                      属性类型默认值必填说明
                      tabsArray[]数据项格式为 {title}
                      tab-classString选项卡样式
                      swiper-classString内容区域 swiper 的样式
                      active-classString选中项样式
                      tab-underline-colorString#07c160选中项下划线颜色
                      tab-active-text-colorString#000000选中项字体颜色
                      tab-inactive-text-colorString#000000未选中项字体颜色
                      tab-background-colorString#ffffff选项卡背景颜色
                      active-tabNumber0激活 tab 索引
                      durationNumber500内容区域切换时长
                      bindtabclickeventhandle点击 tab 时触发,e.detail={index}
                      bindchangeeventhandle内容区域滚动导致 tab 变化时触发, e.detail={index}

                      注意事项

                      • 内容区域采用 <swiper>进行滚动,超出部分将被隐藏,需设置 swiperClass 的高度与子元素一致。
                      • 内容区域子元素需指定 slot=tab-content-index,其中 index 为选项卡的下标(从0开始)。


                      row/col 组件

                      按照栅格化布局思路,再加上响应式布局的特性,提供了 row/col 两个基础布局组件,用来帮助开发者快速适配多屏应用。

                      核心概念是将整个屏幕宽度分为 24 单位,每个单位的大小,由当前屏幕尺寸决定的。例如 375px 的屏幕宽度,那么 1 unit = 375/24 px.

                      使用方法

                      1. npm 安装
                      npm i @miniprogram-component-plus/col --savenpm i @miniprogram-component-plus/row --save
                      1. 开发者工具构建 npm,勾选“使用 npm 模块”,参考 npm 支持
                      2. 页面 json 文件中加入 usingComponents 字段
                      {  "usingComponents": {    "mp-col": "@miniprogram-component-plus/col",    "mp-row": "@miniprogram-component-plus/row"  }}
                      1. 在页面中使用组件
                      <view class="page__desc">三列均分布局</view>    <view>        <mp-row>          <mp-col span="{{8}}">            <view>              <view class="col">              </view>            </view>          </mp-col>          <mp-col span="{{8}}">            <view>              <view class="col">              </view>            </view>          </mp-col>          <mp-col span="{{8}}">            <view>              <view class="col">              </view>            </view>          </mp-col>        </mp-row></view>

                      row 组件属性

                      默认无

                      col 组件属性

                      属性类型默认值必填说明
                      spannumber24当前 col 所占屏幕宽度的份数
                      offsetnumber0距 row 左侧偏移margin 距离
                      pushnumber0距左侧偏移的单位距离
                      pullnumber0距右侧偏移的单位距离
                      xsnumber, Object<span,offset, push, pull>当屏幕 < 768px 时,对应显示的网格规则。例如 xs="2" 或 xs="{ "span": 24, "offset": 0 }"
                      smnumber, Object<span,offset, push, pull>当屏幕 >= 768px, <992px,对应显示的网格规则。
                      mdnumber, Object<span,offset, push, pull>当屏幕 >= 992px, <1200px,对应显示的网格规则。
                      lgnumber, Object<span,offset, push, pull>当屏幕 >= 1200px, <1920px 时,对应显示的网格规则。
                      xlnumber, Object<span,offset, push, pull>当屏幕 >= 1920px 时,对应显示的网格规则。

                      提示:

                      • 同时设置 span 和 响应式属性时,当屏幕超过响应式属性范围时,会使用 span 属性。


                      vtabs

                      纵向选项卡组件,需与 <vtabs-content> 组件结合使用。

                      属性列表

                      属性类型默认值必填说明
                      vtabsArray[]数据项格式为 {title}
                      active-tabNumber0激活 tab 索引
                      tab-bar-classString选项卡样式
                      active-classString选中项样式
                      tab-line-colorString#ff0000选中项侧划线颜色
                      tab-inactive-text-colorString#000000未选中项字体颜色
                      tab-active-text-colorString#ff0000选中项字体颜色
                      tab-inactive-bg-colorString#eeeeee未选中项背景色
                      tab-active-bg-colorString#ffffff选中项背景色
                      animationBooleantrue是否开启动画
                      bindtabclickeventhandle点击 tab 时触发,e.detail={index}
                      bindchangeeventhandle内容区域滚动导致 tab 变化时触发, e.detail={index}

                      vtabs-content

                      纵向选项卡内容。

                      属性类型默认值必填说明
                      tab-indexNumber0vtabs 数据索引(从0开始)

                      index-list

                      索引列表组件,可实现类似通讯录效果。组件内节点将被添加到列表上方。

                      示例代码:

                      const res = {  result: [    [{      cidx: [0, 15],      fullname: "北京市",      id: "110000",      location: {        lat: 39.90469,        lng: 116.40717       },      name: "北京",      pinyin: ["bei", "jing"]    }, {      cidx: [16, 31],      fullname: "天津市",      id: "120000",      location: {lat: 39.0851, lng: 117.19937},      name: "天津",      pinyin: ["tian", "jin"]    }, {      cidx: [32, 42],      fullname: "河北省",      id: "130000",      location: {lat: 38.03599, lng: 114.46979},      name: "河北",      pinyin: ["he", "bei"],    }, {      cidx: [43, 53],      fullname: "山西省",      id: "140000",      location: {lat: 37.87343, lng: 112.56272},      name: "山西",      pinyin:  ["shan", "xi"],    }]  ]}Page({  onLoad(options) {    this.getCitys()  },  onChoose(e) {    console.log('onChoose', e)  },  getCitys() {    const _this = this    const cities = res.result[0]        // 按拼音排序        cities.sort((c1, c2) => {          let pinyin1 = c1.pinyin.join('')          let pinyin2 = c2.pinyin.join('')          return pinyin1.localeCompare(pinyin2)        })        // 添加首字母        const map = new Map()        for (const city of cities) {          const alpha = city.pinyin[0].charAt(0).toUpperCase()          if (!map.has(alpha)) map.set(alpha, [])          map.get(alpha).push({ name: city.fullname })        }            const keys = []        for (const key of map.keys()) {          keys.push(key)        }        keys.sort()            const list = []        for (const key of keys) {          list.push({            alpha: key,            subItems: map.get(key)          })        }        _this.setData({list})  }})

                      <mp-indexList class="city__list" list="{{list}}" bindchoose="onChoose">    <view class="page">        <view class="page__hd">            <view class="page__title">Index List</view>            <view class="page__desc">类通讯录列表</view>        </view>        <view class="page__bd">        </view>    </view></mp-indexList>


                      属性列表

                      属性类型默认值必填说明
                      listArray<listItem>[]列表数据
                      vibratedbooleantrue索引上滑动时是否产生振动,仅 iOS 生效
                      bindchooseeventhandle选择列表项, e.detail={name}

                      listItem 属性列表

                      属性类型说明
                      alphastring首字母(大写)
                      subItemsArray<subItem>子元素集合

                      subItem 属性列表

                      属性类型说明
                      namestring名称

                      注意事项

                      1. demo 中省市信息为模拟数据,开发者可以使用腾讯位置服务提供的 SDK 来获取省市信息。


                      Barrage for MiniProgram

                      小程序弹幕组件。通过 view 的 transform 移动弹幕,覆盖在 原生组件上时,请确保组件已经同层化。参考用例

                      使用方法

                      1. npm 安装
                      npm install --save miniprogram-barrage
                      1. JSON 组件声明
                      {  "usingComponents": {    "barrage": "miniprogram-barrage",  }}
                      1. wxml 引入弹幕组件
                      <video class="video" src="{{src}}">  <barrage class="barrage"></barrage></video>
                      1. js 获取实例
                       Page({  onReady() {    this.addBarrage()  },  addBarrage() {    const barrageComp = this.selectComponent('.barrage')    this.barrage = barrageComp.getBarrageInstance({      font: 'bold 16px sans-serif',      duration: 10,      lineHeight: 2,      mode: 'separate',      padding: [10, 0, 10, 0],      tunnelShow: false    })    this.barrage.open()    this.barrage.addData(data)  } })

                      配置

                      Barrage 默认配置

                      {  duration: 10, // 弹幕动画时长 (移动 2000px 所需时长)  lineHeight: 1.2, // 弹幕行高  padding: [0, 0, 0, 0], // 弹幕区四周留白  alpha: 1, // 全局透明度  font: '10px sans-serif', // 全局字体  mode: 'separate', // 弹幕重叠 overlap  不重叠 separate  range: [0, 1], // 弹幕显示的垂直范围,支持两个值。[0,1]表示弹幕整个随机分布,  tunnelShow: false, // 显示轨道线  tunnelMaxNum: 30, // 隧道最大缓冲长度  maxLength: 30, // 弹幕最大字节长度,汉字算双字节  safeGap: 4, // 发送时的安全间隔  enableTap: false, // 点击弹幕停止动画高亮显示}

                      弹幕数据配置

                      {  color: '#000000', // 默认黑色  content: '', // 弹幕内容  image: {    head: {src, width, height}, // 弹幕头部添加图片    tail: {src, width, height}, // 弹幕尾部添加图片    gap: 4 // 图片与文本间隔  }  }

                      接口

                      barrage.open() // 开启弹幕功能barrage.close() // 关闭弹幕功能,清空弹幕barrage.addData() // 添加弹幕数据barrage.setRange() // 设置垂直方向显示范围barrage.setFont() // 设置全局字体barrage.setAlpha() // 设置全局透明度barrage.showTunnel() // 显示弹幕轨道barrage.hideTunnel() // 隐藏弹幕轨道

                      说明

                      1. 通过 canvas 实现弹幕组件时,对于低版本基础库由于缺失 raf 接口,动画效果不够流畅。
                      2. 2.9.0 起小程序新的 canvas 接口可替代 view 的实现。


                      select-text

                      可选文本组件。该组件有两种使用模式:长按出现选区,与浏览器默认效果一致;长按出现复制按钮,点击复制拷贝全部内容至剪贴板,常见于聊天对话框等场景。

                      需注意的时,为实现点击其它区域隐藏复制按钮,开发者可在页面最外层监听 tap 事件,并将 evt 对象赋值给 on-document-tap。

                      <view bind:tap="handleTap">  <view class="demo-block">    <block wx:for="{{arr}}" wx:key="placement">      <view class="list-item">        <mp-select-text           show-copy-btn           placement="{{item.placement}}"           value="{{item.value}}"           data-id="{{index}}"           bindcopy="onCopy"          on-document-tap="{{evt}}"        >        </mp-select-text>      </view>    </block>    <view class="list-item">      <mp-select-text value="默认的长按效果与浏览器一致"></mp-select-text>    </view>  </view></view>

                      Page({  data: {    arr: [{      value: '长按,上侧复制',      placement: 'top'    }, {      value: '长按,右侧复制',      placement: 'right'    }, {      value: '长按,左侧复制',      placement: 'left'    }, {      value: '长按,下侧复制',      placement: 'bottom'    }]  },  onLoad() {  },  onCopy(e) {    console.log('onCopy', e)  },    handleTouchStart(e) {    console.log('@@ touchstart', e)  },  handleTap(e) {    console.log('@@ tap', e)    this.setData({      evt: e    })  }})


                      属性列表

                      属性类型默认值必填说明
                      valueString文本组件内容
                      spaceString显示连续空格
                      decodeBooleanfalse是否解码
                      show-copy-btnBooleanfalse长按显示复制按钮
                      z-indexNumber99复制按钮的层级
                      active-bg-colorString#DEDEDE长按复制时文本区背景色
                      on-document-tapObject页面监听事件

                      space 的合法值

                      属性类型
                      ensp中文字符空格一半大小
                      emsp中文字符空格大小
                      nbsp根据字体设置的空格大小

                      代码演示

                      在开发者工具中预览效果

                      <view bind:tap="handleTap">  <view class="demo-block">    <block wx:for="{{arr}}" wx:key="placement">      <view class="list-item">        <mp-select-text           show-copy-btn           placement="{{item.placement}}"           value="{{item.value}}"           data-id="{{index}}"           on-document-tap="{{evt}}"        >        </mp-select-text>      </view>    </block>    <view class="list-item">      <mp-select-text value="默认的长按效果与浏览器一致"></mp-select-text>    </view>  </view></view>
                      Page({  data: {    arr: [{      value: '长按,上侧复制',      placement: 'top'    },    {      value: '长按,右侧复制',      placement: 'right'    },    {      value: '长按,左侧复制',      placement: 'left'    },    {      value: '长按,下侧复制',      placement: 'bottom'    }]  },  handleTap(e) {    this.setData({ evt: e })  }})


                      wxml-to-canvas

                      小程序内通过静态模板和样式绘制 canvas ,导出图片,可用于生成分享图等场景。

                      使用方法

                      Step1. npm 安装

                      npm install --save wxml-to-canvas

                      Step2. JSON 组件声明

                      {  "usingComponents": {    "wxml-to-canvas": "wxml-to-canvas",  }}

                      Step3. wxml 引入组件

                      <video class="video" src="{{src}}">  <wxml-to-canvas class="widget"></wxml-to-canvas></video><image src="{{src}}" style="width: {{width}}px; height: {{height}}px"></image>

                      Step4. js 获取实例

                      const {wxml, style} = require('./demo.js')Page({  data: {    src: ''  },  onLoad() {    this.widget = this.selectComponent('.widget')  },  renderToCanvas() {    const p1 = this.widget.renderToCanvas({ wxml, style })    p1.then((res) => {      this.container = res      this.extraImage()    })  },  extraImage() {    const p2 = this.widget.canvasToTempFilePath()    p2.then(res => {      this.setData({        src: res.tempFilePath,        width: this.container.layoutBox.width,        height: this.container.layoutBox.height      })    })  }})

                      wxml 模板

                      支持 view、text、image 三种标签,通过 class 匹配 style 对象中的样式。

                      <view class="container" >  <view class="item-box red">  </view>  <view class="item-box green" >    <text class="text">yeah!</text>  </view>  <view class="item-box blue">      <image class="img" src="https://ss0.bdstatic.com/70cFvHSh_Q1YnxGkpoWK1HF6hhy/it/u=3582589792,4046843010&fm=26&gp=0.jpg" rel="external nofollow" ></image>  </view></view>

                      样式

                      对象属性值为对应 wxml 标签的 cass 驼峰形式。需为每个元素指定 width 和 height 属性,否则会导致布局错误。

                      存在多个 className 时,位置靠后的优先级更高,子元素会继承父级元素的可继承属性。

                      元素均为 flex 布局。left/top 等 仅在 absolute 定位下生效。

                      const style = {  container: {    width: 300,    height: 200,    flexDirection: 'row',    justifyContent: 'space-around',    backgroundColor: '#ccc',    alignItems: 'center',  },  itemBox: {    width: 80,    height: 60,  },  red: {    backgroundColor: '#ff0000'  },  green: {    backgroundColor: '#00ff00'  },  blue: {    backgroundColor: '#0000ff'  },  text: {    width: 80,    height: 60,    textAlign: 'center',    verticalAlign: 'middle',  }}

                      接口

                      f1. renderToCanvas({wxml, style}): Promise

                      渲染到 canvas,传入 wxml 模板 和 style 对象,返回的容器对象包含布局和样式信息。

                      f2. canvasToTempFilePath({fileType, quality}): Promise

                      提取画布中容器所在区域内容生成相同大小的图片,返回临时文件地址。

                      fileType 支持 jpg、png 两种格式,quality 为图片的质量,目前仅对 jpg 有效。取值范围为 (0, 1],不在范围内时当作 1.0 处理。

                      支持的 css 属性

                      布局相关

                      属性名支持的值或类型默认值
                      widthnumber0
                      heightnumber0
                      positionrelative, absoluterelative
                      leftnumber0
                      topnumber0
                      rightnumber0
                      bottomnumber0
                      marginnumber0
                      paddingnumber0
                      borderWidthnumber0
                      borderRadiusnumber0
                      flexDirectioncolumn, rowrow
                      flexShrinknumber1
                      flexGrownumber
                      flexWrapwrap, nowrapnowrap
                      justifyContentflex-start, center, flex-end, space-between, space-aroundflex-start
                      alignItems, alignSelfflex-start, center, flex-end, stretchflex-start

                      支持 marginLeft、paddingLeft 等

                      文字

                      属性名支持的值或类型默认值
                      fontSizenumber14
                      lineHeightnumber / string'1.4em'
                      textAlignleft, center, rightleft
                      verticalAligntop, middle, bottomtop
                      colorstring#000000
                      backgroundColorstringtransparent

                      lineHeight 可取带 em 单位的字符串或数字类型。

                      变形

                      属性名支持的值或类型默认值
                      scalenumber1


                      computed

                      小程序自定义组件扩展 behavior,计算属性 computed 和监听器 watch 的实现。在 data 或者 properties 改变时,会重新计算 computed 字段并触发 watch 监听器。

                      此 behavior 依赖开发者工具的 npm 构建。具体详情可查阅官方 npm 文档。

                      使用方法

                      需要小程序基础库版本 >= 2.6.1 的环境。

                      你可以直接体验一下这个代码片段,它包含了基本用法示例:https://developers.weixin.qq.com/s/gXK31mmZ73dd

                      安装

                      npm install --save miniprogram-computed

                      computed 基本用法

                      const computedBehavior = require('miniprogram-computed')Component({  behaviors: [computedBehavior],  data: {    a: 1,    b: 1,  },  computed: {    sum(data) {      // 注意: computed 函数中不能访问 this ,只有 data 对象可供访问      // 这个函数的返回值会被设置到 this.data.sum 字段中      return data.a + data.b    },  },  methods: {    onTap() {      this.setData({        a: this.data.b,        b: this.data.a + this.data.b,      })    }  }})
                      <view>A = {{a}}</view><view>B = {{b}}</view><view>SUM = {{sum}}</view><button bindtap="onTap">click</button>

                      watch 基本用法

                      const computedBehavior = require('miniprogram-computed')Component({  behaviors: [computedBehavior],  data: {    a: 1,    b: 1,    sum: 2,  },  watch: {    'a, b': function(a, b) {      this.setData({        sum: a + b      })    },  },  methods: {    onTap() {      this.setData({        a: this.data.b,        b: this.data.a + this.data.b,      })    }  }})
                      <view>A = {{a}}</view><view>B = {{b}}</view><view>SUM = {{sum}}</view><button bindtap="onTap">click</button>

                      ^1.0.0 与 ^2.0.0 版本差异

                      这个 behavior 的 ^1.0.0 版本和 ^2.0.0 版本有较大差异。 ^2.0.0 版本基于小程序基础库 2.6.1 开始支持的 observers 定义段实现,具有较好的性能。以下是版本之间主要区别的比较。

                      项目^1.0.0^2.0.0
                      支持的基础库最低版本2.2.32.6.1
                      支持 watch 定义段
                      性能相对较差相对较好

                      常见问题说明

                      我应该使用 computed 还是 watch ?

                      从原理上说, watch 的性能比 computed 更好;但 computed 的用法更简洁干净。

                      此外, computed 字段状态只能依赖于 data 和其他 computed 字段,不能访问 this 。如果不可避免要访问 this ,则必须使用 watch 代替。

                      watch 和小程序基础库本身的 observers 有什么区别?

                      • 无论字段是否真的改变, observers 都会被触发,而 watch 只在字段值改变了的时候触发,并且触发时带有参数。

                      关于 ** 通配符

                      在 watch 字段上可以使用 ** 通配符,是它能够监听这个字段下的子字段的变化(类似于小程序基础库本身的 observers)。示例代码片段

                      const computedBehavior = require('miniprogram-computed')Component({  behaviors: [computedBehavior],  data: {    obj: {      a: 1,      b: 2,    }  },  watch: {    'obj.**': function(obj) {      this.setData({        sum: obj.a + obj.b      })    },  },  methods: {    onTap() {      this.setData({        'obj.a': 10      })    }  }})

                      除此以外:

                      • 对于没有使用 ** 通配符的字段,在 watch 检查值是否发生变化时,只会进行粗略的浅比较(使用 === );
                      • 对于使用了 ** 通配符的字段,则会进行深比较,来尝试精确检测对象是否真的发生了变化,这要求对象字段不能包含循环(类似于 JSON.stringify )。


                      小程序的 MobX 绑定辅助库

                      小程序的 MobX 绑定辅助库。

                      此 behavior 依赖开发者工具的 npm 构建。具体详情可查阅 官方 npm 文档 。
                      可配合 MobX 的小程序构建版 npm 模块 mobx-miniprogram 使用。

                      使用方法

                      需要小程序基础库版本 >= 2.2.3 的环境。

                      也可以直接参考这个代码片段(在微信开发者工具中打开): https://developers.weixin.qq.com/s/36j8NZmC74ac 。

                      1. 安装 mobx-miniprogram 和 mobx-miniprogram-bindings :
                      npm install --save mobx-miniprogram mobx-miniprogram-bindings
                      1. 创建 MobX Store。
                      // store.jsimport { observable, action } from 'mobx-miniprogram'export const store = observable({  // 数据字段  numA: 1,  numB: 2,  // 计算属性  get sum() {    return this.numA + this.numB  },  // actions  update: action(function () {    const sum = this.sum    this.numA = this.numB    this.numB = sum  })})
                      1. 在 Component 构造器中使用:
                      import { storeBindingsBehavior } from 'mobx-miniprogram-bindings'import { store } from './store'Component({  behaviors: [storeBindingsBehavior],  data: {    someData: '...'  },  storeBindings: {    store,    fields: {      numA: () => store.numA,      numB: (store) => store.numB,      sum: 'sum'    },    actions: {      buttonTap: 'update'    },  },  methods: {    myMethod() {      this.data.sum // 来自于 MobX store 的字段    }  }})
                      1. 在 Page 构造器中使用:
                      import { createStoreBindings } from 'mobx-miniprogram-bindings'import { store } from './store'Page({  data: {    someData: '...'  },  onLoad() {    this.storeBindings = createStoreBindings(this, {      store,      fields: ['numA', 'numB', 'sum'],      actions: ['update'],    })  },  onUnload() {    this.storeBindings.destroyStoreBindings()  },  myMethod() {    this.data.sum // 来自于 MobX store 的字段  }})

                      接口

                      将页面、自定义组件和 store 绑定有两种方式: behavior 绑定 和 手工绑定 。

                      behavior 绑定

                      behavior 绑定 适用于 Component 构造器。做法:使用 storeBindingsBehavior 这个 behavior 和 storeBindings 定义段。

                      注意:你可以用 Component 构造器构造页面, 参考文档 。

                      import { storeBindingsBehavior } from 'mobx-miniprogram-bindings'Component({  behaviors: [storeBindingsBehavior],  storeBindings: {    /* 绑定配置(见下文) */  }})

                      手工绑定

                      手工绑定 适用于全部场景。做法:使用 createStoreBindings 创建绑定,它会返回一个包含清理函数的对象用于取消绑定。

                      注意:在页面 onUnload (自定义组件 detached )时一定要调用清理函数,否则将导致内存泄漏!

                      import { createStoreBindings } from 'mobx-miniprogram-bindings'Page({  onLoad() {    this.storeBindings = createStoreBindings(this, {      /* 绑定配置(见下文) */    })  },  onUnload() {    this.storeBindings.destroyStoreBindings()  }})

                      绑定配置

                      无论使用哪种绑定方式,都必须提供一个绑定配置对象。这个对象包含的字段如下:

                      字段名类型含义
                      store一个 MobX observable默认的 MobX store
                      fields数组或者对象用于指定需要绑定的 data 字段
                      actions数组或者对象用于指定需要映射的 actions

                      fields

                      fields 有三种形式:

                      • 数组形式:指定 data 中哪些字段来源于 store 。例如 ['numA', 'numB', 'sum'] 。
                      • 映射形式:指定 data 中哪些字段来源于 store 以及它们在 store 中对应的名字。例如 { a: 'numA', b: 'numB' } ,此时 this.data.a === store.numA this.data.b === store.numB 。
                      • 函数形式:指定 data 中每个字段的计算方法。例如 { a: () => store.numA, b: () => anotherStore.numB } ,此时 this.data.a === store.numA this.data.b === anotherStore.numB 。

                      上述三种形式中,映射形式和函数形式可以在一个配置中同时使用。

                      如果仅使用了函数形式,那么 store 字段可以为空,否则 store 字段必填。

                      actions

                      actions 可以用于将 store 中的一些 actions 放入页面或自定义组件的 this 下,来方便触发一些 actions 。有两种形式:

                      • 数组形式:例如 ['update'] ,此时 this.update === store.update 。
                      • 映射形式:例如 { buttonTap: 'update' } ,此时 this.buttonTap === store.update 。

                      只要 actions 不为空,则 store 字段必填。

                      延迟更新与立刻更新

                      为了提升性能,在 store 中的字段被更新后,并不会立刻同步更新到 this.data 上,而是等到下个 wx.nextTick 调用时才更新。(这样可以显著减少 setData 的调用次数。)

                      如果需要立刻更新,可以调用:

                      • this.updateStoreBindings() (在 behavior 绑定 中)
                      • this.storeBindings.updateStoreBindings() (在 手工绑定 中)


                      小程序瘦身工具

                      通过剔除无用文件、压缩图片、复用代码等方式减少小程序代码包体积。开源项目地址:https://github.com/wechat-miniprogram/miniprogram-slim

                      安装

                      npm install -g miniprogram-slim

                      使用

                      Usage: miniprogram-slim <command>Options:  -v, --version                  output the version number  -h, --help                     output usage informationCommands:  cpd [options] <dir>            Detect duplications in source code  sprite [options] <input...>    Covert images into css sprites  imagemin [options] <input...>  Minify images seamlessly  analyzer [options]             Analyze dependencies of miniprogram, find out unused filesExamples:  $ miniprogram-slim analyzer -t  $ miniprogram-slim cpd src  $ miniprogram-slim imagemin images/**/*.png  $ miniprogram-slim sprite -f emoji images/**/*.png


                      微信小程序定义文件

                      微信小程序 API 的 TypeScript 类型定义文件

                      安装

                      通过 npm 安装:

                      # 安装对应最新基础库的定义文件npm install miniprogram-api-typings

                      或者通过版本号指定一个基础库版本:

                      # 安装对应基础库版本 2.4.1 的定义文件npm install miniprogram-api-typings@2.4.1

                      版本

                      基础库版本npm 版本命令
                      v2.6.52.6.5-2npm install miniprogram-api-typings@2.6.5-2
                      v2.4.22.4.2-2npm install miniprogram-api-typings@2.4.2-2
                      v2.4.12.4.1npm install miniprogram-api-typings@2.4.1
                      v2.4.02.4.0-1npm install miniprogram-api-typings@2.4.0-1

                      贡献

                      定义文件是随 文档 一起自动生成的,所以所有的 PR 都将 不会 被接受。如果您有 bug 反馈或建议,请提一个 issue 给我们。非常感谢!


                      API Promise化

                      扩展微信小程序api支持promise

                      安装

                      npm install --save miniprogram-api-promise

                      使用

                      在小程序入口(app.js)调用一次promisifyAll,只需要调用一次。

                      示例:

                      import { promisifyAll, promisify } from 'miniprogram-api-promise';const wxp = {}// promisify all wx's apipromisifyAll(wx, wxp)console.log(wxp.getSystemInfoSync())wxp.getSystemInfo().then(console.log)wxp.showModal().then(wxp.openSetting())// compatible usagewxp.getSystemInfo({success(res) {console.log(res)}})// promisify single apipromisify(wx.getSystemInfo)().then(console.log)


                      threejs-miniprogram

                      Three.js 小程序 WebGL 的适配版本。

                      使用

                      可参考 example 目录下的示例项目或参照以下流程:

                      1. 通过 npm 安装
                      npm install --save threejs-miniprogram

                      安装完成之后在微信开发者工具中点击构建 npm。

                      1. 导入小程序适配版本的 Three.js
                      import {createScopedThreejs} from 'threejs-miniprogram'Page({  onReady() {    wx.createSelectorQuery()      .select('#webgl')      .node()      .exec((res) => {        const canvas = res[0].node        // 创建一个与 canvas 绑定的 three.js        const THREE = createScopedThreejs(canvas)        // 传递并使用 THREE 变量      })  }})

                      说明

                      • 本项目当前使用的 Three.js 版本号为 0.108.0,如要更新 threejs 版本可发 PR 修改或 fork 后自行修改。
                      • 该适配版本的 THREE 不在全局环境中,如使用 Three.js 的其他配套类库,需要自行传入 THREE 到类库中。
                      • 如在使用过程中发现有适配问题,可通过 issue 反馈或发 PR 修复。


                      lottie-miniprogram

                      lottie 动画库适配小程序的版本。

                      lottie 的相关介绍与动画生成方法等请参考 官方说明
                      依赖小程序基础库版本 >= 2.8.0 的环境

                      使用

                      可参考该代码片段:https://developers.weixin.qq.com/s/2TYvm9mJ75bF。大致步骤如下:

                      1. 通过 npm 安装:
                      npm install --save lottie-miniprogram
                      1. 传入 canvas 对象用于适配
                      <canvas id="canvas" type="2d"></canvas>
                      import lottie from 'lottie-miniprogram'Page({  onReady() {    wx.createSelectorQuery().select('#canvas').node(res => {      const canvas = res.node      lottie.setup(canvas)    }).exec()  }})
                      1. 使用 lottie 接口
                      lottie.setup(canvas)lottie.loadAnimation({  ...})

                      接口

                      目前提供两个接口:

                      lottie.setup(canvas)

                      需要在任何 lottie 接口调用之前调用,传入 canvas 对象

                      lottie.loadAnimation(options)

                      与原来的 loadAnimation 有些不同,支持的参数有:

                      • loop
                      • autoplay
                      • animationData
                      • path (只支持网络地址)
                      • rendererSettings.context (必填)

                      说明

                      • 本项目是以 npm 的方式依赖原 lottie-web 项目,若原项目有新版本,可直接改变依赖的版本号。
                      • 本项目依赖小程序基础库 2.8.0 里性能更好的 canvas 实现,由于还有些小问题没有正式开放,但目前用在此处暂无发现问题。
                      • 由于小程序本身不支持动态执行脚本,因此 lottie 的 expression 功能也是不支持的。


                      sm-crypto

                      小程序 js 库。国密算法 sm2、sm3 和 sm4 的实现。

                      使用此组件需要依赖小程序基础库 2.2.1 以上版本,同时依赖开发者工具的 npm 构建。具体详情可查阅官方 npm 文档。

                      安装

                      npm install --save miniprogram-sm-crypto

                      sm2

                      获取密钥对

                      const sm2 = require('miniprogram-sm-crypto').sm2;let keypair = sm2.generateKeyPairHex();publicKey = keypair.publicKey; // 公钥privateKey = keypair.privateKey; // 私钥

                      加密解密

                      const sm2 = require('miniprogram-sm-crypto').sm2;const cipherMode = 1; // 1 - C1C3C2,0 - C1C2C3,默认为1let encryptData = sm2.doEncrypt(msgString, publicKey, cipherMode); // 加密结果let decryptData = sm2.doDecrypt(encryptData, privateKey, cipherMode); // 解密结果

                      签名验签

                      ps:理论上来说,只做纯签名是最快的。
                      const sm2 = require('miniprogram-sm-crypto').sm2;// 纯签名 + 生成椭圆曲线点let sigValueHex = sm2.doSignature(msg, privateKey); // 签名let verifyResult = sm2.doVerifySignature(msg, sigValueHex, publicKey); // 验签结果// 纯签名let sigValueHex2 = sm2.doSignature(msg, privateKey, {    pointPool: [sm2.getPoint(), sm2.getPoint(), sm2.getPoint(), sm2.getPoint()], // 传入事先已生成好的椭圆曲线点,可加快签名速度}); // 签名let verifyResult2 = sm2.doVerifySignature(msg, sigValueHex2, publicKey); // 验签结果// 纯签名 + 生成椭圆曲线点 + der编解码let sigValueHex3 = sm2.doSignature(msg, privateKey, {    der: true,}); // 签名let verifyResult3 = sm2.doVerifySignature(msg, sigValueHex3, publicKey, {    der: true,}); // 验签结果// 纯签名 + 生成椭圆曲线点 + sm3杂凑let sigValueHex4 = sm2.doSignature(msg, privateKey, {    hash: true,}); // 签名let verifyResult4 = sm2.doVerifySignature(msg, sigValueHex4, publicKey, {    hash: true,}); // 验签结果// 纯签名 + 生成椭圆曲线点 + sm3杂凑(不做公钥推导)let sigValueHex5 = sm2.doSignature(msg, privateKey, {    hash: true,    publicKey, // 传入公钥的话,可以去掉sm3杂凑中推导公钥的过程,速度会比纯签名 + 生成椭圆曲线点 + sm3杂凑快});let verifyResult5 = sm2.doVerifySignature(msg, sigValueHex5, publicKey, {    hash: true,    publicKey,});

                      获取椭圆曲线点

                      const sm2 = require('miniprogram-sm-crypto').sm2;let poin = sm2.getPoint(); // 获取一个椭圆曲线点,可在sm2签名时传入

                      sm3

                      const sm3 = require('miniprogram-sm-crypto').sm3;let hashData = sm3('abc'); // 杂凑

                      sm4

                      加密

                      const sm4 = require('miniprogram-sm-crypto').sm4;const key = [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10];let encryptData = sm4.encrypt([0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10], key); // 加密

                      解密

                      const sm4 = require('miniprogram-sm-crypto').sm4;const key = [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10];let decryptData = sm4.decrypt([0x68, 0x1e, 0xdf, 0x34, 0xd2, 0x06, 0x96, 0x5e, 0x86, 0xb3, 0xe9, 0x4f, 0x53, 0x6e, 0x42, 0x46], 

                      国密算法实现实例:详情


                      快速入门

                      概览

                      miniprogram-i18n 的用法主要分为四部分。分别是:构建脚本与i18配置、i18n文本定义、WXML中的用法及JavaScript中的用法。

                      安装

                      该方案目前需要依赖 Gulp 并且对源文件目录结构有一定的要求,需要确保小程序源文件放置在特定目录下(例如 src/ 目录)。

                      1. 首先在项目根目录运行以下命令安装 gulp 及 miniprogram-i18n 的 gulp 插件。
                      npm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml
                      1. 在小程序运行环境下安装国际化运行时并在开发工具"构建npm"。
                      npm i -S @miniprogram-i18n/core
                      1. 在项目根目录新建 gulpfile.js,并编写构建脚本,可参考 examples/gulpfile.js。
                      更多 Gulp 相关配置请参考 Gulp插件配置文档。

                      使用

                      i18n文本定义

                      miniprogram-i18n 目前采用 JSON 文件对 i18n 文本进行定义。使用之前,需要在项目源文件下新建 i18n 目录。

                      目录结构如下:

                      ├── dist               // 小程序构建目录├── gulpfile.js├── node_modules├── package.json└── src                // 小程序源文件目录|   ├── app.js|   ├── app.json|   ├── app.wxss|   ├── i18n           // 国际化文本目录|   |   ├── en-US.json|   |   └── zh-CN.json

                      i18n 目录可以放置在源文件目录下的任意位置,例如可以跟 Page 或 Component 放在一起。但是需要注意的是,多个 i18n 目录下的文件在构建时会被合并打包,因此如果翻译文本有重复的 key 可能会发生覆盖。如果分开多个 i18n 目录定义需要自行确保 key 是全局唯一的。例如使用 page.index.testKey 这样的能确保唯一的名称。

                      下面我们定义文本:

                      // i18n/en-US.json{  "plainText": "This is a plain text",  "withParams": "{value} is what you pass in"}
                      // i18n/zh-CN.json{  "plainText": "这是一段纯文本",  "withParams": "你传入的值是{value}"}

                      WXML 中的用法

                      定义好 i18n 文本之后,就可以在 WXML 文件里使用了。首先,需要在 WXML 文件对应的 JavaScript 文件里引入国际化运行时。

                      // pages/index/index.jsimport { I18n } from '@miniprogram-i18n/core'Component({  behaviors: [I18n]})
                      注意:这里建议 Page 以及 Component 都采用 Component 构造器进行定义,这样可以使用 I18n 这个 Behavior。如果需要在 Page 构造上使用 I18n 则需要引入 I18nPage 代替 Page 构造器。

                      接着可以在 WXML 文件中获取预先定义好的 i18n 文本。

                      <!-- pages/index/index.wxml --><view>{{ t('plainText') }}</view><input placeholder="{{ t('withParams', {value}) }}"></input>

                      在 WXML 中使用 t 函数(或其他你指定的函数名)来获取文本。 t函数签名如下:

                      t(key: string, params: object)

                      它可以接受两个参数,第一个参数是 i18n 文本的 key,第二个参数是需要传入的插值对象(可以是从 AppService 传过来的值)。

                      JavaScript 中的用法

                      在 JavaScript 里可以直接引用 @miniprogram-i18n/core 这个 NPM 包来获取翻译文本。

                      import { getI18nInstance } from '@miniprogram-i18n/core'const i18n = getI18nInstance()Component({  attached() {    const text = i18n.t('withParams', { value: 'Test' })    console.log(text)    // Test is what you pass in    i18n.setLocale('en-US')  }})

                      同样的,在 i18n 实例上,还暴露了其他一些接口,例如获取当前语言、动态设置当前语言等。具体接口请参考 接口文档。

                      如果你的 JavaScript 对应的 WXML 里已经使用了国际化文本,换言之,即 Component 构造器已经引入了 I18n Behavior,那么所有的实例方法都会被直接挂载到 this 上,你可以通过 this 调用它们。

                      import { I18n } from '@miniprogram-i18n/core'Component({  behaviors: [I18n],  attached() {    const text = this.t('withParams', { value: 'Test' })    console.log(text)    // Test is what you pass in    this.setLocale('en-US')  }})

                      构建

                      在编写完 i18n 文本并在 WXML 或 JavaScript 中调用之后,你需要运行 gulp 命令对 .wxml 文件进行转译并对 i18n 文本进行打包合并。

                      特性

                      目前 miniprogram-i18n 仅支持纯文本及文本插值,后续会对其他 i18n 特性进行支持。

                      文本插值

                      {  "key": "Inserted value: {value}"}
                      i18n.t('key', { value: 'Hello!' })  // Inserted value: Hello!

                      为了方便调用深层嵌套的对象,当前支持使用 . 点语法来访问对象属性。

                      {   "dotted": "Nested value is: { obj.nested.value }"}
                      const value = {  obj: {    nested: {      value: 'Catch you!'    }  }}i18n.t('dotted', value)  // Nested value is: Catch you!

                      select 语句

                      {  "key": "{gender, select, male {His inbox} female {Her inbox} other {Their inbox}}"}
                      i18n.t('key', { gender: 'male' })    // His inboxi18n.t('key', { gender: 'female' })  // Her inboxi18n.t('key')                        // Their inbox

                      select 语句支持子语句文本插值:

                      {  "key": "{mood, select, good {{how} day!} sad {{how} day.} other {Whatever!}}"}
                      i18n.t('key', { mood: 'good', how: 'Awesome'  })  // Awesome day!i18n.t('key', { mood: 'sad', how: 'Unhappy'  })   // Unhappy day.i18n.t('key')                                     // Whatever!
                      注:select 语句支持子句嵌套 select 语句

                      其他尚未支持的特性有:

                      • Pseudo 字符串
                      • 单复数处理
                      • 日期、数字、货币处理
                      • 定义文件的命名空间
                      • 支持 WXML 与 JavaScript 独立定义

                      接口文档

                      miniprogram-i18n API 是运行时在 JavaScript 侧操作 i18n 的接口。

                      接口列表

                      • initI18n(localesConfig: object): I18n
                      • getI18nInstance(): I18n
                      • t(key: string, params: object): string
                      • getLocale(): string
                      • setLocale(currentLocale: string): void
                      • getFallbackLocale(): string
                      • onLocaleChange(handler: (currentLocale: string) => void): object

                      初始化 I18n 运行时

                      initI18n(localesConfig: object): I18n

                      在 app.js 调用 initI18n 来加载 i18n 文本并指定默认语言。若未进行指定,i18n运行时将默认从 /i18n/locales.js 中读取文本及配置。

                      // src/app.jsimport { initI18n } from '@miniprogram-i18n/core'import locales from '/i18n/locales.js'initI18n(locales)App({})

                      获取 I18n 运行时

                      getI18nInstance(): I18n

                      该接口会返回 I18n 运行时实例。

                      import { getI18nInstance } from '@miniprogram-i18n/core'const i18n = getI18nInstance()i18n.t('key')

                      I18n 接口

                      以下五个接口用来获取或操作 I18n,均可在 I18n 实例或 拥有 I18n Behavior 的组件或 I18nPage 上进行调用。 通过组件直接访问成员函数:

                      import { I18n } from '@miniprogram-i18n/core'Component({  behaviors: [I18n],  attached() {    this.t('key')    this.getLocale()  // en-US    this.setLocale('zh-CN')    this.getFallbackLocale()  // zh-CN    this.onLocaleChange((currentLocale) => {      console.log('Locale changed to', currentLocale)    })  }})

                      或从 I18n 实例调用:

                      import { I18n } from '@miniprogram-i18n/core'const i18n = getI18nInstance()i18n.t('key')i18n.getLocale()  // en-USi18n.setLocale('zh-CN')i18n.getFallbackLocale()  // zh-CNi18n.onLocaleChange((currentLocale) => {  console.log('Locale changed to', currentLocale)})

                      t(key: string, params: object): string

                      最主要的翻译函数,通过该函数可以获得预先定义的 i18n 文本。

                      getLocale(): string

                      获取当前设置的语言。默认语言应在 gulp 构建脚本中配置,详见 Gulp插件配置文档。

                      setLocale(currentLocale: string): void

                      设置当前语言。该值应与 i18n 定义文件名相对应。

                      getFallbackLocale(): string

                      获取备选语言。该值在构建脚本中进行配置,一旦设置之后无法在运行时通过接口修改。详见 Gulp插件配置文档。

                      onLocaleChange(handler: (currentLocale: string) => void): object

                      当前语言被修改时触发的事件回调。返回值 object,可通过返回值对象取消事件监听。

                      const event = i18n.onLocaleChange(() => {})event.off()

                      Gulp 插件配置文档

                      miniprogram-i18n 在构建阶段依赖两个 Gulp 插件,分别是 @miniprogram-i18n/gulp-i18n-wxml 和 @miniprogram-i18n/gulp-i18n-locales,gulp-i18n-wxml 负责转译 wxml 文件中的 i18n 自定义语法,gulp-i18n-locales 则负责合并 i18n 定义文件,并进行预处理生成运行时所需的文件。

                      若使用 CLI 进行构建,则可忽略 Gulp 构建的配置。

                      安装

                      因此在使用 i18n 的构建插件之前,需要先安装相关依赖。

                      npm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml

                      依赖安装完成之后,需要建立 gulp 所需的配置并引入 i18n 构建插件。示例如下:

                      const gulpWxmlTransformer = require('@miniprogram-i18n/gulp-i18n-wxml')const gulpLocalesLoader = require('@miniprogram-i18n/gulp-i18n-locales')function transpileWxml() {  return src('src/**/*.wxml')    .pipe(gulpWxmlTransformer())    .pipe(dest('dist/'))}function mergeAndGenerateLocales() {  return src('src/**/i18n/*.json')    .pipe(gulpLocalesLoader({ defaultLocale: 'zh-CN', fallbackLocale: 'zh-CN' }))    .pipe(dest('dist/i18n/'))}

                      更详细的配置请参考 examples。

                      gulp-i18n-wxml 配置

                      该构建函数支持如下参数:

                      interface Options {  wxsPath: string,  wxsModuleName?: string,  i18nFunctionName?: string,}
                      • wxsPath指定 locales.wxs 所在路径,应与 gulp-i18n-locales 中的配置一致,默认为 src/i18n/locales.wxs。
                      • wxsModuleName指定 wxs 模块名称,默认为 i18n。
                      • i18nFunctionName指定 wxml 中的 i18n 函数名,默认为t,可修改为任意合法的函数名。

                      gulp-i18n-locales 配置

                      该构建函数支持如下参数:

                      interface Options {  wxsFileName?: string  jsFileName?: string  defaultLocale?: string  fallbackLocale?: string}
                      • wxsFileName指定 locales wxs 文件名,需以 .wxs 作为后缀,默认为 locales.wxs。
                      • jsFileName指定 locales js 文件名,需以 .js 作为后缀,默认为locales.js。
                      • defaultLocale指定默认语言,默认为 en-US。该值需与 i18n 定义文件名对应。
                      • fallbackLocale指定备选语言,默认为 en-US。该值需与 i18n 定义文件名对应。在运行时无法找到对应语言下的文本时,会从备选语言中进行查找。注:该值无法在运行进行修改。


                      微信同声传译

                      微信同声传译插件是微信自研的语音输入,文本翻译等功能的插件封装,用于提供给第三方小程序调用。

                      体验入口

                      语音输入

                      提供语音的实时流式识别能力。 通过获取全局唯一的语音识别管理器recordRecoManager实现

                      recordRecoManager

                      recordRecoManager 对象的方法列表:

                      方法参数说明
                      startoptions开始识别
                      stop结束识别
                      onStartcallback正常开始录音识别时会调用此事件
                      onRecognizecallback有新的识别内容返回,则会调用此事件
                      onStopcallback识别结束事件
                      onErrorcallback识别错误事件

                      start(options)说明:

                      属性类型必填默认值说明
                      durationNumber60000指定录音的时长,单位ms,最大为60000。如果传入了合法的 duration ,在到达指定的 duration 后会自动停止录音
                      langStringzh_CN识别的语言,目前支持zh_CN en_US zh_HK sichuanhua

                      onStart(callback)回调结果说明:

                      属性类型说明
                      msgString默认Ok

                      onStop(callback)回调结果说明:

                      属性类型说明
                      tempFilePathString录音临时文件地址
                      durationNumber录音总时长,单位: ms
                      fileSizeNumber文件大小,单位: B
                      resultString最终识别结果

                      onError(callback)回调结果说明:

                      属性类型说明
                      retcodeInt错误码
                      msgString错误信息

                      onRecognize(callback)回调结果说明:

                      属性类型说明
                      resultString识别结果

                      onError错误码说明:

                      错误码说明
                      -30001录音接口出错
                      -30002录音暂停接口被调用,录音终止,识别终止
                      -30003录音帧数据未产生或者发送失败导致的数据传输失败
                      -30004因网络或者其他非正常状态导致的未查询识别结果
                      -30005语音识别服务内部错误
                      -30006语音识别服务未在限定时间内识别完成
                      -30007start启动参数错误
                      -30008查询请求时网络失败
                      -30009创建鉴权内部失败
                      -30010发送鉴权时网络失败
                      -30011试图在识别正在进行中是再次调用start,返回错误,正在进行的识别任务正常进行
                      -30012当前无识别任务进行时调用stop错误
                      -30013其他未知错误
                      -40001达到接口调用频率限制

                      示例代码:

                      //app.json{  ...  "plugins": {    ...    "WechatSI": {      "version": "0.0.7",      "provider": "wx069ba97219f66d99"        }  }}//index.jsvar plugin = requirePlugin("WechatSI")let manager = plugin.getRecordRecognitionManager()manager.onRecognize = function(res) {    console.log("current result", res.result)}manager.onStop = function(res) {    console.log("record file path", res.tempFilePath)    console.log("result", res.result)}manager.onStart = function(res) {    console.log("成功开始录音识别", res)}manager.onError = function(res) {    console.error("error msg", res.msg)}manager.start({duration:30000, lang: "zh_CN"})

                      文本翻译

                      文本翻译目前支持的语言有 zh_CN(中国大陆)  en_US(英语)

                      translate(OBJECT)

                      translate(object)说明:

                      参数名类型必填说明
                      lfromString文本语言 zh_CN(中国大陆)   en_US(英语)
                      ltoString目标语言 zh_CN(中国大陆)  en_US(英语)
                      contentString需要被翻译的文本内容,后台限制1000字节大小
                      ttsBoolean是否对翻译结果进行语音合成,默认为false,不进行语音合成
                      successFunction调用成功时触发的callback
                      failFunction调用失败时触发的callback
                      completeFunction接口调用结束的回调函数(调用成功、失败都会执行)

                      success(callback)回调结果说明

                      属性类型说明
                      retcodeIntretcode == 0 时翻译成功
                      originString原始文本
                      resultString翻译结果
                      filenameString语音合成返回的语音地址,仅支持合成中文语音
                      expired_timeInt语音合成链接超时时间戳 如1525930552超时后无法播放,可使用时间为3小时

                      success返回码说明: 翻译成功,合成失败时调用success回调

                      状态码说明
                      0翻译合成成功
                      -10006翻译成功,合成内部错误
                      -10007翻译成功,传入了不支持的语音合成语言
                      -10008翻译成功,语音合成达到频率限制

                      fail(callback)回调结果说明

                      属性类型说明
                      retcodeInt错误码
                      msgString错误信息

                      fail错误码说明:

                      错误码说明
                      -10001语言检查错误
                      -10002输入的待翻译内容格式不正确
                      -10003传入过长的待翻译文本内容
                      -10004翻译内部逻辑错误
                      -10005请求发送失败,请检查网络
                      -40001接口调用频率达到限制,请联系插件开发者

                      示例代码

                      plugin.translate({  lfrom:"en_US",  lto:"zh_CN",  content:"hello, this is the first time to test?",  success: function(res) {    if(res.retcode == 0) {      console.log("result", res.result)    } else {      console.warn("翻译失败", res)    }  },  fail: function(res) {    console.log("网络失败",res)  }})

                      语音合成

                      语音合成支持的语言有 zh_CN(中国大陆),en_US(英文)

                      textToSpeech(OBJECT)

                      textToSpeech(object)说明:

                      参数名类型必填说明
                      langString文本语言 zh_CN(中国大陆)en_US(英文)
                      contentString需要被翻译的文本内容,后台限制1000字节大小
                      successFunction调用成功时触发的callback
                      failFunction调用失败时触发的callback

                      success(callback)回调结果说明

                      属性类型说明
                      retcodeIntretcode == 0 时请求成功
                      originString原始文本
                      filenameString语音合成返回的语音地址,可自行下载使用
                      expired_timeInt语音合成链接超时时间戳 如1525930552,超时后无法播放,可使用时间为3小时

                      success返回码说明:

                      状态码说明
                      0语音合成成功

                      fail(callback)回调结果说明

                      属性类型说明
                      retcodeInt错误码
                      msgString错误信息

                      fail错误码说明:

                      错误码说明
                      -20001语音合成语言格式出错
                      -20002输入的待合成格式不正确
                      -20003语音合成内部错误
                      -20005网络错误
                      -40001接口调用频率达到限制,请联系插件开发者

                      示例代码

                      plugin.textToSpeech({    lang: "zh_CN",    tts: true,    content: "一个常见的需求",    success: function(res) {        console.log("succ tts", res.filename)       },    fail: function(res) {        console.log("fail tts", res)    }})

                      版本要求

                      基础库版本 >= 1.9.94

                      • 使用插件,需要基础库版本 >= 1.9.6
                      • 插件内调用wx.getRecorderManager接口,需要基础库版本 >= 1.9.94

                      配额说明

                      由于资源限制,当前各个接口调用存在配额限制,如业务有特殊更多需求,请邮箱联系roytianzou@tencent.com申请,邮件配额模版如下。 语音输入配额:每个小程序250条/分钟,3w条/天。 文本翻译配额:每个小程序500次/分钟,10w次/天。 语音合成配额:每个小程序100次/分钟,2w次/天。

                      配额申请模版

                      公司简介:(个人则填写个人)

                      小程序简介:

                      小程序appid:

                      申请接口名:

                      当前用户量:(当前未上线可填无)

                      当前调用量:(当前未上线可填无)

                      申请配额: xx 次/分钟, xx次/天。

                      合理的配额推导(请提供使用场景,预期用户量,用户使用频率,高峰时段,平均时长/字数):


                      OCR 支持

                      查看本文档前,建议先阅读《小程序插件文档》 体验工具小程序 —— 该插件完全使用此插件实现。该插件支持身份证识别,行驶证识别和银行卡识别。 小程序码 

                      申请权限

                      • 请在小程序后台搜索本插件(AppID=wx4418e3e031e551be) 设置-第三方服务-添加插件

                      调用限制

                      • 来开放社区购买,appid内的额度在插件、API、服务市场是通用的

                      调用方式

                      app.json中增加声明引入插件 version选择最新的

                        "pages": [],  "plugins": {    "ocr-plugin": {      "version": "3.0.2",      "provider": "wx4418e3e031e551be"    }  }}

                      页面的json也要增加声明

                      {  "usingComponents": {    "ocr-navigator": "plugin://ocr-plugin/ocr-navigator"  }}

                      组件

                      对外暴露自定义组件,UI载体为button(可样式自定义) 封装了

                      参数

                      属性名类型默认值是否必填说明
                      onSuccessHandleEvent接口调用成功的回调函数
                      certificateTypeStringidCard证书类型包含四种 身份证:idCard、驾驶证:drivingLicense、银行卡:bankCard、营业执照:businessLicense

                      返回结果中image_path 是用户证件照片的临时地址,开发者可以通过image_path拿到用户的证件照片

                      以下具体说明四种证件类型的使用方法

                      1、身份证

                      certificateType='idCard' 或 无certificateType这个参数

                      属性名类型默认值是否必填说明
                      onSuccessHandleEvent接口调用成功的回调函数
                      certificateTypeStringidCard证书类型包含四种 身份证:idCard、驾驶证:drivingLicense、银行卡:bankCard、营业执照:businessLicense
                      oppositeBooleantrue是否显示身份证的反面,默认为 true显示反面

                      onSuccess

                      参数 e.detail

                      参考身份证返回结果实例

                      示例代码1

                          <ocr-navigator bind:onSuccess="success" certificateType="idCard" opposite="{{false}}">      <button type="primary">身份证正面识别</button>    </ocr-navigator>    <ocr-navigator bind:onSuccess="success" certificateType="idCard" opposite="{{true}}">      <button type="primary">身份证反面识别</button>    </ocr-navigator>
                      /** wxss **//*自定义按钮样式*/.ocr-wrapper {  margin: 40rpx auto;  width: 375rpx;}.intro {  margin: 40rpx;}

                      身份证返回结果实例

                      {"type":0,"name":{"text":"张三","pos":{"left_top":{"x":98.7780914307,"y":40.9823074341},"right_top":{"x":172.311325073,"y":41.2864379883},"right_bottom":{"x":172.190856934,"y":64.9047088623},"left_bottom":{"x":98.6072158813,"y":64.5630187988}},"label":[]},"gender":{"text":"男","pos":{"left_top":{"x":101.035919189,"y":80.7537384033},"right_top":{"x":121.421043396,"y":80.7818603516},"right_bottom":{"x":121.264938354,"y":101.272567749},"left_bottom":{"x":100.882026672,"y":101.244766235}},"label":[]},"nationality":{"text":"汉","pos":{"left_top":{"x":201.881393433,"y":81.7225189209},"right_top":{"x":222.004470825,"y":81.6959762573},"right_bottom":{"x":221.899169922,"y":101.255821228},"left_bottom":{"x":201.765304565,"y":101.291915894}},"label":[]},"address":{"text":"广州市天河区五山路483号xxxxxxxxx","pos":{"left_top":{"x":95.5787811279,"y":150.794250488},"right_top":{"x":310.358947754,"y":151.617507935},"right_bottom":{"x":310.004699707,"y":220.222885132},"left_bottom":{"x":95.1295013428,"y":219.552230835}},"label":[]},"id":{"text":"4452xxxxxxxxxxxx","pos":{"left_top":{"x":176.158676147,"y":244.072860718},"right_top":{"x":453.888336182,"y":244.978515625},"right_bottom":{"x":453.874603271,"y":266.313659668},"left_bottom":{"x":176.066543579,"y":265.342407227}},"label":[]},"card_position":{"pos":{"left_top":{"x":1085.625,"y":621.75},"right_top":{"x":338.125,"y":594.75},"right_bottom":{"x":303.625,"y":99.75},"left_bottom":{"x":1189.125,"y":126.75}},"label":[]},"image_width":1280,"image_height":960,"image_path":"http://tmp/wx4418e3e031e551be.o6zAJs-yC5ByIjnyyy09jKDZquXk.dlrc7P7WlhnGb4aca86b078fc2acb5b08e7a0f438943.jpg"}

                      2、银行卡

                      certificateType='bankCard'

                      属性名类型默认值是否必填说明
                      onSuccessHandleEvent接口调用成功的回调函数
                      certificateTypeStringbankCard证书类型包含四种 身份证:idCard、驾驶证:drivingLicense、银行卡:bankCard、营业执照:businessLicense

                      onSuccess

                      参数 e.detail

                      参考银行卡返回结果实例

                      示例代码1

                      <ocr-navigator bind:onSuccess="blankSuccess"  certificateType="bankCard">  <button type="primary">银行卡识别</button></ocr-navigator>
                      /** wxss **//*自定义按钮样式*/.ocr-wrapper {  margin: 40rpx auto;  width: 375rpx;}.intro {  margin: 40rpx;}

                      银行卡返回结果实例

                      {"number":{"text":"6225xxxxxxxxxxxx","label":[]},"card_position":{"pos":{"left_top":{"x":2.19140625,"y":227.6171875},"right_top":{"x":729.50390625,"y":206.0546875},"right_bottom":{"x":769.91015625,"y":658.8671875},"left_bottom":{"x":-11.27734375,"y":680.4296875}},"label":[]},"image_width":762,"image_height":1280,"image_path":"http://tmp/wx4418e3e031e551be.o6zAJs-yC5ByIjnyyy09jKDZquXk.dlrc7P7WlhnGb4aca86b078fc2acb5b08e7a0f438943.jpg"}

                      银行卡返回结果

                      银行卡只支持横版储蓄卡,信用卡,并且只能识别出银行卡号,如果需要银行卡名称、过期时间需要用户手动输入

                      3、行驶证

                      certificateType='drivingLicense'

                      属性名类型默认值是否必填说明
                      onSuccessHandleEvent接口调用成功的回调函数
                      certificateTypeStringdrivingLicense证书类型包含四种 身份证:idCard、驾驶证:drivingLicense、银行卡:bankCard、营业执照:businessLicense

                      onSuccess

                      参数 e.detail

                      参考行驶证返回结果实例

                      示例代码1

                      <ocr-navigator bind:onSuccess="driverSuccess" certificateType="drivingLicense" selectedOptions="{{['plateNum','vehicleType','owner']}}">  <button type="primary">行驶证识别</button></ocr-navigator>
                      /** wxss **//*自定义按钮样式*/.ocr-wrapper {  margin: 40rpx auto;  width: 375rpx;}.intro {  margin: 40rpx;}

                      行驶证返回结果实例

                      {"plate_num":{"text":"粤KDxxxx","label":[]},"vehicle_type":{"text":"小型轿车","label":[]},"owner":{"text":"周xx","label":[]},"addr":{"text":"广东省xxxxxxxx","label":[]},"use_character":{"text":"非营运","label":[]},"model":{"text":"东风日产牌xxxxxx","label":[]},"vin":{"text":"LGBH52Exxxxxx","label":[]},"engine_num":{"text":"873073Y","label":[]},"register_date":{"text":"2017-11-13","label":[]},"issue_date":{"text":"2017-11-13","label":[]},"plate_num_b":{"text":"粤R82xxxx","label":[]},"record":{"text":"4418005xxxx","label":[]},"passengers_num":{"text":"26人","label":[]},"total_quality":{"text":"6900kg","label":[]},"prepare_quality":{"text":"4480kg","label":[]},"load_quality":{"text":"","label":[]},"lead_quality":{"text":"","label":[]},"overall_size":{"text":"7725x205xxxx","label":[]},"type":2,"card_position":[{"pos":{"left_top":{"x":454.0625,"y":17.34375},"right_top":{"x":987.8125,"y":11.71875},"right_bottom":{"x":987.8125,"y":562.96875},"left_bottom":{"x":471.5625,"y":546.09375}},"label":[]},{"pos":{"left_top":{"x":-0.9375,"y":28.59375},"right_top":{"x":445.3125,"y":22.96875},"right_bottom":{"x":445.3125,"y":551.71875},"left_bottom":{"x":-0.9375,"y":546.09375}},"label":[]}],"card_position_front":{"pos":{"left_top":{"x":454.0625,"y":17.34375},"right_top":{"x":987.8125,"y":11.71875},"right_bottom":{"x":987.8125,"y":562.96875},"left_bottom":{"x":471.5625,"y":546.09375}},"label":[]},"card_position_back":{"pos":{"left_top":{"x":-0.9375,"y":28.59375},"right_top":{"x":445.3125,"y":22.96875},"right_bottom":{"x":445.3125,"y":551.71875},"left_bottom":{"x":-0.9375,"y":546.09375}},"label":[]},"image_width":1000,"image_height":600,"img_size":{"w":1000,"h":600},"image_path":"http://tmp/wx4418e3e031e551be.o6zAJs-yC5ByIjnyyy09jKDZquXk.dlrc7P7WlhnGb4aca86b078fc2acb5b08e7a0f438943.jpg"}

                      行驶证返回结果

                      行驶证支持正副页面在一张图片中

                      4、营业执照

                      certificateType='businessLicense'

                      属性名类型默认值是否必填说明
                      onSuccessHandleEvent接口调用成功的回调函数
                      certificateTypeStringbusinessLicense证书类型包含四种 身份证:idCard、驾驶证:drivingLicense、银行卡:bankCard、营业执照:businessLicense

                      onSuccess

                      参数 e.detail

                      参考营业执照返回结果实例

                      示例代码1

                      <ocr-navigator bind:onSuccess="businessSuccess"   certificateType="businessLicense">  <button type="primary">营业执照识别</button></ocr-navigator>
                      /** wxss **//*自定义按钮样式*/.ocr-wrapper {  margin: 40rpx auto;  width: 375rpx;}.intro {  margin: 40rpx;}

                      营业执照返回结果实例

                      {"reg_num":{"text":"371400228016303","label":[]},"legal_representative":{"text":"xxxx","label":[]},"enterprise_name":{"text":"xxxxx有限公司","label":[]},"address":{"text":"xxx省xxx市xxx","label":[]},"type_of_enterprise":{"text":"有限责任公司(自然人投资或控股)","label":[]},"business_scope":{"text":"xxxxxxxxxxxx","label":[]},"registered_capital":{"text":"叁佰万元整","label":[]},"valid_period":{"text":"2008年04月12日至年月日","label":[]},"registered_date":{"text":"2008年04月12日","label":[]},"cert_position":{"pos":{"left_top":{"x":65.4609375,"y":115.640625},"right_top":{"x":567.4921875,"y":123.828125},"right_bottom":{"x":567.4921875,"y":811.578125},"left_bottom":{"x":65.4609375,"y":819.765625}},"label":[]},"img_size":{"w":630,"h":874},"image_path":"http://tmp/wx4418e3e031e551be.o6zAJs-yC5ByIjnyyy09jKDZquXk.dlrc7P7WlhnGb4aca86b078fc2acb5b08e7a0f438943.jpg"}

                      说明

                      本文档配合3.0.2以及以上的插件使用,并且调试基础库在2.4.0以及以上才能使用


                      API


                      服务平台

                      除基础组件与接口能力外,「小程序·服务平台」还为小程序开发者提供更丰富的增值能力,开发者可根据需求,选购不同规格的资源包。购买后,通过调用小程序原生快捷接入服务平台内的能力,丰富小程序的功能。

                      AI

                      微信OCR识别

                      微信OCR识别能力是微信团队推出的一套提升移动端快捷信息录入 的工具,目前支持身份证、银行卡、行驶证、营业执照的 OCR 识别。

                      智能对话服务

                      微信智能对话服务是以对话交互为核心, 为有客服需求的个人、企业和组织提供智能对话系统的搭建。

                      夸夸话术服务

                      夸夸话术服务是以对话交互为基础,为用户提供花式夸人的互动娱乐服务。用户接入服务后,可以通过相关的描述语句来唤醒夸夸技能。开发者可以将该技能应用到智能对话、客服等场景中。

                      商品二分类服务

                      商品二分类服务提供可灵活调用的接口,能够判断用户输入的自然语言文本是否与商品相关。开发者可以利用该接口赋能自己的智能搜索、商品服务等场景。

                      多语言翻译

                      提供多语言翻译能力

                      讲笑话情话服务

                      讲笑话情话服务是以对话交互为基础,为用户提供普通笑话、冷笑话、情话等互动娱乐服务。用户接入服务后,可以通过相关的触发语句来唤醒对应技能。开发者可以将该服务应用到智能对话、客服等场景中。

                      情感分析服务

                      情感分析服务是以自然语言处理技术为基础,为有文本分析需求的个人、企业或组织提供识别给定语句的情感状态的能力。具体包括正面、负面、无情感三类。开发者可以将该服务应用到商品评论分析、智能对话、舆情监控等场景中。

                      商品关键词抽取服务

                      商品关键词抽取服务提供可灵活调用的接口,能够从电商商品标题中抽取关键词,包括商品名、品牌名、修饰词、营销词、颜色、材质、时间季节、地点、型号、尺寸规格单位共10类。开发者可以利用该接口赋能自己的智能客服、商品服务等场景。

                      人脸检测与分析

                      检测给定图片中的人脸位置、相应的面部属性和人脸质量信息。面部属性包括性别、年龄、表情、魅力、眼镜、发型、口罩和姿态 ,人脸质量信息包括整体质量分、模糊分、光照分和五官遮挡分。

                      人脸年龄变化

                      用户上传一张人脸图片,基于人脸编辑与生成算法,输出一张人脸变老或变年轻的图片,支持实现人脸不同年龄的变化。从童年到老年,细粒度变化,效果逼真,趣味十足。

                      人脸美颜

                      用户上传一张人脸图片,精准定位五官,实现美肤、亮肤、祛痘等美颜功能。

                      人脸试唇色

                      对图片中的人脸嘴唇进行着色,最多支持同时对一张图中的3张人脸进行试唇色。

                      人脸性别变换

                      用户上传一张人脸图片,基于人脸编辑与生成算法,输出一张人脸性别转换的图片。男变女可实现美颜、淡妆、加刘海和长发的效果;女变男可实现加胡须、变短发的效果。

                      人像分割

                      识别传入图片中人体的完整轮廓,进行抠像。

                      五官定位

                      对请求图片进行五官定位(也称人脸关键点定位),计算构成人脸轮廓的 90 个点,包括眉毛(左右各8点)、眼睛(左右各8点)、鼻子(13点)、嘴巴(22点)、脸型轮廓(21点)、眼珠[或瞳孔](2点)。

                      内容

                      文本内容安全

                      对文本中可能含有的色情、暴恐、时政违规等有害信息进行识别,帮助开发者大幅降低内容违规风险,有效控制审核成本投入。

                      图片内容安全

                      图片内容安全是基于腾讯海量数据资源和深度学习技术,为互联网企业用户提供图片内容的智能审核服务,不仅能帮助用户降低色情、暴力恐怖、时政违规等内容风险,而且能大幅度节省人工审核成本,保护业务健康发展。

                      地点搜索

                      基于腾讯位置服务千万级鲜活地点(POI)数据,提供结合搜索关键词的周边、城市范围、矩形范围(屏幕视野内)等多种地理位置搜索能力,同时提供分类筛选功能,满足不同场景的地点搜索需要。

                      坐标转换

                      实现从其它地图供应商坐标系或标准GPS坐标系,批量转换到腾讯地图坐标系,使之可以在微信小程序地图中准确标注与使用。

                      关键词输入提示

                      用于获取输入地点关键字的补完与提示,提供了面向创建收货/服务地址、打车目的地搜索及位置签到搜索等多种场景策略。服务基于海量点击行为挖掘、训练,准确命中用户所想,平均输入3.2个字即可获取准确结果。

                      驾车路线规划

                      基于驾车场景的智能路线计算引擎,支持多途经点、结合实时路况、不走高速、少收费等多种偏好设置功能,支持车牌限行避让策略,并专为网约车提供接驾、送驾场景的路线规划策略。

                      步行路线规划

                      结合海量步行道路、过街天桥、地下通道及人行出入口等设施数据,提供智能步行路线规划服务。

                      地址解析

                      提供由文字地址到经纬度坐标的转换的能力,可一定程度上兼容地址本身不规范的问题(如错别字,省市区与门牌、地点不匹配、各类干扰词等情况),同时支持返回省市区、行政区划代码信息。

                      逆地址解析

                      提供经纬度坐标到结构化地址的转换能力,结果包含对坐标位置的文字描述、省市区等行政区划信息、门牌号、商圈、道路与交叉口以及周边地点列表等,服务响应快速稳定,对微信、美团、快手等超级APP提供可靠支撑。

                      安全

                      腾讯云正版曲库直通车

                      正版曲库直通车是基于腾讯音乐娱乐集团海量线上背景音乐专用曲库资源,结合腾讯云存储、内容加速分发等基础能力,为解决内容创作过程中的正版背景音乐素材应用问题设计的 PaaS 产品。


                      服务平台 API

                      2.9.4

                      API 均在 wx.serviceMarket 对象下。invokeService 方法可以通过兼容性配置,无需依赖 2.9.4 即可使用,配置方法见底部 兼容性配置 章节说明。

                      从 2.11.1 开始,插件内也可以使用 wx.serviceMarket API,在调用时,消耗的是宿主的资源而不是插件方的资源。

                      invokeService

                      调用服务提供商提供的 API

                      入参

                      接收一个对象,对象下有如下定义的字段:

                      字段名类型必填默认值说明
                      servicestring服务提供商 ID
                      apistring服务 API 名
                      dataObject传递给服务 API 的 JSON 数据

                      返回值

                      返回一个 Promise,如调用失败,则 reject 一个 Error 对象,如调用成功,则 resolve 结果为如下定义的对象:

                      字段名类型必填默认值说明
                      dataObjectString

                      在 data 中,如果服务提供商要求其中某个字段为文件 URL、并且此时希望将本地文件/大数据上传成 URL 作为字段值传入,则可以使用我们提供的 CDN 方法对相应值进行标记,微信会自动在调用服务 API 的时候将其转换成 CDN URL 给到服务提供方。

                      错误码

                      错误码含义
                      -1入参错误
                      -2调用失败
                      -3逻辑失败
                      -6appid错误
                      -7api信息错误
                      -8api信息错误
                      -10api扣费失败
                      -11命中频率

                      示例代码 1: OCR

                      从手机选择图片后,调用 OCR 服务。OCR 服务要求调用方传图片,接收图片的方式是图片 URL。OCR 服务要求调用方的 data 结构如下:

                      字段名类型必填默认值说明
                      img_urlstring图片 URL
                      data_typenumber固定为 3,表示 URL 形式的图片
                      ocr_typenumberOCR 类型,1 为身份证识别

                      OCR 的接口需要传入图片 URL,如果需要将手机本地选择的图片上传转换成 URL,可以使用 CDN 方法对文件路径进行标记(或用任意的存储服务和自建的存储服务,也可以使用云开发的云文件存储服务,但都没有 CDN 方法便捷),以下给出使用 CDN 方法的示例:

                      // 选择图片wx.chooseImage({  count: 1,  success: async function(res) {    try {      const invokeRes = await wx.serviceMarket.invokeService({        service: 'wx79ac3de8be320b71',        api: 'OcrAllInOne',        data: {          // 用 CDN 方法标记要上传并转换成 HTTP URL 的文件          img_url: new wx.serviceMarket.CDN({            type: 'filePath',            filePath: res.tempFilePaths[0],          }),          data_type: 3,          ocr_type: 1        },      })      console.log('invokeService success', invokeRes)      wx.showModal({        title: 'success',        content: JSON.stringify(invokeRes),      })    } catch (err) {      console.error('invokeService fail', err)      wx.showModal({        title: 'fail',        content: err,      })    }  },  fail: function(res) {},  complete: function(res) {},})

                      示例代码 2: 普通 JSON 协议接口

                      有些服务不需要用到 CDN 辅助接口,可以直接 JSON 调用,以下任意举例:

                      // 选择图片wx.chooseImage({  count: 1,  success: function(res) {    // 调用 OCR 服务    wx.serviceMarket.invokeService({      service: 'some_service_id',      api: 'test',      data: {        type: 'x',        name: 'y',      },    }).then(res => {      console.log('invokeService success', res)    }).catch(err => {      console.error('invokeService fail', err)    })  },  fail: function(err) {    console.error(err)  },})

                      CDN

                      标记需要上传到 CDN 的文件/大字符串然后转换成 HTTP URL 的数据,必须在 invokeService 中使用。

                      CDN 方法可以接收三种参数类型:

                      • String
                      • ArrayBuffer
                      • 文件路径定义对象

                      当使用文件路径定义对象时,将在调用服务 API 时自动将相应文件路径对应的文件内容上传至 CDN 并转换成 CDN URL,对象定义如下:

                      字段名 类型 必填 默认值 说明 type String 是 定义对象的类型,必填 filePath filePath String 是 文件路径

                      入参

                      接收一个对象,对象下有如下定义的字段:

                      字段名类型必填说明
                      typestring定义对象的类型,必填 filePath
                      filePathstring文件路径

                      兼容性配置

                      可以通过兼容性配置让 wx.serviceMarket.invokeService API 的使用不受基础库版本约束,配置方式是:在 app.json / game.json 中指定顶层字段 "servicemarket": true,在预览发布时小程序代码包会自动包含此 API 的兼容代码,在 2.9.4 以下也可使用。仅在手机上使用,工具中调试请选择 2.9.4 基础库。


                      多端统一开发工具——kbone

                      kbone 是一个致力于微信小程序和 Web 端同构的解决方案。

                      简介

                      微信小程序的底层模型和 Web 端不同,我们想直接把 Web 端的代码挪到小程序环境内执行是不可能的。kbone 的诞生就是为了解决这个问题,它实现了一个适配器,在适配层里模拟出了浏览器环境,让 Web 端的代码可以不做什么改动便可运行在小程序里。

                      这里有个简单的代码片段:https://developers.weixin.qq.com/s/R9Hm0Qm67Acd,可以使用开发者工具打开看看效果。

                      因为 kbone 是通过提供适配器的方式来实现同构,所以它的优势很明显:

                      • 大部分流行的前端框架都能够在 kbone 上运行,比如 Vue、React、Preact 等。
                      • 支持更为完整的前端框架特性,因为 kbone 不会对框架底层进行删改(比如 Vue 中的 v-html 指令、Vue-router 插件)。
                      • 提供了常用的 dom/bom 接口,让用户代码无需做太大改动便可从 Web 端迁移到小程序端。
                      • 在小程序端运行时,仍然可以使用小程序本身的特性(比如像 live-player 内置组件、分包功能)。
                      • 提供了一些 Dom 扩展接口,让一些无法完美兼容到小程序端的接口也有替代使用方案(比如 getComputedStyle 接口)。

                      使用

                      为了可以让开发者可以更自由地进行项目的搭建,以下提供了三种方式,任选其一即可:

                      使用 kbone-cli 快速开发

                      对于新项目,可以使用 kbone-cli 来创建项目,首先安装 kbone-cli:

                      npm install -g kbone-cli

                      创建项目:

                      kbone init my-app

                      进入项目,按照 README.md 的指引进行开发:

                      // 开发小程序端npm run mp// 开发 Web 端npm run web// 构建 Web 端npm run build
                      PS:项目基于 webpack 构建,关于 webpack 方面的配置可以点此查看,而关于小程序构建相关的详细配置细节可以参考此文档。

                      使用模板快速开发

                      除了使用 kbone-cli 外,也可以直接将现有模板 clone 下来,然后在模板基础上进行开发改造:

                      • Vue 项目模板
                      • React 项目模板
                      • kbone-ui 项目模板
                      • Preact 项目模板
                      • Omi 项目模板

                      项目 clone 下来后,按照项目中 README.md 的指引进行开发。

                      手动配置开发

                      此方案基于 webpack 构建实现,如果你不想要使用官方提供的模板,想要更灵活地搭建自己的项目,又或者是想对已有的项目进行改造,则需要自己补充对应配置来实现 kbone 项目的构建。

                      一般需要补充两个配置:

                      • 构建到小程序代码的 webpack 配置
                      • 使用 webpack 构建中使用到的特殊插件 mp-webpack-plugin 配置

                      点此可以查看具体配置方式和操作流程。

                      kbone-ui

                      kbone-ui 是一个能同时支持 小程序(kbone) 和 vue 框架开发的多端 UI 库。

                      • 即可以基于 kbone 同时开发小程序和 H5,也可以单独使用开发 H5 应用。
                      • 支持以 Vue 语法来支持 H5 端和小程序端运行
                      • 对齐 微信weui 样式组件

                      文档

                      更为详细的说明和指引,可点击查看文档。

                      社区

                      此方案虽然将整个 Web 端框架包含进来并提供了适配层,但是也不是银弹,无法满足所有场景,具体限制可参考问题文档。使用相关问题可在 Kbone社区 发帖。如果还遇到其他问题,可在 issue 中反馈。

                      选择

                      业内其实已经出现了很多关于同构的解决方案了,每个方案都有自己的优劣,不存在能够完美解决所有问题的方案。kbone 也一样,它的优势在上面提到过,而它的不足也是它的实现原理带来的。kbone 是使用一定的性能损耗来换取更为全面的 Web 端特性支持。

                      所以关于性能方面,如果你对小程序的性能特别苛刻,建议直接使用原生小程序开发;如果你的页面节点数量特别多(通常在 1000 节点以上),同时还要保证在节点数无限上涨时仍然有稳定的渲染性能的话,可以尝试一下业内采用静态模板转译的方案;其他情况就可以直接采用 kbone 了。

                      案例

                      微信开放社区


                      介绍


                      腾讯云为开发者提供免费的开发环境和生产环境,更加方便、快速、可靠的构建你的小程序。

                      目前服务端支持 NodeJS 和 PHP 两种语言,开发者可以使用开发者工具同时进行服务端和小程序的开发。

                      开发环境


                      • 免费使用
                      • 自动分配测试用二级域名:xxxxxxx.qcloud.la
                      • 自动部署免费 HTTPS
                      • 仅可用于线上调试,不可发布
                      • 代码部署、运行和数据库与生产环境完全分开
                      • 与微信开发工具打通,可一键部署、调试、重启和恢复代码

                      生产环境


                      • 免费使用
                      • 用户需购买或使用已有的腾讯云域名
                      • 自动部署免费 HTTPS
                      • 用于线上发布,不可调试
                      • 使用微信开发工具上传代码,在腾讯云控制台操作部署,上传和发布分离,降低误操作风险

                      通过微信公众平台授权登录腾讯云


                      打开 微信公众平台 注册并登录小程序,按如下步骤操作:

                      • 单击左侧菜单栏中的【设置】
                      • 单击右侧 Tab 栏中的【开发者工具】
                      • 单击【腾讯云】,进入腾讯云工具页面,单击【开通】
                      • 使用小程序绑定的微信扫码即可将小程序授权给腾讯云,开通之后会自动进去腾讯云微信小程序控制台,显示开发环境已开通,此时可以进行后续操作

                      注意:

                      此时通过小程序开发者工具查看腾讯云状态并不会显示已开通,已开通状态会在第一次部署开发环境之后才会同步到微信开发者工具上。

                      进入微信公众平台后台

                      开通腾讯云

                      腾讯云微信小程序控制台

                      安装开发工具


                      下载并安装最新版本的 微信开发者工具 ,使用小程序绑定的微信号扫码登录开发者工具。

                      微信开发者工具

                      导入 NodeJS DEMO 和配置



                      1. 打开第二步安装的微信开发者工具,点击【小程序项目】按钮。

                      2. 输入小程序 AppID,项目目录选择一个 空的目录 ,接着选择【建立腾讯云 Node.js 启动模板】,点击确定创建小程序项目。

                      微信开发者工具


                      3. 安装依赖

                      为方便本地调试,建议您在本地安装依赖。你也可以跳过这步直接使用开发者工具的“腾讯云”菜单中的“安装依赖”直接在线上安装依赖。

                      在您刚刚选择的目录打开 CMD 安装依赖:


                      1. cd server && npm install

                        安装依赖

                      4. 点击界面右上角的【腾讯云】图标,在下拉的菜单栏中选择【上传测试代码】。 


                        上传按钮

                        5. 首次使用推荐使用,选择【模块上传】并勾选全部选项,然后勾选【部署后自动安装依赖】,点击【确定】开始上传代码。后续修改服务端代码后,推荐选择智能上传,工具仅仅上传有修改过的代码。

                        选择模块

                        上传成功

                        6. 上传代码完成之后,点击右上角的【详情】按钮,接着选择【腾讯云状态】即可看到腾讯云自动分配给你的开发环境域名:

                        查看开发域名

                        7. 如果当前小程序是首次使用腾讯云小程序服务,需要完整复制(包括 https://)开发环境 request 域名,然后在编辑器中打开 client/config.js 文件,将复制的域名填入 host 中并保存,保存之后编辑器会自动编译小程序,左边的模拟器窗口即可实时显示出客户端的 Demo:

                             修改客户端配置    

                        8. 在模拟器中点击【登录】,看到显示“登录成功”,即为开通完成,可以开始你的其他开发了。

                        登录测试

                          导入 PHP DEMO 和配置


                          1. 打开第二步安装的微信开发者工具,点击【小程序项目】按钮。

                            tips:需要注意的是,如果当前小程序已经开通了 NodeJS 环境,需要点击工具右上角详情按钮,选择腾讯云状态,点击切换语言

                            微信开发者工具

                            在腾讯云管理后台中可以选择切换语言环境

                            微信开发者工具

                          2. 输入小程序 AppID,项目目录选择一个空的目录,接着选择【建立腾讯云 PHP 启动模板】,点击确定创建小程序项目。

                            微信开发者工具

                          3. 再次点击【确定】进入开发者工具。

                                     开发者工具

                          4. 点击界面右上角的【腾讯云】图标,在下拉的菜单栏中选择【上传测试代码】。

                            上传按钮

                          5. 上传代码完成之后,点击右上角的【详情】按钮,接着选择【腾讯云状态】即可看到腾讯云自动分配给你的开发环境域名。

                            查看开发域名

                          6. 完整复制(包括 https://)开发环境 request 域名,然后在编辑器中打开 client/config.js 文件,将复制的域名填入 host 中并保存,保存之后编辑器会自动编译小程序,左边的模拟器窗口即可实时显示出客户端的 Demo。修改客户端配置     

                          7. 在模拟器中点击【登录】,看到显示“登录成功”,即为开通完成,可以开始你的其他开发了。

                            ```登录测试

                          其他具体开发文档


                          服务端、客户端的 Demo、SDK 的具体文档:


                          我们建议你先完整阅读该开发文档,这将有助于更快地完成开发。如果发现我们的文档有任何错漏,或者开发过程中有任何疑问,欢迎通过下列邮箱联系我们。

                          weixin_developer@qq.com

                          为方便定位原因,如果是开发过程中的问题,我们建议你提供更多信息,包括但不限于:

                          公司名称

                          mp账户

                          开发者微信号

                          机型

                          操作系统

                          是否必现

                          出现时间

                          操作路径

                          问题描述

                          问题截图

                          代码片段截图

                          不能直接操作 Page.data

                          避免在直接对 Page.data 进行赋值修改,请使用 Page.setData 进行操作才能将数据同步到页面中进行渲染

                          怎么获取用户输入


                          能够获取用户输入的组件,需要使用组件的属性bindchange将用户的输入内容同步到AppService

                          <input id="myInput" bindblur="bindBlur" />
                          var inputContent = {}Page({    data:{      inputContent: {}    },    bindChange:function(e){        inputContent[e.currentTarget.id] = e.detail.value    }})

                          为什么脚本内不能使用window对象


                          页面的脚本逻辑是在JsCore中运行,JsCore是一个没有窗口对象的环境,所以不能在脚本中使用window,也无法在脚本中操作组件

                          为什么zepto/jquery无法使用


                          zepto/jquery会使用到window对象和document对象,所以无法使用。

                          wx.navigateTo无法打开页面


                          一个应用同时只能打开5个页面,当已经打开了5个页面之后,wx.navigateTo不能正常打开新页面。请避免多层级的交互方式,或者使用wx.redirectTo

                          样式表不支持级联选择器


                          WXSS支持以.开始的类选择器。如:

                            .normal_view{    color: #000000;    padding: 10px;  }

                          可以使用标签选择器,控制同一类组件的样式。如:使用input标签选择器控制<input/>的默认样式。

                            input{    width: 100px;  }

                          本地资源无法通过WXSS获取


                          background-image:可以使用网络图片,或者base64,或者使用<image/>标签

                          如何修改窗口的背景色


                          使用page标签选择器,可以修改顶层节点的样式

                          page{  display:block;  min-height:100%;  background-color:red;}

                          HTTPS 请求不成功

                          1. tls 仅支持 1.2 及以上版本
                          2. 部分 Android 机型需要 tls1.0 或者 tls1.1,所以请确保服务器的 tls 版本为 1.0、1.1、1.2

                          网络请求的 referer

                          网络请求的 referer 是不可以设置的,格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中{appid}为小程序的 appid,{version}为小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本。

                          为什么 map 组件总是在最上层

                          mapcanvasvideotextarea是由客户端创建的原生组件,原生组件的层级是最高的,所以页面中的其他组件无论设置z-index为多少,都无法盖在原生组件上。 原生组件暂时还无法放在scroll-view上,也无法对原生组件设置css动画。



                          微信应用号(小程序)设计规范-稀土区

                          微信小程序设计的基本原则是微信设计中心针对在微信类上线的小程序页面总结的设计指南及建议。以下设计原则都是基于对用户的尊重的基础上的,旨在微信生态类建立友好、高效、一致的用户体验的同时,最大程度顺应和支持各业务需求设计,实现用户与程序的共赢。


                          概要

                          基于微信小程序轻快的特点,我们拟定了小程序界面设计指南和建议。 设计指南建立在充分尊重用户知情权与操作权的基础之上。旨在微信生态体系内,建立友好、高效、一致的用户体验,同时最大程度适应和支持不同需求,实现用户与小程序服务方的共赢。

                          一、友好礼貌 

                          为了避免用户在微信中使用小程序服务时,注意力被周围复杂环境干扰,小程序在设计时应该注意减少无关的设计元素对用户目标干扰,礼貌地向用户展示程序侧提供的服务,友好地引导用户进行操作。

                          1. 重点突出

                          每个页面都应有明确的重点,以便于用户每进入一个新页面的时候都能快速地理解页面内容,在确定了重点的前提下,应尽量避免页面上出现其他干扰项影响用户的决策和操作。

                          反例示意

                          此页面的主题是查询,却添加了诸多与查询不相关的业务入口,与用户的预期不符,易造成用户的迷失。

                          微信应用号(小程序)设计规范-稀土区

                          纠正示意

                          去掉任何与用户目标不相关的内容,明确页面主题,在技术和页面控件允许的前提下提供有助于用户目标的帮助内容,比如最近搜索词等。

                          1emphasis_do

                          反例示意

                          操作没有主次,让用户无从选择

                          微信应用号(小程序)设计规范-稀土区

                          纠正示意

                          首先要避免并列过多操作让用户选择,在不得不并列多个操作时,需区分操作主次,减轻用户的选择难度。

                          1emphasis_do2

                          2. 流程明确

                          为了让用户顺畅地使用页面,在用户进行某一个操作流程时,应避免出现用户目标流程之外的内容而打断用户。

                          反例示意

                          用户本打算进行搜索,在进入页面时却被突如其来的模态抽奖框所打断;对于抽奖没有兴趣的用户是非常不友好的干扰;而即便有部分用户确实被“诱人”的抽奖活动所吸引,离开主流程去抽奖之后可能就遗忘了原本的目标,进而失去了对产品真正价值的利用和认识。

                          微信应用号(小程序)设计规范-稀土区


                          二、清晰明确

                          一旦用户进入我们的小程序页面,就有责任和义务清晰明确告知用户身在何处、又可以往何处去,确保用户在页面中游刃有余地穿梭而不迷路,这样才能为用户提供安全的愉悦的使用体验。

                          1. 导航明确,来去自如

                          导航是确保用户在网页中浏览跳转时不迷路的最关键因素。导航需要告诉用户,当前在哪,可以去哪,如何回去等问题。首先在微信系统内的所有小程序的全部页面,均会自带微信提供的导航栏,统一解决当前在哪,如何回去的问题。在微信层级导航保持体验一致,有助于用户在微信内形成统一的体验和交互认知,无需在各小程序和其他微信页面的切换中新增学习成本或改变使用习惯。

                          微信导航栏

                          微信导航栏,直接继承于客户端,除导航栏颜色之外,开发者无需亦不可对其中的内容进行自定义。但开发者需要规定小程序各个页面的跳转关系,让导航系统能够以合理的方式工作。

                          微信导航栏分为导航区域、标题区域以及操作区域。其中导航区控制程序页面进程。目前导航栏分深浅两种基本配色。

                          导航区(iOS)

                          微信进入小程序的第一个页面,导航区通常只有一个操作——“返回”,即返回进入小程序前的微信页面。 进入小程序后的次级页面,导航区的操作为——“返回” 和“关闭”。 “返回”,即返回上一级小程序界面或微信界面。“关闭”,即在当前界面直接退出小程序,回到进入小程序前的微信页面。

                          3navigation_iOS


                          导航区(Android)

                          导航区仅存在唯一操作——直接退出小程序,回到进入小程序前的微信或系统桌面,安卓手机自带的硬件返回键执行返回上一级页面的操作。

                          3navigation_android

                          安卓导航存在一类特殊情况:当用户通过操作区的菜单将小程序添加至安卓桌面,并从安卓桌面打开小程序时,小程序的首页,不展示导航按钮。仅展示小程序标题和操作区。小程序次级页面,导航区只有返回上一级页面的操作,而点击安卓手机自带的硬件返回键也起到相同作用。

                          3navigation_android_special

                          微信导航栏自定义颜色规则(iOS和Android)

                          小程序导航栏支持基本的背景颜色自定义功能,选择的颜色需要在满足可用性前提下,和谐搭配微信提供的两套主导航栏图标。建议参考以下选色效果:

                          选色方案示例

                          微信应用号(小程序)设计规范-稀土区

                          页面内导航

                          开发者可根据自身功能合计需要在页面内添加自有导航。并保持不同页面间导航一致。但是受限于手机屏幕尺寸的限制,小程序页面的导航应尽量简单,若仅为一般线性浏览的页面建议仅使用微信导航栏即可。

                          开发者可选择小程序页面添加标签分页(Tab)导航。标签分页栏可固定在页面顶部或者底部,便于用户在不同的分页间做切换。标签数量不得少于2个,最多不得超过5个,为确保点击区域,建议标签数量不超过4项。一个页面也不应出现一组以上的标签分页栏。

                          其中小程序首页可选择微信提供的原生底部标签分页样式,该样式仅供小程序首页使用。开发时可自定义图标样式、标签文案以及文案颜色等,具体设置项如图标尺寸等参考可参考开发文档和WeUI基础控件库。

                          3navigation_page_bottom

                          顶部标签分页栏颜色可自定义。在自定义颜色选择中,务必注意保持分页栏标签的可用性、可视性和可操作性。

                          3navigation_page_top_dont


                          2. 减少等待,反馈及时

                          页面的过长时间的等待会引起用户的不良情绪,使用微信小程序项目提供的技术已能很大程度缩短等待时间。即便如此,当不可避免的出现了加载和等待的时候,需要予以及时的反馈以舒缓用户等待的不良情绪。

                          启动页加载

                          小程序启动页是小程序在微信内一定程度上展现品牌特征的页面之一。本页面将突出展示小程序品牌特征和加载状态。启动页除品牌标志(Logo)展示外,页面上的其他所有元素如加载进度指示,均由微信统一提供且不能更改,无需开发者开发。

                          4miniapploading

                          页面下拉刷新加载

                          在微信小程序内,微信提供标准的页面下拉刷新加载能力和样式,开发者无需自行开发。

                          4pull-to-refresh

                          页面内加载反馈

                          开发者可在小程序里自定义页面内容的加载样式。建议不管是使用在局部还是全局加载,自定义加载样式都应该尽可能简洁,并使用简单动画告知用户加载过程。开发者也可以使用微信提供的,统一的页面加载样式,如图中例所示。

                          微信应用号(小程序)设计规范-稀土区

                          模态加载

                          模态的加载样式将覆盖整个页面的,由于无法明确告知具体加载的位置或内容将可能引起用户的焦虑感,因此应谨慎使用。除了在某些全局性操作下不要使用模态的加载。

                          微信应用号(小程序)设计规范-稀土区

                          局部加载反馈

                          局部加载反馈即只在触发加载的页面局部进行反馈,这样的反馈机制更加有针对性,页面跳动小,是微信推荐的反馈方式。例如:

                          微信应用号(小程序)设计规范-稀土区

                          加载反馈注意事项

                          • 若载入时间较长,应提供取消操作,并使用进度条显示载入的进度。
                          • 载入过程中,应保持动画效果;无动画效果的加载很容易让人产生该界面已经卡死的错觉。
                          • 不要再同一个页面使用超过1个加载动画。

                          结果反馈

                          除了在用户等待的过程中需予以及时反馈外,对操作的结果也需要予以明确反馈。根据实际情况看,可选择不同的结果反馈样式。对于页面局部的操作,可在操作区域予以直接反馈,对于页面级操作结果,可使用弹出式提示(Toast)、模态对话框或结果页面展示。

                          页面局部操作结果反馈

                          对于页面局部的操作,可在操作区域予以直接反馈,例如点击多选控件前后如下图。对于常用控件,微信设计中心已提供控件库及WeUI控件库,其中的控件都已提供完整的操作反馈。

                          微信应用号(小程序)设计规范-稀土区

                          页面全局操作结果——弹出式提示(Toast)

                          弹出式提示(Toast)适用于轻量级的成功提示,1.5秒后自动消失,并不打断流程,对用户影响较小,适用于不需要强调的操作提醒,例如成功提示。特别注意该形式不适用于错误提示,因为错误提示需明确告知用户,因而不适合使用一闪而过的弹出式提示。

                          微信应用号(小程序)设计规范-稀土区

                          页面全局操作结果——模态对话框

                          对于需要用户明确知晓的操作结果状态可通过模态对话框来提示,并可附带下一步操作指引。

                          5global_popup

                          页面全局操作结果——结果页

                          对于操作结果已经是当前流程的终结的情况,可使用操作结果页来反馈。这种方式最为强烈和明确的告知用户操作已经完成,并可根据实际情况给出下一步操作的指引。

                          5global_result

                          3. 异常可控,有路可退

                          在设计任何的任务和流程时,异常状态和流程往往容易被忽略,而这些异常场景往往是用户最为沮丧和需要帮助的时候,因此需要格外注意异常状态的设计,在出现异常时予以用户必要的状态提示,并告知解决方案,使其有路可退。

                          要杜绝异常状态下,用户莫名其妙又无处可去,停滞在某一个页面的情况。上文中所提到的模态对话框和结果页面都可作为异常状态的提醒方式。除此之外,在表单页面中尤其是表单项较多的页面中,还应明确指出出错项目,以便用户修改。

                          异常状态——表单出错

                          表单报错,在表单顶部告知错误原因,并标识出错误字段提示用户修改。

                          6error

                          三、便捷优雅

                          从PC时代的物理键盘鼠标到移动端时代手指,虽然输入设备极大精简,但是手指操作的准确性却大大不如键盘鼠标精确。为了适应这个变化,需要开发者在设计过程中充分利用手机特性,让用户便捷优雅的操控界面。

                          1. 减少输入

                          由于手机键盘区域小且密集,输入困难的同时还易引起输入错误,因此在设计小程序页面时因尽量减少用户输入,利用现有接口或其他一些易于操作的选择控件来改善用户输入的体验。

                          例如下图中,在添加银行卡时,采用摄像头识别接口来帮助用户输入。除此之外微信团队还对外开放例如地理位置接口等多种微信小程序接口,充分利用这些接口将大大提高用户输入的效率和准确性,进而优化体验。

                          7less-input

                          除了利用接口外,在不得不让用户进行手动输入时,应尽量让用户做选择而不是键盘输入。一方面,回忆易于记忆,让用户在有限的选项中做选择通常来说是容易于完全靠记忆输入;另一方面,仍然是考虑到手机键盘密集的单键输入极易造成输入错误。例如图中,在用户搜索时提供搜索历史快捷选项将帮助用户快速进行搜索,而减少或避免不必要的键盘输入。

                          7less-input2

                          2. 避免误操作

                          因为在手机上我们通过手指触摸屏幕来操控界面,手指的点击精确度远不如鼠标,因此在设计页面上需点击的控件时,需要充分考虑到其热区面积,避免由于可点击区域过小或过于密集而造成误操作。当简单的将原本在电脑屏幕上使用的界面不做任何适配直接移植到手机上时,往往就容易出现这样的问题。由于手机屏幕分辨率各不相同,因此最适宜点击像素尺寸也不完全一致,但换算成物理尺寸后大致是在7mm-9mm之间。在微信提供的标准组件库中,各种控件元素均已考虑到了页面点击效果以及不同屏幕的适配,因此再次推荐使用或模仿标准控件尺寸进行设计。

                          3. 利用接口提升性能

                          微信设计中心已推出了一套网页标准控件库,包括 sketch设计控件库Photoshop设计控件库,后续还将完善小程序组件,这些控件都已充分考虑了移动端页面的特点,能够保证其在移动端页面上的可用性和操作性能; 同时微信开发团队也在不断完善和扩充微信小程序接口,并提供微信公共库,利用这些资源不但能够为用户提供更加快捷的服务,而且对页面性能的提高有极大作用,无形之中提升了用户体验。

                          四、统一稳定

                          除了以上所提到的种种原则,建议接入微信的小程序还应该时刻注意不同页面间的统一性和延续性,在不同的页面尽量使用一致的控件和交互方式。

                          统一的页面体验和有延续性的界面元素都将帮助用最少的学习成本达成使用目标,减轻页面跳动所造成的不适感。正因如此,小程序可根据需要使用微信提供的标准控件,以达到统一稳定的目的。

                          五、视觉规范

                          1. 字体规范

                          微信内字体的使用与所运行的系统字体保持一致,常用字号为20,18,17,16,14,13,11(pt),使用场景具体如下:

                          8Font

                          字体颜色

                          微信应用号(小程序)设计规范-稀土区

                          主内容Black黑色,次要内容Grey灰色;时间戳与表单缺省值Light灰色;大段的说明内容而且属于主要内容用Semi黑;

                          微信应用号(小程序)设计规范-稀土区

                          蓝色为链接用色,绿色为完成字样颜色,红色为出错用色Press与Disable状态分别降低透明度为20%与10%;

                          微信应用号(小程序)设计规范-稀土区

                          2. 列表视觉规范

                          微信应用号(小程序)设计规范-稀土区

                          3. 表单输入视觉规范

                          微信应用号(小程序)设计规范-稀土区

                          4. 按钮使用原则



                          11button3

                          11button4

                          5. 图标使用原则

                          微信应用号(小程序)设计规范-稀土区

                          资源下载

                          为方便设计师进行设计,微信提供一套可供Web设计和小程序使用的基础控件库;同时提供方便开发者调用的资源。

                          预览地址:https://weui.io


                          微信小程序开发目前可以说是非常火热的,很多小伙伴都在学习这方面的知识。本文将为大家带来众多微信小程序的实例源码,小伙伴们可以根据源码来进行进一步学习。


                          源码使用方法:

                          1、克隆项目代码到本地(git应该都要会哈,现在源码几乎都会放github上,会git才方便,不会的可以自学一下哦,不会的也没关系,gitHub上也提供直接下载的链接)

                          2、打开微信开发者工具;

                          3、添加项目->选择本项目目录->编译执行;


                          微信小程序源码:

                          微信小应用示例代码(phodal/weapp-quick)

                          源码链接:https://github.com/phodal/weapp-quick


                          微信小应用地图定位demo(giscafer/wechat-weapp-mapdemo)

                          源码链接:https://github.com/giscafer/wechat-weapp-mapdemo


                          微信小应用- 掘金主页信息流(hilongjw/weapp-gold)

                          源码链接:https://github.com/hilongjw/weapp-gold


                          微信小程序(应用号)示例:微信小程序豆瓣电影(zce/weapp-demo)

                          源码链接:https://github.com/zce/weapp-demo


                          微信小程序-豆瓣电影(hingsir/weapp-douban-film)

                          源码链接:https://github.com/hingsir/weapp-douban-film


                          小程序 hello world 尝鲜(kunkun12/weapp)

                          源码链接:https://github.com/kunkun12/weapp


                          使用微信小程序开发2048游戏(sammffl/wechat-weapp-2048)

                          源码链接:https://github.com/sammffl/wechat-weapp-2048


                          微信小程序-微票(wangmingjob/weapp-weipiao)

                          源码链接:https://github.com/wangmingjob/weapp-weipiao


                          微信小程序购物车DEMO(SeptemberMaples/wechat-weapp-demo)

                          源码链接:https://github.com/SeptemberMaples/wechat-weapp-demo


                          微信小程序V2EX(jectychen/wechat-v2ex)

                          源码链接:https://github.com/jectychen/wechat-v2ex


                          微信小程序-知乎日报(myronliu347/wechat-app-zhihudaily)

                          源码链接:https://github.com/myronliu347/wechat-app-zhihudaily


                          微信小程序-公众号热门文章信息流(hijiangtao/weapp-newsapp)

                          源码链接:https://github.com/hijiangtao/weapp-newsapp


                          微信小程序版Gank客户端  

                          源码链接:https://github.com/lypeer/wechat-weapp-gank


                          微信小程序集成Redux实现的Todo list  

                          源码链接:https://github.com/charleyw/wechat-weapp-redux-todos


                          微信小程序-番茄时钟  

                          源码链接:https://github.com/kraaas/timer


                          微信小程序版聊天室  

                          源码链接: https://github.com/ericzyh/wechat-chat


                          微信小程序-HiApp  

                          源码链接: https://github.com/BelinChung/wxapp-hiapp


                          小程序Redux绑定库  

                          源码链接: https://github.com/charleyw/wechat-weapp-redux


                          微信小程序版微信

                          源码链接:  https://github.com/18380435477/WeApp


                          小程序开发从布局开始

                          源码链接:  https://github.com/hardog/wechat-app-flexlayout


                          微信小程序-音乐播放器 

                          源码链接: https://github.com/eyasliu/wechat-app-music


                          微信小程序-简易计算器-适合入门

                          源码链接: https://github.com/dunizb/wxapp-sCalc


                          微信小程序-github 

                          源码链接:  https://github.com/zhengxiaowai/weapp-github


                          微信小程序-小熊の日记 

                          源码链接:  https://github.com/harveyqing/BearDiary


                          微信小程序

                          源码链接: https://github.com/SeaHub/PigRaising


                          微信小程序(WeChatMeiZhi妹子图)

                          源码链接:https://github.com/brucevanfdm/WeChatMeiZhi


                          以上就是W3Cschool为大家整理的微信小程序实例代码,希望能对各位小伙伴们学习微信小程序开发能够有所帮助。

                          目录结构

                          小程序包含一个描述整体程序的 app 和多个描述各自页面的 page。

                          一个小程序主体部分由三个文件组成,必须放在项目的根目录,如下:

                          文件必需作用
                          app.js小程序逻辑
                          app.json小程序公共配置
                          app.wxss小程序公共样式表

                          一个小程序页面由四个文件组成,分别是:

                          文件类型必需作用
                          js页面逻辑
                          wxml页面结构
                          json页面配置
                          wxss页面样式表

                          注意:为了方便开发者减少配置项,描述页面的四个文件必须具有相同的路径与文件名。

                          允许上传的文件

                          在项目目录中,以下文件会经过编译,因此上传之后无法直接访问到:.js、app.json、.wxml、*.wxss(其中 wxml 和 wxss 文件仅针对在 app.json 中配置了的页面)。除此之外,只有后缀名在白名单内的文件可以被上传,不在白名单列表内文件在开发工具能被访问到,但无法被上传。具体白名单列表如下:

                          1. wxs
                          2. png
                          3. jpg
                          4. jpeg
                          5. gif
                          6. svg
                          7. json
                          8. cer
                          9. mp3
                          10. aac
                          11. m4a
                          12. mp4
                          13. wav
                          14. ogg
                          15. silk


                          虽然微信小程序开发需要使用微信专门的开发者工具,但很多时候我们会使用VSCode辅助进行开发。因为VSCode的插件生态丰富,也可以方便使用npm等js包管理工具。这也给我们使用AI提供了机会——VSCode有通义灵码插件,可以让AI辅助开发!

                          通义灵码简介

                          通义灵码是由阿里云技术团队打造的智能编码助手。它基于通义大模型,能够提供:

                          • 代码续写和优化

                          • 自然语言描述生成代码

                          • 注释生成和代码解释

                          • 单元测试生成

                          • 研发智能问答

                          • 代码问题修复等功能。

                          通义灵码官网:https://tongyi.aliyun.com/lingma/

                          通义灵码支持:JetBrains IDEs、Visual StudioCode、Visual Studio,及远程开发场景(Remote SSH、Docker、WSL、Web IDE),安装后登录账号即可开始使用。

                          安装指南

                          请确保你已经安装了VSCode,本文不再赘述安装过程(详见:Visual Studio Code入门)。 VSCode三端的插件安装方式基本一致,本文以Windows为例,介绍如何在VSCode中安装通义灵码插件。 对于VSCode而言,通义灵码的使用非常简单,只需要在VSCode中安装插件即可。在VSCode中打开插件市场,搜索“​TONGYI Lingma​”即可找到插件,点击安装即可。 
                          安装完成后VSCode的左侧会多出一个通义灵码的图标,点击即可进入插件界面。

                          点击立即登录,同意用户协议,会跳转到登录页面。



                          通义灵码支持多种登录方式,包括账号密码登录、手机号登录、支付宝、阿里云、淘宝、钉钉登录。


                          登录后即可使用通义灵码的各项功能。

                          功能演示

                          代码续写

                          通义灵码提供了行级和函数级的代码补全功能。当你在 IDE 编辑器区进行代码编写时,在开启自动云端生成的模式下,通义灵码会根据当前代码文件及相关代码文件的上下文,自动为你生成行级/函数级的代码建议,此时你可以使用快捷键采纳、废弃,或查看不同的代码建议。

                          同时,当你在编码的过程中,也可以通过快捷键 ​alt+​P​ 手动触发生成代码建议。

                          开发小提示:为了让代码补全功能更贴近我们想要的结果,我们可以先写代码注释描述其功能。例如上图所示

                          通义灵码提供了一组快捷键使用方式,可以更好的进行代码续写的控制:

                          操作macOSWindows
                          接受行间代码建议TabTab
                          废弃行间代码建议escesc
                          查看上一个行间推荐结果⌥(option) + [Alt+[
                          查看下一个行间推荐结果⌥(option)+]Alt+]
                          手动触发行间代码建议⌥(option)+PAlt+P

                          在一些文件中可能不需要代码续写功能,可以参考禁用行间生成。关闭对某类文件的代码续写功能

                          智能问答

                          通义灵码提供了智能问答功能,它可以对你的问题做出回答,你也可以让他进行代码创作。

                          基于智能问答,还能实现很多有用的功能,比如后续的代码注释,代码解释,单元测试生成和代码优化,都是基于基于智能问答实现的。

                          会话创建和清理

                          智能问答是一个持续对话的过程,你可以持续进行提问,但大模型也会因此记录你之前的提问信息,可能会影响后续的回答,为了提高AI生成答案的质量,应该适时清理会话。

                          清理会话可以通过创建一个新会话或者清理来实现:

                          • 清理会话:在对话框中输入/clearContext,然后点击确定即可。

                          • 创建新会话:在智能问答的右上角有一个圆形 ​+​ 号按钮,点击即可创建新对话。

                          代码小技巧

                          通义灵码生成的代码一般都会在右上角有这四个小按钮,分别对应着插入、复制、新建和合并的功能,后续的功能会用到这些小技巧。

                          • 插入 :会把 AI 生成的代码替换到我们选中的代码位置,一般在代码注释和代码优化中应用。

                          • 复制 :则是复制 AI 生成的代码,我们可以自己选择插入的位置。

                          • 新建 :则是新建一个文件,把 AI 生成的代码放进去,一般而言生成测试代码会选择新建一个文件夹存放。

                          • 合并 :则是把代码黏贴到文件中,比如黏贴到选中的代码后,一般我们在智能问答中得到我们需要的代码可以用合并。

                          代码注释

                          通义灵码提供了代码注释功能,它可以根据你的代码生成对应的注释,方便代码阅读和维护。

                          也可以用快捷键shift+alt+V,或者右键菜单中也有代码注释功能。

                          代码解释

                          代码解释与代码注释不同,注释是为了让代码更易读,而代码解释是告诉你代码为什么这么写。 与代码注释相同,选中代码后,点击通义灵码的代码解释按钮,通义灵码会根据你的代码生成对应的解释。 

                          单元测试生成

                          通义灵码可以根据我们的代码,设计对应的测试用例。

                          通义灵码甚至还能贴心地生成对应的测试代码:

                          测试用例代码一般是复制后到一个专门的测试用例文件中,方便后续测试。也可以用新建文件,通义灵码会再帮你创建一个测试用例文件。

                          代码优化

                          代码开发很难做到面面俱到,单人开发往往容易疏漏。传统开发为了避免这种因个人主观原因导致的代码疏漏,会定期组织代码评审,或者让开发者结对编程,互相审核对方的代码。现在有了通义灵码,提供了一种新的方向:使用AI进行代码审查和优化.

                          AI不仅能给出审查结果,提供优化思路,甚至还能给出优化的代码:

                          代码优化一般使用合并(diff)操作来把原代码替换成优化后的代码。

                          AI程序员

                          智能问答往往基于单个文件或者部分代码片段,而通义灵码提供了AI程序员的功能,它基于整个项目,有些时候实现某个功能需要多个代码文件一起修改,AI程序员就能轻松胜任!

                              

                          可以看见ai帮你生成了一些代码,但最后你还得自行选择是否接受他生成的代码,最终决定权还在你自己。


                          框架

                          小程序开发框架的目标是通过尽可能简单、高效的方式让开发者可以在微信中开发具有原生 APP 体验的服务。

                          整个小程序框架系统分为两部分:逻辑层(App Service)和 视图层(View)。小程序提供了自己的视图层描述语言 WXML 和 WXSS,以及基于 JavaScript 的逻辑层框架,并在视图层与逻辑层间提供了数据传输和事件系统,让开发者能够专注于数据与逻辑。

                          响应的数据绑定

                          框架的核心是一个响应的数据绑定系统,可以让数据与视图非常简单地保持同步。当做数据修改的时候,只需要在逻辑层修改数据,视图层就会做相应的更新。

                          通过这个简单的例子来看:

                          在开发者工具中预览效果

                          <!-- 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: 'Weixin'}// Register a Page.Page({  data: helloData,  changeName: function(e) {    // sent data change to view    this.setData({      name: 'MINA'    })  }})
                          • 开发者通过框架将逻辑层数据中的 name 与视图层的 name 进行了绑定,所以在页面一打开的时候会显示 Hello Weixin!;
                          • 当点击按钮的时候,视图层会发送 changeName 的事件给逻辑层,逻辑层找到并执行对应的事件处理函数;
                          • 回调函数触发后,逻辑层执行 setData 的操作,将 data 中的 name 从 Weixin 变为 MINA,因为该数据和视图层已经绑定了,从而视图层会自动改变为 Hello MINA!。

                          页面管理

                          框架 管理了整个小程序的页面路由,可以做到页面间的无缝切换,并给以页面完整的生命周期。开发者需要做的只是将页面的数据、方法、生命周期函数注册到 框架 中,其他的一切复杂的操作都交由 框架 处理。

                          基础组件

                          框架 提供了一套基础的组件,这些组件自带微信风格的样式以及特殊的逻辑,开发者可以通过组合基础组件,创建出强大的微信小程序 。

                          丰富的 API

                          框架 提供丰富的微信原生 API,可以方便的调起微信提供的能力,如获取用户信息,本地存储,支付功能等。


                          自定义组件

                          从小程序基础库版本 1.6.3 开始,小程序支持简洁的组件化编程。所有自定义组件相关特性都需要基础库版本 1.6.3 或更高。

                          开发者可以将页面内的功能模块抽象成自定义组件,以便在不同的页面中重复使用;也可以将复杂的页面拆分成多个低耦合的模块,有助于代码维护。自定义组件在使用时与基础组件非常相似。

                          创建自定义组件

                          类似于页面,一个自定义组件由 json wxml wxss js 4个文件组成。要编写一个自定义组件,首先需要在 json 文件中进行自定义组件声明(将 component 字段设为 true 可将这一组文件设为自定义组件):

                          {  "component": true}

                          同时,还要在 wxml 文件中编写组件模板,在 wxss 文件中加入组件样式,它们的写法与页面的写法类似。具体细节和注意事项参见 组件模板和样式 。

                          代码示例:

                          <!-- 这是自定义组件的内部WXML结构 --><view class="inner">  {{innerText}}</view><slot></slot>
                          /* 这里的样式只应用于这个自定义组件 */.inner {  color: red;}

                          注意:在组件wxss中不应使用ID选择器、属性选择器和标签名选择器。

                          在自定义组件的 js 文件中,需要使用 Component() 来注册组件,并提供组件的属性定义、内部数据和自定义方法。

                          组件的属性值和内部数据将被用于组件 wxml 的渲染,其中,属性值是可由组件外部传入的。更多细节参见 Component构造器 。

                          代码示例:

                          Component({  properties: {    // 这里定义了innerText属性,属性值可以在组件使用时指定    innerText: {      type: String,      value: 'default value',    }  },  data: {    // 这里是一些组件内部数据    someData: {}  },  methods: {    // 这里是一个自定义方法    customMethod: function(){}  }})

                          使用自定义组件

                          使用已注册的自定义组件前,首先要在页面的 json 文件中进行引用声明。此时需要提供每个自定义组件的标签名和对应的自定义组件文件路径:

                          {  "usingComponents": {    "component-tag-name": "path/to/the/custom/component"  }}

                          这样,在页面的 wxml 中就可以像使用基础组件一样使用自定义组件。节点名即自定义组件的标签名,节点属性即传递给组件的属性值。

                          开发者工具 1.02.1810190 及以上版本支持在 app.json 中声明 usingComponents 字段,在此处声明的自定义组件视为全局自定义组件,在小程序内的页面或自定义组件中可以直接使用而无需再声明。

                          代码示例:

                          在开发者工具中预览效果

                          <view>  <!-- 以下是对一个自定义组件的引用 -->  <component-tag-name inner-text="Some text"></component-tag-name></view>

                          自定义组件的 wxml 节点结构在与数据结合之后,将被插入到引用位置内。

                          注意事项

                          一些需要注意的细节:

                          • 因为 WXML 节点标签名只能是小写字母、中划线和下划线的组合,所以自定义组件的标签名也只能包含这些字符。
                          • 自定义组件也是可以引用自定义组件的,引用方法类似于页面引用自定义组件的方式(使用 usingComponents 字段)。
                          • 自定义组件和页面所在项目根目录名不能以“wx-”为前缀,否则会报错。

                          注意,是否在页面文件中使用 usingComponents 会使得页面的 this 对象的原型稍有差异,包括:

                          • 使用 usingComponents 页面的原型与不使用时不一致,即 Object.getPrototypeOf(this) 结果不同。
                          • 使用 usingComponents 时会多一些方法,如 selectComponent 。
                          • 出于性能考虑,使用 usingComponents 时, setData 内容不会被直接深复制,即 this.setData({ field: obj }) 后 this.data.field === obj 。(深复制会在这个值被组件间传递时发生。)

                          如果页面比较复杂,新增或删除 usingComponents 定义段时建议重新测试一下。


                          插件

                          插件的开发和使用自小程序基础库版本 1.9.6 开始支持。(如果插件包含页面,则需要基础库版本 2.1.0 。)

                          插件是对一组 js 接口、自定义组件 或页面的封装,用于嵌入到小程序中使用。插件不能独立运行,必须嵌入在其他小程序中才能被用户使用;而第三方小程序在使用插件时,也无法看到插件的代码。因此,插件适合用来封装自己的功能或服务,提供给第三方小程序进行展示和使用。

                          插件开发者可以像开发小程序一样编写一个插件并上传代码,在插件发布之后,其他小程序方可调用。小程序平台会托管插件代码,其他小程序调用时,上传的插件代码会随小程序一起下载运行。

                          相对于普通 js 文件或自定义组件,插件拥有更强的独立性,拥有独立的 API 接口、域名列表等,但同时会受到一些限制,如 一些 API 无法调用或功能受限。还有个别特殊的接口,虽然插件不能直接调用,但可以使用 插件功能页 来间接实现。

                          同时,框架会对小程序和小程序使用的每个插件进行数据安全保护,保证它们之间不能窃取其他任何一方的数据(除非数据被主动传递给另一方)。

                          对于插件开发者,请阅读 开发插件 章节;对于插件使用者,请阅读 使用插件 章节。


                          小程序插件功能介绍

                          插件,是可被添加到小程序内直接使用的功能组件。开发者可以像开发小程序一样开发一个插件,供其他小程序使用。同时,小程序开发者可直接在小程序内使用插件,无需重复开发,为用户提供更丰富的服务。

                          如需开发插件,请阅读开发插件部分;如需使用插件,请阅读使用插件部分。

                          开发插件

                          开放范围及服务类目

                          开放范围:企业、媒体、政府及其他组织主体

                          开发者可选择当前小程序账号已选类目中的一个,作为插件的服务类目。以下为当前已开放的插件服务类目,将逐步开放更多类目。

                          一级类目二级类目特殊说明
                          物流服务邮政、装卸搬运、收件/派件、快递柜、查件、仓储服务、货物运输
                          教育服务婴幼儿教育、学历教育(培训机构)、学历教育(学校)、素质教育、教育平台、驾校培训、特殊人群教育、出国留学、教育装备
                          医疗服务就医服务、互联网医院仅医疗类小程序可使用
                          政务民生交通违法、博物馆、出入境、邮政、交管、城市道路、税务、司法、气象、户政、治安、环保、民政、教育、水电、市场监督管理、体育/福利彩票、检验检疫、交通、商务、航空、街道居委、农林畜牧海洋、社科档案、应急、科学技术与地质、统计、经济发展与改革、政务服务大厅、医疗、体育、水利、信访、城管、监狱戒毒、海关、住建、人力资源、文化、社保、政务民生、边防、国安、公证、检察、法院、纪检审计、财政、公积金、党/团/组织、食品监督管理、新闻出版及广电、知识产权、烟草管理、网信
                          金融业征信业务、保险、银行、公募基金、证券/期货、证券/期货投资咨询需在插件页面展示服务提供方,如:当前服务由xxx提供
                          交通服务公交/地铁、长途汽车、停车服务、代驾服务、租车、顺风车/拼车、加油站服务、骑车、高速服务、网约车、航空、火车/高铁/动车、导航地图、水运、充电服务
                          房地产服务物业管理、房屋中介、房屋装修
                          生活服务生活缴费、家政服务、丽人服务、宠物(非医院类)、婚庆服务、休闲娱乐、百货/超市/便利店、求职/招聘
                          餐饮服务餐厅排队、点餐平台、外卖平台、餐饮服务场所/餐饮服务管理企业
                          旅游服务签证办理、景区服务、旅游退税、住宿服务、出境WiFi、旅游管理单位
                          文娱其他视频、电台、小说1.此类目插件首次提交代码审核,需经当地互联网主管机关审核确认,预计审核时长7天左右;
                          2.视频类目插件仅限非个人主体小程序使用;
                          3.插件暂未开放文娱-视频广场类目;
                          4.接入使用视频类目插件的小程序开发者,应当遵循小程序使用“视频类插件”的相关规范
                          文娱音乐、有声读物、动漫
                          工具记账、投票、日历、天气、备忘录、办公、计算器、网络代理、健康管理、报价/比价、发票查询、预约/报名、图片处理、信息查询
                          商家自营服装内衣、鞋靴、箱包皮具、海淘、母婴用品、玩具、3C数码、家用电器、美妆、个护家清、珠宝玉石、时尚首饰、眼镜、钟表、运动户外、乐器、园艺/鲜花、工艺品、家居家纺、办公/文具、农资、宠物食品/用品、家装/五金/建材、机械电子产品、食品饮料
                          电商平台电商平台
                          it科技基础电信运营商、电信业务代理商仅限已有【it科技-基础电信运营商】或【it科技-电信业务代理商】类目小程序使用
                          社交笔记、问答、社区/论坛、陌生人交友1. 插件首次提交代码审核,需经当地互联网主管机关审核确认,预计审核时长7天左右。
                          2. 此类目下插件仅限社交类目小程序使用。
                          社交直播1. 插件首次提交代码审核,需经当地互联网主管机关审核确认,预计审核时长7天左右。
                          2. 直播插件仅限电商平台、部分教育类目小程序使用
                          商业服务法律服务平台、会展服务、广告/设计、公关/推广/市场调查、一般财务服务、企业管理、环保回收/废品回收、摄影/扩印、软件/建站/技术开发、出国移民
                          体育体育场馆服务、体育培训、在线健身
                          汽车服务汽车经销商/4S店、汽车厂商、维修保养、汽车报价/比价、汽车用品

                          插件开发接入流程

                          以下为插件开发接入流程:

                          1. 开通插件功能
                          2. 填写开发信息并开发
                          3. 完善基本信息
                          4. 提交审核、发布
                          5. 管理插件使用申请

                          开通插件功能

                          小程序开发者无需重新注册账号,可直接在小程序管理后台开通插件功能,完成基本信息填写后完成开通。

                          开通入口:小程序管理后台-小程序插件

                          填写插件基本信息,插件的基本信息将在插件申请流程、小程序基本信息页中展示。

                          填写开发信息并完成开发

                          设置插件的服务器域名及Token信息后,即可在开发者工具中开发插件。

                          开发者工具内设置请见:《插件开发指南》

                          完善基本信息

                          插件在提交审核前,请确认已设置插件名称、插件头像、插件简介等信息,并已上传插件开发文档,便于开发者接入插件。

                          基本信息完善

                          登录小程序管理后台-小程序插件-基本设置,确认名称、头像、简介、添加方式、客服联系方式等信息都已完备。

                          插件开发文档编辑、上传

                          为便于小程序开发者快速接入插件服务,插件开发者可上传、发布插件开发文档,供接入方查看。

                          (1)编辑

                          除了插件代码本身,小程序开发者可以另外上传一份插件开发文档。这份文档必须放置在插件项目根目录中的 doc 目录下,目录结构如下:

                          doc├── README.md   // 插件文档,应为 markdown 格式└── picture.jpg // 其他资源文件,仅支持图片

                          其中,引用到的图片资源不能是网络图片,必须放在这个目录下。

                          (2)上传

                          编辑 README.md 之后,可以使用开发者工具预览插件文档和单独上传插件文档。

                          上传入口位置:README.md文档右下角

                          (3)发布

                          在开发者工具中上传文档之后,文档不会立刻发布。此时可以使用账号和密码登录 插件管理后台 ,在 小程序插件 > 基本设置 中预览、发布插件文档。

                          文档发布后,可多次更新修改。

                          插件版本管理

                          开发者可在开发者工具内上传代码并在小程序插件开发助手内完成插件的开发和调试。请注意:插件暂不支持在体验版中体验

                          在开发者工具上传代码后,开发者可”小程序管理后台-小程序插件-开发管理“内管理插件版本。

                          插件发布前需要提交微信小程序团队审核,审核通过后才可发布。

                          提交审核时,插件开发者需要填写以下信息:插件服务类目、标签、预览图及功能描述。

                          插件服务类目:插件可从当前小程序已通过的服务类目中选择一个。已开放类目表格见插件开放范围及类目

                          标签:请填写与插件提供的服务相关的标签。

                          预览图:可上传插件的预览图,发布后将展示在插件详情页帮助用户提前了解插件功能

                          功能描述:为便于审核团队体验及审核插件功能,请开发者填写基本介绍及插件的使用说明。

                          使用申请管理

                          开发者可在”小程序管理后台-小程序插件-申请管理“内处理插件的接入申请。插件开发者可在24小时内选择”通过“或”拒绝“申请方使用插件。

                          插件支付功能简介

                          插件内可使用支付能力,帮助插件开发者完成服务闭环。

                          以下为接入流程

                          (1)插件所在小程序开通微信支付能力,查看小程序开通微信支付指南

                          (2)根据使用场景,参照下表选择合适的支付模式

                          支付模式适用范围典型使用场景接入流程
                          服务商插件内涉及为入驻商家提供商品销售、代收款等服务,即销售的商品不是插件开发者提供的。电商平台为入驻商户提供货架、购物车等服务;餐饮平台为线下入驻商户提供点餐、买单服务1. 申请成为微信支付服务商,查看《微信支付服务商功能介绍》《微信支付服务商接入指引》
                          2. 为商户创建子商户号
                          3. 绑定子商户号及插件所在的小程序账号,查看“服务商商户号与AppID账号关联管理” 指引
                          4. 在插件内使用子商户号发起支付

                          (3)在插件管理后台提交插件支付能力申请,审核通过后将可在插件内使用微信支付能力

                          使用插件

                          小程序开发者可便捷地把插件添加到自己的小程序内,丰富小程序的服务。当用户在使用小程序时,将可以在小程序内使用插件提供的服务。

                          开放范围

                          所有小程序。小程序使用的插件,其插件类目不能超过小程序主体类型当前开放的范围,具体见开放的服务类目表

                          接入流程

                          1. 在小程序管理后台添加插件小程序开发者可在“小程序管理后台-设置-第三方服务-插件管理”中查找需要的插件,并申请使用。插件开发者在24小时内通过后,小程序开发者可在小程序内使用该插件。
                          2. 在小程序代码中使用插件详见《插件开发文档》


                          扫普通链接二维码打开小程序

                          为了方便小程序开发者更便捷地推广小程序,兼容线下已有的二维码,微信公众平台开放扫描普通链接二维码跳转小程序能力。

                          功能介绍

                          普通链接二维码,是指开发者使用工具对网页链接进行编码后生成的二维码。

                          线下商户可不需更换线下二维码,在小程序后台完成配置后,即可在用户扫描普通链接二维码时打开小程序,使用小程序的功能。

                          对于普通链接二维码,目前支持使用微信“扫一扫”或微信内长按识别二维码跳转小程序。

                          开放范围

                          企业、媒体、政府及其他组织类型小程序。

                          二维码跳转规则

                          注意:从2017年5月开始,微信客户端支持二维码规则根据“子路径匹配”。如原有二维码链接为 http://www.qq.com/a/123456 ,其中123456为业务参数,则可配置规则 http://www.qq.com/a/ 实现扫码打开小程序。

                          微信客户端扫码将按以下匹配规则控制跳转:

                          1. 二维码链接的协议、域名与已配置的二维码规则一致。
                          2. 二维码链接属于后台配置的二维码规则的子路径。(如需支持子路径匹配,请确认后台配置的二维码规则以/结尾)
                          3. 如果二维码规则包含参数,链接?后为参数部分,参数要求前缀匹配。

                          常见匹配错误类型:

                          后台已配置的二维码规则线下二维码完整链接错误原因
                          http://www.qq.com/a/bhttps://www.qq.com/a/b协议不一致
                          https://www.qq.com/a/bhttps://www.weixin.qq.com/a/b域名不一
                          https://www.qq.com/a/b?id=123https://www.qq.com/a/b?id=132参数不满足前缀匹配
                          https://www.qq.com/a/bhttps://www.qq.com/a/bc不属于子路径
                          https://www.qq.com/a/bhttps://www.qq.com/a/b/123规则没有以/结尾,不支持子路径匹配
                          https://www.qq.com/a/(已发布)
                          https://www.qq.com/a/b(未发布)
                          https://www.qq.com/a/b命中未发布规则不会跳转小程序

                          二维码内容获取

                          在小程序后台配置二维码跳转小程序规则之后即可使用微信(6.5.6及其以上客户端版本)扫码打开小程序。

                          二维码链接内容会以参数 q 的形式带给页面,在onLoad事件中提取 q 参数并自行 decodeURIComponent 一次(对于小游戏可使用 wx.getEnterOptionsSync 接口获取),即可获取原二维码的完整内容。同时会附加一个参数 scancode_time(UNIX 时间戳,单位秒),表示用户扫码的时间。

                          Page({  onLoad(query) {    const q = decodeURIComponent(query.q) // 获取到二维码原始链接内容    const scancode_time = parseInt(query.scancode_time) // 获取用户扫码时间 UNIX 时间戳  }})

                          配置流程

                          登录小程序后台,进入“开发管理-开发设置-扫普通链接二维码打开小程序”,开启功能后即可配置二维码规则。

                          二维码规则

                          根据二维码跳转规则,开发者需要填写需要跳转小程序的二维码规则。要求如下:

                          1. 二维码规则的域名须通过ICP备案的验证。
                          2. 支持http、https开头的链接(如:http://wx.qq.com、https://wx.qq.com/mp/、https://wx.qq.com/mp?id=123)。
                          3. 部分账号支持hlht开头的链接,且根据协议规则,hlht链接的参数在中间,以运营商ID结尾。(如:http://******.运营商ID)
                          4. 一个小程序账号可配置不多于100个二维码前缀规则。

                          前缀占用规则

                          开发者可选择是否占用符合二维码匹配规则的所有子规则。如选择占用,则其他账号不可申请使用满足该前缀匹配规则的其他子规则。

                          如:若开发者A配置二维码规则:https://wx.qq.com/mp?id=123,并选择“占用所有子规则“,其他开发者将不可以配置满足前缀匹配的子规则如https://wx.qq.com/mp?id=1234。

                          如提示“此规则已被占用”,请联系对应小程序开发者沟通解决。

                          校验文件

                          下载随机校验文件,并将文件上传至服务器指定位置的目录下,方可通过所属权校验。

                          验证文件放置规则: 放置于URL中声明的最后一级子目录下,若无子目录,则放置于host所属服务器的顶层目录下。请根据页面提示将验证文件放置在指定的目录下。

                          小程序功能页面

                          配置扫描二维码后打开的小程序功能页面路径,如:pages/index/index。

                          测试调试

                          开发者可对已配置的二维码规则进行测试和调试。

                          测试仅对指定的测试链接和测试范围内的微信用户生效,其他用户扫码后跳转网页,不影响全网用户正常使用。在二维码规则发布后,开发者仍然可以选择在指定版本(开发版/体验版/线上版本)下测试,请注意扫码用户要打开开发版必须提交过代码。

                          测试范围

                          开发者可根据开发进度选择在开发版/体验版/线上版本测试“普通二维码跳转小程序”的功能。

                          测试链接

                          填写符合二维码前缀匹配规则的二维码完整链接用于测试,如包括参数,请完整填写。

                          一个规则可以填写不多于5个测试链接,可多次修改。若二维码与测试链接匹配,且用户微信号是小程序指定的管理员/开发者/体验者,将打开指定版本的小程序。

                          发布

                          测试完成后开发者可将二维码跳转规则发布现网,发布后扫描所有符合匹配规则的二维码,将跳转至指定的小程序页面。

                          为确保用户体验,小程序必须先发布代码才可以发布二维码跳转规则。

                          一个小程序账号一个月可发布不多于500次二维码跳转规则。