• UIKit
  • SDK
  • 服务端 API
Chat/
SDK/
Flutter/
会话/
SDK
  • 安装即时通信 IM SDK
    • 安装
  • 初始化即时通信 IM SDK
    • 初始化
  • 登录和注销
    • 登录和注销
  • 消息
    • 消息概述
    • 发送消息
    • 接收消息
    • 历史消息
    • 转发消息
    • 修改消息
    • 消息插入
    • 删除消息
    • 清空消息
    • 撤回消息
    • 在线消息
    • 已读回执
    • 查询消息
    • 群 @ 消息
    • 定向群消息
    • 通知免打扰
    • 消息扩展
  • 会话
    • 会话概述
    • 会话列表
    • 获取会话
    • 未读会话数
    • 置顶会话
    • 删除会话
    • 会话草稿
    • 会话组
  • 群组
    • 群组概述
    • 群组管理
    • 群资料
    • 群成员管理
    • 群成员资料
    • 自定义群属性
  • 用户
    • 用户资料
    • 好友管理
    • 好友列表
    • 黑名单
  • 离线推送
    • 离线推送
  • 信令
    • 信令管理
  • 局部搜索
    • 查找消息
    • 查找好友
    • 查找群组
    • 查找群成员
  • 接口参考文档
    • 客户接口
  • 开发指引
  • 控制台指南
    • 创建和升级应用
    • 基本配置
    • 功能配置
    • 账号管理
    • 群组管理
    • 回调配置
  • 产品介绍
    • 消息管理
      • 单聊消息
      • 消息存储
      • 离线推送
      • 群消息
      • 消息格式
    • 账号系统
      • 登陆验证
      • 在线状态管理
    • 群相关
      • 群组系统
      • 群组管理
    • 用户资料和关系链
      • 资料管理
      • 关系链管理
  • 购买指南
    • 计费概述
    • 价格中心
  • 错误码

会话列表

功能描述

用户在登录 App 后,可以展示最近会话列表,方便找到目标会话。 会话列表功能主要分为获取会话列表、处理会话列表更新。 本文将为您介绍具体的实现细节。

获取会话列表

您可以调用 getConversationList(点击查看详情) 获取会话列表。该接口拉取的是本地缓存的会话,如果服务器会话有更新,SDK 内部会自动同步,然后在 V2TIMConversationListener 回调告知客户。
用户的会话以列表的形式返回,列表中存储的是 V2TIMConversation 对象。目前 IM SDK 对会话列表的排序规则为:
Flutter sdk 3.8.0及以后版本, 该接口获取的会话列表默认已经按照会话对象的 orderKey 做了排序。orderKey 值越大,代表该会话排序越靠前。orderKey 字段是整型数,当发送新消息、接收新消息、设置草稿或置顶会话时,会话被激活,orderKey 字段会增大。
Flutter sdk 3.8.0 以前版本,该接口获取的会话列表默认已经按照会话 lastMessage -> timestamp 做了排序。timestamp 越大,会话越靠前。
注意:
在某些场景下,可能出现会话的 lastMessage 为空(例如清空会话消息)。如果您使用 5.5.892 以前的 SDK,使用 lastMessage 排序时需要额外处理这种异常。我们建议您升级到 5.5.892 及以后的版本,使用 orderKey 字段排序。
您可以使用 getConversationList 实现一次性拉取或分页拉取。参考下文说明。

一次性拉取

一次性拉取适合会话数量比较少的情况(100 个以内)。此时可以将拉取的 count 设置为 INT_MAX(一般会话数量不会达到 INT_MAX 这么多)。
示例代码如下:
V2TimValueCallback<V2TimConversationResult> convList = await TencentImSDKPlugin.v2TIMManager.getConversationManager().getConversationList(nextSeq: '0',count: 100);

分页拉取

