通过案例的方式讲解微信小程序中常用 API 的使用，主要包括如何使用动画 API 制作动画、如何通过登录 API 实现用户登录、如何调用微信开放能力实现用户头像和昵称的获取、如何通过地图 API 实现地图功能，以及如何通过 WebSocketAPI、SocketTask 实现在线聊天。

学习目标：

• 掌握动画 API，能够完成动画的制作
• 熟悉登录流程时序，能够归纳微信小程序的登录流程
• 掌握登录 API，能够运用 wxlogin () 方法实现用户登录
• 掌握数据缓存 API，能够对数据进行存储、获取和移除等操作
• 掌握头像昵称填写功能，能够实现头像选择和昵称填写
• 掌握腾讯地图 SDK，能够实现腾讯地图 SDK 的接入和使用
• 掌握 map 组件，能够灵活运用 map 组件实现地图效果
• 掌握地图 API，能够实现地图中地理位置的获取等功能
• 掌握位置 API，自能够实现获取当前地理位置的功能
• 掌握路由 API，能够利用路由 API 实现页面跳转
• 掌握 WebSocket API，能够成功创建 WebSocket 连接
• 学握 SocketTask，能够使用 SocketTask 管理 WebSocket 连接

# 1. 动画 API

概念：动画 API 用于在微信小程序中完成动画效果的制作。在微信小程序中添加动画效果，可以让页面中的内容动起来。动画效果对浏览者的视觉冲击力远远高于静态画面，更能吸引浏览者。

动画 API 的使用方法如下：

第一步：通过 wx.createAnimation () 方法获取 Animation 实例；

var animation = wx.createAnimation(Object  object)  

 // Animation 实例

wx.createAnimation () 方法的常用选项：

wx.createAnimation () 方法的 timingFunction 选项有多个合法值，具体如下表所示：

Animation 实例的常用方法如下表所示：

动画 API 的使用方法如下：

第一步：通过 wx.createAnimation () 方法获取 Animation 实例；

var  animation = wx.createAnimation(Object object)  

 //  Animation 实例

第二步：调用 Animation 实例的方法实现动画效果。

动画 API 的使用案例：

①在 pages/index/index.js 文件的 Page ({}) 中定义页面初始数据 move。

data: {

  move: {}

},

//move 对象用于保存动画队列

②在 pages/index/index.wxml 文件编写页面结构。

<view animation="">hello world</view>

<button bindtap="translate">动画</button>

<!-- 绑定事件处理函数为 translate () -->

③在 pages/index/index.js 文件的 Page ({}) 中定义 translate () 函数实现动画效果。

translate: function () {

  var animation = wx.createAnimation({

    duration: 4000,

    timingFunction: 'ease'

  })

  animation.translate(50, 70).step()

  this.setData({

    move: animation.export()

  })

}

④完成上述代码后，运行程序，单击 “动画” 按钮后，“hello world” 向右下角平移，单击按钮前后的对比效果图如下。

# 2. 登录流程时序

登录流程时序

概念：登录流程时序由微信小程序官方文档提供，通过对登录流程时序的学习，可以完成登录功能的开发。微信官方提供的登录功能可以方便地获取微信提供的用户身份标识，从而使开发者服务器能够识别每个微信小程序用户。

微信小程序官方文档提供的登录流程时序图如下所示。

用户登录流程的参与角色：

小程序：用户使用的客户端，即微信小程序。

开发者服务器：微信小程序的后端服务器，用于为微信小程序用户提供服务。

微信接口服务：微信为开发者服务器提供的接口。

登录流程：

①获取 code

• 在微信小程序中通过 wx.login () 方法获取临时登录凭证 code。

②将 code 发送给开发者服务器

• 在获取 code 后，使用 wx.request () 方法将 code 发送给开发者服务器。

③校验登录凭证

• 开发者服务器将 appid、appsecret 和 code 发送给微信接口服务进行登录凭证校验，如果校验成功，微信接口服务会返回 session_key、openid、unionid 等信息。

④开发者服务器自定义登录态

• 在开发者服务器中为登录成功的用户生成一个 token，然后通过验证 token 的有效性来识别用户的登录状态。

# 3. 登录 API

登录 API 可以完成登录功能的开发。微信小程序提供了登录 API，其使用方法是，调用 wx.login () 方法获取用户登录凭证 code，获取后，将它发送给开发者服务器。

wx.login () 方法的常用选项

success 回调函数执行后，其参数会接收到一个对象，对象中有一个 code 属性，如下表所示。

