Merge pull request #988 from haoxiuwen/flutter481

Add Flutter SDK 4.8.1 Release Notes

Author: haoxiuwen

docs/document/flutter/message_retrieve.md

@@ -168,4 +168,19 @@ EMConversation? conv =
       // 每次获取的消息数量。取值范围为 [1,400]。
       count: 50,
     );
+```
+
+### 获取会话在一定时间内的消息数
+
+你可以调用 `loadMessagesFromTime` 方法从 SDK 本地数据库中获取会话在某个时间段内的全部消息数。
+
+```dart
+EMConversation? conversation =
+    await EMClient.getInstance.chatManager.getConversation(conversationId);
+if (conversation != null) {
+    List<EMMessage> messages = await conversation.loadMessagesFromTime(
+    startTime: startMs,
+    endTime: endMs,
+    );
+}
 ```

docs/document/flutter/message_search.md

@@ -11,6 +11,8 @@
 - `EMChatManager.searchMsgFromDB`：根据关键字搜索会话消息。
 - `EMChatManager#loadMessagesWithKeyword`：根据搜索范围搜索所有会话中的消息。
 - `EMConversation#loadMessagesWithKeyword`：根据搜索范围搜索当前会话中的消息。
+- `EMChatManager#searchMsgsByOptions`：根据单个或多个消息类型，搜索本地数据库中所有会话的消息。
+- `EMConversation#searchMsgsByOptions` 根据单个或多个消息类型，搜索本地数据库中单个会话的消息。
 
 ## 前提条件
 
@@ -90,4 +92,58 @@ try {
   debugPrint("loadMessagesWithKeyword error: ${e.code}, ${e.description}");
 }
 
-```
+```
+
+### 根据消息类型搜索所有会话中的消息
+
+你可以调用 `EMChatManager#searchMsgsByOptions` 方法除了设置消息时间戳、消息数量、发送方、搜索方向等条件搜索当前会话中的消息，你还可以设置单个或多个消息类型搜索本地数据库中所有会话的消息。
+
+:::tip
+若使用该功能，需将 SDK 升级至 V4.8.1 或以上版本。
+:::
+
+```dart
+// from：会话中发送方的用户 ID。若传空字符串，搜索对发送方不限制。
+// count：要查询的消息条数。取值范围为 [1,400]。
+try {
+  const searchOptions = MessageSearchOptions(
+    types: [MessageType.TXT, MessageType.IMAGE],
+    from: fromUser,
+    ts: startTime,
+    direction: EMSearchDirection.Up,
+    count: 50
+  );
+  List<EMMessage> msgs =
+      await EMClient.getInstance.chatManager.searchMsgsByOptions(
+    searchOptions,
+  );
+} on EMError catch (e) {
+  debugPrint("error code: ${e.code}, desc: ${e.description}");
+}
+```
+
+### 根据消息类型搜索当前会话中的消息
+
+你可以调用 `EMConversation#searchMsgsByOptions` 方法除了设置消息时间戳、消息数量、发送方、搜索方向等条件搜索当前会话中的消息，你还可以设置单个或多个消息类型搜索本地数据库中单个会话的消息。
+
+:::tip
+若使用该功能，需将 SDK 升级至 V4.8.1 或以上版本。
+:::
+
+```dart
+// from：当前会话中发送方的用户 ID。若传空字符串，搜索对发送方不限制。
+// count：要查询的消息条数。取值范围为 [1,400]。
+  try {
+    const searchOptions = MessageSearchOptions(
+        types: [MessageType.TXT, MessageType.IMAGE],
+        from: fromUser,
+        ts: startTime,
+        direction: EMSearchDirection.Up,
+        count: 50);
+    conversation.searchMsgsByOptions(
+      searchOptions,
+    );
+  } on EMError catch (e) {
+    debugPrint("error code: ${e.code}, desc: ${e.description}");
+  }
+```     

docs/document/flutter/multi_device.md

