频道管理

2026-06-24

功能简介

频道（Channel）是社群内聊天互动的基本载体，功能类似传统群组，每个社群可包含多个频道。ZIM SDK 提供了完整的频道管理能力，支持以下功能：

创建/解散频道
更新频道名称、头像、公告
设置/删除频道自定义属性
查询频道信息及列表
设置频道禁言状态
监听频道列表变更与信息更新

前提条件

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

频道类型说明

类型	说明	加入方式	可见性
GENERAL	默认频道，创建社群时自动创建，社群级别的 Tips 和通知会发在此频道	自动加入	所有成员可见
PUBLIC	公开频道，需要创建社群之后再创建	自动加入	所有成员可见

说明

GENERAL 和 PUBLIC 功能完全一样，区别仅在于创建时机：GENERAL 在创建社群时自动创建，PUBLIC 需要在创建社群后手动创建。

创建频道

加入社群后，调用 createCommunityChannel 接口，传入频道基础信息 ZIMCommunityChannelInfo 与创建配置 ZIMCommunityChannelCreateConfig 在指定社群中创建频道。

说明

只有社群群主和管理员有权限创建频道。
创建社群时系统会自动创建一个类型为 GENERAL 的默认频道；开发者可以在此基础上创建更多公开频道（PUBLIC）。
channelID 支持开发者自定义，仅支持数字、英文字符及以下特殊字符：! # $ % & ( ) + - : ; < = . > ? @ [ ] ^ _ { } | ~，但不能以 # 开头。若不填，ZIM 服务端会创建以 #C 开头的 channelID 的频道。
创建成功后即已加入频道，无需再调用加入接口。

示例代码

ZIMCommunityChannelInfo channelInfo = ZIMCommunityChannelInfo()
  ..channelID = 'channel_001'
  ..channelName = '公告频道' //最大长度300字符，可配置
  ..channelAvatarUrl = 'https://example.com/channel_avatar.png' //最大长度100字符，可配置
  ..communityID = communityID;

ZIMCommunityChannelCreateConfig config = ZIMCommunityChannelCreateConfig()
  ..channelNotice = '这是频道公告' //最大长度500字符，可配置
  ..channelAttributes = {'type': 'announcement'};

try {
    ZIMCommunityChannelCreatedResult result =
        await ZIM.getInstance()!.createCommunityChannel(channelInfo, config);
    // result.channelFullInfo 包含频道完整信息
} on PlatformException catch (onError) {
    // 创建失败
}

ZIMCommunityChannelInfo channelInfo = ZIMCommunityChannelInfo()
  ..channelID = 'channel_001'
  ..channelName = '公告频道' //最大长度300字符，可配置
  ..channelAvatarUrl = 'https://example.com/channel_avatar.png' //最大长度100字符，可配置
  ..communityID = communityID;

ZIMCommunityChannelCreateConfig config = ZIMCommunityChannelCreateConfig()
  ..channelNotice = '这是频道公告' //最大长度500字符，可配置
  ..channelAttributes = {'type': 'announcement'};

try {
    ZIMCommunityChannelCreatedResult result =
        await ZIM.getInstance()!.createCommunityChannel(channelInfo, config);
    // result.channelFullInfo 包含频道完整信息
} on PlatformException catch (onError) {
    // 创建失败
}

解散频道

调用 dismissCommunityChannel 接口解散指定社群中的频道，频道解散后所有成员将无法再访问该频道。

注意

类型为 GENERAL 的默认频道不可解散。

示例代码

try {
    await ZIM.getInstance()!.dismissCommunityChannel(channelID, communityID);
    // 解散成功
} on PlatformException catch (onError) {
    // 解散失败
}

try {
    await ZIM.getInstance()!.dismissCommunityChannel(channelID, communityID);
    // 解散成功
} on PlatformException catch (onError) {
    // 解散失败
}

更新频道资料

社群所有者和管理员可以更新频道的名称、头像和公告。

更新频道名称

调用 updateCommunityChannelName 接口更新频道名称。频道名称最大长度300字符，可配置。

示例代码

try {
    await ZIM.getInstance()!
        .updateCommunityChannelName('新的频道名称', channelID, communityID);
    // 更新成功
} on PlatformException catch (onError) {
    // 更新失败
}

