微信小程序开发实战之 05-微信小程序常用 API（下）

小程序组件与 API

动画 API

wx.createAnimation 方法用于获取动画实例 Animation，通过该实例的相关属性和方法实现动画效果。

wx.createAnimation 方法的基本选项：

名称	描述
duration	动画持续时间，单位为毫秒，默认值为 400
timingFunction	动画效果，默认值为 linear linear：匀速 ease：开始和结束速度较快，中间速度较慢，比较平滑 ease-in：以慢速开始的过渡效果，开始速度较慢，然后逐渐加快 ease-in-out：开始和结束速度较慢，中间速度较快的过渡效果，过渡更加自然 ease-out：以慢速结束的过渡效果，开始速度较快，然后逐渐减慢 step-start：在过渡的开始立即从初始状态跳转到最终状态，没有中间过渡过程 step-end：在过渡的结束立即从初始状态跳转到最终状态，没有中间过渡过程，只是在过渡结束时才发生状态变化
delay	动画延迟时间，单位为毫秒，默认值为 0
transformOrigin	设置旋转元素的基点位置，默认值（x, y, z）为 50%, 50%, 0

Animation 实例的基本方法：

名称	描述
rotate(angle)	旋转。旋转角度取值范围为 [-180, 180]
export()	导出动画队列，该方法每次调用后会清掉之前的动画操作将该方法导出的动画队列传递给页面中组件的 animation 属性，即可为相应的组件添加动画效果
scale(sx, sy)	缩放
translate（tx, ty）	平移变换
skew(ax, ay)	倾斜。倾斜角度取值范围为 [-180, 180]
step(object)	指定一个动画实例的下一个关键帧，表示一组动画完成
opacity(value)	设置透明度
backgroundColor(value)	设置背景颜色
width(value)	设置宽度
top(value)	设置 top 值

示例：wx.createAnimation

首页页面结构（pages/index/index.wxml）：

HTML 复制代码

<button bindtap="playAnimation">开始动画</button>
<text>\n</text>
<text animation="{{myAnimation}}">Hello World!</text>

首页页面逻辑（pages/index/index.js）：

JavaScript 复制代码

Page({
    data: {
        myAnimation: null
    },
    playAnimation() {
        let animation = wx.createAnimation({
            duration: 3000,
            timingFunction: 'ease',
        })

        // 平移元素
        animation.translate(200, 300)

        // 定义一帧
        animation.step()

        // 导出动画
        this.setData({
            myAnimation: animation.export()
        })
    }
})

示例效果：

登录流程时序

小程序可以通过微信官方提供的登录能力方便地获取微信提供的用户身份标识，快速建立小程序内的用户体系。

小程序登录流程：

登录流程时序说明：

在微信小程序中，通过 wx.login 方法获取临时登录凭证 code。
每一次调用 wx.login 方法都会生成新的 code，code 有效时间为 5 分钟且只能使用 1 次。
获取到临时登录凭证 code 后，通过 wx.request 方法发送携带 code 的请求到开发者服务器。
开发者服务器（后端服务器）将小程序 AppId、小程序密钥 AppSecret、临时登录凭证 code 发送请求给微信接口服务进行登录凭证校验。
微信接口服务校验成功，会返回用户会话密钥 session_key、用户标识 openid、unionid 等信息。
会话密钥 session_key 是对用户数据进行加密签名的密钥，当调用获取用户信息等微信接口时，需要使用会话密钥解密相关数据，因此为了应用自身的数据安全，开发者服务器不应该把会话密钥下发到小程序，也不应该对外提供这个密钥，一般会将会话密钥存储在开发者服务器中。
openid 是用户的唯一标识，同一个微信用户在不同 AppId 的微信小程序中，openid 是不同的。
unionid 是用户在微信开放平台账号下的唯一标识，若当前微信小程序已绑定到微信开放平台账号，则会返回此信息。
如果开发者拥有多个移动应用、网站应用、和公众账号（包括小程序），可通过 unionid 来区分用户的唯一性，只要是同一个微信开放平台账号下的移动应用、网站应用和公众账号（包括小程序），用户的 unionid 是唯一的，也就是说同一用户对同一个微信开放平台下的不同应用，unionid 是相同的。
开发者服务器可以根据用户标识生成自定义登录态，用于后续业务逻辑中前后端交互时识别用户身份。

