群成员管理

---

功能简介

ZIM SDK 提供了群成员管理功能，支持查询群组成员列表、查询群组成员基本信息以及转让群主等功能。

前提条件

在实现“群成员管理”功能之前，请确保：

• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID 和 ServerSecret。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考 项目管理 - 即时通讯），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。
• 已获取登录 SDK 所需的 Token，详情请参考 使用 Token 鉴权。
• 已集成 ZIM SDK，详情请参考 快速开始 - 实现基本收发消息 的 “3 集成 SDK”。

实现流程

查询群成员列表

用户登录 ZIM SDK、并加入某个群组后，如果想要了解自己所在群组都有哪些成员，可以通过调用 queryGroupMemberList 接口，分页查询该群组的成员列表。单次调用接口最多可获取 100 名成员，传入 count 超过 100 按照 100 处理。

查询成功后，用户可以通过 ZIMGroupMemberListQueriedResult 收到查询结果。

queryGroupMemberList 说明

queryGroupMemberList(groupID: string, config: ZIMGroupMemberQueryConfig): Promise<ZIMGroupMemberListQueriedResult>

示例代码

// 群内成员查询群组的成员列表
var groupID = '';
// count 超过 100 按 100 处理
var config = { count: 10, nextFlag: 0 };

zim.queryGroupMemberList(groupID, config)
    .then(function ({ groupID, userList, nextFlag }) {
        // 查询成功
    })
    .catch(function (err) {
        // 查询失败
    });

查询群成员信息

用户登录 ZIM SDK、并加入某个群组后，如果想要了解自己所在群组的某个成员的信息，可以通过调用 queryGroupMemberInfo 接口，查询该成员的个人信息。

查询成功后，用户可以通过 ZIMGroupMemberInfoQueriedResult 收到查询结果。

queryGroupMemberInfo 说明

queryGroupMemberInfo(userID: string, groupID: string): Promise<ZIMGroupMemberInfoQueriedResult>

示例代码

// 群内成员 查询群组内某个成员的信息
var groupID = '';
var userID = '';
zim.queryGroupMemberInfo(userID, groupID)
    .then(function ({ groupID, userInfo }) {
        // 查询成功
    })
    .catch(function (err) {
        // 查询失败
    });

设置群成员昵称

用户登录 ZIM SDK、并加入某个群组后，如果想要设置自己在群组中的昵称，可以通过调用 setGroupMemberNickname 接口，设置昵称。

设置成功后，用户可以通过 ZIMGroupMemberNicknameUpdatedResult 收到通知。

setGroupMemberNickname 说明

setGroupMemberNickname(
    nickname: string,
    forUserID: string,
    groupID: string,
): Promise<ZIMGroupMemberNicknameUpdatedResult> 

示例代码