try {
    await ZIM.getInstance()!
        .updateCommunityChannelName('新的频道名称', channelID, communityID);
    // 更新成功
} on PlatformException catch (onError) {
    // 更新失败
}

更新频道头像

调用 updateCommunityChannelAvatarUrl 接口更新频道头像。频道头像最大长度100字符，可配置。

示例代码

try {
    await ZIM.getInstance()!.updateCommunityChannelAvatarUrl(
        'https://example.com/new_channel_avatar.png', channelID, communityID);
    // 更新成功
} on PlatformException catch (onError) {
    // 更新失败
}

try {
    await ZIM.getInstance()!.updateCommunityChannelAvatarUrl(
        'https://example.com/new_channel_avatar.png', channelID, communityID);
    // 更新成功
} on PlatformException catch (onError) {
    // 更新失败
}

更新频道公告

调用 updateCommunityChannelNotice 接口更新频道公告内容。频道公告最大长度500字符，可配置。

示例代码

try {
    await ZIM.getInstance()!
        .updateCommunityChannelNotice('新的频道公告内容', channelID, communityID);
    // 更新成功
} on PlatformException catch (onError) {
    // 更新失败
}

try {
    await ZIM.getInstance()!
        .updateCommunityChannelNotice('新的频道公告内容', channelID, communityID);
    // 更新成功
} on PlatformException catch (onError) {
    // 更新失败
}

设置频道属性

频道属性以键值对形式存储，可用于扩展频道的自定义信息。

设置属性

调用 setCommunityChannelAttributes 接口，批量设置频道自定义属性。操作失败的键名将通过 errorKeys 返回。

示例代码

Map<String, String> channelAttributes = {'key1': 'value1', 'key2': 'value2'};

try {
    ZIMCommunityChannelAttributesOperatedResult result =
        await ZIM.getInstance()!
            .setCommunityChannelAttributes(channelAttributes, channelID, communityID);
    // result.errorKeys 列出失败的键
} on PlatformException catch (onError) {
    // 操作失败
}

Map<String, String> channelAttributes = {'key1': 'value1', 'key2': 'value2'};

try {
    ZIMCommunityChannelAttributesOperatedResult result =
        await ZIM.getInstance()!
            .setCommunityChannelAttributes(channelAttributes, channelID, communityID);
    // result.errorKeys 列出失败的键
} on PlatformException catch (onError) {
    // 操作失败
}

删除属性

调用 deleteCommunityChannelAttributes 接口，按键名批量删除频道属性。

示例代码

List<String> keys = ['key1', 'key2'];

try {
    await ZIM.getInstance()!
        .deleteCommunityChannelAttributes(keys, channelID, communityID);
    // 删除成功
} on PlatformException catch (onError) {
    // 删除失败
}

List<String> keys = ['key1', 'key2'];

try {
    await ZIM.getInstance()!
        .deleteCommunityChannelAttributes(keys, channelID, communityID);
    // 删除成功
} on PlatformException catch (onError) {
    // 删除失败
}

查询频道信息

调用 queryCommunityChannelsInfo 接口，批量查询指定频道的完整信息，包括频道名称、头像、公告、禁言状态等。查询失败的频道 ID 将通过 errorChannelIDs 返回。

示例代码

List<String> channelIDs = ['channel_001', 'channel_002'];

try {
    ZIMCommunityChannelsInfoQueriedResult result =
        await ZIM.getInstance()!.queryCommunityChannelsInfo(channelIDs, communityID);
    // result.channelInfos 包含各频道完整信息
} on PlatformException catch (onError) {
    // 查询失败
}

List<String> channelIDs = ['channel_001', 'channel_002'];

try {
    ZIMCommunityChannelsInfoQueriedResult result =
        await ZIM.getInstance()!.queryCommunityChannelsInfo(channelIDs, communityID);
    // result.channelInfos 包含各频道完整信息
} on PlatformException catch (onError) {
    // 查询失败
}

查询频道列表

调用 queryCommunityChannelList 接口，分页拉取指定社群中的所有频道列表。返回的频道对象 ZIMCommunityChannel 中的 conversationID 字段，即是后续收发消息时所需的会话 ID。

分页规则与查询社群列表一致：首次将 config.nextFlag 设为 0，后续将返回的 nextFlag 传入下次请求，直到返回 0 为止。count 取值范围 1-100，推荐值 20。

