Merge pull request #546 from haoxiuwen/doc-v2

Add Conversation Mark for Release Notes 4.3.0
easemob · Dec 22, 2023 · 3da178c · 3da178c
2 parents c4c3afe + b148fd9
commit 3da178c
Show file tree

Hide file tree

Showing 70 changed files with 2,902 additions and 1,395 deletions.
diff --git a/docs/.vuepress/sidebar/document.ts b/docs/.vuepress/sidebar/document.ts
@@ -41,14 +41,27 @@ const documentSidebar = [
   {
     text: '基础功能',
     children: [
+      {
+        text: '会话管理',
+        collapsible: true,
+        children: [
+          { text: '会话介绍', link: 'conversation_overview.html' },
+          { text: '会话列表', link: 'conversation_list.html' },
+          { text: '本地会话', link: 'conversation_local.html', only: ['web'] },
+          { text: '会话未读数', link: 'conversation_unread.html', except: ['web'] },
+          { text: '置顶会话', link: 'conversation_pin.html' },
+          { text: '会话标记', link: 'conversation_mark.html', except: ['windows', 'react-native', 'flutter', 'unity'] },
+          { text: '删除会话', link: 'conversation_delete.html' },
+        ]
+      },
       {
         text: '消息管理',
         collapsible: true,
         children: [
           { text: '消息概述', link: 'message_overview.html' },
           { text: '发送和接收消息', link: 'message_send_receive.html' },
-          { text: '管理本地会话和消息', link: 'message_manage.html', except: ['react-native'] },
-          { text: '管理会话和消息', link: 'message_manage.html', only: ['react-native'] },
+          { text: '管理本地消息', link: 'message_manage.html', except: ['react-native'] },
+          { text: '管理消息', link: 'message_manage.html', only: ['react-native'] },
           { text: '管理服务端消息', link: 'message_retrieve.html', except: ['react-native'] },
           { text: '管理消息回执', link: 'message_receipt.html' },
           { text: '修改消息', link: 'message_modify.html' },
@@ -133,6 +146,19 @@ const documentSidebar = [
     text: '基本功能',
     children: [
       { text: '初始化及登录', link: 'initialization.html' },
+      {
+        text: '会话管理',
+        collapsible: true,
+        children: [
+          { text: '会话介绍', link: 'conversation_overview.html' },
+          { text: '会话列表', link: 'conversation_list.html' },
+          { text: '本地会话', link: 'conversation_local.html' },
+          { text: '会话未读数', link: 'conversation_unread.html' },
+          { text: '置顶会话', link: 'conversation_pin.html' },
+          { text: '会话标记', link: 'conversation_mark.html'},
+          { text: '删除会话', link: 'conversation_delete.html'},
+        ]
+      },
       {
         text: '消息管理',
         collapsible: true,

diff --git a/docs/document/android/conversation_delete.md b/docs/document/android/conversation_delete.md
@@ -0,0 +1,62 @@
+# 删除会话
+
+<Toc />
+
+删除好友或退出群组后，SDK 不会自动删除对应的单聊或群聊会话。你可以调用相应的接口从服务器和本地删除单个会话及其历史消息。
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 初始化，并连接到服务器，详见 [快速开始](quickstart.html)。
+- 了解环信即时通讯 IM API 的使用限制，详见 [使用限制](/product/limitation.html)。
+
+## 技术原理
+
+环信即时通讯 IM 支持从服务器和本地删除单个会话及其历史消息，主要方法如下：
+
+- `deleteConversationFromServer`：单向删除服务端的单个会话及其历史消息。
+- `deleteConversation`：删除本地单个会话及其历史消息。
+
+## 实现方法
+
+### 单向删除服务端会话及其历史消息
+
+你可以调用 `deleteConversationFromServer` 方法删除服务器端会话和历史消息。会话和消息删除后，当前用户无法从服务器获取该会话和消息，对本地的会话无影响，但会删除本地消息，而其他用户不受影响。
+
+调用该方法之前，需调用 `getConversation` 方法获取会话 ID。
+
+示例代码如下：
+
+```java
+//获取指定的会话 ID。
+EMConversation conversation = EMClient.getInstance().chatManager().getConversation(username);
+
+// 删除指定会话。如果需要保留历史消息，`isDeleteServerMessages` 传 `false`。
+EMClient.getInstance().chatManager().deleteConversationFromServer(conversationId, conversationType, isDeleteServerMessages, new EMCallBack() {
+    @Override
+    public void onSuccess() {
+
+    }
+
+    @Override
+    public void onError(int code, String error) {
+
+    }
+});
+```
+
+### 删除本地会话及历史消息
+
+你可以删除本地会话和历史消息，示例代码如下：
+
+```java
+// 删除指定用户的会话，如果需要保留历史消息，传 `false`。
+EMClient.getInstance().chatManager().deleteConversation(username, true);
+```
+
+```java
+// 删除指定会话中指定的一条历史消息。
+EMConversation conversation = EMClient.getInstance().chatManager().getConversation(username);
+conversation.removeMessage(deleteMsg.msgId);
+```
diff --git a/docs/document/android/conversation_list.md b/docs/document/android/conversation_list.md
@@ -0,0 +1,78 @@
+# 会话列表
+
+<Toc />
+
+对于单聊、群组聊天和聊天室会话，用户发消息时 SDK 会自动创建会话并将会话添加至用户的会话列表。
+
+环信服务器和本地均存储会话，你可以获取会话列表。**服务器默认存储 100 条会话，可存储 7 天。若提升这两个上限，需联系环信商务。**
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 初始化，并连接到服务器，详见 [快速开始](quickstart.html)。
+- 了解环信即时通讯 IM API 的使用限制，详见 [使用限制](/product/limitation.html)。
+
+## 技术原理
+
+环信即时通讯 IM 支持从服务器和本地获取会话列表，主要方法如下：
+
+- `asyncFetchConversationsFromServer`：从服务器获取会话列表。
+- `getAllConversationsBySort`：获取本地所有会话。
+
+## 实现方法
+
+### 从服务器分页获取会话列表
+
+你可以调用 `asyncFetchConversationsFromServer` 方法从服务端分页获取会话列表，包含单聊和群组聊天会话，不包含聊天室会话。SDK 按照会话活跃时间（会话的最新一条消息的时间戳）的倒序返回会话列表，每个会话对象中包含会话 ID、会话类型、是否为置顶状态、置顶时间（对于未置顶的会话，值为 `0`）、会话标记以及最新一条消息。从服务端拉取会话列表后会更新本地会话列表。
+
+若在初始化时，将 `EMOptions#setLoadEmptyConversations` 设置为 `true` 允许返回空会话，则会话列表中会包含空会话，否则不包含。
+
+:::tip
+1. **若使用该功能，需在环信控制台开通，并将 SDK 升级至 4.0.3。而且，只有开通该功能，你才能使用置顶会话和会话标记功能。** 
+2. 建议你在首次下载、卸载后重装应用等本地数据库无数据情况下拉取服务端会话列表。其他情况下，调用 `getAllConversationsBySort` 或 `getAllConversations` 方法获取本地所有会话即可。
+3. 通过 RESTful 接口发送的消息默认不创建或写入会话。若会话中的最新一条消息通过 RESTful 接口发送，获取会话列表时，该会话中的最新一条消息显示为通过非 RESTful 接口发送的最新消息。若要开通 RESTful 接口发送的消息写入会话列表的功能，需联系商务。
+:::
+
+示例代码如下：
+
+```java
+// limit: 每页返回的会话数。取值范围为 [1,50]。
+// cursor: 开始获取数据的游标位置。若获取数据时传 `null` 或者空字符串（""），SDK 从最新活跃的会话开始获取。
+int limit = 10;
+String cursor = "";
+EMClient.getInstance().chatManager().asyncFetchConversationsFromServer(limit, cursor, new EMValueCallBack<EMCursorResult<EMConversation>>() {
+    @Override
+    public void onSuccess(EMCursorResult<EMConversation> result) {
+        // 获取到的会话列表
+        List<EMConversation> conversations = result.getData();
+        // 下一次请求的 cursor
+        String nextCursor = result.getCursor();
+    }
+
+    @Override
+    public void onError(int error, String errorMsg) {
+
+    }
+});
+```
+
+### 获取本地所有会话
+
+你可以调用 `getAllConversationsBySort` 方法一次性获取本地所有会话。SDK 从内存中获取会话，若未从本地数据库中加载过，会先从数据库加载到内存中。获取会话后，SDK 按照会话活跃时间（最新一条消息的时间戳）的倒序返回会话，置顶会话在前，非置顶会话在后，会话列表为 `List<EMConversation>` 结构。
+
+本地会话列表包含单聊和群组聊天会话，至于是否包含聊天室会话，取决于在 SDK 初始化时 `com.hyphenate.chat.EMOptions#setDeleteMessagesAsExitChatRoom` 参数的设置。若设置为 `true`，即离开聊天室时删除该聊天室的所有本地消息，则本地会话列表中不包含聊天室会话。若设置为 `false`，即保留该聊天室的所有本地消息，则本地会话列表中包含聊天室会话。
+
+若在初始化时，将 `EMOptions#setLoadEmptyConversations` 设置为 `true` 允许返回空会话，则会话列表中会包含空会话，否则不包含。
+
+:::tip
+若使用该功能，需将 SDK 升级至 4.0.3。
+:::
+
+示例代码如下：
+
+```java
+List<EMConversation> conversations = EMClient.getInstance().chatManager().getAllConversationsBySort();
+```
+
+你也可以调用 `getAllConversations` 方法返回 `Map <String, EMConversation>` 结构的会话。
diff --git a/docs/document/android/conversation_mark.md b/docs/document/android/conversation_mark.md
@@ -0,0 +1,163 @@
+# 会话标记
+
+<Toc />
+
+某些情况下，你可能需要对会话添加标记，例如会话标星或将会话标为已读或未读。即时通讯云 IM 支持对单聊和群聊会话添加标记，最大支持 20 个标记，所以一个会话最多可添加 20 个标记。
+
+如果要使用会话标记功能，你需要确保开通了[会话列表服务](conversation_list.html#从服务器分页获取会话列表)并将 SDK 版本升级至 4.3.0 或以上版本。
+
+你需要自行维护会话标记与具体业务含义（比如 `MARK_0` 为重要会话）之间的映射关系。例如：
+
+```java
+Map<EMConversation.EMMarkType,String> mapping=new HashMap<>();
+mapping.put(EMConversation.EMMarkType.MARK_0,"important");
+mapping.put(EMConversation.EMMarkType.MARK_1,"normal");
+mapping.put(EMConversation.EMMarkType.MARK_2,"unimportant");
+mapping.put(EMConversation.EMMarkType.MARK_3,"boys");
+mapping.put(EMConversation.EMMarkType.MARK_4,"girls");
+……
+```
+
+## 技术原理
+
+环信即时通讯 IM 支持会话标记功能，主要方法如下：
+
+- `EMChatManager#asyncAddConversationMark`：标记会话。
+- `EMChatManager#asyncRemoveConversationMark`：取消标记会话。
+- `EMChatManager#asyncGetConversationsFromServerWithCursor`：根据会话标记从服务器分页查询会话列表。
+- 根据会话标记从本地查询会话列表：调用 `getAllConversations` 方法获取本地所有会话后自己进行会话过滤。
+- `EMConversation#marks`：获取本地单个会话的所有标记。
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 初始化，并连接到服务器，详见 [快速开始](quickstart.html)。
+- 了解环信即时通讯 IM API 的使用限制，详见 [使用限制](/product/limitation.html)。
+- **[开通服务端会话列表功能](conversation_list#从服务器分页获取会话列表)**。
+
+## 实现方法
+
+### 标记会话
+
+你可以调用 `asyncAddConversationMark` 方法标记会话。每次最多可为 20 个会话添加标记。调用该方法会同时为本地和服务器端的会话添加标记。
+
+添加会话标记后，若调用 `asyncFetchConversationsFromServer` 接口从服务器分页获取会话列表，返回的会话对象中包含会话标记，你需要通过 `EMConversation#marks` 方法获取。若你已经达到了服务端会话列表长度限制（默认 100 个会话），服务端会根据会话的活跃度删除不活跃会话，这些会话的会话标记也随之删除。
+
+:::tip
+对会话添加标记，例如会话标星，并不影响会话的其他逻辑，例如会话的未读消息数。
+:::
+
+```java
+String conversationId = "huanhuan";
+List<String> ids=new ArrayList<>();
+ids.add(conversationId);
+EMClient.getInstance().chatManager().asyncAddConversationMark(ids, EMConversation.EMMarkType.MARK_0, new EMCallBack() {
+    @Override
+    public void onSuccess() {
+
+    }
+
+    @Override
+    public void onError(int code, String error) {
+
+    }
+});
+```
+
+### 取消标记会话
+
+你可以调用 `asyncRemoveConversationMark` 方法删除会话标记。每次最多可移除 20 个会话的标记。
+
+调用该方法会同时移除本地和服务器端会话的标记。
+
+```java
+String conversationId = "huanhuan";
+List<String> ids=new ArrayList<>();
+ids.add(conversationId);
+EMClient.getInstance().chatManager().asyncRemoveConversationMark(ids, EMConversation.EMMarkType.MARK_0,new EMCallBack() {
+    @Override
+    public void onSuccess() {
+
+    }
+
+    @Override
+    public void onError(int code, String error) {
+
+    }
+});
+```
+
+### 根据会话标记从服务器分页查询会话列表
+
+你可以调用 `asyncGetConversationsFromServerWithCursor` 方法根据会话标记从服务器分页获取会话列表。SDK 会按会话标记的时间的倒序返回会话列表，每个会话对象中包含会话 ID、会话类型、是否为置顶状态、置顶时间（对于未置顶的会话，值为 0）、会话标记以及最新一条消息。从服务端拉取会话列表后会更新本地会话列表。
+
+```java
+// 最终的查询结果全部放入 result 中。
+List<EMConversation> result=new ArrayList<>();
+// cursor：查询的开始位置。若传入空字符串，SDK 从最新标记操作的会话开始获取。
+String cursor="";
+// filter：会话查询选项，包括会话标记和每页获取的会话条数（最多可获取 10 条）。下面的代码以查询服务端所有标记了 `EMConversation.EMMarkType.MARK_0` 的会话为例。
+EMConversationFilter filter=new EMConversationFilter(EMConversation.EMMarkType.MARK_0,10);
+doAsyncGetConversationsFromServerWithCursor(result,cursor,filter);
+
+private void doAsyncGetConversationsFromServerWithCursor(List<EMConversation> result, @NonNull String cursor, @NonNull EMConversationFilter filter) {
+        EMClient.getInstance().chatManager().asyncGetConversationsFromServerWithCursor(cursor, filter, new EMValueCallBack<EMCursorResult<EMConversation>>() {
+            @Override
+            public void onSuccess(EMCursorResult<EMConversation> value) {
+                List<EMConversation> datas=value.getData();
+                if(!CollectionUtils.isEmpty(datas)){
+                    result.addAll(datas);
+                }
+                String cursor_ = value.getCursor();
+                if(!TextUtils.isEmpty(cursor_)){
+                    doAsyncGetConversationsFromServerWithCursor(result,cursor_,filter);
+                }
+            }
+
+            @Override
+            public void onError(int error, String errorMsg) {
+
+            }
+        });
+    }
+```
+
+### 根据会话标记从本地查询会话列表
+
+对于本地会话，你可以调用 `getAllConversations` 方法获取本地所有会话后自己进行会话过滤。下面以查询标记了 `EMConversation.EMMarkType.MARK_0` 的所有本地会话为例。
+
+```java
+//最终的查询结果全部放入 result 中。
+List<EMConversation> result=new ArrayList<>();
+Map<String, EMConversation> localConversations = EMClient.getInstance().chatManager().getAllConversations();
+if(localConversations!=null&&!localConversations.isEmpty()){
+    for(EMConversation conversation:localConversations.values()){
+        Set<EMConversation.EMMarkType> marks = conversation.marks();
+        if(marks!=null&&!marks.isEmpty()){
+            for(EMConversation.EMMarkType mark:marks){
+                if(mark==EMConversation.EMMarkType.MARK_0){
+                    result.add(conversation);
+                }
+            }
+        }
+    }
+}
+```
+
+### 获取本地单个会话的所有标记
+
+你可以调用 `EMConversation#marks` 方法获取本地单个会话的所有标记，示例代码如下：
+
+```java
+EMConversation conversation = EMClient.getInstance().chatManager().getConversation("conversationId");
+Set<EMMarkType> marks = conversation.marks();
+```
+
+
+
+
+
+
+
+