IM UIKit 支持云端会话分组功能。本文档旨在帮助开发者快速将会话分组能力集成到您的应用中，主要介绍如何开启、配置和使用该功能。

功能介绍

会话分组用于在云端会话列表中对会话进行分类和筛选。启用后，会话列表顶部会展示分组栏，默认包含以下分组：

分组	说明
全部	展示全部云端会话
@我	展示存在 @ 我消息的会话
未读	展示存在未读消息的会话
自定义分组	展示用户创建并设置为可见的会话分组

用户可在分组管理页面中执行以下操作：

• 创建、重命名、删除自定义分组
• 将会话添加到分组或从分组中移除
• 调整分组的显示状态和展示顺序

前提条件

使用会话分组功能前，请确认满足以下条件：

• 使用 IM UIKit 10.9.50 或更高版本，并保持 NEChatKit、NEConversationUIKit 等 IM UIKit 模块版本一致。
• 应用使用 云端会话模式，并在初始化 IM UIKit 前将 V2NIMSDKOption.enableV2CloudConversation 设置为 true。
• 集成的是云端会话列表组件 NEConversationUIKit；本地会话列表组件 NELocalConversationUIKit 不展示分组功能。
• IM UIKit 已完成初始化并登录云信 IM。
• 应用的云信账号和 AppKey 已开通云端会话及会话分组服务。
• 应用的最低部署版本为 iOS 13.0。

实现步骤

添加依赖

在应用的 Podfile 中添加云端会话列表组件依赖：

rubytarget 'YourApp' do
  pod 'NEConversationUIKit', '10.9.50'
end

NEConversationUIKit 会依赖 NEChatKit、NEBaseUIKit 等基础组件。若项目同时显式依赖多个 IM UIKit 组件，请统一使用相同版本，避免版本不一致。

开启云端会话

会话分组依赖云端会话服务。初始化 IM UIKit 时，需通过 V2NIMSDKOption 开启云端会话。

enableV2CloudConversation 属于初始化配置，必须 在调用 IMKitClient.instance.setupIM2 前设置。

swiftimport NEChatKit
import NIMSDK

let option = NIMSDKOption()
option.appKey = "YOUR_APP_KEY"

let v2Option = V2NIMSDKOption()
v2Option.enableV2CloudConversation = true

IMKitClient.instance.setupIM2(option, v2Option)

配置会话分组开关

建议在进入会话列表页面前完成配置。运行期间修改开关后，需重新进入会话列表页面，或让已有页面重新进入前台以生效。

该配置为进程内全局配置，不负责持久化。如需允许用户自行开关此功能，请由应用保存用户选择，并在下次启动时重新设置。

会话分组 UI 由 IMKitConfigCenter.shared.enableConversationGroup 控制，默认值为 true。

参数	类型	说明	默认值
enableConversationGroup	Bool	控制是否启用会话分组 UI。设为 false 时，UI 层不展示会话分组功能。	true

swiftimport NEChatKit

// 开启会话分组
IMKitConfigCenter.shared.enableConversationGroup = true

// 关闭会话分组
IMKitConfigCenter.shared.enableConversationGroup = false

开关生效规则

会话分组仅在以下 两个条件同时满足 时展示：

textV2NIMSDKOption.enableV2CloudConversation == true
                         AND
IMKitConfigCenter.shared.enableConversationGroup == true

不同配置组合的结果如下：

云端会话	会话分组开关	会话列表表现
开启	开启	展示会话分组栏及分组管理入口。
开启	关闭	不展示会话分组 UI，按照普通云端会话列表展示。
关闭	开启或关闭	不展示分组 UI（NELocalConversationUIKit 本地会话模式不支持该功能）。

关闭 enableConversationGroup 仅隐藏 UIKit 提供的分组 UI，不会 删除已创建的云端分组，也 不会 清除分组中的会话数据。重新开启后，云端分组仍可继续使用。

用户侧操作流程

启用功能后，用户可通过会话列表完成以下操作：