登录 API

wx.login 方法用于获取用户登录凭证 code。

wx.login 方法的基本选项：

名称	描述
timeout	超时时间，单位为毫秒
success	调用成功的回调函数该事件回调函数可以接收一个 res 参数，通过 res.code 可以获取用户临时登录凭证
fail	调用失败的回调函数
complete	调用结束的回调函数

示例：wx.login

首页页面结构（pages/index/index.wxml）：

HTML 复制代码

<button bindtap="login">登录</button>

首页页面逻辑（pages/index/index.js）：

JavaScript 复制代码

Page({
    login() {
        wx.login({
            success: function (res) {
                console.log("用户临时登录凭证：" + res.code)

                // 拿到code后发送请求给开发者服务器登录
            }
        })
    }
})

示例效果：

数据缓存 API

数据缓存 API 可以实现数据的缓存，加快读取数据的速度。

数据缓存的基本方法：

方式	名称	描述
异步	wx.setStorage(object)	将数据存储在本地缓存指定的 key 中单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB
	wx.getStorage(object)	从本地缓存中异步获取指定 key 的内容
	wx.getStorageInfo(object)	异步获取当前 storage 的相关信息
	wx.removeStorage(object)	从本地缓存中移除指定 key
同步	wx.setStorageSync(key, data)	同步版本
	wx.getStorageSync(key)	同步版本
	wx.getStorageInfoSync()	同步版本
	wx.removeStorage(key)	同步版本

wx.setStorage 方法的基本选项：

名称	描述
key	本地缓存中指定的 key
data	需要存储的内容只支持原生类型、Date、能够通过 JSON.stringify 序列化的对象
encrypt	是否开启加密存储，默认值为 false 只有异步的 getStorage 接口支持开启加密存储开启后，将会对 data 使用 AES128 解密，接口回调耗时将会增加若开启加密存储，setStorage 和 getStorage 需要同时声明 encrypt 的值为 true
success	接口调用成功的回调函数
fail	接口调用失败的回调函数
complete	接口调用结束的回调函数，无论成功还是失败都会执行

wx.getStorage 方法的基本选项：

名称	描述
key	本地缓存中指定的 key
encrypt	是否开启加密存储，默认值为 false
success	接口调用成功的回调函数该事件回调函数可以接收一个 res 参数，通过 res.data 可以获取对应 key 的数据
fail	接口调用失败的回调函数
complete	接口调用结束的回调函数，无论成功还是失败都会执行

示例：wx.setStorage 和 wx.getStorage

首页页面结构（pages/index/index.wxml）：

HTML 复制代码

<button bindtap="setStorage">存数据</button>
<button bindtap="getStorage">取数据</button>
<button bindtap="removeStorage">删数据</button>

首页页面逻辑（pages/index/index.js）：

JavaScript 复制代码

Page({
    setStorage() {
        wx.setStorage({
            key: "myName",
            data: "多仔"
        })

        wx.showToast({
            title: "存储成功"
        })
    },
    getStorage() {
        wx.getStorage({
            key: "myName",
            success: function(res) {
                wx.showToast({
                    title: "取到的值：" + res.data
                })
            },
            fail: function () {
                wx.showToast({
                    title: "取值失败"
                })
            }
        })
    },
    removeStorage() {
        wx.removeStorage({
            key: "myName",
            success: function(res) {
                wx.showToast({
                    title: "删除成功"
                })
            }
        })
    }
})

示例效果：

头像昵称填写

在微信小程序中，当用户登录后，可以在页面中展示用户的头像和昵称。

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

头像选择的基本用法：

HTML 复制代码

<button open-type="chooseAvatar" bindchooseavatar="选择头像后触发事件">...</button>

昵称填写的基本用法：

