QQ小游戲 關系鏈數(shù)據(jù)指南

一個QQ用戶的關系鏈數(shù)據(jù)包括兩部分： 該用戶好友的用戶數(shù)據(jù) 該用戶所在的某個群的群成員的用戶數(shù)據(jù)。 為了豐富游戲的社交玩法，我們提供了獲取關系鏈數(shù)據(jù)的 API： qq.getFriendCloudStorage() 獲取當前用戶也玩該小游戲的好友的用戶數(shù)據(jù) qq.getGroupCloudStorage() 獲取當前用戶在某個群中也玩該小游戲的成員的用戶數(shù)據(jù) 這兩個 API 的返回結果都是一個對象數(shù)組，數(shù)組的每一個元素都是一個表示用戶數(shù)據(jù)的對象，其結構如下：

用戶的 游戲數(shù)據(jù) 指的是用戶的段位、戰(zhàn)績等游戲業(yè)務特有的數(shù)據(jù)，通過調(diào)用 qq.setUserCloudStorage() 可以將當前用戶的游戲數(shù)據(jù)托管在QQ后臺。只有被托管過數(shù)據(jù)的用戶，才會被視為 玩過 該小游戲的用戶，才會出現(xiàn)在 qq.getFriendCloudStorage() 和 qq.getGroupCloudStorage() 返回的對象數(shù)組中。 除此之外，我們還提供了以下 API：

• qq.removeUserCloudStorage() 刪除用戶托管數(shù)據(jù)中指定字段的數(shù)據(jù)
• qq.getUserCloudStorage() 獲取當前用戶的托管數(shù)據(jù)

qq.getUserCloudStorage、qq.getFriendCloudStorage() 和 qq.getGroupCloudStorage() 只能在 開放數(shù)據(jù)域 中調(diào)用。 qq.setUserCloudStorage() 和 qq.removeUserCloudStorage() 可以同時在 主域 和開放數(shù)據(jù)域中調(diào)用。

開放數(shù)據(jù)域

開放數(shù)據(jù)域 是一個封閉、獨立的 JavaScript 作用域。要讓代碼運行在開放數(shù)據(jù)域，需要在 game.json 中添加配置項 openDataContext 指定開放數(shù)據(jù)域的代碼目錄。添加該配置項表示小游戲啟用了開放數(shù)據(jù)域，這將會導致一些 限制

{
  "deviceOrientation": "portrait",
  "openDataContext": "src/myOpenDataContext"
}

同時還需要在該目錄下創(chuàng)建 index.js 作為開放數(shù)據(jù)域的入口文件，其代碼運行在開放數(shù)據(jù)域。game.js 是整個游戲的入口文件，其代碼運行在 主域。對應以上配置，應該有如下的目錄結構：

├── src
|   └── myOpenDataContext
|       ├── index.js
|       └── ...
├── game.js
├── game.json
└── ...

src/myOpenDataContext 是 開放數(shù)據(jù)域的代碼目錄，除 src/myOpenDataContext 以外是 主域的代碼目錄。

主域和開放數(shù)據(jù)域中的代碼不能相互 require。以如下的目錄結構為例：

├── src
|   └── myOpenDataContext
|       ├── index.js
|       ├── util.js
|       └── ...
├── lib
|   └── render.js
└── game.js

在 game.js 中不能 require('src/myOpenDataContext/util') 在 src/myOpenDataContext/index.js 中不能 require('../../lib/render.js')

主域和開放數(shù)據(jù)域的通信

開放數(shù)據(jù)域不能向主域發(fā)送消息。

主域可以向開放數(shù)據(jù)域發(fā)送消息。調(diào)用 qq.getOpenDataContext() 方法可以獲取開放數(shù)據(jù)域?qū)嵗{(diào)用實例上的 OpenDataContext.postMessage() 方法可以向開放數(shù)據(jù)域發(fā)送消息。

// game.js
const openDataContext = qq.getOpenDataContext()
openDataContext.postMessage({
  text: 'hello',
  year: (new Date()).getFullYear()
})

在開放數(shù)據(jù)域中通過 qq.onMessage() 方法可以監(jiān)聽從主域發(fā)來的消息。

// src/myOpenDataContext/index.js
qq.onMessage(data => {
  console.log(data)
  /* {
    text: 'hello',
    year: 2018
  } */
})

展示關系鏈數(shù)據(jù)

如果想要展示通過關系鏈 API 獲取到的用戶數(shù)據(jù)，如繪制排行榜等業(yè)務場景，需要將排行榜繪制到 sharedCanvas 上，再在主域?qū)?sharedCanvas 渲染上屏。