如果您的应用场景会产生较多的会话数,考虑到加载效率、网络省流,我们建议您采用分页拉取的方式。每次分页拉取的数量建议不超过 100 个。
分页拉取的步骤:
1. 首次调用 getConversationList 时,指定参数 nextSeq 为 0(表示从头开始拉取会话列表),指定 count 为 50(表示一次拉取 50 个会话对象)。
2. 首次拉取会话列表成功后,getConversationList 的回调结果 V2TIMConversationResult 中会包含 nextSeq(下次分页拉取的字段)、isFinish(会话拉取是否完成)。
如果 isFinished 为 true,表示所有会话已经拉取完成。
如果 isFinished 为 false,表示还有更多的会话可以拉取。此时并不意味着要立刻开始拉取 “下一页” 的会话列表。在常见的通信软件中,分页拉取通常由用户的滑动操作触发的,用户每上拉一次会话列表就触发一次分页拉取。
3. 当用户继续上拉会话列表时,如果还有更多的会话可以拉取,可以继续调用 getConversationList 接口,并传入新一轮的 nextSeqcount 参数(数值来自上一次拉取返回的 V2TIMConversationResult 对象)。
4. 重复执行 步骤 3 直至 isFinished 返回 true。
示例代码如下:
//获取会话列表
V2TimValueCallback<V2TimConversationResult> getConversationListRes =
await TencentImSDKPlugin.v2TIMManager
.getConversationManager()
.getConversationList(
count: 100, //分页拉取的个数,一次分页拉取不宜太多,会影响拉取的速度,建议每次拉取 100 个会话
nextSeq: "0"//分页拉取的游标,第一次默认取传 0,后续分页拉传上一次分页拉取成功回调里的 nextSeq
);
if (getConversationListRes.code == 0) {
//拉取成功
bool? isFinished = getConversationListRes.data?.isFinished;//是否拉取完
String? nextSeq = getConversationListRes.data?.nextSeq;//后续分页拉取的游标
List<V2TimConversation?>? conversationList =
getConversationListRes.data?.conversationList;//此次拉取到的消息列表
//如果没有拉取完,使用返回的nextSeq继续拉取直到isFinished为true
if (!isFinished!) {
V2TimValueCallback<V2TimConversationResult> nextConversationListRes =
await TencentImSDKPlugin.v2TIMManager
.getConversationManager()
.getConversationList(count: 100, nextSeq: nextSeq = "0");//使用返回的nextSeq继续拉取直到isFinished为true
}

getConversationListRes.data?.conversationList?.forEach((element) {
element?.conversationID;//会话唯一 ID,如果是单聊,组成方式为 c2c_userID;如果是群聊,组成方式为 group_groupID。
element?.draftText;//草稿信息
element?.draftTimestamp;//草稿编辑时间,草稿设置的时候自动生成。
element?.faceUrl;//会话展示头像,群聊头像:群头像;单聊头像:对方头像。
element?.groupAtInfoList;//群会话 @ 信息列表,通常用于展示 “有人@我” 或 “@所有人” 这两种提醒状态。
element?.groupID;//当前群聊 ID,如果会话类型为群聊,groupID 会存储当前群的群 ID,否则为 null。
element?.groupType;//当前群聊类型,如果会话类型为群聊,groupType 为当前群类型,否则为 null。
element?.isPinned;//会话是否置顶
element?.lastMessage;//会话最后一条消息
element?.orderkey;//会话排序字段
element?.recvOpt;//消息接收选项
element?.showName;//会话展示名称,群聊会话名称优先级:群名称 > 群 ID;单聊会话名称优先级:对方好友备注 > 对方昵称 > 对方的 userID。
element?.type;//会话类型,分为 C2C(单聊)和 Group(群聊)。
element?.unreadCount;//会话未读消息数,直播群(AVChatRoom)不支持未读计数,默认为 0。
element?.userID;//对方用户 ID,如果会话类型为单聊,userID 会存储对方的用户 ID,否则为 null。
});
}

会话列表更新

IM SDK 会在登录成功后、用户上线后、以及断线重连后,自动更新会话列表。 为了获取会话列表的更新,您需要操作如下几步:
1. 添加会话监听器。
2. 接收会话变更通知并处理。
3. 移除会话监听器。非必须,可按照业务逻辑按需调用。

添加会话监听器