HTML 复制代码

<input type="nickname"></input>

示例：头像昵称填写

首页页面结构（pages/index/index.wxml）：

HTML 复制代码

<image src="{{avatarUrl}}" style="width: 200rpx; height: 200rpx;"></image>
<button open-type="chooseAvatar" bindchooseavatar="chooseAvatar">选择头像</button>

<input type="nickname" placeholder="请输入昵称" model:value="{{nickName}}"></input>

首页页面逻辑（pages/index/index.js）：

JavaScript 复制代码

Page({
    data: {
        avatarUrl: "https://wwc.6os.net/addons/test_api/avatar.jpg",
        nickName: ""
    },
    chooseAvatar(e) {
        console.log(e)
        this.setData({
            avatarUrl: e.detail.avatarUrl
        })
    }
})

示例效果：

腾讯地图 SDK

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

腾讯位置服务：https://lbs.qq.com/

使用腾讯地图 SDK 前，需要申请开发者密钥。

进入腾讯位置服务平台，创建一个新的应用。

为已创建的腾讯位置服务应用添加开发者密钥 key，选择所有产品并按照要求填写相关信息。

开发者密钥 key 申请完成后，在平台中下载腾讯地图-微信小程序 JavaScript SDK，并将 SDK 文件复制到微信小程序项目中。

下载地址：https://lbs.qq.com/miniProgram/jsSdk/jsSdkGuide/jsSdkOverview

进入微信小程序管理后台，添加腾讯地图的合法的服务器域名 https://apis.map.qq.com。

腾讯地图 SDK 的使用方法：引入 SDK 核心类，实例化 QQMapWX 实例，通过 QQMapWX 实例实例的相关属性和方法实现地图功能。

微信小程序 JavaScript SDK 开发指南：https://lbs.qq.com/miniProgram/jsSdk/jsSdkGuide/jsSdkOverview

微信小程序在获取当前的地理位置时，需要在开发者在微信小程序全局配置文件（app.json）中对隐私和权限进行声明。

声明隐私和权限的基本用法：

JSON 复制代码

"permission": {
    "scope.userLocation": {
		"desc": "需要获取您的位置信息"
    }
},
"requiredPrivateInfos": ["getLocation"]

示例：腾讯地图 SDK

全局配置文件（app.json）：

JSON 复制代码

"permission": {
    "scope.userLocation": {
		"desc": "需要获取您的位置信息"
    }
},
"requiredPrivateInfos": ["getLocation"]

首页页面逻辑（pages/index/index.js）：

JavaScript 复制代码

// 引入腾讯地图SDK
const QQMapWX = require("../../libs/qqmap-wx-jssdk.min")

// 实例化QQMapWX实例
const txmap = new QQMapWX({
    // 开发者密钥key
    key: "2UDBZ-XXXXX-XXXXX-XXXXX-XXXXX-SHBOM"
})

Page({
    onReady() {
        // 搜索附近的地点
        txmap.search({
            keyword: "学校",
            success: function (res) {
                console.log(res)
            },
            fail: function () {
                console.log("搜索失败")
            }
        })
    }
})

示例效果：

map 组件

map 组件用于在页面中显示地图，支持移动、缩放、添加标记点等功能。

map 组件的基本用法：

HTML 复制代码

<map></map>

map 组件的基本属性：

名称	描述
longitude	中心经度，必填
latitude	中心纬度，必填
scale	缩放级别，默认值为 16，取值范围为 3～20
markers	标记点对象数组
show-location	是否显示带有方向的当前定位点，默认值为 false
bindregionchange	视野发生变化时触发的事件处理函数

标记点对象 marker 的基本属性：

名称	描述
id	标记点 id
longitude	标记点经度
latitude	标记点纬度
iconPath	标记点的图标路径
title	标记点名称，点击时显示
zIndex	显示层级
alpha	标记点的透明度，默认值为 1，取值范围为 0～1
width	标记点宽度
height	标记点高度

示例：map 组件

首页页面结构（pages/index/index.wxml）：

