本地最近会话
功能概述
最近会话列表,即最近联系人列表。当收到新联系人的消息时,SDK会自动生成这个消息对应的本地最近会话。它记录了包括联系人帐号、联系人类型、最近一条消息的时间、消息状态、消息内容、未读条数等信息。
原型是RecentContact
,接口说明如下:
返回值 | RecentContact 接口 | 说明 |
---|---|---|
MsgAttachment | getAttachment() | 获取最近一条消息的附件内容 |
String | getContactId() | 获取最近联系人的 ID(好友帐号,群 ID 等) |
String | getContent() | 获取最近一条消息的缩略内容 |
Map | getExtension() | 获取最近会话对象的扩展字段 |
String | getFromAccount() | 获取最近一条消息的发送方的帐号 |
String | getFromNick() | 获取与该联系人的最近一条消息的发送方的昵称 |
MsgStatusEnum | getMsgStatus() | 获取最近一条消息状态 |
MsgTypeEnum | getMsgType() | 获取最近一条消息的消息类型 |
String | getRecentMessageId() | 获取最近一条消息的客户端ID, 即 IMMessage#getUuid() |
SessionTypeEnum | getSessionType() | 获取会话类型,是单聊还是群聊等 |
long | getTag() | 获取标签属性 |
long | getTime() | 获取最近一条消息的时间,单位为 ms |
int | getUnreadCount() | 获取未读消息条数 |
void | setExtension(Map extension) | 设置最近会话对象的扩展字段 |
void | setMsgStatus(MsgStatusEnum msgStatus) | 设置最近一条消息的状态 |
void | setTag(long tag) | 设置一个标签,用于做联系人置顶、最近会话列表排序等扩展用途。 |
获取最近会话
获取最近会话列表,一般用于首页显示会话列表
获取最近会话列表
- 异步接口:
/**
* 查询最近联系人列表数据
*
* @return InvocationFuture
*/
public InvocationFuture<List<RecentContact>> queryRecentContacts();
- 同步接口:
/**
* 查询最近联系人列表数据(同步接口)
*
* @return InvocationFuture
*/
public List<RecentContact> queryRecentContactsBlock();
- 示例
NIMClient.getService(MsgService.class).queryRecentContacts()
.setCallback(new RequestCallbackWrapper<List<RecentContact>>() {
@Override
public void onResult(int code, List<RecentContact> recents, Throwable e) {
// recents参数即为最近联系人列表(最近会话列表)
}
});
获取最近会话列表(自定义)
过滤指定消息类型
当希望返回的会话的最近一条消息不是某一类消息时,可以使用以下过滤接口。
如希望最近一条消息为非文本消息时,使用该接口的返回的会话,将取最近的一条非文本的消息作为最近一条消息。
- 异步接口:
/**
* 查询最近联系人列表数据
*
* @return InvocationFuture
*/
public InvocationFuture<List<RecentContact>> queryRecentContacts(MsgTypeEnum filterMsgType);
- 同步接口:
/**
* 查询最近联系人列表数据, 过滤指定消息类型(同步接口)
*
* @return InvocationFuture
*/
public List<RecentContact> queryRecentContactsBlock(MsgTypeEnum filterMsgType);
- 示例
NIMClient.getService(MsgService.class).queryRecentContacts(MsgTypeEnum.text)
.setCallback(new RequestCallbackWrapper<List<RecentContact>>() {
@Override
public void onResult(int code, List<RecentContact> recents, Throwable e) {
// recents参数即为最近联系人列表(最近会话列表)
}
});
获取少量会话
可以获取指定数量的最近会话:
- 异步接口
/**
* 查询最近联系人会话列表数据, 可以设置limit, 防止本地会话过多时,导致第一次加载慢
*
* @param limit 获取本地会话的数量,最大100,超过100修正到100
* @return InvocationFuture
*/
InvocationFuture<List<RecentContact>> queryRecentContacts(int limit);
- 同步接口
/**
* 查询最近联系人会话列表数据(同步接口),可以设置limit, 防止本地会话过多时,导致第一次加载慢
*
* @param limit 获取本地会话的数量,最大100,超过100修正到100
*/
List<RecentContact> queryRecentContactsBlock(int limit);
- 示例
NIMClient.getService(MsgService.class).queryRecentContacts(10);
获取指定的最近会话
v5.9.0版本开始,支持通过会话id获取对应的会话。
/**
* 查询最近联系人会话列表数据(同步接口),可以设置limit, 防止本地会话过多时,导致第一次加载慢
* @param contactId - 会话id ,对方帐号或群组id。
* @param sessionType - 会话类型。
*/
RecentContact queryRecentContact(java.lang.String contactId, SessionTypeEnum sessionType);
创建最近会话
创建一个空的最近会话:
/**
* @param contactId - 会话id ,对方帐号或群组id。
* @param sessionType - 会话类型。
* @param tag - 会话tag , eg:置顶标签(UIKit中的实现: RECENT_TAG_STICKY) ,用户参照自己的tag 实现即可, 如不需要,传 0 即可。
* @param time - 会话时间 ,单位为ms。
* @param saveToDB - 是否需要将会话保存在DB中,注意以下两点:
1,如果已经存在相同的会话(contactId 、sessionType 一样),则不会保存在db中;
2,如果之前不存在相同的会话,且needSaveToDB为true 会触发MsgServiceObserve.observeRecentContact(Observer, boolean)通知;
*/
RecentContact createEmptyRecentContact(java.lang.String contactId,
SessionTypeEnum sessionType,
long tag,
long time,
boolean saveToDB);
此外,当某条消息无对应的本地最近会话时,可以使用以下接口根据消息创建本地最近会话。
/**
* @param message - 消息。
* @param needNotify - 是否需要触发MsgServiceObserve.observeRecentContact(Observer, boolean)的通知
*/
void updateRecentByMessage(IMMessage message, boolean needNotify);
更新最近会话
更新最近会话
/**
* 更新一条最近联系人会话的属性。目前可设置的属性有:tag, extension。
* @param recent - 待更新的最近联系人会话数据
*/
void updateRecent(RecentContact recent);
如果想收到 MsgServiceObserve.observeRecentContact(Observer, boolean) 的通知, 可使用以下接口进行更新:
/**
* 更新一条最近联系人会话的属性。目前可设置的属性有:tag, extension。
* @param recent - 待更新的最近联系人会话数据
*/
void updateRecentAndNotify(RecentContact recent);
监听最近会话变更
当最近会话对象以及其属性发生变更时,SDK 会更新对应聊天对象的最近联系人资料,并发出最近联系人更新通知。
- API 原型
/**
* 注册/注销最近联系人列表变化观察者
* @param observer 观察者,参数为变化的最近联系人列表
* @param register true为注册,false为注销
*/
public void observeRecentContact(Observer<List<RecentContact>> observer, boolean register);
- 示例
// 创建观察者对象
Observer<List<RecentContact>> messageObserver = new Observer<List<RecentContact>>() {
@Override
public void onEvent(List<RecentContact> messages) {
}
}
// 注册/注销观察者
NIMClient.getService(MsgServiceObserve.class).observeRecentContact(messageObserver, register);
未读数
获取未读数
获取总未读数
/**
* 获取未读数总数
*/
public int getTotalUnreadCount();
示例
int unreadNum = NIMClient.getService(MsgService.class).getTotalUnreadCount();
获取单个会话未读数
通过 RecentContact - getUnreadCount()
方法获取。
重置未读数
调用以下接口重置当前会话,SDK会自动管理消息的未读数。该接口会自动调用clearUnreadCount(String, SessionTypeEnum)
将正在聊天对象的未读数清零。如果有新消息到达,且消息来源是正在聊天的对象,其未读数也不会递增。
/**
* 设置当前会话
* @param account, - 聊天对象帐号,或者以下两个值:MSG_CHATTING_ACCOUNT_ALL与MSG_CHATTING_ACCOUNT_NONE。
* @param sessionType 会话类型。如果account不是具体的对象,该参数将被忽略
*/
void setChattingAccount(java.lang.String account, SessionTypeEnum sessionType);
一般在退出聊天界面时,需要恢复更新未读数:
// 恢复更新未读数
NIMClient.getService(MsgService.class).setChattingAccount(MsgService.MSG_CHATTING_ACCOUNT_NONE, SessionTypeEnum.None);
如果需要不进入聊天窗口就将未读数清零,可以调用如下接口来实现:
/**
* 将指定最近联系人的未读数清零(标记已读)。<br>
* 调用该接口后,会触发{@link MsgServiceObserve#observeRecentContact(Observer, boolean)} 通知
*
* @param account 聊天对象帐号
* @param sessionType 会话类型
*/
void clearUnreadCount(String account, SessionTypeEnum sessionType);
/**
* 将指定最近联系人的未读数清零(标记已读)。<br>
* 调用该接口后,会触发{@link MsgServiceObserve#observeRecentContact(Observer, boolean)} 通知
*
* @param sessionKeyList 聊天对象帐号,第一个元素为account, 第二个元素为会话类型
*/
void clearUnreadCount(List<Pair<String, SessionTypeEnum>> sessionKeyList);
/**
* 将所有联系人的未读数清零(标记已读)
* 调用该接口后,会触发{@link MsgServiceObserve#observeRecentContact(Observer, boolean)} 通知
*/
void clearAllUnreadCount();
未读数多端同步
开启会话的未读数多端同步后,在其中一个客户端读过的会话在其它端也会被标记为已读。
开启方法:设置 SDKOptions - sessionReadAck
属性为 true 。
删除最近会话
删除最近会话
SDK 支持删除指定的本地和云端最近会话。但会保留会话内的消息。调用时,总未读消息数会减去当前会话的未读数。
- API 介绍
MsgService 提供了三种方法: 其中deleteRecentContact(RecentContact) 和 deleteRecentContact2(String, SessionTypeEnum)的区别在于后者会触发 MsgServiceObserve#observeRecentContactDeleted 通知。另一个接口不会触发MsgServiceObserve#observeRecentContactDeleted,而且可以配置是否同时删除漫游消息
- API 原型
不触发观察者通知版本:
/**
* 从最近联系人列表中删除一项。
* 调用这个接口删除数据后,不会引发观察者通知。
*
* @param recent 待删除的最近联系人项
*/
public void deleteRecentContact(RecentContact recent);
触发观察者通知版本:
/**
* 删除最近联系人记录。
* 调用该接口后,会触发{@link MsgServiceObserve#observeRecentContactDeleted(Observer, boolean)}通知
*
* @param account
* @param sessionType
*/
public void deleteRecentContact2(String account, SessionTypeEnum sessionType);
可配置版本:
/**
* 删除最近联系人记录。<br>
*
* @param account 会话ID
* @param sessionType 会话类型,只能选{@link SessionTypeEnum#P2P}和{@link SessionTypeEnum#Team}会删漫游消息
* @param deleteType 删除类型,决定是否删除本地记录和漫游记录,
* 如果为null,视为{@link DeleteTypeEnum#REMAIN}
* @param sendAck 如果参数合法,是否向其他端标记此会话为已读
*/
InvocationFuture<Void> deleteRecentContact(String account, SessionTypeEnum sessionType, DeleteTypeEnum deleteType, boolean sendAck);
- 示例
// 不触发观察者通知版本
NIMClient.getService(MsgService.class).deleteRecentContact(recent);
//触发观察者通知版本
NIMClient.getService(MsgService.class).deleteRecentContact2(account, SessionTypeEnum.P2P);
// 可配置版本,配置既删本地会话,也删除漫游消息。而且要发送ACK
NIMClient.getService(MsgService.class).deleteRecentContact(sessionId, sessionType, DeleteTypeEnum.LOCAL_AND_REMOTE, true)
.setCallback(deleteRecentCallback);
删除漫游消息
SDK 支持删除指定联系人的漫游消息,可以通过以下方法实现:
- API 原型
/**
* 删除指定最近联系人的漫游消息。
* 不删除本地消息,但如果在其他端登录,当前时间点该会话已经产生的消息不漫游。
*
* @return InvocationFuture 可设置回调函数,监听删除结果。
*/
public InvocationFuture<Void> deleteRoamingRecentContact(String contactId, SessionTypeEnum sessionTypeEnum);
- 参数说明
参数 | 说明 |
---|---|
contactId | 最近联系人的 ID(好友帐号,群 ID 等) |
sessionTypeEnum | 会话类型 |
- 示例
NIMClient.getService(MsgService.class)
.deleteRoamingRecentContact(contactId, sessionTypeEnum)
.setCallback(new RequestCallback<Void>() { ... });


此文档对你是否有帮助

