====== 6.API 接口 ======

[[https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html|微信开放文档API]]

===== -#1 类型 =====

==== - 事件监听 API ====

以<wrap em> on</wrap> 开头的 API 用来监听某个事件是否触发，如：wx.onSocketOpen，wx.onCompassChange 等。

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

<code javascript>
wx.onCompassChange(function (res) {
  console.log(res.direction)
})
</code> 

==== - 同步 API ====

以 Sync 结尾的 API 都是同步 API， 如 wx.setStorageSync，wx.getSystemInfoSync 等。

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

<code javascript>
try {
  wx.setStorageSync('key', 'value')
} catch (e) {
  console.error(e)
}
</code> 

==== - 异步 API ====

大多数 API 都是异步 API，如 wx.request，wx.login 等。这类 API 接口通常都接受一个 Object 类型的参数。

[[https://developers.weixin.qq.com/miniprogram/dev/framework/app-service/api.html#API|Object 参数说明]]

[[https://developers.weixin.qq.com/miniprogram/dev/framework/app-service/api.html#API|回调函数的参数]]

success，fail，complete 函数调用时会传入一个 Object 类型参数

==== - 异步API返回Promise ====

异步 API 支持 callback & promise 两种调用方式。

<code javascript>
// callback 形式调用
wx.chooseImage({
  success(res) {
    console.log('res:', res)
  }
})
</code>

<code javascript>
// promise 形式调用
wx.chooseImage().then(res => console.log('res: ', res))
</code>

===== API发起请求 wx.request =====

在小程序/小游戏中使用网络相关的 API 时，需要注意下列问题: \\
  * 每个微信小程序需要事先设置通讯域名,小程序只可以跟指定的域名进行网络通信。
  * 服务器域名请在 「小程序后台-开发-开发设置-服务器域名」 中进行配置。
  * 域名只支持 https，不能使用 IP 地址，可以配置端口。
  * 域名必须经过 ICP 备案。
  * api.weixin.qq.com 不能被配置为服务器域名，相关API也不能在小程序内调用。通过服务器使用 getAccessToken 接口获取 access_token，并调用相关 API；
  * 超时时间可以在 app.json 或 game.json 中通过 networktimeout 配置。


<code javascript>
wx.request({
  url: 'test.php', //仅为示例，并非真实的接口地址
  data: {
     x: '' ,
     y: ''
  },
  header:{
      "Content-Type":"application/json" //返回的数据是什么类型
  },
  success: function(res) {
     console.log(res.data)
  }
})

requestTask.abort() // 取消请求任务

</code>

OBJECT参数说明 \\

^ 参数名       | 类型        ^ 必填  | 说明                                            |
| url       | String    | 是   | 开发者服务器接口地址                                    |
| data      | data      |     | 请求的参数                                         |
| success   | Function  |     | 收到开发者服务成功返回的回调函数，res = {data: '开发者服务器返回的内容'}  |
| complete  | Function  |     | 接口调用结束的回调函数（调用成功、失败都会执行）                      |

success返回参数说明 \\

^ 参数名         | 类型                         ^ 说明                              ^
| data        | Object/String/ArrayBuffer  | 开发者服务器返回的数据                     |
| statusCode  | Number                     | 开发者服务器返回的 HTTP 状态码              |
| header      | Object                     | 开发者服务器返回的 HTTP Response Header  |


==== 以天气api为例 ====

 [[https://www.jianshu.com/p/63585bdbdbc2|如何将接口获取到的数据展示到微信小程序上]] \\

<code javascript>
//获取数据
wx.request({
  url: '******', //这里填写你的接口路径
  header: { //这里写你借口返回的数据是什么类型，这里就体现了微信小程序的强大，直接给你解析数据，再也不用去寻找各种方法去解析json，xml等数据了
      'Content-Type': 'application/json'
  },
  data: {//这里写你要请求的参数
     x: '' ,
     y: ''
  },

  success: function(res) {
  //这里就是请求成功后，进行一些函数操作
    console.log(res.data)
  }
})
</code>

<code javascript>
// js文件
  onLoad: function () {
    var that = this//不要漏了这句，很重要
    wx.request({
      url: 'https://www.apiopen.top/weatherApi?city=成都',
      headers: {
        'Content-Type': 'application/json'
      },
      success: function (res) {
         that.setData({
           date: res.data.data.forecast[0].date,
                  fengxiang: res.data.data.forecast[0].fengxiang,
                  type: res.data.data.forecast[0].type
           //res代表success函数的事件对，data是固定的，fengxiang是是上面json数据中fengxiang
         })
      }
    })
  }
</code>

<code wxml>
//wxml文件
{{date}}
{{fengxiang}}
{{type}}
</code>

==== 封装公共参数 ====

[[https://www.jianshu.com/p/c732123feadd|小程序封装wx.request]]

===== wx.setStorageSync =====

  * 参数 string key 本地缓存中指定的 key
  * any data 需要存储的内容。只支持原生类型、Date、及能够通过JSON.stringify序列化的对象。

<code javascript>
try {
  wx.setStorageSync('key', 'value')
} catch (e) { }
</code>

使用场景

小程序在获取用户授权后，获取用户的昵称和头像且会从数据库查询两个值显示到首页页面。
已经取得授权的情况下刷新，可以不弹框直接获取昵称和头像。此时也需要将数据库中的值显示到首页页面。
显然，再次向后台发出请求，获取数据库中的值是无法实现的。因为在页面显示的变量名是固定的，两次请求返回的值赋给同一个变量无法实现，且网络请求的先后顺序也不能确定。

使用

此种情况，就需要将首次查询（点击授权按钮）的值存入到本地缓存中，
当再次刷新时，将缓存中的值显示到页面上。
[[https://blog.csdn.net/java13245/article/details/103639697|微信小程序：数据缓存及使用（wx.setStorageSync(string key, any data)， wx.getStorageSync(string key)）]]


===== wx.getStorageSync =====

从本地缓存中获取指定 key 的内容，wx.getStorage 的同步版本 [[https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.getStorageSync.html|any wx.getStorageSync(string key)]]


  * 参数 string key  本地缓存中指定的 key
  * 返回值 any data key对应的内容

<code javascript>
try {
  var value = wx.getStorageSync('key')
  if (value) {
    // Do something with return value
  }
} catch (e) {
  // Do something when catch error
}
</code>

===== 媒体 =====

===== 文件 =====

===== 数据 =====

===== 位置 =====

===== 设备 =====