HTML 复制代码

<map markers="{{mapMarkers}}" style="width: 100%; height: 100%;"></map>

首页页面逻辑（pages/index/index.js）：

JavaScript 复制代码

Page({
    data: {
        mapMarkers: [
            {
                id: 1,
                longitude: 118.12,
                latitude: 25.12,
                title: "安溪清水岩",
                iconPath: "/images/gps.png",
                width: 50,
                height: 50
            }
        ]
    }
})

示例效果：

地图 API

wx.createMapContext 方法用于获取地图上下文实例 MapContext，通过该实例的相关方法实现对 map 组件地图的控制。

获取 MapContext 实例的基本用法：

JavaScript 复制代码

const mapCtx = wx.createMapContext("map组件的id")

MapContext 实例的基本方法：

名称	描述
getCenterLocation()	获取当前地图中心的经纬度，返回国家测绘局（GCJ-02）坐标系
moveToLication()	将地图中心移至当前定位点

getCenterLocation 方法的基本选项：

名称	描述
iconPath	图标路径
success	接口调用成功的回调函数该事件回调函数可以接收一个 res 参数，通过 res.longitude 和 res.latitude 获取经纬度数据
fail	接口调用失败的回调函数
complete	接口调用结束的回调函数，无论成功还是失败都会执行

moveToLication 方法的基本选项：

名称	描述
longitude	经度
latitude	纬度
success	接口调用成功的回调函数
fail	接口调用失败的回调函数
complete	接口调用结束的回调函数，无论成功还是失败都会执行

示例：wx.createMapContext

首页页面结构（pages/index/index.wxml）：

HTML 复制代码

<map id="myMap" style="width: 100%; height: 80%;"></map>
<button bindtap="moveLocation">前往"清水岩"</button>

首页页面逻辑（pages/index/index.js）：

JavaScript 复制代码

Page({
    moveLocation() {
        let mapCtx = wx.createMapContext("myMap")

        mapCtx.moveToLocation({
            longitude: 118.12,
            latitude: 25.12,
        })
    }
})

示例效果：

位置 API

wx.getLocation 方法用于获取当前地理位置。

对于正式项目，若想使用位置 API，需要在微信小程序管理后台申请接口权限、填写用户隐私保护指引，并在微信小程序全局配置文件（app.json）添加隐私声明。

wx.getLocation 方法的基本选项：

名称	描述
type	设为 WGS84 可返回 GPS 坐标设为 GCJ-02 可返回用于微信内置地图查看位置的坐标
success	接口调用成功的回调函数该事件回调函数可以接收一个 res 参数 res.longitude：经度 res.latitude：纬度 res.speed：速度，单位为 m/s res.altitude：高度，单位为 m
fail	接口调用失败的回调函数
complete	接口调用结束的回调函数，无论成功还是失败都会执行

示例：wx.getLocation

首页页面结构（pages/index/index.wxml）：

HTML 复制代码

<map id="myMap" style="width: 100%; height: 80%;"></map>
<button bindtap="getLocation">获取位置</button>

首页页面逻辑（pages/index/index.js）：

JavaScript 复制代码

Page({
    getLocation() {
        let mapCtx = wx.createMapContext("myMap")

        wx.getLocation({
            type: "GCJ-02",
            success(res) {
                console.log(res)

                mapCtx.moveToLocation({
                    longitude: res.longitude,
                    latitude: res.latitude
                })
            }
        })
    }
})

示例效果：

路由 API

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

wx.navigateTo：跳转到另一个页面，跳转后原来的页面会保留，并在导航栏左侧提供一个返回按钮，用户可以返回到之前的页面。
wx.redirectTo：关闭当前页面，跳转到一个新页面。
wx.switchTab：跳转到某个标签页，并关闭其他所有非标签页的页面。

路由 API 的基本选项：

名称	描述
url	需要跳转的路径，路径后可以带参数在目标页面的 onLoad 钩子函数中，可以接收一个 options 参数对象，以获取跳转时传递的参数数据
success	接口调用成功的回调函数
fail	接口调用失败的回调函数
complete	接口调用结束的回调函数，无论成功还是失败都会执行