操作	说明
切换分组	点击顶部的 “全部”、“@我”、“未读” 或自定义分组，筛选当前会话列表
进入管理页	点击分组栏右侧的管理入口，进入会话分组管理页面
创建分组	创建自定义分组。最多支持 10 个，名称最长 20 个字符
显示管理	设置分组显示或隐藏，调整可见分组的展示顺序
分组设置	进入自定义分组设置页，修改名称、添加会话、移除会话或删除分组

单个自定义分组最多添加 100 个会话。其他服务端数量限制以云信 IM 服务配置和对应错误码为准。

内部实现逻辑

分组数据组成

UIKit 将内置筛选项与云端自定义分组合并展示：

数据来源	说明
内置分组	“全部”、“@我”、“未读” 由 UIKit 构建，其中 “@我” 和 “未读” 属于本地筛选入口
云端分组	自定义分组的名称、ID 和会话成员关系来自云端会话分组服务，支持多端同步
本地配置	分组是否显示及展示顺序保存在当前设备本地配置中，按登录账号隔离，不同步至其他设备

在其他设备创建并同步过来的新自定义分组，若当前设备尚无本地展示配置，会默认进入 隐藏分组区域，用户可在管理页面中手动设为可见。

数据加载与筛选

进入云端会话列表后，UIKit 按以下流程加载数据：

text1. “全部” → 直接展示当前云端会话列表
2. “@我” / “未读” → 基于当前会话数据筛选；当前分页无匹配项但仍有更多会话时，继续加载下一页
3. 自定义分组 → 按分组 ID 分页查询该分组中的云端会话，并进行缓存和排序
4. 网络恢复 → 重新加载会话分组数据

默认会话列表分页和自定义分组选择均由 ConversationGroupViewModel 管理，当前分组页大小为 50；管理页加载成员时使用独立分页状态。

未读数更新

UIKit 会分别查询默认筛选条件和各自定义分组的未读数，并订阅筛选未读数变化通知。查询过滤器会设置 ignoreMuted = true。收到通知后，仅更新对应分组的未读数，无需重新加载整个会话列表；“@我” 数量根据当前会话数据本地计算。

多端变更同步

UIKit 通过 ConversationGroupRepo 监听以下云端会话分组事件：

• 创建分组
• 删除分组
• 修改分组信息
• 向分组添加会话
• 从分组移除会话

收到事件后，UIKit 会刷新受影响的分组数据、会话缓存和未读数。分组的 本地显示状态与排序不参与多端同步。

源码说明

模块	主要职责	关键代码
NEChatKit	提供会话分组全局开关，封装会话分组仓储和 SDK Provider	IMKitConfigCenter.swift、ConversationGroupRepo.swift、ConversationGroupProvider.swift
NEConversationUIKit	提供分组栏、管理页面、设置页面及数据状态与 UI 交互	NEBaseConversationController.swift、ConversationGroupViewModel.swift、NEConversationGroupBar.swift
	保存当前账号在本设备的分组显示状态和排序	NEConversationGroupLocalConfigHelper.swift
app	展示云端会话分组初始化配置和开关的示例用法	SceneDelegate.swift、ConfigTestViewController.swift

主要调用关系

textNEBaseConversationController
        ↓
ConversationGroupViewModel
        ↓
ConversationGroupRepo
        ↓
ConversationGroupProvider
        ↓
云信 IM SDK 会话分组服务

注意事项

• enableConversationGroup 是 UIKit 展示开关，不等同于 SDK 的云端会话开关，两者需要同时开启。
• 关闭 UIKit 开关不会删除云端分组数据。
• 分组显示状态和排序为本地配置，多端之间可能不同；自定义分组本身及成员关系由云端同步。
• 会话分组功能不适用于 NELocalConversationUIKit 本地会话列表。
• 切换账号时，本地展示配置会按账号隔离。
• 创建、修改、删除分组以及增删分组会话需要可用网络；失败时 UIKit 会根据服务端错误码展示对应提示。