本地最近会话

功能概述

最近会话列表，即最近联系人列表。当收到新联系人的消息时，SDK 会自动生成这个消息对应的本地最近会话。它记录了包括联系人帐号、联系人类型、最近一条消息的时间、消息状态、消息内容、未读条数等信息。

最近会话原型NIMSession：

以下表格中，类型末尾加“?”（如 “String?”）表示对应的参数为可选参数。

类型	属性	说明
String	sessionId	最近联系人的 ID（好友帐号，群 ID 等）
String？	senderAccount	获取与该联系人的最后一条消息的发送方的帐号
String？	senderNickname	获取与该联系人的最后一条消息的发送方的昵称
NIMSessionType	sessionType	获取会话类型
String？	lastMessageId	最近一条消息的消息 ID [NIMMessage.uuid]
NIMMessageType？	lastMessageType	获取最近一条消息的消息类型
NIMMessageStatus？	lastMessageStatus	获取最近一条消息状态
String?	lastMessageContent	获取最近一条消息的缩略内容。对于文本消息，返回文本内容。对于其他消息，返回一个简单的说明内容
int?	lastMessageTime	获取最近一条消息的时间，单位为 ms
NIMMessageAttachment?	lastMessageAttachment	如果最近一条消息是扩展消息类型，获取消息的附件内容. 在最近消息列表，第三方 app 可据此自主定义显示的缩略语
int?	unreadCount	获取该联系人的未读消息条数
Map<String, dynamic>?	extension	扩展字段
int?	tag	设置一个标签，用于做联系人置顶、最近会话列表排序等扩展用途。 SDK 不关心 tag 的意义。 第三方 app 需要事先规划好可能的用途

获取最近会话

获取最近会话列表，一般用于首页显示会话列表

获取最近会话列表

• API 原型

dartclass MessageService {
    /// 获取最近会话列表
    ///
    /// 最近会话列表，即最近联系人列表。当收到新联系人的消息时，SDK会自动生成这个消息对应的本地最近会话。
    /// 它记录了包括联系人帐号、联系人类型、最近一条消息的时间、消息状态、消息内容、未读条数等信息。
    ///
    /// [limit] 获取本地会话的数量，最大为100；如果不设置该值，会返回全量会话列表
    Future<NIMResult<List<NIMSession>>> querySessionList([int? limit]) async {
      return _platform.querySessionList(limit);
    }
}

• 示例

dartNIMResult<List<NIMSession>> result = await NimCore.instance.messageService.querySessionList(100);

获取最近会话列表(自定义)

过滤指定消息类型

当希望返回的会话的最近一条消息不是某一类消息时，可以使用以下过滤接口。

如希望最近一条消息为非文本消息时，使用该接口的返回的会话，将取最近的一条非文本的消息作为最近一条消息。

• API 原型

dartclass MessageService {
    /// [filterMessageType] 过滤消息类型
    Future<NIMResult<List<NIMSession>>> querySessionListFiltered(
        List<NIMMessageType> filterMessageTypeList);
}

• 示例

dartNIMResult<List<NIMSession>> result =
await NimCore.instance.messageService.querySessionListFiltered([NIMMessageType.text, NIMMessageType.image]);

获取指定的最近会话

dartclass MessageService {
    /// [sessionInfo] - 会话信息
    Future<NIMResult<NIMSession>> querySession(NIMSessionInfo sessionInfo);
}

创建最近会话

创建一个空的最近会话

dartclass MessageService {
    /// 创建一条空的联系人会话，并保存到数据库中
    /// [sessionId] - 会话id ，对方帐号或群组id。
    /// [sessionType] - 会话类型
    /// [tag] - 会话tag ， eg:置顶标签（UIKit中的实现： RECENT_TAG_STICKY），用户参照自己的tag 实现即可， 如不需要，传 0 即可
    /// [time] - 会话时间 ，单位为ms。
    /// [linkToLastMessage] - 是否放入最后一条消息的相关信息
    Future<NIMResult<NIMSession>> createSession({
        required String sessionId,
        required NIMSessionType sessionType,
        int tag = 0,
        required int time,
        bool linkToLastMessage = false,
      });
}

此外，当某条消息无对应的本地最近会话时，可以使用以下接口根据消息创建本地最近会话。

dartclass MessageService {
    /// 使用消息更新会话对象（Windows和macOS暂不支持）
    /// [message] 消息对象
    /// [needNotify] 是否需要发送通知
    Future<NIMResult<void>> updateSessionWithMessage({
      required NIMMessage message,
      bool needNotify = false,
    });
}

更新最近会话

更新最近会话

dartclass MessageService {
    /// 更新会话对象（Windows和macOS暂不支持）
    /// [needNotify] 是否需要发送通知
    /// 仅支持修改 tag 以及 extension
    Future<NIMResult<void>> updateSession({
      required NIMSession session,
      bool needNotify = false,
    });
}

监听最近会话变更

当最近会话对象以及其属性发生变更时，SDK 会更新对应聊天对象的最近联系人资料，并发出最近联系人更新通知。

• API 原型

dartclass MessageService {
    /// 最近会话更新
    Stream<List<NIMSession>> get onSessionUpdate;
}

未读数

获取未读数

• API 原型

dartclass MessageService {
    /// 获取未读数总数
    /// [queryType] 查询类型
    Future<NIMResult<int>> queryTotalUnreadCount({
        NIMUnreadCountQueryType queryType = NIMUnreadCountQueryType.all
    });
}

示例

dartNIMResult<int> result = await NimCore.instance.messageService.queryTotalUnreadCount();

清空指定会话未读数

• API 原型

dart/// 清除未读数
  ///
  /// [sessionInfoList] 请求列表
  ///
  /// 返回不能成功处理的请求列表
  Future<NIMResult<List<NIMSessionInfo>>> clearSessionUnreadCount(
    List<NIMSessionInfo> sessionInfoList,
  ) {
    return _platform.clearSessionUnreadCount(sessionInfoList);
  }

示例

dartNIMResult<List<NIMSessionInfo>> result = await  NimCore.instance.messageService.clearSessionUnreadCount(sessionInfoList);

清空所有会话的未读计数

• API 原型

dart
  /// 清空所有会话的未读计数
  ///
  Future<NIMResult<void>> clearAllSessionUnreadCount() {
    return _platform.clearAllSessionUnreadCount();
  }

示例

dartNIMResult<void> result = await  NimCore.instance.messageService.clearAllSessionUnreadCount();

删除最近会话

删除最近会话

• API 原型

dartclass MessageService {
    /// 删除最近联系人记录。
    /// 调用该接口后，会触发[MessageService.onSessionDelete]通知
    ///
    /// [deleteType] 删除类型，决定是否删除本地记录和漫游记录
    ///
    /// [sendAck] 如果参数合法，是否向其他端标记此会话为已读
    Future<NIMResult<void>> deleteSession({
        required NIMSessionInfo sessionInfo,
        required NIMSessionDeleteType deleteType,
        required bool sendAck,
      });
}

观察者通知

dartclass MessageService {
    /// 最近会话删除
    Stream<NIMSession> get onSessionDelete
}

Web 不支持该事件。