微信小程序：API综述

来自CloudWiki
跳转至： 导航， 搜索

API（Application Programming Interface）

  • 由小程序开发框架提供的预先定义的函数
  • 可直接按需调用功能，无需获取源码或理解内部细节

从必然王国 走向 自由王国

小程序API分类

  • 网络 媒体 文件 数据缓存 画布
  • 位置 设备 开放接口等

小程序API的类型

事件监听API

约定以 on开头的 API 用来监听某个事件是否触发，如：wx.onSocketOpen，wx.onCompassChange 等。

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


如wx.onCompassChange(function callback)

监听罗盘数据变化事件。频率：5 次/秒，接口调用后会自动开始监听，可使用 wx.stopCompass 停止监听。

代码示例： 

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


数据操作API

数据的读取及写入

读取：wx.get***

写入：wx.set*** 

  if (wx.getUserProfile) {
      this.setData({
        canIUseGetUserProfile: true
      })
    }

同步API

参考文档：http://www.woshipm.com/pmd/261387.html

-可由函数返回值获取结果

约定以 Sync 结尾的 API 都是同步 API， 如wx.setStorageSync，wx.getSystemInfoSync 等。此外，也有一些其他的同步 API，如 wx.createWorker，wx.getBackgroundAudioManager 等

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

代码示例： 

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

异步API

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

Wexin22020601.png

三个回调函数: success，fail，complete

知识：回调函数

原理

回调函数的核心是委托制

⑴定义一个回调函数；

⑵提供函数实现的一方在初始化的时候，将回调函数的函数指针注册给调用者；

⑶当特定的事件或条件发生的时候，调用者使用函数指针调用回调函数对事件进行处理。

你到一个商店买东西，刚好你要的东西没有货，于是你在店员那里留下了你的电话，过了几天店里有货了，店员就打了你的电话，然后你接到电话后就到店里去取了货。在这个例子里，你的电话号码就叫回调函数，你把电话留给店员就叫登记回调函数，店里后来有货了叫做触发了回调关联的事件，店员给你打电话叫做调用回调函数，你到店里去取货叫做响应回调事件。回答完毕。

作者：常溪玲

链接：https://www.zhihu.com/question/19801131/answer/13005983

适用场景

在特定条件满足时执行一个任务

使用

  • 定义一个函数将要执行的任务与一特定事件建立关联
  • 当该函数关联的事件触发的时候，函数将被执行（回调机制）

优点

程序的任务执行变为异步，无需一直等待任务执行完成

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

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

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

代码示例： 

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


   wx.getUserProfile({
      desc: '展示用户信息', // 声明获取用户个人信息后的用途，后续会展示在弹窗中，请谨慎填写
      success: (res) => {
        console.log(res)
        this.setData({
          userInfo: res.userInfo,
          hasUserInfo: true
        })
      }
    })

云开发 API

开通并使用微信云开发，即可使用云开发API，在小程序端直接调用服务端的云函数。

代码示例： 

wx.cloud.callFunction({
  // 云函数名称
  name: 'cloudFunc',
  // 传给云函数的参数
  data: {
    a: 1,
    b: 2,
  },
  success: function(res) {
    console.log(res.result) // 示例
  },
  fail: console.error
})

// 此外，云函数同样支持promise形式调用

参考文档

[1] 微信小程序的API该如何使用？ https://jingyan.baidu.com/article/215817f7b89f121eda14231f.html

取自“http://www.openbrains.net/mediawiki/index.php?title=微信小程序：API综述&oldid=29468”