示例代码

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

try {
    ZIMCommunityChannelListQueriedResult result =
        await ZIM.getInstance()!.queryCommunityChannelList(communityID, 100, config);
    // result.channelList 为频道列表
} on PlatformException catch (onError) {
    // 查询失败
}

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

try {
    ZIMCommunityChannelListQueriedResult result =
        await ZIM.getInstance()!.queryCommunityChannelList(communityID, 100, config);
    // result.channelList 为频道列表
} on PlatformException catch (onError) {
    // 查询失败
}

设置频道禁言

调用 muteCommunityChannels 接口，批量设置指定频道的禁言状态。禁言配置通过 ZIMCommunityChannelMuteConfig 传入。

channelIDs 和 communityID 是接口方法的直接参数，非 config 配置字段。

配置字段	说明
`mode`	禁言范围。枚举值对照：`NONE`(0) = 不禁言、`NORMAL`(1) = 禁言普通成员、`ALL`(2) = 全员禁言、`CUSTOM`(3) = 自定义角色范围
`duration`	禁言时长（秒），取值范围 1-2592001（约 30 天），或 `-1` 表示永久禁言
`roles`	当 `mode` 为 `CUSTOM` 时，指定被禁言的角色列表

操作失败的频道 ID 将通过 errorChannelIDs 返回。详细操作请参考社群禁言。

示例代码

List<String> channelIDs = ['channel_001', 'channel_002'];
ZIMCommunityChannelMuteConfig config = ZIMCommunityChannelMuteConfig()
  ..duration = 3600
  ..mode = ZIMCommunityChannelMuteMode.all;

try {
    ZIMCommunityChannelsMutedResult result =
        await ZIM.getInstance()!
            .muteCommunityChannels(true, channelIDs, communityID, config);
    // result.errorChannelIDs 列出失败的频道
} on PlatformException catch (onError) {
    // 操作失败
}

List<String> channelIDs = ['channel_001', 'channel_002'];
ZIMCommunityChannelMuteConfig config = ZIMCommunityChannelMuteConfig()
  ..duration = 3600
  ..mode = ZIMCommunityChannelMuteMode.all;

try {
    ZIMCommunityChannelsMutedResult result =
        await ZIM.getInstance()!
            .muteCommunityChannels(true, channelIDs, communityID, config);
    // result.errorChannelIDs 列出失败的频道
} on PlatformException catch (onError) {
    // 操作失败
}

监听频道变更

频道列表变更

当社群中频道被创建或解散，导致频道列表发生变化时，SDK 会触发 onCommunityChannelListChanged 回调。changeInfoList 包含各变更频道的变更类型及频道信息。

示例代码

ZIMEventHandler.onCommunityChannelListChanged =
    (ZIM zim, ZIMCommunityChannelListChangedEventResult result) {
    for (final changeInfo in result.changeInfoList) {
        // changeInfo 包含频道变更信息
    }
};

ZIMEventHandler.onCommunityChannelListChanged =
    (ZIM zim, ZIMCommunityChannelListChangedEventResult result) {
    for (final changeInfo in result.changeInfoList) {
        // changeInfo 包含频道变更信息
    }
};

频道信息更新

当频道资料（名称、头像、公告、属性、禁言状态等）发生变化时，SDK 会触发 onCommunityChannelInfoUpdated 回调。updateInfoList 包含变更后的频道完整信息。

示例代码

ZIMEventHandler.onCommunityChannelInfoUpdated =
    (ZIM zim, ZIMCommunityChannelInfoUpdatedEventResult result) {
    for (final updateInfo in result.updateInfoList) {
        // updateInfo 包含更新后的频道信息
    }
};

ZIMEventHandler.onCommunityChannelInfoUpdated =
    (ZIM zim, ZIMCommunityChannelInfoUpdatedEventResult result) {
    for (final updateInfo in result.updateInfoList) {
        // updateInfo 包含更新后的频道信息
    }
};

频道管理

功能简介

前提条件

频道类型说明

创建频道

解散频道

更新频道资料

更新频道名称

更新频道头像

更新频道公告

设置频道属性

设置属性

删除属性

查询频道信息

查询频道列表

设置频道禁言

监听频道变更

频道列表变更

频道信息更新

相关参考