关系链数据

** 基础库最低版本: 1.17.0

一个 QQ 用户的关系链数据包括两部分:

  • 该用户好友的用户数据
  • 该用户所在的某个群的群成员的用户数据。

为了丰富小程序的社交玩法,我们提供了类似于小游戏使用关系数据链的方法:

<open-data>组件

属性 类型 默认值 必填 说明
type string 开放数据类型
share-ticket string 当 type=groupCloudStorage 时有效,群分享对应的 shareTicket
key-list Array.<string> 要拉取的 key 列表
component-data Object 从主域透传给开放数据域的数据,会自动注入到自定义开放数据域组件的 properties 中
generic:simple-component string 指定使用哪个自定义开放数据域组件来渲染开放数据,具体说明见下方
binderror eventhandle 开放数据请求或定向分享失败时触发,event.detail = {errMsg: "getGroupCloudStorage:fail no data"}

type的合法值

说明 最低版本
userCloudStorage 获取当前用户的应用数据 1.17.0
friendCloudStorage 获取当前用户也玩该小程序的好友的应用数据 1.17.0
groupCloudStorage 获取当前用户在某个群中也玩该小程序的成员的应用数据 1.17.0
potentialFriendList 获取可能对游戏感兴趣的未注册的好友名单。每次调用最多可获得 5 个好友 1.20.0
reactiveFriendList 获取曾经玩过游戏但最近不常玩的好友名单。每次调用最多可获得 5 个好友 1.20.0

可通过 generic:simple-component属性指定自定义开放数据域组件进行渲染. 使用方法同抽象节点

当数据获取成功后,通过generic:simple-component指定的自定义开放数据域组件中会在properties中自动注入以下属性:

属性 类型 说明
kvDataList Array.<KVData> type=userCloudStorage
userList Array.<UserData> type=friendCloudStoragetype=groupCloudStorage
list Array.<FriendInfo> type=potentialFriendListtype=reactiveFriendList
componentData Object 从主域透传给开放数据域的数据

KVData数据结构说明

属性 类型 说明
key string 数据的 key
value KVData 数据的 value

UserData数据结构说明

属性 类型 说明
openid string 用户的 openid
avatarUrl string 用户的 QQ 头像 url
nickname string 用户的 QQ 昵称
kvDataList Array.<KVData> 用户的应用数据

FriendInfo数据结构说明

属性 类型 说明
openid string 用户的 openid
avatarUrl string 用户的 QQ 头像 url
nickname string 用户的 QQ 昵称

用户的 应用数据 指的是用户的分数、段位等小程序业务特有的数据,通过调用 qq.setUserCloudStorage() 可以将当前用户的应用数据托管在 QQ 后台。只有被托管过数据的用户,才会被视为 玩过 该小程序的用户,才会出现在 type=friendCloudStoragetype=groupCloudStorage<open-data>组件中

除此之外,我们还提供了以下 API:

  • qq.removeUserCloudStorage() 删除用户托管数据中指定字段的数据

自定义开放数据域组件说明

自定义开放数据域组件 类似于自定义组件,不过有以下限制:

  • 组件所有的生命周期函数都不会被触发
  • 无法绑定任何事件回调(所有事件绑定都会被过滤掉)
  • 无法通过createSelectorQuerycreateIntersectionObserver 接口获取自定义开放数据域组件的任何节点
  • 仅支持使用<view><text><image><button> 组件,其他组件会被自动过滤掉
  • 开放数据域组件内引用的任何组件,其style属性都会被置空
  • 拥有独立的作用域,qml 文件引用的 qs 模块会重新生成新的实例

同时自定义开放数据域组件内使用的组件有以下限制:

<image>组件:

  • 只能使用本地或 QQ CDN 的图片,不能使用开发者自己服务器上的图片。

<button>组件:

仅支持以下类型:

  • open-type=shareMessageToFriend 定向分享
  • open-type=modifyFriendInteractiveStorage 修改好友的互动型托管数据

如何在自定义开放数据域组件中使用关系链数据

使用<open-data>组件请求关系链数据后,其返回结果在自定义开放数据域组件自动注入中kvDataListuserList属性

  • 如果需要对数据进行预处理(排序,过滤等操作)可通过QS文件对属性进行处理。

使用示例:

page/index/index.qml

<view>
    <open-data
        type="friendCloudStorage"
        generic:simple-component="ranklist"
        keyList="{{ ['score'] }}">
    </open-data>
</view>

1
2
3
4
5
6
7
8

page/index/index.json

{
  "usingComponents": {
    "ranklist": "/openDataContext/ranklist"
  }
}
1
2
3
4
5

openDataContext/ranklist.qml

<qs src="./tools.qs" module="tools"/>
<view class="ranklist">
    <view qq:for="{{tools.processData(userList)}}" class="item">
        <view class="name">{{item.nickname}}</view>
        <image class="avatar" src="{{item.avatarUrl}}"></image>
        <view class="score">{{item.kvDataList[0].value}}</view>
    </view>
</view>
1
2
3
4
5
6
7
8

openDataContext/tools.qs

module.exports.processData = function (userList) {
  return userList.sort(function (a, b) {
    a.kvDataList[0].value > b.kvDataList[0].value;
  });
};
1
2
3
4
5