您可以调用 addConversationListener(点击查看详情) 添加会话监听器。添加监听器后,您才能接收到会话变更事件。
示例代码如下:
TencentImSDKPlugin.v2TIMManager.getConversationManager().addConversationListener(listener: V2TimConversationListener(onConversationChanged: (conversationList) {

},
//其他 ));

会话新增变更通知

您可以在 V2TIMConversationListener(点击查看详情) 中的事件,获取会话列表变更的通知。
目前 IM SDK 支持的会话变更事件有:
事件
说明
建议
onSyncServerStart
同步服务器会话开始
SDK 会在登录成功或者断网重连后自动同步服务器会话,您可以监听这个事件做一些 UI 进度展示操作。
onSyncServerFinish
同步服务器会话完成
如果会话有变更,会通过 onNewConversation/onConversationChanged 回调告知。
onSyncServerFailed
同步服务器会话失败
您可以监听这个事件做一些 UI 异常展示操作。
onNewConversation
有会话新增
例如收到一个新同事发来的单聊消息、被拉入了一个新的群组中,此时可以重新对会话列表做排序。
onConversationChanged
有会话更新
例如未读计数发生变化、最后一条消息被更新等,此时可以重新对会话列表做排序。
onTotalUnreadMessageCountChanged
会话未读总数变更通知
详情请参考 会话未读数
onConversationGroupCreated
会话分组被创建
会话分组相关能力。
onConversationGroupDeleted
会话分组被删除
会话分组相关能力。
onConversationGroupNameChanged
会话分组名变更
会话分组相关能力。
onConversationsAddedToGroup
会话分组新增会话
会话分组相关能力。
onConversationsDeletedFromGroup
会话分组删除会话
会话分组相关能力。
说明:
为保证会话列表顺序符合最后一条消息的排序原则,每次会话变更/新增后,您需要对数据源重新排序。
如果您使用 Flutter sdk 3.8.0 以前的版本,可以使用 lastMessage 排序,但是需要注意处理 lastMessage 为空(例如清空会话消息)的情况。
如果您使用 Flutter sdk 3.8.0 及以后的版本,使用 orderKey 字段排序。
我们强烈建议您升级到 Flutter sdk 3.8.0 及以后版本。
示例代码如下:
//设置群组监听器
V2TimGroupListener listener = V2TimGroupListener(onApplicationProcessed:
(String groupID, V2TimGroupMemberInfo opUser, bool isAgreeJoin,
String opReason) async {
//加群请求已经被群主或管理员处理了(只有申请人能够收到)
//groupID 群 ID
//opUser 处理人
//isAgreeJoin 是否同意加群
//opReason 处理原因
}, onGrantAdministrator: (String groupID, V2TimGroupMemberInfo opUser,
List<V2TimGroupMemberInfo> memberList) async {
//指定管理员身份
//groupID 群 ID
//opUser 处理人
//memberList 被处理的群成员
}, onGroupAttributeChanged:
(String groupID, Map<String, String> groupAttributeMap) async {
//收到群属性更新的回调
//groupID 群 ID
//groupAttributeMap 群的所有属性
}, onGroupCreated: (String groupID) async {
//创建群(主要用于多端同步)
//groupID 群 ID
}, onGroupDismissed: (String groupID, V2TimGroupMemberInfo opUser) async {
//群被解散了(全员能收到)
//groupID 群 ID
//opUser 处理人
}, onGroupInfoChanged:
(String groupID, List<V2TimGroupChangeInfo> changeInfos) async {
//群信息被修改(全员能收到)
//groupID 群 ID
//changeInfos 修改的群信息
}, onGroupRecycled: (String groupID, V2TimGroupMemberInfo opUser) async {
//群被回收(全员能收到)
//groupID 群 ID
//opUser 处理人
}, onMemberEnter:
(String groupID, List<V2TimGroupMemberInfo> memberList) async {
//有用户加入群(全员能够收到)
//groupID 群 ID
//memberList 加入的成员
}, onMemberInfoChanged: (String groupID,
List<V2TimGroupMemberChangeInfo> v2TIMGroupMemberChangeInfoList) async {
//群成员信息被修改,仅支持禁言通知(全员能收到)。
//groupID 群 ID
//v2TIMGroupMemberChangeInfoList 被修改的群成员信息
}, onMemberInvited: (String groupID, V2TimGroupMemberInfo opUser,
List<V2TimGroupMemberInfo> memberList) async {
//某些人被拉入某群(全员能够收到)
//groupID 群 ID
//opUser 处理人
//memberList 被拉进群成员
}, onMemberKicked: (String groupID, V2TimGroupMemberInfo opUser,
List<V2TimGroupMemberInfo> memberList) async {
//某些人被踢出某群(全员能够收到)
//groupID 群 ID
//opUser 处理人
//memberList 被踢成员
}, onMemberLeave: (String groupID, V2TimGroupMemberInfo member) async {
//有用户离开群(全员能够收到)
//groupID 群 ID
//member 离开的成员
}, onQuitFromGroup: (String groupID) async {
//主动退出群组(主要用于多端同步,直播群(AVChatRoom)不支持)
//groupID 群 ID
}, onReceiveJoinApplication:
(String groupID, V2TimGroupMemberInfo member, String opReason) async {
//有新的加群请求(只有群主或管理员会收到)
//groupID 群 ID
//member 申请人
//opReason 申请原因
}, onReceiveRESTCustomData: (String groupID, String customData) async {
//收到 RESTAPI 下发的自定义系统消息
//groupID 群 ID
//customData 自定义数据
}, onRevokeAdministrator: (String groupID, V2TimGroupMemberInfo opUser,
List<V2TimGroupMemberInfo> memberList) async {
//取消管理员身份
//groupID 群 ID
//opUser 处理人
//memberList 被处理的群成员
}, onTopicCreated: (String groupID, String topicID) async {
//话题创建通知
//groupID 创建话题的群组id
//topicID 创建的话题id
}, onTopicDeleted: (String groupID, List<String> topicIDList) async {
//话题创建通知
//groupID 删除话题的群组id
//topicIDList 删除的话题id列表
}, onTopicInfoChanged: (String groupID, V2TimTopicInfo topicInfo) async {
//话题信息更新通知
//groupID 话题信息更新的群组id
//topicInfo 话题信息更新的属性
});
//添加群组监听器
TencentImSDKPlugin.v2TIMManager.addGroupListener(listener: listener);

移除会话监听器

您可以调用 removeConversationListener(点击查看详情) 移除会话监听器。移除后,您将无法再接收到会话变更事件。 该步骤不是必须的,您可以按照自己的业务逻辑按需调用。
示例代码如下:
conversationManager.removeConversationListener(conversationListener);

发送不更新 lastMessage 的消息

会话列表界面,通常需要展示每个会话的最新一条消息预览及发送时间,此时您可以使用 V2TIMConversationlastMessage 作为数据源实现。但是某些场景下,如果您不希望一些消息(例如系统提示等)显示为会话的最新消息,可以在 sendMessage 时设置 isExcludedFromLastMessagefalse/no
发送消息参考 发送消息
说明:
isExcludedFromLastMessage 仅Flutter SDK 4.0.0 及以上版本支持。