Merge pull request #533 from haoxiuwen/doc-v2

Modify Client API of Obtaining Contact List

docs/document/android/group_overview.md

@@ -24,7 +24,7 @@
 | 类型 | 分为公开群和私有群，创建群组时可设置入群是否需获得群主和群管理员的同意，支持不同使用场景。 | 没有公开和私有之分，所有用户均可自由加入或退出。      |
 | 最大成员数   | 成员数支持取决于所选择的版本，最高版本支持 8,000 人。        | 成员数支持取决于所选择的版本，最高版本支持 10,000 人。如需提升该上限，请联系商务。 |
 | 离线推送消息 | 离线时，会收到推送消息。             | 离线时，不会收到推送消息；成员（除聊天室白名单中的成员）离线超过 2 分钟会自动退出聊天室。          |
-| 离线消息存储 | 支持离线消息存储，App 下的所有群组共存储 200 条消息。<br/>用户上线时，会收到离线消息。 | 不支持离线消息存储。如果需要用户新加入聊天室时服务器推送最近的历史消息，可以联系商务开通聊天室历史消息推送，每个会话默认支持 10 条消息，最多可调整至 200 条。 |
+| 离线消息存储 | 支持离线消息存储，对于每个终端用户来说，群聊会话共存储 200 条消息。<br/>用户上线时，会收到离线消息。 | 不支持离线消息存储。如果需要用户新加入聊天室时服务器推送最近的历史消息，可以联系商务开通聊天室历史消息推送，每个会话默认支持 10 条消息，最多可调整至 200 条。 |
 | 漫游消息存储 | 支持漫游消息存储。你可以从服务器获取指定会话的消息。 | 不支持漫游消息存储。 |
 | 消息可靠性   | 群组中发送的所有消息，用户都会收到。        | 当消息量大时，聊天室中超过阈值的消息会被丢弃。消息开始丢弃的阈值为每秒 100 条消息，可以根据需求进行调整。 |
 

docs/document/android/releasenote.md

@@ -6,7 +6,10 @@
 
 ### 新增特性
 