@@ -137,6 +137,41 @@ final options = EMOptions(appKey: appKey, osType: 1);
 EMClient.getInstance.init(options);
 ```
 
+### 设置登录设备的扩展信息
+
+即时通讯 IM 自 4.8.1 版本开始支持设备的自定义扩展信息，这样在多设备场景下，若有设备被踢下线，被踢设备能获得该设备的自定义扩展信息。
+
+初始化 SDK 时，你可以调用 `EMOptions.loginExtension` 方法设置登录设备的自定义扩展信息。设置后，若因达到了登录设备数量限制而导致在已登录的设备上强制退出时（例如 Android 平台提示 `206` 错误，`USER_LOGIN_ANOTHER_DEVICE`），被踢设备收到的 `EMConnectionEventHandler#onUserDidLoginFromOtherDevice` 回调会包含导致该设备被踢下线的新登录设备的自定义扩展信息。
+
+:::notice
+登录成功后才会将该设置发送到服务器。
+:::
+
+```dart
+// 设置登录设备的扩展信息
+final options = EMOptions(appKey: appKey, loginExtension: "extension");
+
+// 添加连接事件监听   
+EMClient.getInstance.addConnectionEventHandler(
+  "identifier",
+  EMConnectionEventHandler(
+    onUserDidLoginFromOtherDevice: (info) {
+      debugPrint(info.deviceName);
+      debugPrint(info.ext);
+    },
+  ),
+);
+
+
+... 
+
+// 移除连接事件监听
+EMClient.getInstance.removeConnectionEventHandler("identifier");
+...
+
+
+```
+
 ### 强制指定账号从单个设备下线
 
 你可以调用 `kickDevice` 方法通过传入用户 ID 和登录密码或用户 token 将指定账号从单个登录设备踢下线。被踢设备会收到 `onUserKickedByOtherDevice` 回调。调用该方法前，你需要首先通过 `EMClient#fetchLoggedInDevices` 方法获取设备 ID。

docs/document/flutter/releasenote.md

@@ -2,6 +2,36 @@
 
 <Toc />
 
