支付宝小程序基础API、应用级事件

菜蛋_
385 阅读7分钟

开启掘金成长之旅！这是我参与「掘金日新计划 · 12 月更文挑战」的第20点击查看活动详情

支付宝小程序API

事件监听

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

image.png

功能API

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

异步型功能API

大部分 API 都是异步型功能 API，例如 [my.navigateTo]、[my.request]。异步型功能 API 的入参都为一个 Object 对象，并包含三个子属性：

image.png
回调结果若无特殊说明，一般为一个 Object 对象，包含以下子属性：

image.png
以发起网络请求的 my.request API 为例：

image.png

同步型功能API

以 Sync 结尾的 API 都是同步型功能 API，例如 [my.setStorageSync]、[my.getBatteryInfoSync]等。

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

image.png

基础API

  1. my.canIUse:判断小程序的API、入参或返回值、组件、属性等是否在当前版本可用的API。
    如果想判断 API 是否可用，入参需要形如 ${API}.${type}.${param}.${option}：

    • ${API} 表示 API 的名称，不包括 my. 的名称。例如：想判断 my.getFileInfo，只需传入 getFileInfo 即可。
    • ${type} 表示 API 的调用方式，有效值为 object/return/callback。
    • ${param} 表示参数的某一个属性名。
    • ${option} 表示参数属性的具体属性值。

如果想判断组件是否可用，入参需要形如 ${component}.${attribute}.${option}：

-   `${component}` 表示组件名称。
-   `${attribute}` 表示组件属性名。
-   `${option}` 表示组件属性值。

示例代码（结果为true）：

image.png 2. my.env:my.env 是小程序环境变量对象 API。

image.png

image.png

image.png 3. my.getLaunchOptionsSync:获取冷启动的参数。my.getLaunchOptionsSync 用来获取小程序 [冷启动] 时的启动参数。与 [App.onLaunch] 的回调参数一致。
返回值

image.png
示例代码：

image.png 4. my.getEnterOptionsSync:my.getEnterOptionsSync 用来获取本次小程序启动时的参数。如果当前是 [冷启动]，则返回值与 [App.onLaunch] 的回调参数一致；如果当前是 [热启动]，则返回值与 [App.onShow]一致。
返回值：

image.png
示例代码：

image.png 5. my.SDKVersion:my.SDKVersion 是获取基础库版本号的 API。
效果：

image.png
示例代码：

image.png

Q：怎么才能升级基础库版本到最新或到指定的版本？

A：IDE 中可通过模拟器上方的“展开面板”按钮 -> “设置”，选择对应的基础库版本进行调试；真机运行时，以实际客户端中基础库版本为准，客户端内建了基础库自动更新逻辑，无法在小程序中控制；旧版支付宝客户端可能无法自动更新到最新的小程序基础库，需要升级客户端 ，在后台指定小程序运行时要求的最低基础库版本。 6. getAccountInfoSync：获取小程序版本信息
返回值 image.png image.png 7. my.getAppidSync:my.getAppIdSync 是同步获取小程序 APPID 的 API。

image.png
示例代码

image.png 8. my.getRunScene:my.getRunScene 是用于获取当前小程序的运行时版本的 API。

image.png

image.png

image.png

image.png
示例代码：

image.png 9. my.base64ToArrayBuffer:my.base64ToArrayBuffer 将 Base64 字符串转成 ArrayBuffer 对象。
示例代码：

image.png 9. my.arrayBufferToBase64：my.arrayBufferToBase64 将 ArrayBuffer 对象转成 Base64 字符串。
示例代码：

image.png

