社群成员管理

2026-06-24

功能简介

ZIM SDK 提供了完整的社群成员管理能力，支持以下功能：

邀请用户加入社群
踢出社群成员
更新成员角色
转让社群所有权
查询社群成员列表
查询指定成员信息
设置成员禁言状态
监听成员状态与信息变更

前提条件

请参考实现基本消息收发完成 ZIM SDK 获取、初始化和用户登录。
请参考使用 Token 鉴权实现用户鉴权登录。
社群功能需要 ZIM SDK 3.0.0 及以上版本。
社群功能为旗舰版功能，使用前请联系 ZEGO 技术支持开通。
社群功能的 Token 生成方式与其他 ZIM 功能一致，无需额外权限声明。

邀请用户加入社群

调用 inviteUsersIntoCommunity 接口，批量邀请用户加入社群。邀请无需对方同意，被邀请用户直接成为社群成员。被邀请用户必须已在系统中注册。单次调用接口最多一次邀请 100 名用户加入社群。

操作失败的用户信息将通过 errorUserList 返回。

示例代码

List<String> userIDs = ['user_1', 'user_2'];

try {
    ZIMCommunityUsersInvitedResult result =
        await ZIM.getInstance()!.inviteUsersIntoCommunity(userIDs, communityID);
    // result.errorUserList 列出邀请失败的用户
} on PlatformException catch (onError) {
    // 操作失败
}

List<String> userIDs = ['user_1', 'user_2'];

try {
    ZIMCommunityUsersInvitedResult result =
        await ZIM.getInstance()!.inviteUsersIntoCommunity(userIDs, communityID);
    // result.errorUserList 列出邀请失败的用户
} on PlatformException catch (onError) {
    // 操作失败
}

常见错误码

错误码	说明	处理建议
6001004	社群不存在	确认 communityID 是否正确
6001005	用户不在社群中	仅在特定场景出现，确认用户状态
6001007	社群权限错误	确认当前用户是否有邀请权限

踢出社群成员

调用 kickCommunityMembers 接口，批量将指定成员从社群中移除。单次调用接口最多一次从社群踢出 100 名用户。

注意

仅社群所有者和管理员可调用此接口。

示例代码

List<String> userIDs = ['user_1', 'user_2'];

try {
    ZIMCommunityMembersKickedResult result =
        await ZIM.getInstance()!.kickCommunityMembers(userIDs, communityID);
    // result.errorUserList 列出失败的用户
} on PlatformException catch (onError) {
    // 操作失败
}

List<String> userIDs = ['user_1', 'user_2'];

try {
    ZIMCommunityMembersKickedResult result =
        await ZIM.getInstance()!.kickCommunityMembers(userIDs, communityID);
    // result.errorUserList 列出失败的用户
} on PlatformException catch (onError) {
    // 操作失败
}

更新社群成员角色

调用 updateCommunityMemberRole 接口，修改指定成员在社群中的角色，如将普通成员设置为管理员。

注意

仅社群所有者可调用此接口。社群角色 1 为社群群主，2 为社群管理员，3 为社群普通成员。

示例代码

// ZIMCommunityMemberRole.manager = 管理员
try {
    await ZIM.getInstance()!.updateCommunityMemberRole(
        ZIMCommunityMemberRole.manager, 'target_user_id', communityID);
    // 角色更新成功
} on PlatformException catch (onError) {
    // 操作失败
}

// ZIMCommunityMemberRole.manager = 管理员
try {
    await ZIM.getInstance()!.updateCommunityMemberRole(
        ZIMCommunityMemberRole.manager, 'target_user_id', communityID);
    // 角色更新成功
} on PlatformException catch (onError) {
    // 操作失败
}

转让社群所有权

调用 transferCommunityOwner 接口，将当前社群的所有权转让给社群内的其他成员。转让后，原所有者将成为普通成员。

注意

仅社群所有者可调用此接口。

示例代码

try {
    await ZIM.getInstance()!
        .transferCommunityOwner('new_owner_user_id', communityID);
    // 转让成功
} on PlatformException catch (onError) {
    // 转让失败
}

try {
    await ZIM.getInstance()!
        .transferCommunityOwner('new_owner_user_id', communityID);
    // 转让成功
} on PlatformException catch (onError) {
    // 转让失败
}

查询社群成员列表

调用 queryCommunityMemberList 接口，分页拉取指定社群的成员列表。

分页规则与查询社群列表一致：首次将 config.nextFlag 设为 0，后续将返回的 nextFlag 传入下次请求，直到 nextFlag 返回 0 为止。

示例代码

ZIMCommunityMemberListQueryConfig config =
    ZIMCommunityMemberListQueryConfig()..nextFlag = 0;

try {
    ZIMCommunityMemberListQueriedResult result =
        await ZIM.getInstance()!.queryCommunityMemberList(communityID, 100, config);
    // result.memberList 为成员列表
} on PlatformException catch (onError) {
    // 查询失败
}

