跳到主要内容

群组查询

本文档指导您如何使用融云即时通讯（IM）Harmony IMLib SDK 实现获取已加入群组、获取指定群组资料等功能。

提示

此功能从 1.8.0 版本开始支持。

开通服务​

使用此功能前，您需要在控制台开通信息托管服务。

群组查询​

您可以查询或搜索已加入的群组。

获取群组资料​

调用 getGroupsInfo 方法获取群组资料。

  • 该方法优先从本地查找，当用户不在群组中时，本地不存在或本地群组信息缓存超过 10 分钟才会从服务端拉取最新信息。
  • 单次调用最多支持获取 20 个群组资料。

代码示例​

TypeScript
// 群组 ID 列表
let groupIds = ["group1Id", "group2Id"];

IMEngine.getInstance().getGroupsInfo(groupIds).then(result => {
  if (EngineError.Success !== result.code) {
    // 获取群组信息失败
    return;
  }
  
  // 获取群组信息成功
  let ret : Object = result;
  if (result.data) {
    ret = Array.from(result.data as Array<GroupInfo>);
  }
});

获取指定已加入群组的资料​

使用 getJoinedGroups 根据当前用户已加入的群组 ID 获取群组资料。

该接口支持批量获取，您可以一次传入多个 groupId 获取多个群组资料，最多不超过 20 个。

代码示例​

TypeScript
// 群组 ID 列表
let groupIds = ["group1Id", "group2Id"];

IMEngine.getInstance().getJoinedGroups(groupIds).then(result => {
  if (EngineError.Success !== result.code) {
    // 获取失败
    return;
  }
  
  // 获取成功
  let ret: object = result;
  if (result.data) {
    ret = Array.from(result.data as Array<GroupInfo>);
  }
});

按角色获取已加入群组的资料​

使用 getJoinedGroupsByRole 按群成员角色分页获取已加入的群组。

此接口支持返回本次查询条件的总数，见 PagingQueryResult 的 totalCount。

参数说明​

群成员角色 GroupMemberRole 枚举介绍：

枚举值群成员角色
Undef未定义角色（使用此枚举查询代表查询全部类型群成员）
Normal普通群成员
Manager群管理员
Owner群主
提示

分页拉取说明：

  1. 首次拉取时，PagingQueryOption 的 pageToken 无需设置（设置 null、设置 ""，效果等同）。
  2. 拉取第二页需要传入首次拉取返回结果 PagingQueryResult 类型中的 pageToken。
    • 如果不为 ""，则可以传入该值再次拉取，直至 pageToken 返回为 ""，表示全部拉取完成。
    • 如果为 ""，表示没有下一页或已拉取完成，无需再次拉取。如传递 ""，将视为拉取首页数据。

示例代码​

TypeScript
// 通过 role 参数指定拉取全部群成员角色类型的群组
let role : GroupMemberRole = GroupMemberRole.Undef; // 按需使用角色枚举值
// 分页拉取参数
let pageToken = null;
// 设置分页大小，取值范围为 [1~100]
let count = 10;
// 按加入群组时间正序、倒序获取。true：正序；false：倒序
let order = false;
// 分页请求参数
let paging_option = new PagingQueryOption(pageToken, count, order);

IMEngine.getInstance().getJoinedGroupsByRole(role, paging_option).then(result => {
  if (EngineError.Success !== result.code) {
    // 拉取失败
    return
  }
  
  // 拉取成功
  if (result.data) {
    let data: PagingQueryResult<GroupInfo> = result.data;
    let pageToken: string = data?.pageToken;
    let totalCount: number = data?.totalCount;
    let arr: Array<GroupInfo> = Array.from(data?.data as Array<GroupInfo>);
    // 使用返回的 pageToken 拉取下一页
  }
});

按群名称搜索已加入群组的资料​

使用 searchJoinedGroups 根据群名称搜索已加入的群组。

此接口支持返回本次查询条件的总数，见 PagingQueryResult 的 totalCount。

提示

分页拉取说明：

  1. 首次拉取时，PagingQueryOption 的 pageToken 无需设置（设置 null、设置 ""，效果等同）。
  2. 拉取第二页需要传入首次拉取返回结果 PagingQueryResult 类型中的 pageToken。
    • 如果不为 ""，则可以传入该值再次拉取，直至 pageToken 返回为 ""，表示全部拉取完成。
    • 如果为 ""，表示没有下一页或已拉取完成，无需再次拉取。如传递 ""，将视为拉取首页数据。

代码示例​

TypeScript
// 群名称
let groupName = "groupName";
// 分页拉取参数
let pageToken = null;
// 设置分页大小，取值范围为 [1~200]
let count = 10;
// 按加入群组时间正序、倒序获取。true：正序；false：倒序
let order = false;
// 分页请求参数
let paging_option = new PagingQueryOption(pageToken, count, order);

IMEngine.getInstance().searchJoinedGroups(groupName, paging_option).then(result => {
  if (EngineError.Success !== result.code) {
    // 拉取失败
    return;
  }
  
  // 拉取成功
  if (result.data) {
    let data: PagingQueryResult<GroupInfo> = result.data;
    let pageToken: string = data?.pageToken;
    let totalCount: number = data?.totalCount;
    let arr: Array<GroupInfo> = Array.from(data?.data as Array<GroupInfo>);
    // 使用返回的 pageToken 拉取下一页
  }
});
最后于 更新