应用级事件

  1. my.onAppShow:my.onAppShow 是监听小程序切前台事件的 API。该事件与框架 [app.js 注册小程序] 时 onShow 参数的回调时机一致。对应的取消监听 API 请参见 [my.offAppShow]。(与onShow的区别是可以关闭监听） image.png

使用限制

  • 基础库 [1.20.0] 或更高版本；支付宝客户端 10.1.68 或更高版本，若版本较低，建议采取 [兼容处理]。
  • 由于开发者工具版本限制，目前本 API 暂不支持在开发者工具调试和真机调试，仅支持真机预览。开发者请调至 预览 模式，在支付宝客户端扫码查看效果。
  • 请勿使用 API 监听匿名函数，否则将无法关闭监听
  • 此 API 支持个人支付宝小程序、企业支付宝小程序使用。
    示例代码：

image.png image.png 2. my.offAppShow:my.offAppShow 是取消监听小程序切前台事件的 API。

使用限制

  • 基础库 [1.20.0] 或更高版本；支付宝客户端 10.1.68 或更高版本，若版本较低，建议采取 [兼容处理]。
  • 由于开发者工具版本限制，目前本 API 暂不支持在开发者工具调试和真机调试，仅支持真机预览。开发者请调至 预览 模式，在支付宝客户端扫码查看效果。
  • 请勿使用 API 监听匿名函数，否则将无法关闭监听。
  • 此 API 支持个人支付宝小程序、企业支付宝小程序使用。
    示例代码

image.png 3. my.onAppHide:my.onAppHide 是监听小程序切后台事件的 API。该事件与框架 [app.js 注册小程序] 时 onHide 参数的回调时机一致。对应的取消监听 API 请参见 [my.offAppHide]。
示例代码：

image.png

image.png 4. my.offAppHide:my.offAppHide 是取消监听小程序切后台事件的 API。 image.png 5. my.onPageNotFound:my.onPageNotFound 是监听小程序要打开的页面不存在事件的 API。该事件与 [App.onPageNotFound] 的回调时机一致。

注意事项

  • 开发者可以在回调中进行页面重定向，但必须在回调中同步处理，异步处理（例如 setTimeout 异步执行）无效。
  • 若开发者没有调用 my.onPageNotFound 绑定监听，也没有声明 App.onPageNotFound，当跳转页面不存在时，将推入支付宝原生的 页面不存在 提示页面。
  • 如果回调中又重定向到另一个不存在的页面，将推入支付宝原生的 页面不存在 提示页面，并且不再第二次回调。
  • 仅响应小程序冷启动或热启动时的页面找不到事件，不支持处理 [路由 API] 的失败场景。

image.png

image.png
示例代码：

image.png 6. my.offPageNotFound:my.offPageNotFound 是取消监听小程序要打开的页面不存在事件的 API

image.png
示例代码：

image.png 7. my.onUnhandledRejection:my.onUnhandledRejection 是监听未处理的 Promise 拒绝事件（即 unhandledrejection 事件）的 API。当 Promise 被 reject 且没有 reject 处理器的时候，会触发 unhandledrejection 事件，该事件的回调时机和参数与 [App.onUnhandledRejection] 的一致。

使用限制

image.png

  • 基础库 [1.24.1] 或更高版本；支付宝客户端 10.1.75 或更高版本，若版本较低，建议采取 [兼容处理]。
  • 此 API 支持个人支付宝小程序、企业支付宝小程序使用。
  • 如果 [app.onUnhandledRejection]方法 或 my.onUnhandledRejection(callback) 的回调函数内继续触发 Promise 的 unhandledrejection 事件，则可能会导致循环触发 unhandledrejection 事件，请注意规避。

image.png

image.png

image.png 8. my.offUnhandledRejection:my.offUnhandledRejection 是取消监听 unhandledrejection 事件的 API。

image.png
示例代码： image.png 9. my.onError:my.onError 是监听小程序错误事件的 API。目前仅指 JS 执行错误。触发时机和参数与 [App.onError]一致

使用限制

  • 基础库 [1.21.0] 或更高版本；支付宝客户端 10.1.75 或更高版本，若版本较低，建议采取 [兼容处理]。
  • 使用 my.onError 监听到的报错，app.js 中的 onError 方法也会监听到。
  • 使用 my.onError 监听页面报错，如果在多个页面开启监听没有关闭，则页面报错时会触发多个监听事件，建议在页面关闭时调用 [my.offError]关闭监听。
  • 此 API 支持个人支付宝小程序、企业支付宝小程序使用

image.png

image.png
示例代码：

image.png 10. my.offError:my.offError 是取消监听小程序错误事件的 API。 image.png
示例代码：

image.png 11. my.onComponentError:my.onComponentError 是用于监听小程序自定义组件内部 JS 代码的 error 事件。

当自定义组件内部 JS 代码运行抛出错误时，除了会执行 [my.onError]回调外，同时会触发 my.onComponentError 回调。

image.png

image.png
示例代码（监听自定义组件生命周期方法和用户自定义的组件实例方法，执行抛错时都会触发 my.onComponentError 回调。）

image.png 12. my.offCComponentError:my.offComponentError 是用于取消监听小程序自定义组件内部 JS 代码的 error 事件。

image.png
示例代码（监听自定义组件生命周期方法和用户自定义的组件实例方法，执行抛错时都会触发 my.onComponentError 回调。）

image.png 13. my.onLazyLoadError:监听小程序异步组件（[懒加载插件]、[分包异步化]）加载失败事件。 image.png

Number timeout

超时等待时间（单位：ms）。可选，默认值 5000。该设置全局有效，多次指定超时时间则覆盖前面的设置。

加载异步组件通常需要下载分包，分包下载超过 timeout 值会触发 errMsg 为 loadSubpackage: timeout 的回调。分包确认下载失败时，会再次触发 errMsg 为 loadSubpackage: fail 的回调。

注意

若在页面中使用该接口进行监听，请确保在必要时手动调用 my.offLazyLoadError 取消监听，避免内存泄漏。

image.png 14. my.offLazyLoadError:移除小程序异步组件（[懒加载插件]、[分包异步化]加载失败事件监听函数。

image.png

image.png

avatar
文章
阅读
粉丝