关系链数据使用指南

    • 该用户好友的用户数据

    • 该用户所在的某个群的群成员的用户数据。为了丰富游戏的社交玩法，我们提供了获取关系链数据的 API：

    • qq.getFriendCloudStorage() 获取当前用户也玩该小游戏的好友的用户数据

    • 获取当前用户在某个群中也玩该小游戏的成员的用户数据这两个 API 的返回结果都是一个对象数组，数组的每一个元素都是一个表示用户数据的对象，其结构如下：

    用户的 指的是用户的段位、战绩等游戏业务特有的数据，通过调用 qq.setUserCloudStorage() 可以将当前用户的游戏数据托管在QQ后台。只有被托管过数据的用户，才会被视为 玩过 该小游戏的用户，才会出现在 和 qq.getGroupCloudStorage() 返回的对象数组中。

    除此之外，我们还提供了以下 API：

    开放数据域 是一个封闭、独立的 JavaScript 作用域。要让代码运行在开放数据域，需要在 game.json 中添加配置项 openDataContext 指定开放数据域的代码目录。添加该配置项表示小游戏启用了开放数据域，这将会导致一些 限制。

    同时还需要在该目录下创建 index.js 作为开放数据域的入口文件，其代码运行在开放数据域。game.js 是整个游戏的入口文件，其代码运行在 主域。对应以上配置，应该有如下的目录结构：

    1. ├── src
    2. |   └── myOpenDataContext
    3. |       ├── index.js
    4. |       └── ...
    5. ├── game.js
    6. ├── game.json
    7. └── ...

    src/myOpenDataContext 是 开放数据域的代码目录，除 src/myOpenDataContext 以外是 主域的代码目录。

    主域和开放数据域中的代码不能相互 require。以如下的目录结构为例：

    1. ├── src
    2. |   └── myOpenDataContext
    3. |       ├── index.js
    4. |       ├── util.js
    5. |       └── ...
    6. ├── lib
    8. └── game.js

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

    主域可以向开放数据域发送消息。调用 方法可以获取开放数据域实例，调用实例上的 OpenDataContext.postMessage() 方法可以向开放数据域发送消息。

    在开放数据域中通过 方法可以监听从主域发来的消息。

    1. // src/myOpenDataContext/index.js
    2. qq.onMessage(data => {
    3.   console.log(data)
    4.     text: 'hello',
    5.     year: 2018
    6.   } */
    7. })

    如果想要展示通过关系链 API 获取到的用户数据，如绘制排行榜等业务场景，需要将排行榜绘制到 sharedCanvas 上，再在主域将 sharedCanvas 渲染上屏。

    1. // src/myOpenDataContext/index.js
    2. const sharedCanvas = qq.getSharedCanvas()
    4. function drawRankList(data) {
    5.   data.forEach((item, index) => {
    6.     // ...
    7.   })
    8. }
    11.   success: res => {
    12.     const data = res.data
    13.     drawRankList(data)
    14.   }
    15. })

    sharedCanvas 是主域和开放数据域都可以访问的一个离屏画布。在开放数据域调用 qq.getSharedCanvas() 将返回 sharedCanvas。

    在主域中可以通过开放数据域实例访问 sharedCanvas，通过 drawImage() 方法可以将 sharedCanvas 绘制到上屏画布。

    1. // game.js
    2. const openDataContext = qq.getOpenDataContext()
    3. const sharedCanvas = openDataContext.canvas
    5. const canvas = qq.createCanvas()
    6. const context = canvas.getContext('2d')
    7. context.drawImage(sharedCanvas, 0, 0)

    sharedCanvas 的宽高只能在主域设置，不能在开放数据域中设置。

    1. // game.js
    2. sharedCanvas.width = 400
    3. sharedCanvas.height = 200

    sharedCanvas 本质上也是一个离屏 Canvas，而重设 Canvas 的宽高会清空 Canvas 上的内容。所以要通知开放数据域去重绘 sharedCanvas。

    1. // src/myOpenDataContext/index.js
    2.   if (data.command === 'render') {
    3.     // ... 重绘 sharedCanvas
    4.   }
    5. })

    当小游戏启动开放数据域，即在 game.json 中添加 openDataContext 配置项时。小游戏环境会对主域和开放数据域应用一些限制。

    • sharedCanvas 只能被绘制到上屏 canvas 上。
    • 上屏 canvas 不能调用 toDataURL，其 context 不能调用 getImageData。
    • sharedCanvas 不能调用 toDataURL 和 getContext。
    • 不能将上屏 canvas 和 sharedCanvas 以任意形式绘制到其他 canvas 上，包括 drawImage、createPattern、texImage2D、texSubImage2D。
    • sharedCanvas 的宽高只能在主域设置

    开放数据域

    • 不能设置 sharedCanvas 的宽高开放数据域只能调用有限的 API，如下所示：

    图片

    • qq.createImage()开放数据域的 Image 只能使用本地或QQ CDN 的图片，不能使用开发者自己服务器上的图片。对于非本地或非QQ CDN 的图片，可以先从主域 下载图片文件，再通过 OpenDataContext.postMessage() 把文件路径传给开放数据域去使用。

    开放数据

    监听主域消息