// src/myOpenDataContext/index.js
const sharedCanvas = qq.getSharedCanvas()


function drawRankList(data) {
  data.forEach((item, index) => {
    // ...
  })
}


qq.getFriendCloudStorage({
  success: res => {
    const data = res.data
    drawRankList(data)
  }
})

sharedCanvas 是主域和開放數(shù)據(jù)域都可以訪問的一個離屏畫布。在開放數(shù)據(jù)域調(diào)用 qq.getSharedCanvas() 將返回 sharedCanvas。

// src/myOpenDataContext/index.js
const sharedCanvas = qq.getSharedCanvas()
const context = sharedCanvas.getContext('2d')
context.fillStyle = 'red'
context.fillRect(0, 0, 100, 100)

在主域中可以通過開放數(shù)據(jù)域?qū)嵗L問 sharedCanvas，通過 drawImage() 方法可以將 sharedCanvas 繪制到上屏畫布。

// game.js
const openDataContext = qq.getOpenDataContext()
const sharedCanvas = openDataContext.canvas


const canvas = qq.createCanvas()
const context = canvas.getContext('2d')
context.drawImage(sharedCanvas, 0, 0)

sharedCanvas 的寬高只能在主域設置，不能在開放數(shù)據(jù)域中設置。

// game.js
sharedCanvas.width = 400
sharedCanvas.height = 200

sharedCanvas 本質(zhì)上也是一個離屏 Canvas，而重設 Canvas 的寬高會清空 Canvas 上的內(nèi)容。所以要通知開放數(shù)據(jù)域去重繪 sharedCanvas。

// game.js


openDataContext.postMessage({
  command: 'render'
})

// src/myOpenDataContext/index.js
openDataContext.onMessage(data => {
  if (data.command === 'render') {
    // ... 重繪 sharedCanvas
  }
})

限制

當小游戲啟動開放數(shù)據(jù)域，即在 game.json 中添加 openDataContext 配置項時。小游戲環(huán)境會對主域和開放數(shù)據(jù)域應用一些限制。

主域

1. sharedCanvas 只能被繪制到上屏 canvas 上。

2. 上屏 canvas 不能調(diào)用 toDataURL，其 context 不能調(diào)用 getImageData。

3. sharedCanvas 不能調(diào)用 toDataURL 和 getContext。

4. 不能將上屏 canvas 和 sharedCanvas 以任意形式繪制到其他 canvas 上，包括 drawImage、createPattern、texImage2D、texSubImage2D。

5. sharedCanvas 的寬高只能在主域設置

開放數(shù)據(jù)域

1. 不能設置 sharedCanvas 的寬高 開放數(shù)據(jù)域只能調(diào)用有限的 API，如下所示： 幀率
   • requestAnimationFrame()
   • cancelAnimationFrame() Timer
   • setTimeout()
   • clearTimeout()
   • setInterval()
   • clearInterval() 觸摸事件
   • qq.onTouchStart()
   • qq.onTouchMove()
   • qq.onTouchEnd()
   • qq.onTouchCancel()
   • qq.offTouchStart()
   • qq.offTouchMove()
   • qq.offTouchEnd()
   • qq.offTouchCancel() 畫布
   • qq.createCanvas() 開放數(shù)據(jù)域的所有 canvas 只支持 2d 渲染模式 圖片
   • qq.createImage() 開放數(shù)據(jù)域的 Image 只能使用本地或QQ CDN 的圖片，不能使用開發(fā)者自己服務器上的圖片。對于非本地或非QQ CDN 的圖片，可以先從主域 qq.downloadFile() 下載圖片文件，再通過 OpenDataContext.postMessage() 把文件路徑傳給開放數(shù)據(jù)域去使用。 開放數(shù)據(jù)
   • qq.getFriendCloudStorage()
   • qq.getGroupCloudStorage()
   • qq.getUserCloudStorage()
   • qq.setUserCloudStorage()
   • qq.removeUserCloudStorage() 調(diào)用開放數(shù)據(jù)API之前, 需要調(diào)用qq.login()獲取登錄憑證。 監(jiān)聽主域消息
   • qq.onMessage()