-- [IM SDK] 新增[好友备注功能](user_relationship.html#设置好友备注)。
+- [IM SDK] 新增[设置好友备注功能](user_relationship.html#设置好友备注)。
+- [IM SDK] 新增 `asyncFetchAllContactsFromServer` 方法[从服务器一次性或分页获取好友列表](user_relationship.html#获取好友列表)，每个好友对象包含好友的用户 ID 和好友备注。
+- [IM SDK] 新增 `fetchContactFromLocal` 方法[从本地获取单个好友的用户 ID 和好友备注](user_relationship.html#从服务端获取好友列表)。
+- [IM SDK] 新增 `asyncFetchAllContactsFromLocal` 方法[从本地分页获取好友列表](user_relationship.html#从本地获取好友列表)，每个好友对象包含好友的用户 ID 和好友备注。
 - [IM SDK] 新增 `EMMessage#isBroadcast` 属性用于判断通过该消息是否为聊天室全局广播消息。可通过[调用 REST API 发送聊天室全局广播消息](/document/server-side/message_chatroom.html#发送聊天室全局广播消息)。
 - [IM SDK] 新增 `EMGroupManager#asyncGetJoinedGroupsCountFromServer` 方法用于[从服务器获取当前用户已加入的群组数量](group_manage.html#查询当前用户已加入的群组数量)。 
 - [IM SDK] 新增[错误码 706](error.html) `CHATROOM_OWNER_NOT_ALLOW_LEAVE`，表示聊天室所有者不允许离开聊天室。若初始化时，`EMOptions#allowChatroomOwnerLeave` 参数设置为 `false`，聊天室所有者调用 `leaveChatRoom` 方法离开聊天室时会提示该错误。

docs/document/android/user_relationship.md

@@ -125,12 +125,13 @@ EMClient.getInstance().contactManager().asyncSetContactRemark(userId, remark, ne
 
 #### 获取好友列表
 
-- 从服务端获取好友列表：
+##### 从服务端获取好友列表
 
-调用以下两种方法返回好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+   自 4.2.1 版本开始，你可以调用 `asyncFetchAllContactsFromServer` 方法从服务器一次性或分页获取好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+
+- 一次性从服务端获取整个好友列表。
 
 ```java
-//一次性从服务端获取整个好友列表
 EMClient.getInstance().contactManager().asyncFetchAllContactsFromServer(new EMValueCallBack<List<EMContact>>() {
     @Override
     public void onSuccess(List<EMContact> value) {
@@ -142,8 +143,11 @@ EMClient.getInstance().contactManager().asyncFetchAllContactsFromServer(new EMVa
 
     }
 });
+```
 
-//从服务端分页获取好友列表
+- 从服务端分页获取好友列表。
+
+```java
 // limit 的取值范围为 [1,50]
 List<EMContact> contacts=new ArrayList<>();
 String cursor= "";
@@ -171,24 +175,25 @@ private void doAsyncFetchAllContactsFromServer(List<EMContact> contacts, String
     });
 ```
 
-你也可以调用 `getAllContactsFromServer` 方法从服务器获取所有好友的列表，该列表只包含好友的用户 ID。
+此外，你也可以调用 `getAllContactsFromServer` 方法从服务器获取所有好友的列表，该列表只包含好友的用户 ID。
 
 ```java
 // 从服务器获取好友列表。
 // 同步方法，会阻塞当前线程。异步方法为 asyncGetAllContactsFromServer(EMValueCallBack)。
 List<String> usernames = EMClient.getInstance().contactManager().getAllContactsFromServer();
 ```
 
-- 从本地获取好友列表
+##### 从本地获取好友列表
 
-调用以下两种方法返回好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+   自 4.2.1 版本开始，你可以调用 `asyncFetchAllContactsFromServer` 方法从本地获取单个好友的用户 ID 和好友备注；你也可以调用 `asyncFetchAllContactsFromLocal` 方法一次性获取整个好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
 
-:::notice
-需要从服务器获取好友列表之后，才能从本地获取到好友列表。
-:::
+   :::notice
+   需要从服务器获取好友列表之后，才能从本地获取到好友列表。
+   :::
+
+- 从本地获取单个好友。
 
 ```java
-//从本地获取单个好友
 try {
     EMContact emContact = EMClient.getInstance().contactManager().fetchContactFromLocal(userId);
     String remark = emContact.getRemark();
@@ -197,8 +202,11 @@ try {
 } catch (HyphenateException e) {
     EMLog.e(TAG, "fetchContactFromLocal error:" + e.getMessage());
 };
+```
 
-//一次性从本地获取整个好友列表
+- 一次性从本地获取整个好友列表。
+
+```java
 EMClient.getInstance().contactManager().asyncFetchAllContactsFromLocal(new EMValueCallBack<List<EMContact>>() {
     @Override
     public void onSuccess(List<EMContact> value) {
@@ -212,7 +220,7 @@ EMClient.getInstance().contactManager().asyncFetchAllContactsFromLocal(new EMVal
 });
 ```
 
-你也可以调用 `getContactsFromLocal` 方法从本地获取所有好友的列表，该列表只包含好友的用户 ID。
+此外，你也可以调用 `getContactsFromLocal` 方法从本地一次性获取所有好友的列表，该列表只包含好友的用户 ID。
 
 示例代码如下：
 

docs/document/ios/releasenote.md

@@ -6,7 +6,10 @@
 
 ### 新增特性
 
-- [IM SDK] 新增[好友备注功能](user_relationship.html#设置好友备注)。
+- [IM SDK] 新增[设置好友备注功能](user_relationship.html#设置好友备注)。
+- [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] 新增 `EMGroupManager#getJoinedGroupsCountFromServerWithCompletion` 方法用于[从服务器获取当前用户已加入的群组数量](group_manage.html#查询当前用户已加入的群组数量)。
 - [IM SDK] 新增[错误码 706](error.html) `EMErrorChatroomOwnerNotAllowLeave`，表示聊天室所有者不允许离开聊天室。若初始化时，`EMOptions#canChatroomOwnerLeave` 参数设置为 `false`，聊天室所有者调用 `leaveChatroom` 方法离开聊天室时会提示该错误。

docs/document/ios/user_relationship.md

@@ -152,25 +152,29 @@ if (!aError) {
 
 你可以从服务器获取好友列表，也可以从本地获取已保存的好友列表。
 
-- 从服务端获取好友列表
+1. 从服务端获取好友列表：
 
-调用以下两种方法返回好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+   自 4.2.0 版本开始，你可以调用 `getAllContactsFromServerWithCompletion` 或 `getContactsFromServerWithCursor` 方法从服务器一次性或分页获取好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
 
-```objectivec
+- 一次性从服务端获取整个好友列表。
 
+```objectivec
 //一次性从服务端获取整个好友列表
 [EMClient.sharedClient.contactManager getAllContactsFromServerWithCompletion:^(NSArray<EMContact *> * _Nullable aList, EMError * _Nullable aError) {
             
     }];
+```
 
-//从服务端分页获取好友列表
+- 从服务端分页获取好友列表。
+
+```objectivec
 //pageSize 的取值范围为 [1,50]
 [EMClient.sharedClient.contactManager getContactsFromServerWithCursor:@"" pageSize:50 completion:^(EMCursorResult<EMContact *> * _Nullable aResult, EMError * _Nullable aError) {
 
     }];
 ```
 
-你也可以调用 `getContactsFromServerWithCompletion` 方法从服务器获取所有好友的列表。该列表只包含好友的用户 ID。
+此外，你也可以调用 `getContactsFromServerWithCompletion` 方法从服务器获取所有好友的列表。该列表只包含好友的用户 ID。
 
 ```objectivec
 // 从服务器获取好友列表。
@@ -184,25 +188,27 @@ if (!aError) {
 }];
 ```
 
-- 从本地获取好友列表
+2. 从本地获取好友列表
 
-:::notice
-需要从服务器获取好友列表之后，才能从本地获取到好友列表。
-:::
+   :::notice
+   需要从服务器获取好友列表之后，才能从本地获取到好友列表。
+   :::
 
-调用以下两种方法返回好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+   自 4.2.0 版本开始，你可以调用 `getContact` 方法从本地获取单个好友的用户 ID 和好友备注；你也可以调用 `getAllContacts` 方法一次性获取整个好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+
+- 从本地获取单个好友。  
 
 ```objectivec
-//从本地获取单个好友
 EMContact* contact = [EMClient.sharedClient.contactManager getContact:@"userId"];
+```
 
+- 一次性从本地获取整个好友列表。
 
-//一次性从本地获取整个好友列表
+```objectivec
 NSArray<EMContact*>* contacts = [EMClient.sharedClient.contactManager getAllContacts];
-
 ```
 
-你也可以调用 `getContacts` 方法从本地获取所有好友的列表，该列表只包含好友的用户 ID。
+此外，你也可以调用 `getContacts` 方法从本地一次性获取所有好友的列表，该列表只包含好友的用户 ID。
 
 示例代码如下：
 

docs/document/web/releasenote.md

@@ -6,7 +6,8 @@
 
 ### 新增特性
 
-- [IM SDK] 新增[好友备注功能](user_relationship.html#设置好友备注)。
+- [IM SDK] 新增[设置好友备注功能](user_relationship.html#设置好友备注)。
+- [IM SDK] 新增 `getAllContacts` 和 `getContactsWithCursor` 方法分别用于一次性和分页获取好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
 - [IM SDK] 消息结构新增 `broadcast` 字段, 用于判断该消息是否为聊天室全局广播消息。可通过[调用 REST API 发送聊天室全局广播消息](/document/server-side/message_chatroom.html#发送聊天室全局广播消息)。
 
 ### 优化

docs/document/web/user_relationship.md

@@ -109,10 +109,11 @@ conn
 
 #### 获取好友列表
 
-调用以下两种方法返回好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+自 4.3.0 版本，你可以调用 `getAllContacts` 或 `getContactsWithCursor` 方法一次性或分页获取好友列表，其中每个好友对象包含好友的用户 ID 和好友备注。
+
+- 一次性获取全部好友列表：
 
 ```javascript
-// 一次性获取全部好友列表
 conn
   .getAllContacts()
   .then((res) => {
@@ -121,9 +122,11 @@ conn
   .catch((e) => {
     console.log(e, 'getAllContacts failed');
   });
+```
 
+- 分页获取好友列表：
 
-// 分页获取好友列表
+```javascript
 conn
   .getContactsWithCursor({
     pageSize: 20, // 每页期望获取的联系人数量。取值范围为 [1,50]，默认为 `20`。
@@ -137,7 +140,7 @@ conn
   });
 ```
 
-你可以调用 `getContacts` 方法从服务端获取所有好友的列表，该列表只包含好友的用户 ID。
+此外，你可以调用 `getContacts` 方法从服务端一次性获取好友列表，该列表只包含好友的用户 ID。
 
 ```javascript
 conn.getContacts().then((res) => {