微信小游戲開發(fā)配置API接口
小游戲開發(fā)者:微信小游戲開發(fā)配置API接口
文件結(jié)構(gòu)
小游戲只有以下兩個(gè)必要文件:
├── game.js └── game.json
- game.js 小游戲入口文件
- game.json 配置文件
配置
小游戲開發(fā)者通過在根目錄編寫一個(gè) game.json 文件進(jìn)行配置,開發(fā)者工具和客戶端需要讀取這個(gè)配置,完成相關(guān)界面渲染和屬性設(shè)置。
deviceOrientation | String | 支持的屏幕方向 | portrait |
showStatusBar | Boolean | 是否顯示狀態(tài)欄 | false |
networkTimeout | Number | 網(wǎng)絡(luò)請(qǐng)求的超時(shí)時(shí)間,單位:毫秒 | 60000 |
networkTimeout.request | Number | wx.request 的超時(shí)時(shí)間,單位:毫秒 | 60000 |
networkTimeout.connectSocket | Number | wx.connectSocket 的超時(shí)時(shí)間,單位:毫秒 | 60000 |
networkTimeout.uploadFile | Number | wx.uploadFile 的超時(shí)時(shí)間,單位:毫秒 | 60000 |
networkTimeout.downloadFile | Number | wx.downloadFile 的超時(shí)時(shí)間,單位:毫秒 | 60000 |
workers | String | 多線程 Worker 配置項(xiàng),詳細(xì)請(qǐng)參考 Worker文檔 | 無 |
key | 數(shù)據(jù)類型 | 說明 | 默認(rèn)值 |
---|
deviceOrientation
portrait | 豎屏 |
landscape | 橫屏 |
值 | 說明 |
---|
示例配置
{ "deviceOrientation": "portrait", "networkTimeout": { "request": 5000, "connectSocket": 5000, "uploadFile": 5000, "downloadFile": 5000 } }
wx API
你只能使用 JavaScript 來編寫小游戲。小游戲的運(yùn)行環(huán)境是一個(gè) 綁定了一些方法的 JavaScript VM。不同于瀏覽器,這個(gè)運(yùn)行環(huán)境沒有 BOM 和 DOM API,只有 wx API。接下來我們將介紹如何用 wx API 來完成創(chuàng)建畫布、繪制圖形、顯示圖片以及響應(yīng)用戶交互等基礎(chǔ)功能。
創(chuàng)建 Canvas
調(diào)用 wx.createCanvas() 接口,可以創(chuàng)建一個(gè) Canvas 對(duì)象。
var canvas = wx.createCanvas()
此時(shí)創(chuàng)建的 canvas 是一個(gè)上屏 Canvas,已經(jīng)顯示在了屏幕上,且與屏幕等寬等高。
console.log(canvas.width, canvas.height)
在整個(gè)小游戲代碼中首次調(diào)用 wx.createCanvas() 創(chuàng)建的是上屏 Canvas,之后調(diào)用則創(chuàng)建的是離屏 Canvas。如果你的項(xiàng)目中使用了官方提供的 Adapter 即 weapp-adapter.js(關(guān)于什么是 Adpater 請(qǐng)參考官方教程 Adapter),那么你此時(shí)創(chuàng)建的會(huì)是一個(gè)離屏 Canvas。因?yàn)樵?weapp-adapter.js 已經(jīng)調(diào)用了一次 wx.createCanvas(),并把返回的 canvas 作為全局變量暴露出來。假設(shè)你的項(xiàng)目目錄結(jié)構(gòu)如下:
├── game.js ├── weapp-adapter.js └── game.json
在 weapp-adapter.js 中已經(jīng)調(diào)用了一次 wx.createCanvas(),并把返回的 canvas 作為全局變量暴露出來。
// weapp-adapter canvas = wx.createCanvas()
如果你在 require weapp-adapter.js 之后再調(diào)用 wx.createCanvas(),那么創(chuàng)建的 Canvas 會(huì)是一個(gè)離屏的 Canvas,因?yàn)榇藭r(shí)已經(jīng)不是對(duì)該 API 的首次調(diào)用。
require('./weapp-adapter') var myCanvas = wx.createCanvas()
在 Canvas 上進(jìn)行繪制
但是由于沒有在 canvas 上進(jìn)行繪制,所以 canvas 是透明的。使用 2d 渲染上下文的進(jìn)行簡(jiǎn)單的繪制,可以在屏幕左上角看到一個(gè) 100x100 的紅色矩形。
var context = canvas.getContext('2d') context.fillStyle = 'red' context.fillRect(0, 0, 100, 100)
通過 Canvas.getContext() 方法可以獲取 2d 或 WebGL 渲染上下文 RenderingContext,調(diào)用渲染上下文的繪制方法可以在 Canvas 上進(jìn)行繪制。小游戲基本上支持 2d 和 WebGL 1.0 所有的屬性和方法,詳情請(qǐng)見 RenderingContext。由于使用 WebGL 的繪制過程較為復(fù)雜,所以本文中的示例代碼都以 2d 渲染上下文的繪制方法編寫。
通過設(shè)置 width 和 height 屬性可以改變 Canvas 對(duì)象的寬高,但這也會(huì)導(dǎo)致 Canvas 內(nèi)容的清空和渲染上下文的重置。
canvas.width = 300 canvas.height = 300
顯示圖片
通過 wx.createImage() 接口,可以創(chuàng)建一個(gè) Image 對(duì)象。Image 對(duì)象可以加載圖片。當(dāng) Image 對(duì)象被繪制到 Canvas 上時(shí),圖片才會(huì)顯示在屏幕上。
var image = wx.createImage()
設(shè)置 Image 對(duì)象的 src 屬性可以加載一張本地圖片或網(wǎng)絡(luò)圖片,當(dāng)圖片加載完畢時(shí)會(huì)執(zhí)行注冊(cè)的 onload 回調(diào)函數(shù),此時(shí)可以將 Image 對(duì)象繪制到 Canvas 上。
image.onload = function () { console.log(image.width, image.height) context.drawImage(image, 0, 0) } image.src = 'logo.png'
創(chuàng)建多個(gè) Canvas
在整個(gè)小游戲運(yùn)行期間,首次調(diào)用 wx.createCanvas 接口創(chuàng)建的是一個(gè)上屏 Canvas。在這個(gè) canvas 上繪制的內(nèi)容都將顯示在屏幕上。而第二次、第三次等后幾次調(diào)用 wx.createCanvas 創(chuàng)建的都會(huì)是離屏 Canvas。在離屏 Canvas 上繪制的內(nèi)容僅僅只是繪制到了這個(gè)離屏 Canvas 上,并不會(huì)顯示在屏幕上。
以如下代碼為例,運(yùn)行后會(huì)發(fā)現(xiàn)屏幕上并沒有在 (0, 0) 的位置顯示 100x100 的紅色矩形。因?yàn)槲覀兪窃谝粋€(gè)離屏的 Canvas 繪制的。
var screenCanvas = wx.createCanvas() var offScreenCanvas = wx.createCanvas() var offContext = offScreenCanvas.getContext('2d') offContext.fillStyle = 'red' offContext.fillRect(0, 0, 100, 100)
為了讓這個(gè)紅色矩形顯示在屏幕上,我們需要把離屏的 offScreenCanvas 繪制到上屏的 screenCanvas 上。
var screenContext = screenCanvas.getContext('2d') screenContext.drawImage(offScreenCanvas, 0, 0)
動(dòng)畫
在 JavaScript 中,一般通過 setInterval/setTimeout/requestAnimationFrame 來實(shí)現(xiàn)動(dòng)畫效果。小游戲?qū)@些 API 提供了支持:
- setInterval()
- setTimeout()
- requestAnimationFrame()
- clearInterval()
- clearTimeout()
- cancelAnimationFrame()
另外,還可以通過 wx.setPreferredFramesPerSecond() 修改執(zhí)行 requestAnimationFrame 回調(diào)函數(shù)的頻率,以降低性能消耗。
觸摸事件
響應(yīng)用戶與屏幕的交互是游戲中必不可少的部分,小游戲參照 DOM 中的 TouchEvent 提供了以下監(jiān)聽觸摸事件的 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) })
全局對(duì)象
window 對(duì)象是瀏覽器環(huán)境下的全局對(duì)象。小游戲的運(yùn)行環(huán)境中沒有 BOM API,因此沒有 window 對(duì)象。但是提供了全局對(duì)象 GameGlobal,所有全局定義的變量都是 GameGlobal 的屬性。
console.log(GameGlobal.setTimeout === setTimeout) console.log(GameGlobal.requestAnimationFrame === requestAnimationFrame) // true
開發(fā)者可以根據(jù)需要把自己封裝的類和函數(shù)掛載到 GameGlobal 上。
GameGlobal.render = function () { //省略方法的具體實(shí)現(xiàn)... } render()
GameGlobal 是一個(gè)全局對(duì)象,本身也是一個(gè)存在循環(huán)引用的對(duì)象。
console.log(GameGlobal === GameGlobal.GameGlobal)
console.log 無法在真機(jī)上將存在循環(huán)引用的對(duì)象輸出到 vConsole 中。因此真機(jī)調(diào)試時(shí)請(qǐng)注釋 console.log(GameGlobal) 這樣的代碼,否則將會(huì)產(chǎn)生這樣的錯(cuò)誤
An object width circular reference can't be logged
小游戲更新
小游戲啟動(dòng)會(huì)有兩種情況,一種是「冷啟動(dòng)」,一種是「熱啟動(dòng)」。 假如用戶已經(jīng)打開過某小游戲,然后在一定時(shí)間內(nèi)再次打開該小游戲,此時(shí)無需重新啟動(dòng),只需將后臺(tái)態(tài)的小游戲切換到前臺(tái),這個(gè)過程就是熱啟動(dòng);冷啟動(dòng)指的是用戶首次打開或小游戲被微信主動(dòng)銷毀后再次打開的情況,此時(shí)小游戲需要重新加載啟動(dòng)。
更新機(jī)制
小游戲冷啟動(dòng)時(shí)如果發(fā)現(xiàn)有新版本,將會(huì)異步下載新版本的代碼包,并同時(shí)用客戶端本地已有的包進(jìn)行啟動(dòng),即新版本的小游戲需要等下一次冷啟動(dòng)才會(huì)應(yīng)用上。 如果需要馬上應(yīng)用最新版本,可以使用 wx.getUpdateManager() API 進(jìn)行處理。
getUpdateManager 的使用示例
v1.9.90 基礎(chǔ)庫以后,可以通過 wx.getUpdateManager() 獲取全局唯一的版本更新管理器,用于管理小游戲更新;另外請(qǐng)下載最新版本的開發(fā)者工具(1.02.1803130 以上)才支持在開發(fā)者工具上調(diào)試。
由于是新版本才支持的 API,請(qǐng)?jiān)谑褂们跋扰袛嗍欠裰С郑纾?/p>
if (wx.getUpdateManager) { console.log('支持 wx.getUpdateManager') }
獲取到 updateManager 實(shí)例后,updateManager 包含以下方法:
onCheckForUpdate | callback | 當(dāng)向微信后臺(tái)請(qǐng)求完新版本信息,會(huì)進(jìn)行回調(diào) |
onUpdateReady | callback | 當(dāng)新版本下載完成,會(huì)進(jìn)行回調(diào) |
onUpdateFailed | callback | 當(dāng)新版本下載失敗,會(huì)進(jìn)行回調(diào) |
applyUpdate | 當(dāng)新版本下載完成,調(diào)用該方法會(huì)強(qiáng)制當(dāng)前小游戲應(yīng)用上新版本并重啟 | |
方法 | 參數(shù) | 說明 |
---|
onCheckForUpdate(callback) 回調(diào)結(jié)果說明:
hasUpdate | Boolean | 是否有新的版本 |
屬性 | 類型 | 說明 |
---|
注: 檢查更新操作由微信在小游戲冷啟動(dòng)時(shí)自動(dòng)觸發(fā),不需由開發(fā)者主動(dòng)觸發(fā),開發(fā)者只需監(jiān)聽檢查結(jié)果即可。
onUpdateReady(callback) 回調(diào)結(jié)果說明:
當(dāng)微信檢查到小游戲有新版本,會(huì)主動(dòng)觸發(fā)下載操作(無需開發(fā)者觸發(fā)),當(dāng)下載完成后,會(huì)通過 onUpdateReady 告知開發(fā)者。
onUpdateFailed(callback) 回調(diào)結(jié)果說明:
當(dāng)微信檢查到小游戲有新版本,會(huì)主動(dòng)觸發(fā)下載操作(無需開發(fā)者觸發(fā)),如果下載失?。赡苁蔷W(wǎng)絡(luò)原因等),會(huì)通過 onUpdateFailed 告知開發(fā)者。
applyUpdate() 說明:
當(dāng)小游戲新版本已經(jīng)下載時(shí)(即收到 onUpdateReady 回調(diào)),可以通過這個(gè)方法強(qiáng)制重啟小游戲并應(yīng)用上最新版本。
完整使用示例
if (typeof wx.getUpdateManager === 'function') { const updateManager = wx.getUpdateManager() updateManager.onCheckForUpdate(function (res) { // 請(qǐng)求完新版本信息的回調(diào) console.log(res.hasUpdate) }) updateManager.onUpdateReady(function () { // 新的版本已經(jīng)下載好,調(diào)用 applyUpdate 應(yīng)用新版本并重啟 updateManager.applyUpdate() }) updateManager.onUpdateFailed(function () { // 新的版本下載失敗 }) }