注意：code 即为调用 wx.login () 方法获取的用户登录凭证。

wx.login () 方法的具体用法

wx.login({

  success: res => {

    if (res.code) {		//res.code 为登录获取的 code   

      wx.request({	// 登录成功之后发起网络请求

        url: 'http://127.0.0.1:3000/login',

        method: 'post',

        data: { code: res.code	// 设置参数，把 code 传递给服务器}

      })

    } else {		// 登录失败，在控制台输出错误信息

      console.log('登录失败！' + res.errMsg)

    }

  }

})

# 4. 数据缓存 API

数据缓存 API 可以实现数据的缓存，从而加快读取数据的速度。在微信小程序中，需要保存一些临时数据时，例如，保存用户登录后获取到的 token， 或保存一些经常需要从服务器中下载的数据，提高微信小程序下次打开时的加载速度。

常见的数据缓存方法如下表所示：

注意：

存储的最大数据长度：

单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。

wx.setStorage () 方法的常用选项如下表所示：

异步与同步的区别：

异步方法：

• 不会阻塞当前任务
• 异步方法需要通过传入回调函数获取结果
• 在发生错误时，异步方法会执行 fail () 回调函数返回错误

同步方法：

• 同步方法名以 Sync 结尾
• 同步方法直到处理完之后才能继续向下执行
• 同步方法通过返回值获取结果
• 在发生错误时，同步方法通过 try...catch 捕获异常来获取错误信息

使用异步方法存储、获取缓存数据示例：

wx.setStorage({		// 存储缓存数据

  key: 'key',		// 本地缓存中指定的 key

  data: 'value',		// 需要存储的内容（支持对象或字符串）

  success: res => {},	// 接口调用成功的回调函数

  fail: res => {}		// 接口调用失败的回调函数

})

wx.getStorage({		// 获取缓存数据

  key: 'key',		// 本地缓存中指定的 key

  success: res => {		// 接口调用成功的回调函数

    console.log(res.data)

  },

  fail: res => {}		// 接口调用失败的回调函数

}

# 5. 头像昵称填写

头像昵称是在用户登录小程序后，显示在页面中的头像和昵称。目前，微信小程序不允许开发者在未获得用户同意的情况下展示用户的头像和昵称，当需要展示时，应使用微信小程序的头像昵称填写功能。

头像选择的使用方法

• 将 button 组件的 open-type 属性值设置为 chooseAvatar，当用户选择头像之后，可通过 bindchooseavatar 绑定的事件处理函数获取头像信息的临时路径。

昵称填写的使用方法

• 将 input 组件的 type 属性值设置为 nickname，当用户在此 input 进行输入时，键盘上方会展示用户的微信昵称，用户可以使用该昵称，也可以手动填写昵称。

演示头像昵称填写功能的使用

①在 pages/index/index.js 文件中编写页面所需的数据。

const defaultAvatar = '/images/avatar.png'

Page({

  data: {

    avatarUrl: defaultAvatar

  },

})

//defaultAvatar 默认头像途径

②在 pages/index/index.wxml 文件中编写页面结构。

<button class="avatar-wrapper" open-type="chooseAvatar" bindchooseavatar="onChooseAvatar">

  <image class="avatar" src="" />

</button>

<input type="nickname" class="nickname" placeholder="请输入昵称" />

③在 pages/index/index.wxss 文件中编写样式。

.avatar-wrapper {

  width: 160rpx;

  height: 160rpx;

  padding: 0;

  background: none;

}

.avatar {

  width: 160rpx;

  height: 160rpx;

  border-radius: 20rpx;

}

.nickname {

  width: 80%;

  height: 100rpx;

  margin: 20px auto;

  border: 1px solid #000000;

  text-align: center;

}

④在 pages/index/index.js 文件中编写 onChooseAvatar () 函数，获取头像信息的临时路径。

onChooseAvatar: function (e) {

  const { avatarUrl } = e.detail

  this.setData({ avatarUrl })

}

在手机中预览微信小程序。首先在微信开发者工具中单击 “预览” 按钮，获得预览二维码，然后用手机中的微信客户端扫描二维码打开微信小程序，初始页面效果如图所示：

# 6.AP () 函数

若要在微信小程序启动、显示、隐藏时执行某些操作，或者在各个页面中需要共享一些数据时，可以通过 App () 函数实现。App () 函数用于注册一个微信小程序，该函数必须在 app.js 文件中调用，且只能调用一次。

App () 函数的参数是一个对象，通过该对象可以指定应用生命周期回调函数和保存一些共享数据。

应用生命周期函数

• 应用生命周期函数是指微信小程序 “启动→运行→销毁” 期间依次调用的函数

应用生命周期回调函数如下表所示：

App 实例的获取：

//getApp () 函数获取微信小程序全局唯一的 App 实例

const app = getApp()

通过 getApp () 函数获取 App 实例之后，可以访问 App 实例的属性或调用 App 实例的方法。

注意：

定义在 App () 函数的参数 {} 中的方法，可以直接使用 this 获取 App 实例，不必使用 getApp () 函数。

# 7. 腾讯地图 SDK

腾讯地图 SDK 是一套为开发者提供多种地理位置服务的工具，可以使开发者在自己的应用中加入地图相关的功能，轻松访问腾讯地图服务和数据， 更好地实现微信小程序的地图功能。

腾讯地图 SDK 的使用步骤分为以下 5 步：

腾讯地图 SDK 的使用方法：

• 首先引入 SDK 核心类，通过 new QQMapWX () 构造函数创建 QQMapWX 实例；
• 然后通过该实例的相关属性和方法实现地点搜索等功能。在这里使用 search () 方法搜索周边兴趣点（Point of Interest，POI）信息，例如 “酒店”“餐饮”“学校” 等。

search () 方法的常用选项如下表所示：

通过示例代码演示腾讯地图 SDK 的使用。

// 引入 SDK 核心类，js 文件的位置可自行放置

const QQMapWX = require('../../libs/qqmap-wx-jssdk.js')

// 创建 QQMapWX 实例

const qqmapsdk = new QQMapWX({ key: '填写自己申请的开发者密钥' })

// 实现逻辑代码的编写

// 实现逻辑代码的编写

Page({

    onShow: function () { 

        qqmapsdk.search({// 搜索信息 keyword: ' 酒店 ',

            success: res => {

                console.log(res)}, 

            fail: res => {console.log(res)}

        })

    }

})

保存代码后，控制台中可以看到通过 “酒店” 关键词搜索到的周边 POI 信息。

# 8.map 组件

在微信小程序中，map 组件可以为用 户提供地图功能。map 组件可以在页 面中显示地图，并且支持移动、缩放、添加标记点等功能。map 组件通过 <map>< /map > 标签来定义。

map 组件的常用属性如下表所示

markers 数组中的每一项为一个表示标记点的 marker 对象，marker 对象的属性如下表所示：

marker 标记点的定义：

①在 pages/index/index.wxml 文件中为 map 组件添加 markers 属性

<map id="myMap" markers="" scale="3"></map>

②在 pages/index/index.wxss 中编写样式，让地图组件占满整个页面

map {

    width: 100%;

    height: 100%; position: absolute;

}

③在 pages/index/index.js 文件中定义数据

data: {

    markers: [{ id: 1,

               iconPath: '/images/gps.png', 

               longitude: 113.324520,

               latitude: 23.099994

               // 标记点 id

               // 图标路径

               // 经度

               // 维度（广州市

              }]

},

# 9. 地图 API

地图 API 可以在 map 组件创建地图完成后，在 JS 文件中对地图进行控制。小 程序中，使用 wx.createMapContext () 方法创建 MapContext（Map 上下文） 实例，然后通过该实例的相关方法来 操作 map 组件。

MapContext 实例的常用方法如下表所示

MapContext 实例的 getCenterLocation () 方法的常用选项如下表所示

MapContext 实例的 moveToLocation () 方法的常用选项如下表所示

获取当前地图中心经纬度的示例：

// 调用 getCenterLocation () 方法获取当前地图中心的经度和纬度

mapCtx.getCenterLocation({ 

    success: res => {

        const longitude = res.longitude 

        const latitude = res.latitude 

        console.log(longitude, latitude)

    }

})

# 10. 位置 API

位置 API 用于实现获取当前地理位置的功能。在日常生活中，通过地图软件可以实时定位自己或者朋友的位置， 方便出行。微信小程序中，通过调用 wx.getLocation () 方法的 success 回调函数获取定位结果。

注意：

对于正式项目，若要使用位置 API，需要在微信小程序管理后台的 “开发管理 - 接口设置” 页面中申请开通，并且还需要在 app.json 文件中添加请求用户隐私信息的声明

// 请求用户隐私信息的声明

"requiredPrivateInfos": 

[ "getLocation"

],

wx.getLocation () 方法的常用选项如下表所示：

wx.getLocation () 方法的 success () 回调函数的参数是一个对象，该对象的属性如下表所示

wx.getLocation () 方法的使用

// 调用 wx.getLocation () 方法获取当前地理位置的经度和纬度

wx.getLocation({ 

    type: 'gcj02', 

    success: res => {

        const longitude = res.longitude 

        const latitude = res.latitude 

        console.log(longitude, latitude)

    }

})

# 11. 路由 API

路由 API 的作用：用于实现页面跳转。

常用的路由 API 方法：

wx.navigateTo()

• 用于跳转到另一个页面，跳转←后原来的页面会保留，并在导 “航栏左侧提供一个返回按钮，用户可以返回到之前的页面。该方法不能用于标签页切换。

wx.redirectTo()

• 用于关闭当前页面，跳转到一←众新页面。该方法不能用于标 < 签页切换。

wx.switchTab()

• 用于跳转到某个标签页，并关 < 团其他所有非标签页的页面。

路由 API 方法的常用选项如下表所示

路由 API 的使用

①在 pages/index/index:wxml 文件中编写一见点击按钮时触发、navigateTo () 函数。

<button bindtapnavigateTo 路由</button>

绑定事件处理函数为 navigateTo ()

②在 app.json 文件中创建 pages/list/list 页面，然后在 pages/index/index.js

文件中编写 navigateTo () 函数，实现跳转到 pages/list/list 页面

Page({

    navigateTo: 

    function () {

        wx.navigateTo({

            url: '/pages/list/list?id=1',

            success: () => {console.log('跳转成功')},

            {console.log('跳转完成')}

})

},

})

③在 pages/list/list.js 文件中编写 onLoad () 函数，输出 options 参数的值

onLoad: function(options) { 

    console.log(options)

},

④保存上述代码后，运行程序，单击 “路由” 按钮后，在控制台中输出结果

通过查看控制台中的结果，可以看出从 index 页面成功跳转到 list 页面，并传递了参数 id。

# 12.WebSocket API

WebSocket API：允许服务器主动向微信小程序发送消息。

WebSocket 是一种在单个 TCP 连接上进行全双工通信的协议，它会在客户端与服务器之间专门建立一条通道，使客户端与服务器之间的数据交换变得简单。客户端与服务器只需要完成一次握手，两者之间就可以创建持久性的连接，并进行双向数据传输。

通过 wx.connectSocket () 方法可以创建一个 WebSocket 连接，该方法的常用选项如下表所示。

wx.connectSocket () 方法的使用

调用 wx.connectSocket () 方法创建 WebSocket 连接

wx.connectSocket({
  // 服务器地址
  url: 'ws://127.0.0.1:3000'      	
})   

# 13.SocketTask

当项目中同时存在多个 WebSocket 的连 接 时 ， 使 用 SocketTask 管 理 WebSocket 连接，会使每一条链路的生命周期都更可控。而使用 wx 对象的方法可能会出现一些与预期不一致的情况。

SocketTask 实例的创建

//ws1 是一个 SocketTask 实例

const ws1 = wx.connectSocket({ 

    url: 'ws://127.0.0.1:3000'

SocketTask 实例的常用方法如下表所示

SocketTask 实例的 send () 方法的常用选项如下表所示

SocketTask 实例的 close () 方法的常用选项如下表所示

SocketTask 实例的 onOpen () 方法的属性如下表所示

SocketTask 的使用：

n 创建 WebSocket 连接、监听 WebSocket 连接打开事件、监听 WebSocket 接收到服务器的消息事件

onLoad: function () {

// 创建 WebSocket 连接

const ws1 = wx.connectSocket({ })

// 监听 WebSocket 连接打开事件

ws1.onOpen(res => { })

// 监听 WebSocket 接收到服务器的消息事件

ws1.onMessage(data => { })

}

创建 WebSocket 连接

const ws1 = wx.connectSocket({

    url: 'ws://127.0.0.1:3000',	// 本地服务器地址

    // 连接成功

    success: resConnect => { console.log(resConnect) },

    // 连接失败

    fail: resConnectError => { console.log(resConnectError) }

})

监听 WebSocket 连接打开事件

ws1.onOpen(res => { 

    ws1.send({

        data: JSON.stringify({ 

            number: '123', }), 

        success: resSend => { 

            console.log(resSend) },

        fail: resSendError => { 

            console.log(resSendError) }

    })

})

监听 WebSocket 接收到服务器的消息事件

ws1.onMessage(

    data => { 

        console.log(data.data)

})