+## 版本 V4.8.1 2024-10-14
+
+#### 新增特性
+
+- 支持[加入聊天室时携带扩展信息、是否退出之前加入的全部聊天室](room_manage.html#加入聊天室)：
+  - 新增 `EMChatRoomManager.joinChatRoom(String roomId, {bool leaveOther = true,String? ext,})` 方法，支持设置加入聊天室时携带的扩展信息，并指定是否退出所有其他聊天室。
+  - 新增 `EMChatRoomEventHandler.onMemberJoinedFromChatRoom(String roomId, String participant, String? ext)` 回调，当用户加入聊天室携带了扩展信息时，聊天室内其他人可以在用户加入聊天室的回调中，获取到扩展信息。
+- 新增 `EMPushManager.syncConversationsSilentMode()` 方法，支持从服务器获取所有会话的推送通知方式的设置。
+- 新增 `EMPushManager.bindDeviceToken(String notifierName, String deviceToken)` 方法。
+- 新增 `EMConversation.remindType()` 方法，用于本地存储会话的推送通知方式。
+- 新增 `EMConversation.getLocalMessageCount()` 方法，用于[获取 SDK 本地数据库中会话在某个时间段内的全部消息数](message_retrieve.html#获取会话在一定时间内的消息数)。
+- 新增[设备登录时允许携带自定义消息，并将其传递给被踢的设备](multi_device.html#设置登录设备的扩展信息)：
+  - 新增 `LoginExtensionInfo` 用户设备扩展信息。
+  - 新增 `EMOptions.loginExtension` 设置登录时携带的扩展信息。
+- [IM SDK] 新增根据多个消息类型搜索本地消息：
+  - `EMChatManager#searchMsgsByOptions`：[根据单个或多个消息类型，搜索本地数据库中所有会话的消息](message_search.html#根据消息类型搜索所有会话中的消息)。
+  - `EMConversation#searchMsgsByOptions`：[根据单个或多个消息类型，搜索本地数据库中单个会话的消息](message_search.html#根据消息类型搜索当前会话中的消息)。
+
+#### 优化
+
+- 支持 AUT 协议， 优化弱网环境下的服务连接成功率;
+- `updateHMSPushToken`、`updateFCMPushToken`、`updateAPNsDeviceToken` 方法过期，`EMOptions` 中的 `enableOppoPush`、`enableMiPush`、`enableMeiZuPush`、`enableFCM`、`enableVivoPush`、`enableHWPush`、`enableAPNs`、`enableHonorPush` 过期， 使用 `EMPushManager.bindDeviceToken` 代替；
+- 修改 `EMConnectionEventHandler.onUserDidLoginFromOtherDevice(String deviceName)` 方法为 `EMConnectionEventHandler.onUserDidLoginFromOtherDevice(LoginExtensionInfo info)`
+
+#### 修复
+
+- 修复 `fetchConversationsByOptions` 偶尔引起的崩溃；
+- 修复拉黑联系人时缓存未及时更新的问题；
+- 修复退出登录再登录后推送可能不工作的问题。
+
 ## 版本 V4.6.1 2024-6-11
 
 ### 新增特性

docs/document/flutter/room_manage.md

@@ -78,6 +78,27 @@ try {
 }
 ```
 
+同时，你可以调用 `EMChatRoomManager.joinChatRoom` 方法，设置加入聊天室时携带的扩展信息，并指定是否退出所有其他聊天室。调用该方法后，聊天室内其他成员会收到 `EMChatRoomEventHandler.onMemberJoinedFromChatRoom(String roomId, String participant, String? ext)` 回调，当用户加入聊天室携带了扩展信息时，聊天室内其他人可以在用户加入聊天室的回调中，获取到扩展信息。
+
+```dart
+EMClient.getInstance.chatRoomManager.joinChatRoom(
+  "roomId",
+  leaveOther: false,
+  ext: 'ext',
+);
+
+// 添加聊天室事件监听
+EMClient.getInstance.chatRoomManager.addEventHandler(
+  "identifier",
+  EMChatRoomEventHandler(
+    onMemberJoinedFromChatRoom: (roomId, participant, ext) {},
+  ),
+);
+
+// 移除聊天室事件监听
+EMClient.getInstance.chatRoomManager.removeEventHandler("identifier");
+```
+
 ### 获取聊天室详情
 
 聊天室所有成员均可以调用 `EMChatManager#fetchChatRoomInfoFromServer` 获取聊天室详情，包括聊天室 ID、聊天室名称，聊天室描述、最大成员数、聊天室所有者、是否全员禁言以及聊天室权限类型。聊天室公告、管理员列表、成员列表、黑名单列表、禁言列表需单独调用接口获取。

docs/product/product_dynamics.md

@@ -22,7 +22,7 @@
 
 | 动态名称   | 动态描述 | 发布时间       | 相关文档          |
 | :----- | :------- | :---------------- | :---------------- |
-| SDK 4.8.0 开发版发布  | **新增特性**：<br/> - 移动端支持 AUT 协议，优化弱网环境下的服务连接成功率。<br/> - 移动端支持[本地存储会话的推送通知方式](/document/ios/push/push_notification_mode_dnd.html#从服务器获取所有会话的推送通知方式设置)，并支持从服务器获取所有会话的推送通知方式的设置。<br/> - 移动端支持[本地获取指定会话某个时间段内的消息数](/document/android/message_retrieve.html#获取会话在一定时间内的消息数)。<br/> - 客户端支持[加入聊天室时携带的扩展信息，并可指定是否退出所有其他聊天室](/document/android/room_manage.html#加入聊天室)。<br/> - Web 端[设备登录时允许携带自定义扩展消息并传递给被踢的设备](/document/web/multi_device.html#设置登录设备的扩展信息)，应用于被踢设备展示提示信息或进行业务判断。<br/> - Web 端支持[使用固定的设备 ID](/document/web/multi_device.html)，这会影响多端登录互踢的策略。<br/> - Web 端支持[聊天室所有者解散聊天室](/document/web/room_manage.html#解散聊天室)。<br/>**优化**：<br/> 移动端设置和获取用户属性时，包括[设置当前用户的属性](/document/web/userprofile.html#设置当前用户的属性)、[获取单个或多个用户的用户属性](/document/web/userprofile.html#获取用户属性)和[获取指定用户的指定用户属性](/document/web/userprofile.html#获取指定用户的指定用户属性)时，若超过调用频率限制，会上报错误码 4 `EMErrorExceedServiceLimit`（iOS）或 `EXCEED_SERVICE_LIMIT`（Android）。| 2024-07-01   | <br/> - [Android 4.8.0 更新日志](/document/android/releasenote.html#版本-v4-8-0-dev-2024-07-01-开发版)<br/> - [iOS 4.8.0 更新日志](/document/ios/releasenote.html#版本-v4-8-0-dev-2024-07-01-开发版)。<br/> - [Web 4.8.0 更新日志](/document/web/releasenote.html#版本-v4-8-0-dev-2024-07-01-开发版)。|
+| SDK 4.8.0 开发版发布  | **新增特性**：<br/> - 移动端支持 AUT 协议，优化弱网环境下的服务连接成功率。<br/> - 移动端支持[本地存储会话的推送通知方式](/document/ios/push/push_notification_mode_dnd.html#从服务器获取所有会话的推送通知方式设置)，并支持从服务器获取所有会话的推送通知方式的设置。<br/> - 移动端支持[本地获取指定会话某个时间段内的消息数](/document/android/message_retrieve.html#获取会话在一定时间内的消息数)。<br/> - 客户端支持[加入聊天室时携带的扩展信息，并可指定是否退出所有其他聊天室](/document/android/room_manage.html#加入聊天室)。<br/> - Web 端[设备登录时允许携带自定义扩展消息并传递给被踢的设备](/document/web/multi_device.html#设置登录设备的扩展信息)，应用于被踢设备展示提示信息或进行业务判断。<br/> - Web 端支持[使用固定的设备 ID](/document/web/multi_device.html)，这会影响多端登录互踢的策略。<br/> - Web 端支持[聊天室所有者解散聊天室](/document/web/room_manage.html#解散聊天室)。<br/>**优化**：<br/> 移动端设置和获取用户属性时，包括[设置当前用户的属性](/document/web/userprofile.html#设置当前用户的属性)、[获取单个或多个用户的用户属性](/document/web/userprofile.html#获取用户属性)和[获取指定用户的指定用户属性](/document/web/userprofile.html#获取指定用户的指定用户属性)时，若超过调用频率限制，会上报错误码 4 `EMErrorExceedServiceLimit`（iOS）或 `EXCEED_SERVICE_LIMIT`（Android）。| 2024-07-01   | <br/> - [Android 4.8.0 更新日志](/document/android/releasenote.html#版本-v4-8-0-dev-2024-07-01-开发版)<br/> - [iOS 4.8.0 更新日志](/document/ios/releasenote.html#版本-v4-8-0-dev-2024-07-01-开发版)。<br/> - [Web 4.8.0 更新日志](/document/web/releasenote.html#版本-v4-8-0-dev-2024-07-01-开发版)。<br/> - [Flutter 4.8.1 更新日志](/document/flutter/releasenote.html#版本-v4-8-1-dev-2024-10-15-开发版)。|
 
 | 动态名称   | 动态描述 | 发布时间       | 相关文档          |
 | :----- | :------- | :---------------- | :---------------- |

docs/uikit/chatuikit/android/chatfeature_message.md

@@ -43,7 +43,7 @@
 
 #### 如何使用
 
-消息转发特性在 `EaseChatConfig` 中默认开启，即 `enableReplyMessage` 的默认值为 `true`。要关闭该特性，需将该参数设置为 `false`。
+消息引用特性在 `EaseChatConfig` 中默认开启，即 `enableReplyMessage` 的默认值为 `true`。要关闭该特性，需将该参数设置为 `false`。
 
 示例代码如下：
 

docs/uikit/chatuikit/android/chatuikit_contactlist.md

@@ -130,7 +130,7 @@ EaseContactsListFragment.Builder()
 class CustomContactListAdapter : EaseContactListAdapter() {
     override fun getItemNotEmptyViewType(position: Int): Int {
         // 根据消息类型设置自定义 itemViewType。
-        // 如果使用默认的 itemViewTyp，返回 super.getItemNotEmptyViewType(position) 即可。
+        // 如果使用默认的 itemViewTyp2，返回 super.getItemNotEmptyViewType(position) 即可。
         return CUSTOM_YOUR_CONTACT_TYPE
     }
 

docs/uikit/chatuikit/android/chatuikit_conversation.md

@@ -88,7 +88,7 @@ EaseConversationListFragment.Builder()
 class CustomConversationListAdapter : EaseConversationListAdapter() {
     override fun getItemNotEmptyViewType(position: Int): Int {
         // 根据消息类型设置自定义 itemViewType。
-        // 如果使用默认的 itemViewTyp，返回 super.getItemNotEmptyViewType(position) 即可。
+        // 如果使用默认的 itemViewType，返回 super.getItemNotEmptyViewType(position) 即可。
         return CUSTOM_YOUR_CONVERSATION_TYPE
     }
 
@@ -233,7 +233,7 @@ binding?.titleConversations?.setBackgroundColor(ContextCompat.getColor(mContext,
 
 ```kotlin
 
-// 是否使用默认的搜索功能（跳转 EaseSearchActivity 搜索页面 目前支持搜索用户、会话、消息、黑名单用户。
+// 是否使用默认的搜索功能（跳转 EaseSearchActivity 搜索页面）。目前支持搜索用户、会话、消息、黑名单用户。
 // true：是；(默认) false: 否。 
 EaseConversationListFragment.Builder().useSearchBar(true)