Merge pull request #446 from haoxiuwen/doc-v2

Add Local Conversation Management for Web

docs/.vuepress/sidebar/document.ts

@@ -47,7 +47,7 @@ const documentSidebar = [
         children: [
           { text: '消息概述', link: 'message_overview.html' },
           { text: '发送和接收消息', link: 'message_send_receive.html' },
-          { text: '管理本地消息数据', link: 'message_manage.html', except: ['web', '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' },

docs/document/android/message_manage.md

@@ -1,8 +1,8 @@
-# 管理本地消息数据
+# 管理本地会话和消息
 
 <Toc />
 
-本文介绍环信即时通讯 IM SDK 如何管理本地消息数据。SDK 内部使用 SQLite 保存本地消息，方便消息处理。
+本文介绍环信即时通讯 IM SDK 如何管理本地会话和消息。SDK 内部使用 SQLite 保存本地消息，方便消息处理。
 
 除了发送和接收消息外，环信即时通讯 IM SDK 还支持以会话为单位对本地的消息数据进行管理，如获取与管理未读消息、搜索和删除历史消息以及统计消息流量等。其中，会话是一个单聊、群聊或者聊天室所有消息的集合。用户需在会话中发送消息、查看或清空历史消息等操作。
 

docs/document/android/message_overview.md

@@ -24,7 +24,7 @@
 
 ### 消息功能
 
-#### 管理本地消息数据
+#### 管理本地会话和消息
 
 使用环信即时通讯 IM 发送和接收到的消息会存储在本地数据库，消息以会话为单位进行管理。用户可基于会话获取、删除、导入和插入消息。
 

docs/document/flutter/message_manage.md

@@ -1,8 +1,8 @@
-# 管理本地消息数据
+# 管理本地会话和消息
 
 <Toc />
 
-本文介绍环信即时通讯 IM Flutter SDK 如何管理本地消息数据。
+本文介绍环信即时通讯 IM Flutter SDK 如何管理本地会话和消息。
 
 除了发送和接收消息外，环信即时通讯 IM Flutter SDK 还支持以会话为单位对本地的消息数据进行管理，如获取与管理未读消息、搜索和删除历史消息等。其中，会话是一个单聊、群聊或者聊天室所有消息的集合。用户需在会话中发送消息以及查看或清空历史消息。
 

docs/document/ios/message_manage.md

@@ -1,8 +1,8 @@
-# 管理本地消息数据
+# 管理本地会话和消息
 
 <Toc />
 
-本文介绍环信即时通讯 IM iOS SDK 如何管理本地消息数据。SDK 内部使用 SQLite 保存本地消息，方便消息处理。
+本文介绍环信即时通讯 IM iOS SDK 如何管理本地会话和消息。SDK 内部使用 SQLite 保存本地消息，方便消息处理。
 
 除了发送和接收消息外，环信即时通讯 IM SDK 还支持以会话为单位对本地的消息数据进行管理，如获取与管理未读消息、删除聊天记录、搜索历史消息以及统计消息流量等。其中，会话是一个单聊、群聊或者聊天室所有消息的集合。用户需在会话中发送消息或查看历史消息，还可进行清空聊天记录等操作。
 

docs/document/unity/message_manage.md

@@ -1,8 +1,8 @@
-# 管理本地消息数据
+# 管理本地会话和消息
 
 <Toc />
 
-本文介绍即时通讯 IM SDK 如何管理本地消息数据。
+本文介绍即时通讯 IM SDK 如何管理本地会话和消息。
 
 除了发送和接收消息外，环信即时通讯 IM SDK 还支持以会话为单位对本地的消息数据进行管理，如获取与管理未读消息、搜索和删除历史消息等。其中，会话是一个单聊、群聊或者聊天室所有消息的集合。用户需在会话中发送消息以及查看或清空历史消息。
 

docs/document/web/message_manage.md

@@ -0,0 +1,176 @@
+# 管理本地会话
+
+环信即时通讯 IM Web SDK 内部使用 IndexedDB 在本地数据库中保存单聊和群聊会话，支持现代浏览器，例如 Chrome、Firefox、Safari 以及使用这些引擎的其他浏览器（例如 Microsoft Edge），**不支持 Internet Explorer（IE）浏览器**。
+
+使用环信即时通讯 IM Web SDK 时，要支持本地会话存储，需要集成本地存储插件。**该插件只支持通过按需导入的方式集成**。
+
+示例代码如下：
+
+```javascript
+import MiniCore from "easemob-websdk/miniCore/miniCore";
+import * as contactPlugin from "easemob-websdk/contact/contact";
+import * as localCachePlugin from "easemob-websdk/localCache/localCache";
+
+const miniCore = new MiniCore({
+  appKey: "your appKey",
+});
+// 使用联系人插件, "contact" 为固定值。
+miniCore.usePlugin(contactPlugin, "contact");
+// 使用本地存储插件, "localCache" 为固定值。
+miniCore.usePlugin(localCachePlugin, "localCache");
+
+// 登录即时通讯 IM。
+miniCore.open({
+  username: "userId",
+  password: "password",
+});
+```
+
+## 技术原理
+
+环信即时通讯 IM SDK 支持你通过调用 API 在项目中实现如下功能：
+
+- 获取本地会话列表；
+- 获取单个本地会话；
+- 设置会话自定义字段；
+- 对会话的未读消息数清零；
+- 删除单个本地会话；
+- 同步服务端会话列表到本地数据库。
+
+## 前提条件
+
+开始前，请确保满足以下条件：
+
+- 完成 SDK 4.3.0 或以上版本 SDK 的初始化，详见 [快速开始](overview.html)；
+- 了解环信即时通讯 IM 的使用限制，详见 [使用限制](/product/limitation.html)；
+- 集成本地会话存储插件。
+
+## 实现方法
+
+本节介绍如何使用环信即时通讯 IM Web SDK 提供的 API 实现上述功能。
+
+会话对象的结构如下所示:
+
+```typescript
+interface ConversationItem {
+	// 会话 ID。
+	conversationId: string;
+	// 会话类型：单聊和群聊分别为 `singleChat` 和 `groupChat`。
+	conversationType: ConversationType;
+	// 会话的未读消息数。
+	unReadCount?: number;
+	// 最新的一条消息。
+	lastMessage?: LocalMessageBody;
+	// 会话自定义字段。
+	customField?: Record<string, any>;
+}
+```
+
+### 获取本地会话列表
+
+你可以调用 `getLocalConversations` 方法一次性获取本地所有会话的列表。获取会话后，SDK 按照会话活跃时间（最新一条消息的时间戳）的倒序返回会话列表。会话列表数据为 <ConversationItem[]> 结构。
+
+示例代码如下：
+
+```javascript
+
+miniCore.localCache.getLocalConversations().then((res)=>{
+   // 获取本地会话列表成功。
+   console.log(res)
+})
+```
+
+### 获取单个本地会话
+
+你可以调用 `getLocalConversation` 方法获取单个本地会话对象，示例代码如下：
+
+```javascript
+const options = {
+   // 会话类型：单聊和群聊分别为 `singleChat` 和 `groupChat`。
+   conversationType: 'singleChat',
+   // 会话 ID。
+   conversationId: 'conversationId'
+}
+
+miniCore.localCache.getLocalConversation(options).then((res)=>{
+   // 获取本地会话成功。
+   console.log(res)
+})
+```
+
+### 设置会话自定义字段
+
+你可以调用 `setLocalConversationCustomField` 方法设置本地会话的自定义字段，即传入 key-value 对象，key 为字段名，value 是字段值。
+
+示例代码如下：
+
+```javascript
+
+const options = {
+   // 会话类型：单聊和群聊分别为 `singleChat` 和 `groupChat`。
+   conversationType: 'singleChat',
+   // 会话 ID。
+   conversationId: 'conversationId',
+   // 会话自定义字段。
+   customField: { custom: 'custom' }
+}
+
+miniCore.localCache.setLocalConversationCustomField(options).then(()=>{
+   // 设置会话自定义字段成功。
+})
+```
+
+### 对会话的未读消息数清零
+
+你可以调用 `clearConversationUnreadCount` 方法对单个本地会话的未读消息数清零。示例代码如下：
+
+```javascript
+
+const options = {
+   // 会话类型：单聊和群聊分别为 `singleChat` 和 `groupChat`。
+   conversationType: 'singleChat',
+   // 会话 ID。
+   conversationId: 'conversationId'
+}
+
+miniCore.localCache.clearConversationUnreadCount(options).then(()=>{
+   // 对指定会话的未读消息数清零成功。
+})
+```
+
+### 删除单个本地会话
+
+你可以调用 `removeLocalConversation` 方法删除单个本地会话，示例代码如下：
+
+```javascript
+const options = {
+   // 会话类型：单聊和群聊分别为 `singleChat` 和 `groupChat`。
+   conversationType: 'singleChat',
+   // 会话 ID。
+   conversationId: 'conversationId',
+   // 是否删除本地消息, 默认值为 `true`。
+   isRemoveLocalMessage: true
+}
+
+miniCore.localCache.removeLocalConversation(options).then(()=>{
+   // 删除本地会话成功。
+})
+```
+
+### 同步服务端会话列表到本地
+
+你可以调用 `getServerConversations` 方法获取服务端会话列表并同步到本地数据库。示例代码如下：
+
+```javascript
+const options = {
+   /** 每页期望获取的会话数量。取值范围为 [1,50]，默认为 `20`。*/
+   pageSize: 20,
+   /** 开始获取数据的游标位置。若传空字符串（''），SDK 从最新活跃的会话开始获取。*/
+   cursor: ''
+}
+miniCore.contact.getServerConversations(options).then((res)=>{
+   // 获取服务端会话列表并同步本地成功。
+   console.log(res)
+})
+```
+

docs/document/web/message_overview.md

@@ -26,7 +26,7 @@
 
 ### 消息功能
 
-#### 管理本地消息数据
+#### 管理本地会话和消息
 
 Web 端暂无相关功能。
 

docs/document/windows/message_manage.md

@@ -1,8 +1,8 @@
-# 管理本地消息数据
+# 管理本地会话和消息
 
 <Toc />
 
-本文介绍即时通讯 IM SDK 如何管理本地消息数据。
+本文介绍即时通讯 IM SDK 如何管理本地会话和消息。
 
 除了发送和接收消息外，环信即时通讯 IM SDK 还支持以会话为单位对本地的消息数据进行管理，如获取与管理未读消息、搜索和删除历史消息等。其中，会话是一个单聊、群聊或者聊天室所有消息的集合。用户需在会话中发送消息以及查看或清空历史消息。