// 群内成员设置昵称。
// 注意：群主可以设置自己和其他群内成员在该群中的昵称；其他群内成员仅可以设置自己在该群中的昵称。
var groupID = '';
var forUserID = '';
var nickname = '';
zim.setGroupMemberNickname(nickname, forUserID, groupID)
    .then(function ({ groupID, forUserID, nickname }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

// 注册监听“群成员信息变更”的回调
zim.on('groupMemberInfoUpdated', function (zim, { groupID, userList, operatedInfo }) {
    console.log('groupMemberInfoUpdated', groupID, userList, operatedInfo);
});

设置群成员角色

群主登录 ZIM SDK 后，可以通过调用 setGroupMemberRole 接口，设置其他群内成员的角色，比如设置某个群成员为普通成员或者为管理员。

设置成功后，群主可以通过 ZIMGroupMemberRoleUpdatedResult 类型收到设置结果。

群内成员可以通过 groupMemberInfoUpdated 收到用户角色变更的通知。

群成员角色与权限说明

ZIM SDK 默认支持将用户设置为群主、管理员、普通成员。在群组中，群主拥有所有客户端权限，可以实现所有群组功能。管理员拥有大部分客户端权限。普通成员拥有的客户端权限最少，具体如下表所示：

setGroupMemberRole 说明

setGroupMemberRole(role: number, forUserID: string, groupID: string): Promise<ZIMGroupMemberRoleUpdatedResult>

示例代码

//  群主设置普通成员用户为管理员
var groupID = '';
var forUserID = '';
var role = 2;
zim.setGroupMemberRole(role, forUserID, groupID)
    .then(function ({ groupID, forUserID, role }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

// 注册监听“群成员信息变更”的回调
zim.on('groupMemberInfoUpdated', function (zim, { groupID, userList, operatedInfo }) {
    console.log('groupMemberInfoUpdated', groupID, userList, operatedInfo);
});

转让群主

用户登录 ZIM SDK、并加入某个群组后，如果自己是某个群组中的群主，可以通过调用 transferGroupOwner 接口，传入 toUserID（被转让群主的群成员 ID），将自己的群主角色，转让给其他群内成员。

转让成功后，群内成员可以通过 groupMemberInfoUpdated 收到群主变更的通知。

transferGroupOwner 说明

transferGroupOwner(toUserID: string, groupID: string): Promise<ZIMGroupOwnerTransferredResult>

示例代码

// 转让群主身份给其他群内成员
var groupID = '';
var toUserID = '';
zim.transferGroupOwner(toUserID, groupID)
    .then(function ({ groupID, toUserID }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

// 注册监听“群成员状态变更”的回调
zim.on('groupMemberStateChanged', function (zim, { groupID, state, event, userList, operatedInfo }) {
    console.log('groupMemberStateChanged', groupID, state, event, userList, operatedInfo);
});

// 注册监听“群成员信息变更”的回调
zim.on('groupMemberInfoUpdated', function (zim, { groupID, userList, operatedInfo }) {
    console.log('groupMemberInfoUpdated', groupID, userList, operatedInfo);
});

查询群内成员数量

用户登录 ZIM SDK、并加入某个群组后，如果想要了解自己所在群组的成员数量，可以通过调用 queryGroupMemberCount 接口，查询该群成员的数量。

查询成功后，用户可以通过 ZIMGroupMemberCountQueriedResult 收到查询结果。

queryGroupMemberCount 说明

queryGroupMemberCount(groupID: string): Promise<ZIMGroupMemberCountQueriedResult> 

示例代码

// 查询群内成员数量
var groupID = '';
zim.queryGroupMemberCount(groupID)
    .then(function ({ groupID, count }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

搜索群成员

用户登录 ZIM SDK、并加入群组后，如果想要根据条件在群成员中搜索用户，可以通过调用 searchLocalGroupMembers 接口，传入 groupID、config 搜索符合条件的群成员。

搜索结果将通过 ZIMGroupMembersSearchedResult 回调接口返回。

searchLocalGroupMembers 说明

searchLocalGroupMembers(
    groupID: string,
    config: ZIMGroupMemberSearchConfig,
): Promise<ZIMGroupMembersSearchedResult>

ZIMGroupMemberSearchConfig 参数说明

示例代码

// 在某个群组中搜索名称中包含 “zego” 的群成员

var config = {
    count: 10, // 搜索结果数量
    nextFlag: 0,
    keywords: ['zego'], // 设置关键词为 “zego”，最多支持 5 个。当设置多个关键词后，搜索结果只展示同时包含所有关键词的本地消息
    isAlsoMatchGroupMemberNickname: true, // 如果群成员用户昵称包含 zego，搜索结果将包含该群成员
};

zim.searchLocalGroupMembers('groupID', config)
    .then(function ({ groupID, userList, nextFlag }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

设置群成员禁言状态

登录 ZIM SDK 后，用户可以禁言或解禁自己管理的群组内的特定成员。调用 muteGroupMembers 接口，批量修改 100 名群成员的禁言状态。禁言期限可为永久（ZIMGroupMemberMuteConfig > duration 为 -1）或最长为 7 天（ZIMGroupMemberMuteConfig > duration 为 604800）。当 ZIMGroupMemberMuteConfig > duration 为 0 时，表示取消禁言。

设置成功后，操作用户可以通过 muteGroupMembers 收到结果。

禁言或解禁成功后，全体群成员会收到 groupMemberInfoUpdated，得知哪些群成员无法在该群组发言或解除禁言状态。

var isMute = true;
var userIDs = ["user_1", "user_2", "user_3"];
var groupID = "group_id";
var config = {
    duration: 30,  // 设置禁言时间为 30 秒
};

zim.muteGroupMembers(isMute, userIDs, groupID, config)
    .then(function ({ groupID, isMute, duration, mutedUserIDs, errorUserList }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

查询群内禁言成员列表

登录 ZIM SDK 后，群成员如需了解所在群组的被禁言成员列表，可调用 queryGroupMemberMutedList 接口进行查询。

查询成功后，操作用户可通过 ZIMGroupMemberMutedListQueriedResult 获取具体信息。

// 群内成员查询群组的成员列表
var groupID = "group_id";
var config = {
    count: 100,
    nextFlag: 0,
}

zim.queryGroupMemberMutedList(groupID, config)
    .then(function ({ groupID, userList, nextFlag }) {
        // 操作成功
    })
    .catch(function (err) {
        // 操作失败
    });

获取当前群成员禁言状态

如需主动获取当前用户在群组的禁言状态，请通过以下任意方法：

• 参考 会话管理 - 拉取会话列表 主动拉取会话列表。
• 参考 会话管理 - 更新会话列表，监听会话变更回调，更新会话列表。

当会话类型是群类型时，从返回结果中的 ZIMGroupConversation 获取 mutedExpiredTime，即群禁言时间，单位为秒。

mutedExpiredTime 值说明如下：

• 为 -1 时，表示当前用户永久无法在该群组发言。
• 为 0 时，表示当前用户可以在该群组发言。
• 为其他值时，表示当前用户于该数值时间内无法在该群组发言。