微信小游戏开发配置API接口

2022-04-21 管理员

微信小游戏开发者通过在根目录编写一个game.json文件进行配置，开发者工具和客户端需要读取这个配置，完成相关界面渲染和属性设置，只能使用JavaScript来编写微信小游戏，微信小程序游戏的运行环境是一个绑定了一些方法的JavaScript VM。

小游戏开发者：微信小游戏开发配置API接口

文件结构

小游戏只有以下两个必要文件：

├── game.js
└── game.json

game.js 小游戏入口文件
game.json 配置文件

配置

小游戏开发者通过在根目录编写一个 game.json 文件进行配置，开发者工具和客户端需要读取这个配置，完成相关界面渲染和属性设置。

key	数据类型	说明	默认值
deviceOrientation	String	支持的屏幕方向	portrait
showStatusBar	Boolean	是否显示状态栏	false
networkTimeout	Number	网络请求的超时时间，单位：毫秒	60000
networkTimeout.request	Number	wx.request 的超时时间，单位：毫秒	60000
networkTimeout.connectSocket	Number	wx.connectSocket 的超时时间，单位：毫秒	60000
networkTimeout.uploadFile	Number	wx.uploadFile 的超时时间，单位：毫秒	60000
networkTimeout.downloadFile	Number	wx.downloadFile 的超时时间，单位：毫秒	60000
workers	String	多线程 Worker 配置项，详细请参考 Worker文档	无

deviceOrientation

值	说明
portrait	竖屏
landscape	横屏

示例配置

{ "deviceOrientation": "portrait", "networkTimeout": { "request": 5000, "connectSocket": 5000, "uploadFile": 5000, "downloadFile": 5000 }
}

wx API

你只能使用 JavaScript 来编写小游戏。小游戏的运行环境是一个绑定了一些方法的 JavaScript VM。不同于浏览器，这个运行环境没有 BOM 和 DOM API，只有 wx API。接下来我们将介绍如何用 wx API 来完成创建画布、绘制图形、显示图片以及响应用户交互等基础功能。

创建 Canvas

调用 wx.createCanvas() 接口，可以创建一个 Canvas 对象。

var canvas = wx.createCanvas()

此时创建的 canvas 是一个上屏 Canvas，已经显示在了屏幕上，且与屏幕等宽等高。

console.log(canvas.width, canvas.height)

在整个小游戏代码中首次调用 wx.createCanvas() 创建的是上屏 Canvas，之后调用则创建的是离屏 Canvas。如果你的项目中使用了官方提供的 Adapter 即 weapp-adapter.js（关于什么是 Adpater 请参考官方教程 Adapter），那么你此时创建的会是一个离屏 Canvas。因为在 weapp-adapter.js 已经调用了一次 wx.createCanvas()，并把返回的 canvas 作为全局变量暴露出来。假设你的项目目录结构如下：

├── game.js
├── weapp-adapter.js
└── game.json

在 weapp-adapter.js 中已经调用了一次 wx.createCanvas()，并把返回的 canvas 作为全局变量暴露出来。

// weapp-adapter canvas = wx.createCanvas()

如果你在 require weapp-adapter.js 之后再调用 wx.createCanvas()，那么创建的 Canvas 会是一个离屏的 Canvas，因为此时已经不是对该 API 的首次调用。

require('./weapp-adapter') var myCanvas = wx.createCanvas()

在 Canvas 上进行绘制

但是由于没有在 canvas 上进行绘制，所以 canvas 是透明的。使用 2d 渲染上下文的进行简单的绘制，可以在屏幕左上角看到一个 100x100 的红色矩形。

var context = canvas.getContext('2d')
context.fillStyle = 'red' context.fillRect(0, 0, 100, 100)

通过 Canvas.getContext() 方法可以获取 2d 或 WebGL 渲染上下文 RenderingContext，调用渲染上下文的绘制方法可以在 Canvas 上进行绘制。小游戏基本上支持 2d 和 WebGL 1.0 所有的属性和方法，详情请见 RenderingContext。由于使用 WebGL 的绘制过程较为复杂，所以本文中的示例代码都以 2d 渲染上下文的绘制方法编写。

通过设置 width 和 height 属性可以改变 Canvas 对象的宽高，但这也会导致 Canvas 内容的清空和渲染上下文的重置。

canvas.width = 300 canvas.height = 300

显示图片

通过 wx.createImage() 接口，可以创建一个 Image 对象。Image 对象可以加载图片。当 Image 对象被绘制到 Canvas 上时，图片才会显示在屏幕上。

var image = wx.createImage()

设置 Image 对象的 src 属性可以加载一张本地图片或网络图片，当图片加载完毕时会执行注册的 onl oad 回调函数，此时可以将 Image 对象绘制到 Canvas 上。

image.onload = function () { console.log(image.width, image.height)
    context.drawImage(image, 0, 0)
}
image.src = 'logo.png'

创建多个 Canvas

在整个小游戏运行期间，首次调用 wx.createCanvas 接口创建的是一个上屏 Canvas。在这个 canvas 上绘制的内容都将显示在屏幕上。而第二次、第三次等后几次调用 wx.createCanvas 创建的都会是离屏 Canvas。在离屏 Canvas 上绘制的内容仅仅只是绘制到了这个离屏 Canvas 上，并不会显示在屏幕上。