ZIMCommunityMemberListQueryConfig config =
    ZIMCommunityMemberListQueryConfig()..nextFlag = 0;

try {
    ZIMCommunityMemberListQueriedResult result =
        await ZIM.getInstance()!.queryCommunityMemberList(communityID, 100, config);
    // result.memberList 为成员列表
} on PlatformException catch (onError) {
    // 查询失败
}

查询指定成员信息

调用 queryCommunityMembers 接口，批量查询指定用户在社群中的成员信息，包括角色、禁言状态等。

示例代码

List<String> userIDs = ['user_1', 'user_2'];

try {
    ZIMCommunityMembersQueriedResult result =
        await ZIM.getInstance()!.queryCommunityMembers(userIDs, communityID);
    // result.memberList 为成员信息
} on PlatformException catch (onError) {
    // 查询失败
}

List<String> userIDs = ['user_1', 'user_2'];

try {
    ZIMCommunityMembersQueriedResult result =
        await ZIM.getInstance()!.queryCommunityMembers(userIDs, communityID);
    // result.memberList 为成员信息
} on PlatformException catch (onError) {
    // 查询失败
}

设置成员禁言

调用 muteCommunityMembers 接口，批量设置指定成员在社群内指定频道中的禁言状态。禁言配置通过 ZIMCommunityMemberMuteConfig 传入。

配置字段	说明
`channelID`	指定禁言生效的频道 ID。留空则对所有频道生效。
`duration`	禁言时长（秒），取值范围 1-2592001（约 30 天），或 `-1` 表示永久禁言。

注意

仅社群所有者和管理员可调用此接口。

示例代码

List<String> userIDs = ['user_1', 'user_2'];
ZIMCommunityMemberMuteConfig config = ZIMCommunityMemberMuteConfig()
  ..duration = 3600
  ..channelID = 'channel_001';

try {
    await ZIM.getInstance()!
        .muteCommunityMembers(true, userIDs, communityID, config);
    // 禁言设置成功
} on PlatformException catch (onError) {
    // 操作失败
}

List<String> userIDs = ['user_1', 'user_2'];
ZIMCommunityMemberMuteConfig config = ZIMCommunityMemberMuteConfig()
  ..duration = 3600
  ..channelID = 'channel_001';

try {
    await ZIM.getInstance()!
        .muteCommunityMembers(true, userIDs, communityID, config);
    // 禁言设置成功
} on PlatformException catch (onError) {
    // 操作失败
}

监听成员变更

成员状态变化

当成员加入或离开社群时，SDK 会触发 onCommunityMemberStateChanged 回调。通过 updateInfo.getState() 可判断成员是进入（ENTERED）还是退出（EXITED）。

示例代码

ZIMEventHandler.onCommunityMemberStateChanged =
    (ZIM zim, ZIMCommunityMemberStateChangedEventResult result) {
    for (final updateInfo in result.updateInfoList) {
        if (updateInfo.state == ZIMCommunityMemberChangeState.Entered) {
            // 成员加入社群
        } else if (updateInfo.state == ZIMCommunityMemberChangeState.Exited) {
            // 成员离开社群
        }
    }
};

ZIMEventHandler.onCommunityMemberStateChanged =
    (ZIM zim, ZIMCommunityMemberStateChangedEventResult result) {
    for (final updateInfo in result.updateInfoList) {
        if (updateInfo.state == ZIMCommunityMemberChangeState.Entered) {
            // 成员加入社群
        } else if (updateInfo.state == ZIMCommunityMemberChangeState.Exited) {
            // 成员离开社群
        }
    }
};

成员信息更新

当社群成员的昵称、角色或禁言状态等信息发生变化时，SDK 会触发 onCommunityMemberInfoUpdated 回调。

示例代码

ZIMEventHandler.onCommunityMemberInfoUpdated =
    (ZIM zim, ZIMCommunityMemberInfoUpdatedEventResult result) {
    for (final updateInfo in result.updateInfoList) {
        final memberInfo = updateInfo.memberInfo;
        // memberInfo.memberRole：成员角色
        // memberInfo.muteInfo：禁言信息
    }
};

ZIMEventHandler.onCommunityMemberInfoUpdated =
    (ZIM zim, ZIMCommunityMemberInfoUpdatedEventResult result) {
    for (final updateInfo in result.updateInfoList) {
        final memberInfo = updateInfo.memberInfo;
        // memberInfo.memberRole：成员角色
        // memberInfo.muteInfo：禁言信息
    }
};

社群成员管理

功能简介

前提条件

邀请用户加入社群

踢出社群成员

更新社群成员角色

转让社群所有权

查询社群成员列表

查询指定成员信息

设置成员禁言

监听成员变更

成员状态变化

成员信息更新

相关参考