示例：wx.redirectTo

全局配置文件（app.json）：

JSON 复制代码

"pages": [
    "pages/index/index",
    "pages/users/users"
]

首页页面结构（pages/index/index.wxml）：

HTML 复制代码

<button bindtap="redirect">跳转到users</button>

首页页面逻辑（pages/index/index.js）：

JavaScript 复制代码

Page({
    redirect() {
        wx.redirectTo({
            url: '/pages/users/users'
        })
    }
})

示例效果：

navicator 组件

navicator 组件用于实现页面之间的跳转。

navicator 组件的基本用法：

HTML 复制代码

<navicator url="...">...</navicator>

navicator 组件的基本属性：

名称	描述
target	在哪个目标上发生跳转，默认值为当前微信小程序
url	需要跳转的路径，路径后可以带参数在目标页面的 onLoad 钩子函数中，可以接收一个 options 参数对象，以获取跳转时传递的参数数据
open-type	跳转方式 navigate（默认值）：保留当前页面，跳转到其他页面，不能跳转到 tabBar 页面 redirect：关闭当前页面，跳转到其他页面，不能跳转到 tabBar 页面 switchTab：跳转到 tabBar，并关闭其他所有非 tabBar 页面 reLaunch：关闭所有页面，打开到应用内的某个页面 navigateBack：关闭当前页面，返回上一页面或多级页面 exit：退出微信小程序
delta	当 open-type=navigateBack 时生效，表示回退层数，默认值为 1

示例：navicator 组件

全局配置文件（app.json）：

JSON 复制代码

"pages": [
    "pages/index/index",
    "pages/users/users"
]

首页页面结构（pages/index/index.wxml）：

HTML 复制代码

<navigator url="/pages/users/users" open-type="redirect">跳转到users</navigator>

示例效果：

WebSocket API

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

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

WebSocket 协议是以 ws 或 wss 开头的，在微信小程序中，正式项目必须使用 wss 开头的 WebSocket 协议。

wx.connectSocket 方法用户创建一个 WebSocket 连接。

wx.connectSocket 方法的基本选项：

名称	描述
url	开发者服务器 wss 接口地址
header	请求头
timeout	超时时间，单位为毫秒
success	接口调用成功的回调函数
fail	接口调用失败的回调函数
complete	接口调用结束的回调函数，无论成功还是失败都会执行

SocketTask

wx.connectSocket 方法的返回值是一个 SocketTask 实例，SocketTask 实例用于管理 WebSocket 连接，使每一条链路的生命周期都更可控。

SocketTask 实例的基本方法：

名称	描述
send()	通过 WebSocket 连接发送数据
close()	关闭 WebSocket 连接
onOpen()	监听 WebSocket 连接打开事件
onClose()	监听 WebSocket 连接关闭事件
onError()	监听 WebSocket 错误事件
onMessage()	监听 WebSocket 连接接收到服务器的消息事件

send 方法的基本选项：

名称	描述
data	需要发送的内容
success	接口调用成功的回调函数
fail	接口调用失败的回调函数
complete	接口调用结束的回调函数，无论成功还是失败都会执行

close 方法的基本选项：

名称	描述
code	关闭连接的状态，表示连接被关闭的原因默认值为 1000，表示正常关闭连接
reason	可读字符串，表示连接被关闭的原因
success	接口调用成功的回调函数
fail	接口调用失败的回调函数
complete	接口调用结束的回调函数，无论成功还是失败都会执行

onClose 方法的基本属性：

名称	描述
code	关闭连接的状态豪，表示连接被关闭的原因默认值为 1000，表示正常关闭连接
reason	可读字符串，表示连接被关闭的原因

onOpen 方法的基本属性：

名称	描述
header	连接成功的请求头
profile	网络请求过程中的一些调试信息

onError 方法的基本属性：

名称	描述
errMsg	错误信息

onMessage 方法的基本属性：

名称	描述
data	服务器返回的消息