Merge pull request #586 from haoxiuwen/doc-v2

Add Flutter 4.2.0 /RN 1.3.0 Release Notes
easemob · Jan 4, 2024 · e5fd2cc · e5fd2cc
2 parents a365ced + 24b8762
commit e5fd2cc
Show file tree

Hide file tree

Showing 21 changed files with 314 additions and 65 deletions.
diff --git a/docs/document/android/group_manage.md b/docs/document/android/group_manage.md
@@ -215,7 +215,7 @@ String cursor = result.getCursor();
 
 ### 查询当前用户已加入的群组数量
 
-你可以调用 `EMGroupManager#asyncGetJoinedGroupsCountFromServer` 方法从服务器获取当前用户已加入的群组数量。单个用户可加入群组数量的上限取决于订阅的即时通讯的套餐包，详见[产品价格](/product/pricing.html#套餐包功能详情)。
+自 4.2.1 版本开始，你可以调用 `EMGroupManager#asyncGetJoinedGroupsCountFromServer` 方法从服务器获取当前用户已加入的群组数量。单个用户可加入群组数量的上限取决于订阅的即时通讯的套餐包，详见[产品价格](/product/pricing.html#套餐包功能详情)。
 
 ```java
 EMClient.getInstance().groupManager().asyncGetJoinedGroupsCountFromServer(new EMValueCallBack<Integer>() {

diff --git a/docs/document/android/message_send_receive.md b/docs/document/android/message_send_receive.md
@@ -103,7 +103,7 @@ EMClient.getInstance().chatManager().sendMessage(message);
 
 在新消息到来时，你会收到 `onMessageReceived` 的回调，消息接收时可能是一条，也可能是多条。你可以在该回调里遍历消息队列，解析并显示收到的消息。
 
-对于聊天室消息，你可以通过消息的 `EMMessage#isBroadcast` 属性判断通过该消息是否为[通过 REST API 发送的聊天室全局广播消息](/document/server-side/message_chatroom.html#发送聊天室全局广播消息)。
+对于聊天室消息，你可以通过消息的 `EMMessage#isBroadcast` 属性判断该消息是否为[通过 REST API 发送的聊天室全局广播消息](/document/server-side/message_chatroom.html#发送聊天室全局广播消息)。
 
 ```java
 EMMessageListener msgListener = new EMMessageListener() {

diff --git a/docs/document/android/user_relationship.md b/docs/document/android/user_relationship.md
@@ -6,7 +6,7 @@
 
 SDK 提供用户关系管理功能，包括好友列表管理和黑名单管理：
 
-- 好友列表管理：查询好友列表、申请添加好友、同意好友申请、拒绝好友申请和删除好友等操作。
+- 好友列表管理：查询好友列表、申请添加好友、同意好友申请、拒绝好友申请、删除好友和设置好友备注等操作。
 - 黑名单管理：查询黑名单列表、添加用户至黑名单以及将用户移除黑名单等操作。
 
 本文介绍如何通过环信即时通讯 IM SDK 管理好友关系。
@@ -105,7 +105,7 @@ EMClient.getInstance().contactManager().deleteContact(username);
 
 #### 设置好友备注
 
-你可以调用 `asyncSetContactRemark` 方法设置单个好友的备注。
+自 4.2.1 版本开始，你可以调用 `asyncSetContactRemark` 方法设置单个好友的备注。
 
 好友备注的长度不能超过 100 个字符。
 
@@ -182,9 +182,9 @@ List<String> usernames = EMClient.getInstance().contactManager().getAllContactsF
 
 #### 从本地获取好友列表
 
-自 4.2.1 版本开始，你可以调用 `asyncFetchAllContactsFromServer` 方法从本地获取单个好友的用户 ID 和好友备注；你也可以调用 `asyncFetchAllContactsFromLocal` 方法一次性获取整个好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+自 4.2.1 版本开始，你可以调用 `fetchContactFromLocal` 方法从本地获取单个好友的用户 ID 和好友备注；你也可以调用 `asyncFetchAllContactsFromLocal` 方法一次性获取整个好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
 
-:::notice
+:::tip
 需要从服务器获取好友列表之后，才能从本地获取到好友列表。
 :::
 

diff --git a/docs/document/flutter/conversation_list.md b/docs/document/flutter/conversation_list.md
@@ -26,7 +26,9 @@
 
 你可以调用 `fetchConversation` 方法从服务端分页获取会话列表，包含单聊和群组聊天会话，不包含聊天室会话。SDK 按照会话活跃时间（会话的最新一条消息的时间戳）的倒序返回会话列表，每个会话对象中包含会话 ID、会话类型、是否为置顶状态、置顶时间（对于未置顶的会话，值为 `0`）以及最新一条消息。从服务端拉取会话列表后会更新本地会话列表。
 
-:::notice
+若在初始化时，将 `EMOptions#enableEmptyConversation` 设置为 `true` 允许返回空会话，则会话列表中会包含空会话，否则不包含。
+
+:::tip
 1. **若使用该功能，需在环信控制台开通该功能，并将 SDK 升级至 4.0.0。只有开通该功能，你才能使用置顶会话功能。** 
 2. 建议在 app 安装时或本地没有会话时调用该方法，否则调用 `loadAllConversations` 获取本地会话即可。
 3. 通过 RESTful 接口发送的消息默认不创建或写入会话。若会话中的最新一条消息通过 RESTful 接口发送，获取会话列表时，该会话中的最新一条消息显示为通过非 RESTful 接口发送的最新消息。若要开通 RESTful 接口发送的消息写入会话列表的功能，需联系商务。

diff --git a/docs/document/flutter/group_manage.md b/docs/document/flutter/group_manage.md
@@ -15,6 +15,7 @@
 - 获取群组详情
 - 获取群成员列表
 - 获取群组列表
+- 查询当前用户已加入的群组数量
 - 屏蔽、解除屏蔽群消息
 - 监听群组事件
 
@@ -210,6 +211,21 @@ try {
 }
 ```
 
+### 查询当前用户已加入的群组数量
+
+自 4.2.0 版本开始，你可以调用 `EMGroupManager#fetchJoinedGroupCount` 方法从服务器获取当前用户已加入的群组数量。单个用户可加入群组数量的上限取决于订阅的即时通讯的套餐包，详见[产品价格](/product/pricing.html#套餐包功能详情)。
+
+```dart
+void fetchJoinedGroupCount() async {
+  try {
+    int count =
+        await EMClient.getInstance.groupManager.fetchJoinedGroupCount();
+  } on EMError catch (e) {
+    // error.
+  }
+}
+```
+
 ### 屏蔽和解除屏蔽群消息
 
 群成员可以屏蔽群消息和解除屏蔽群消息。

diff --git a/docs/document/flutter/message_send_receive.md b/docs/document/flutter/message_send_receive.md
@@ -124,10 +124,12 @@ EMClient.getInstance.chatManager.sendMessage(message).then((value) {
 
 你可以添加 `EMChatEventHandler` 监听器接收消息。
 
-该 `EMChatEventHandler` 可以多次添加。请记得在不需要的时候移除该监听器，如在 `dispose` 时。
+`EMChatEventHandler` 可以多次添加。请记得在不需要的时候移除该监听器，如在 `dispose` 时。
 
 在新消息到来时，你会收到 `onMessagesReceived` 的事件，消息接收时可能是一条，也可能是多条。你可以在该回调里遍历消息队列，解析并显示收到的消息。
 
+对于聊天室消息，你可以通过消息的 `EMMessage#isBroadcast` 属性判断该消息是否为[通过 REST API 发送的聊天室全局广播消息](/document/server-side/message_chatroom.html#发送聊天室全局广播消息)。
+
 ```dart
 // 继承并实现 EMChatEventHandler
 class _ChatMessagesPageState extends State<ChatMessagesPage> {

diff --git a/docs/document/flutter/releasenote.md b/docs/document/flutter/releasenote.md
@@ -2,6 +2,29 @@
 
 <Toc />
 
+## 4.2.0 2024-1-4
+
+#### 新增特性
+
+- 新增[设置好友备注功能](user_relationship.html#设置好友备注)。
+- 新增 `EMContactManager#fetchContacts` 和 `EMContactManager#fetchAllContacts` 方法分别[从服务器一次性和分页获取好友列表](user_relationship.html#从服务端获取好友列表)，每个好友对象包含好友的用户 ID 和好友备注。从服务器一次性获取好友列表（只包含好友的用户 ID）的原接口 `getAllContactsFromServer` 已废弃，由 `fetchAllContactIds` 替换。
+- 新增 `EMContactManager#getContact` 方法[从本地获取单个好友的用户 ID 和好友备注](user_relationship.html#从本地获取好友列表)。
+- 新增 `EMContactManager#getAllContacts` 方法[从本地分页获取好友列表](user_relationship.html#从本地获取好友列表)，每个好友对象包含好友的用户 ID 和好友备注。一次性获取本地好友列表（只包含好友的用户 ID）的原接口 `getAllContactsFromDB` 已废弃，由 `getAllContactIds` 替换。
+- 新增 `EMMessage#isBroadcast` 属性用于判断该消息是否为聊天室全局广播消息。可通过[调用 REST API 发送聊天室全局广播消息](/document/server-side/message_chatroom.html#发送聊天室全局广播消息)。
+- 新增 `EMGroupManager#fetchJoinedGroupCount` 方法用于从服务器获取当前用户已加入的群组数量。
+- 新增[错误码 706](/android/error.html)，表示聊天室所有者不允许离开聊天室。若初始化时，`EMOptions#isChatRoomOwnerLeaveAllowed` 参数设置为 false，聊天室所有者调用 `EMChatRoomManager#leaveChatroom` 方法离开聊天室时会提示该错误。
+- 新增 `EMOptions#enableEmptyConversation` 属性用于在初始化时配置获取会话列表时是否允许返回空会话。
+- 申请入群被拒绝的回调 `EMGroupEventHandler#onRequestToJoinDeclinedFromGroup` 中新增 decliner 和 applicant 参数表示申请者和拒绝者的用户 ID。
+
+#### 优化
+
+- 统一 Agora Token 和 EaseMob Token 登录方式，原 `EMClient#login` 方法废弃，使用 `EMClient#loginWithToken` 和 `EMClient#loginWithPassword` 方法代替。此外，新增 EaseMob Token 即将过期及已过期的回调，即 EaseMob Token 已过期或有效期过半时也返回 `EMConnectionEventHandler#onTokenDidExpire` 和 `EMClientDelegate#onTokenWillExpire` 回调。
+
+#### 修复
+
+- 修复网络恢复时重连 2 次的问题。
+- 修复未登录时调用 leaveChatroom 方法返回的错误提示不准确。
+
 ## 版本 4.1.3 2023-11-1
 
 #### 新增

diff --git a/docs/document/flutter/user_relationship.md b/docs/document/flutter/user_relationship.md
@@ -6,7 +6,7 @@
 
 SDK 提供用户关系管理功能，包括好友列表管理和黑名单管理：
 
-- 好友列表管理：查询好友列表、申请添加好友、同意好友申请、拒绝好友申请和删除好友等操作。
+- 好友列表管理：查询好友列表、申请添加好友、同意好友申请、拒绝好友申请、删除好友和设置好友备注等操作。
 - 黑名单管理：查询黑名单列表、添加用户至黑名单以及将用户移除黑名单等操作。
 
 本文介绍如何通过环信即时通讯 IM Flutter SDK 管理用户关系。
@@ -19,8 +19,12 @@ SDK 提供用户关系管理功能，包括好友列表管理和黑名单管理
 - `deleteContact` 删除好友；
 - `acceptInvitation` 同意好友申请；
 - `declineInvitation` 拒绝好友申请；
-- `getAllContactsFromServer` 从服务器获取好友列表；
-- `getAllContactsFromDB` 从本地数据库中获取好友列表；
+- `setContactRemark` 设置好友备注；
+- `fetchAllContacts`/`fetchContacts`：一次性/分页从服务器获取好友列表（每个好友对象包含好友的用户 ID 和好友备注）；
+- `fetchAllContactIds` 一次性从服务器获取好友列表(列表只包含好友的用户 ID)；
+- `getContact`：获取本地单个好友（单个好友的用户 ID 和好友备注）；
+- `getAllContacts`：一次性获取本地好友列表（每个好友对象包含好友的用户 ID 和好友备注）；
+- `getAllContactIds`：一次性获取本地好友列表（列表只包含好友的用户 ID）；
 - `addUserToBlockList` 添加用户到黑名单；
 - `removeUserFromBlockList` 将用户从黑名单移除；
 - `getBlockListFromServer` 从服务器获取黑名单列表。
@@ -35,6 +39,7 @@ SDK 提供用户关系管理功能，包括好友列表管理和黑名单管理
 ## 实现方法
 
 ### 管理好友列表
+
 #### 添加好友
 
 1. 用户添加指定用户为好友
@@ -104,20 +109,6 @@ EMClient.getInstance.contactManager.removeEventHandler("UNIQUE_HANDLER_ID");
     EMClient.getInstance.contactManager.removeEventHandler("UNIQUE_HANDLER_ID");
 ```
 
-#### 获取好友列表
-
-1. 从服务器获取好友列表
-
-```dart
-List<String> contacts = await EMClient.getInstance.contactManager.getAllContactsFromServer();
-```
-
-2. 从本地数据库中获取好友列表
-
-```dart
-List<String> contacts = await EMClient.getInstance.contactManager.getAllContactsFromDB();
-```
-
 #### 删除好友
 
 删除联系人时会同时删除对方联系人列表中的该用户，建议执行双重确认，以免发生误删操作。删除操作不需要对方同意或者拒绝。
@@ -138,6 +129,120 @@ try {
 }
 ```
 
+#### 设置好友备注
+
+自 4.2.0 版本开始，你可以调用 `asyncSetContactRemark` 方法设置单个好友的备注。
+
+好友备注的长度不能超过 100 个字符。
+
+```dart
+void updateRemark(String userId, String newRemark) async {
+  try {
+    await EMClient.getInstance.contactManager.setContactRemark(
+      userId: userId,
+      remark: newRemark,
+    );
+  } on EMError catch (e) {
+    // error.
+  }
+}
+```
+
+#### 从服务端获取好友列表
+
+自 4.2.0 版本开始，你可以调用 `fetchAllContactsFromServer` 方法从服务器一次性或分页获取好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+
+- 一次性获取服务端好友列表。
+
+```dart
+void fetchAllContactsFromServer() async {
+  try {
+    List<EMContact> list = await EMClient.getInstance.contactManager.fetchAllContacts();
+  } on EMError catch (e) {
+    // error.
+  }
+}
+```
+
+- 分页获取服务端好友列表。
+
+```dart
+// pageSize 的取值范围为 [1,50]
+void fetchContactsFromServer(String cursor, int pageSize) async {
+  try {
+    EMCursorResult<EMContact> result =
+        await EMClient.getInstance.contactManager.fetchContacts(
+      cursor: cursor,
+      pageSize: pageSize,
+    );
+  } on EMError catch (e) {
+    // error.
+  }
+}
+```
+
+此外，你也可以调用 `fetchAllContactIds` 方法从服务器获取所有好友的列表，该列表只包含好友的用户 ID。
+
+```dart
+void fetchAllContactIds() async {
+  try {
+    List<String> userIds =
+        await EMClient.getInstance.contactManager.fetchAllContactIds();
+  } on EMError catch (e) {
+    // error.
+  }
+}
+```
+
+#### 从本地获取好友列表
+
+自 4.2.0 版本开始，你可以调用 `getContact` 方法从本地获取单个好友的用户 ID 和好友备注；你也可以调用 `getAllContacts` 方法一次性获取整个好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+
+:::tip
+需要从服务器获取好友列表之后，才能从本地获取到好友列表。
+:::
+
+- 获取本地单个好友。
+
+```dart
+void getLocalContact(String userId) async {
+  try {
+    EMContact? contact =
+        await EMClient.getInstance.contactManager.getContact(userId: userId);
+  } on EMError catch (e) {
+    // error.
+  }
+}
+```
+
+- 一次性获取本地好友列表。
+
+```dart
+void getAllLocalContact() async {
+  try {
+    List<EMContact> contacts =
+        await EMClient.getInstance.contactManager.getAllContacts();
+  } on EMError catch (e) {
+    // error.
+  }
+}
+```
+
+此外，你也可以调用 `getAllContactIds` 方法从本地一次性获取所有好友的列表，该列表只包含好友的用户 ID。
+
+示例代码如下：
+
+```dart
+void getAllLocalContactIds() async {
+  try {
+    List<String> userIds =
+        await EMClient.getInstance.contactManager.getAllContactIds();
+  } on EMError catch (e) {
+    // error.
+  }
+}
+```
+
 ### 管理黑名单
 
 黑名单是与好友无任何关系的独立体系。可以将任何用户加入黑名单，不论该用户与你是否是好友关系。

diff --git a/docs/document/ios/group_manage.md b/docs/document/ios/group_manage.md
@@ -217,7 +217,7 @@ do {
 
 ### 查询当前用户已加入的群组数量
 
-你可以调用 `EMGroupManager#getJoinedGroupsCountFromServerWithCompletion` 方法用于从服务器获取当前用户已加入的群组数量。单个用户可加入群组数量的上限取决于你订阅的即时通讯的套餐包，详见[产品价格](/product/pricing.html#套餐包功能详情)。
+自 4.2.0 版本开始，你可以调用 `EMGroupManager#getJoinedGroupsCountFromServerWithCompletion` 方法用于从服务器获取当前用户已加入的群组数量。单个用户可加入群组数量的上限取决于你订阅的即时通讯的套餐包，详见[产品价格](/product/pricing.html#套餐包功能详情)。
 
 ```objectivec
 [EMClient.sharedClient.groupManager getJoinedGroupsCountFromServerWithCompletion:^(NSInteger groupCount, EMError * _Nullable aError) {

diff --git a/docs/document/ios/message_send_receive.md b/docs/document/ios/message_send_receive.md
@@ -86,7 +86,7 @@ message.priority = EMChatRoomMessagePriorityHigh;
 
 在新消息到来时，你会收到 `messagesDidReceive` 的回调，消息接收时可能是一条，也可能是多条。你可以在该回调里遍历消息队列，解析并显示收到的消息。
 
-对于聊天室消息，你可以通过消息的 `EMChatMessage#broadcast` 属性判断通过该消息是否为[通过 REST API 发送的聊天室全局广播消息](/document/server-side/message_chatroom.html#发送聊天室全局广播消息)。
+对于聊天室消息，你可以通过消息的 `EMChatMessage#broadcast` 属性判断该消息是否为[通过 REST API 发送的聊天室全局广播消息](/document/server-side/message_chatroom.html#发送聊天室全局广播消息)。
 
 ```objectivec
 // 添加代理。

diff --git a/docs/document/ios/releasenote.md b/docs/document/ios/releasenote.md
@@ -27,7 +27,7 @@
 - [IM SDK] 新增 `getAllContactsFromServerWithCompletion` 和 `getContactsFromServerWithCursor` 方法分别[从服务器一次性和分页获取好友列表](user_relationship.html#从服务端获取好友列表)，每个好友对象包含好友的用户 ID 和好友备注。
 - [IM SDK] 新增 `getContact` 方法[从本地获取单个好友的用户 ID 和好友备注](user_relationship.html#从本地获取好友列表)。
 - [IM SDK] 新增 `getAllContacts` 方法[从本地分页获取好友列表](user_relationship.html#从本地获取好友列表)，每个好友对象包含好友的用户 ID 和好友备注。
-- [IM SDK] 新增 `EMChatMessage#broadcast` 属性用于判断通过该消息是否为聊天室全局广播消息。可通过[调用 REST API 发送聊天室全局广播消息](/document/server-side/message_chatroom.html#发送聊天室全局广播消息)。
+- [IM SDK] 新增 `EMChatMessage#broadcast` 属性用于判断该消息是否为聊天室全局广播消息。可通过[调用 REST API 发送聊天室全局广播消息](/document/server-side/message_chatroom.html#发送聊天室全局广播消息)。
 - [IM SDK] 新增 `EMGroupManager#getJoinedGroupsCountFromServerWithCompletion` 方法用于[从服务器获取当前用户已加入的群组数量](group_manage.html#查询当前用户已加入的群组数量)。
 - [IM SDK] 新增[错误码 706](error.html) `EMErrorChatroomOwnerNotAllowLeave`，表示聊天室所有者不允许离开聊天室。若初始化时，`EMOptions#canChatroomOwnerLeave` 参数设置为 `false`，聊天室所有者调用 `leaveChatroom` 方法离开聊天室时会提示该错误。
 - [IM SDK] 新增 `EMOptions#loadEmptyConversations` 属性用于在初始化时配置获取会话列表时是否允许返回空会话。

diff --git a/docs/document/ios/user_relationship.md b/docs/document/ios/user_relationship.md
@@ -3,10 +3,12 @@
 <Toc />
 
 用户登录后，可进行添加联系人、获取好友列表等操作。
+
 本文介绍如何通过环信即时通讯 IM SDK 管理好友关系，包括添加、同意、拒绝、删除、查询好友，以及管理黑名单，包括添加、移出、查询黑名单。
+
 SDK 提供用户关系管理功能，包括好友列表管理和黑名单管理：
 
-- 好友列表管理：查询好友列表、申请添加好友、同意好友申请、拒绝好友申请和删除好友等操作。
+- 好友列表管理：查询好友列表、申请添加好友、同意好友申请、拒绝好友申请、删除好友和设置好友备注等操作。
 - 黑名单管理：查询黑名单列表、将添加用户至黑名单以及从黑名单中移出用户等操作。
 
 ## 技术原理
@@ -138,7 +140,7 @@ if (!aError) {
 
 #### 设置好友备注
 
-你可以调用 `setContactRemark` 方法设置好友备注。
+自 4.2.0 版本开始，你可以调用 `setContactRemark` 方法设置好友备注。
 
 好友备注的长度不能超过 100 个字符。
 
@@ -188,7 +190,7 @@ if (!aError) {
 
 #### 从本地获取好友列表
 
-:::notice
+:::tip
 需要从服务器获取好友列表之后，才能从本地获取到好友列表。
 :::