• 下载
  • 社区

API 使用说明

支付宝小程序开发框架提供了丰富的 JSAPI(原生 API) 和 OpenAPI(开放能力 API),开发者可方便快捷地调用这些 API,详情请参见 API 概览

  • OpenAPI 是支付宝开放平台在小程序上开放的开放能力 API。通过 OpenAPI,小程序可以轻松实现用户授权、获取会员基础信息、获取用户手机号、小程序唤起支付、跳转支付宝卡包、会员开卡授权等多种多样的功能。

  • JSAPI 按实现的功能分类,可分为界面、多媒体、缓存、文件、位置、网络、设备、数据安全、分享、收藏、自定义通用菜单、小程序当前运行版本类型、自定义分析、更新管理等 14 个大类。

其中,JSAPI 分为两大类:事件监听 API、功能 API。

事件监听 API

事件监听型 API 以 my.on 开头,用于监听某个系统事件是否触发。
事件监听型 API 接受一个 callback 回调函数作为参数。当具体事件触发时,会触发 callback 函数调用。该 callback 函数可以传给对应以 my.off 开头的同名 API 来解除监听关系,如果直接调用以 my.off 开头的同名 API 则解除所有监听关系。
以监听低功耗蓝牙设备的特征值变化的事件 API my.onBLECharacteristicValueChange 为例:

Page({
  onLoad() {
    this.callback = this.callback.bind(this);
    my.onBLECharacteristicValueChange(this.callback);
  },
  onUnload() {
    // 页面卸载时解除某个监听
    my.offBLECharacteristicValueChange(this.callback);
    // 或者解除所有监听
    // my.offBLECharacteristicValueChange();
  },
  callback(res) {
    console.log(res);
  },
});

功能 API

功能型 API 是不以 my.onmy.off 开头的 API,用于实现某个特定功能。功能型 API 可分为异步型 API 和同步型 API。

异步型功能 API

大部分 API 都是异步型功能 API,例如 my.navigateTomy.request。异步型功能 API 的入参都为一个 Object 对象,并包含三个子属性:

属性 类型 必填 描述
success Function 调用成功的回调函数。
fail Function 调用失败的回调函数。
complete Function 调用结束的回调函数(调用成功、失败都会执行)。

回调结果若无特殊说明,一般为一个 Object 对象,包含以下子属性:

属性 类型 说明
errCode String 错误码,接口调用成功,errorCode=0 。
errorMsg String 错误信息,接口调用成功返回 ok
其他 - API 返回的其他数据。

以发起网络请求的 my.request API 为例:

// dataType 为 json 示例
my.request({
  url: 'https://httpbin.org/post',
  method: 'POST',
  data: {
    from: '支付宝',
    production: 'AlipayJSAPI',
  },
  dataType: 'json',
  success: function(res) {
    my.alert({content: 'success'});
  },
  fail: function(res) {
    my.alert({content: 'fail'});
  },
  complete: function(res) {
    my.alert({content: 'complete'});
  }
});

同步型功能 API

Sync 结尾的 API 都是同步型功能 API,例如 my.setStorageSyncmy.getBatteryInfoSync 等。

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

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

以上为通用说明,特定 API 的入参及返回值以详细 API 文档为准。