以如下代码为例，运行后会发现屏幕上并没有在 (0, 0) 的位置显示 100x100 的红色矩形。因为我们是在一个离屏的 Canvas 绘制的。

var screenCanvas = wx.createCanvas() var offScreenCanvas = wx.createCanvas() var offContext = offScreenCanvas.getContext('2d')
offContext.fillStyle = 'red' offContext.fillRect(0, 0, 100, 100)

为了让这个红色矩形显示在屏幕上，我们需要把离屏的 offScreenCanvas 绘制到上屏的 screenCanvas 上。

var screenContext = screenCanvas.getContext('2d')
screenContext.drawImage(offScreenCanvas, 0, 0)

动画

在 JavaScript 中，一般通过 setInterval/setTimeout/requestAnimationFrame 来实现动画效果。小游戏对这些 API 提供了支持：

setInterval()
setTimeout()
requestAnimationFrame()
clearInterval()
clearTimeout()
cancelAnimationFrame()

另外，还可以通过 wx.setPreferredFramesPerSecond() 修改执行 requestAnimationFrame 回调函数的频率，以降低性能消耗。

触摸事件

响应用户与屏幕的交互是游戏中必不可少的部分，小游戏参照 DOM 中的 TouchEvent 提供了以下监听触摸事件的 API：

wx.onTouchStart()
wx.onTouchMove()
wx.onTouchEnd()
wx.onTouchCancel()

wx.onTouchStart(function (e) { console.log(e.touches)
})

wx.onTouchMove(function (e) { console.log(e.touches)
})

wx.onTouchEnd(function (e) { console.log(e.touches)
})

wx.onTouchCancel(function (e) { console.log(e.touches)
})

全局对象

window 对象是浏览器环境下的全局对象。小游戏的运行环境中没有 BOM API，因此没有 window 对象。但是提供了全局对象 GameGlobal，所有全局定义的变量都是 GameGlobal 的属性。

console.log(GameGlobal.setTimeout === setTimeout) console.log(GameGlobal.requestAnimationFrame === requestAnimationFrame) // true

开发者可以根据需要把自己封装的类和函数挂载到 GameGlobal 上。

GameGlobal.render = function () { //省略方法的具体实现... }

render()

GameGlobal 是一个全局对象，本身也是一个存在循环引用的对象。

console.log(GameGlobal === GameGlobal.GameGlobal)

console.log 无法在真机上将存在循环引用的对象输出到 vConsole 中。因此真机调试时请注释 console.log(GameGlobal) 这样的代码，否则将会产生这样的错误

An object width circular reference can't be logged

小游戏更新

小游戏启动会有两种情况，一种是「冷启动」，一种是「热启动」。假如用户已经打开过某小游戏，然后在一定时间内再次打开该小游戏，此时无需重新启动，只需将后台态的小游戏切换到前台，这个过程就是热启动；冷启动指的是用户首次打开或小游戏被微信主动销毁后再次打开的情况，此时小游戏需要重新加载启动。

更新机制

小游戏冷启动时如果发现有新版本，将会异步下载新版本的代码包，并同时用客户端本地已有的包进行启动，即新版本的小游戏需要等下一次冷启动才会应用上。如果需要马上应用最新版本，可以使用 wx.getUpdateManager() API 进行处理。

getUpdateManager 的使用示例

v1.9.90 基础库以后，可以通过 wx.getUpdateManager() 获取全局唯一的版本更新管理器，用于管理小游戏更新；另外请下载最新版本的开发者工具(1.02.1803130 以上)才支持在开发者工具上调试。

由于是新版本才支持的 API，请在使用前先判断是否支持，例如：

if (wx.getUpdateManager) { console.log('支持 wx.getUpdateManager')
}

获取到 updateManager 实例后，updateManager 包含以下方法：

方法	参数	说明
onCheckForUpdate	callback	当向微信后台请求完新版本信息，会进行回调
onUpdateReady	callback	当新版本下载完成，会进行回调
onUpdateFailed	callback	当新版本下载失败，会进行回调
applyUpdate		当新版本下载完成，调用该方法会强制当前小游戏应用上新版本并重启

onCheckForUpdate(callback) 回调结果说明：

属性	类型	说明
hasUpdate	Boolean	是否有新的版本

注：检查更新操作由微信在小游戏冷启动时自动触发，不需由开发者主动触发，开发者只需监听检查结果即可。

onUpdateReady(callback) 回调结果说明：

当微信检查到小游戏有新版本，会主动触发下载操作（无需开发者触发），当下载完成后，会通过 onUpdateReady 告知开发者。

onUpdateFailed(callback) 回调结果说明：

当微信检查到小游戏有新版本，会主动触发下载操作（无需开发者触发），如果下载失败（可能是网络原因等），会通过 onUpdateFailed 告知开发者。

applyUpdate() 说明：

当小游戏新版本已经下载时（即收到 onUpdateReady 回调），可以通过这个方法强制重启小游戏并应用上最新版本。

完整使用示例

if (typeof wx.getUpdateManager === 'function') { const updateManager = wx.getUpdateManager()

  updateManager.onCheckForUpdate(function (res) { // 请求完新版本信息的回调 console.log(res.hasUpdate)
  })

  updateManager.onUpdateReady(function () { // 新的版本已经下载好，调用 applyUpdate 应用新版本并重启 updateManager.applyUpdate()
  })

  updateManager.onUpdateFailed(function () { // 新的版本下载失败 })
}