From aca2f8862dacb5432f86ddbb09f130e397a7eb83 Mon Sep 17 00:00:00 2001 From: haoxiuwen Date: Thu, 28 Sep 2023 11:47:34 +0800 Subject: [PATCH] Add Local Conversation Management for Web --- docs/.vuepress/sidebar/document.ts | 2 +- docs/document/android/message_manage.md | 4 +- docs/document/android/message_overview.md | 2 +- docs/document/flutter/message_manage.md | 4 +- docs/document/ios/message_manage.md | 4 +- docs/document/unity/message_manage.md | 4 +- docs/document/web/message_manage.md | 176 ++++++++++++++++++++++ docs/document/web/message_overview.md | 2 +- docs/document/windows/message_manage.md | 4 +- 9 files changed, 189 insertions(+), 13 deletions(-) create mode 100644 docs/document/web/message_manage.md diff --git a/docs/.vuepress/sidebar/document.ts b/docs/.vuepress/sidebar/document.ts index b62a0d0ed..c58cea6a2 100644 --- a/docs/.vuepress/sidebar/document.ts +++ b/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' }, diff --git a/docs/document/android/message_manage.md b/docs/document/android/message_manage.md index aa756a7d7..117e7eb8f 100644 --- a/docs/document/android/message_manage.md +++ b/docs/document/android/message_manage.md @@ -1,8 +1,8 @@ -# 管理本地消息数据 +# 管理本地会话和消息 -本文介绍环信即时通讯 IM SDK 如何管理本地消息数据。SDK 内部使用 SQLite 保存本地消息，方便消息处理。 +本文介绍环信即时通讯 IM SDK 如何管理本地会话和消息。SDK 内部使用 SQLite 保存本地消息，方便消息处理。 除了发送和接收消息外，环信即时通讯 IM SDK 还支持以会话为单位对本地的消息数据进行管理，如获取与管理未读消息、搜索和删除历史消息以及统计消息流量等。其中，会话是一个单聊、群聊或者聊天室所有消息的集合。用户需在会话中发送消息、查看或清空历史消息等操作。 diff --git a/docs/document/android/message_overview.md b/docs/document/android/message_overview.md index b6672c58d..5cc7a54e2 100644 --- a/docs/document/android/message_overview.md +++ b/docs/document/android/message_overview.md @@ -24,7 +24,7 @@ ### 消息功能 -#### 管理本地消息数据 +#### 管理本地会话和消息 使用环信即时通讯 IM 发送和接收到的消息会存储在本地数据库，消息以会话为单位进行管理。用户可基于会话获取、删除、导入和插入消息。 diff --git a/docs/document/flutter/message_manage.md b/docs/document/flutter/message_manage.md index 359609ec9..45dca995a 100644 --- a/docs/document/flutter/message_manage.md +++ b/docs/document/flutter/message_manage.md @@ -1,8 +1,8 @@ -# 管理本地消息数据 +# 管理本地会话和消息 -本文介绍环信即时通讯 IM Flutter SDK 如何管理本地消息数据。 +本文介绍环信即时通讯 IM Flutter SDK 如何管理本地会话和消息。 除了发送和接收消息外，环信即时通讯 IM Flutter SDK 还支持以会话为单位对本地的消息数据进行管理，如获取与管理未读消息、搜索和删除历史消息等。其中，会话是一个单聊、群聊或者聊天室所有消息的集合。用户需在会话中发送消息以及查看或清空历史消息。 diff --git a/docs/document/ios/message_manage.md b/docs/document/ios/message_manage.md index c613b71c2..4dd21f558 100644 --- a/docs/document/ios/message_manage.md +++ b/docs/document/ios/message_manage.md @@ -1,8 +1,8 @@ -# 管理本地消息数据 +# 管理本地会话和消息 -本文介绍环信即时通讯 IM iOS SDK 如何管理本地消息数据。SDK 内部使用 SQLite 保存本地消息，方便消息处理。 +本文介绍环信即时通讯 IM iOS SDK 如何管理本地会话和消息。SDK 内部使用 SQLite 保存本地消息，方便消息处理。 除了发送和接收消息外，环信即时通讯 IM SDK 还支持以会话为单位对本地的消息数据进行管理，如获取与管理未读消息、删除聊天记录、搜索历史消息以及统计消息流量等。其中，会话是一个单聊、群聊或者聊天室所有消息的集合。用户需在会话中发送消息或查看历史消息，还可进行清空聊天记录等操作。 diff --git a/docs/document/unity/message_manage.md b/docs/document/unity/message_manage.md index b016feda4..5595e77c9 100644 --- a/docs/document/unity/message_manage.md +++ b/docs/document/unity/message_manage.md @@ -1,8 +1,8 @@ -# 管理本地消息数据 +# 管理本地会话和消息 -本文介绍即时通讯 IM SDK 如何管理本地消息数据。 +本文介绍即时通讯 IM SDK 如何管理本地会话和消息。 除了发送和接收消息外，环信即时通讯 IM SDK 还支持以会话为单位对本地的消息数据进行管理，如获取与管理未读消息、搜索和删除历史消息等。其中，会话是一个单聊、群聊或者聊天室所有消息的集合。用户需在会话中发送消息以及查看或清空历史消息。 diff --git a/docs/document/web/message_manage.md b/docs/document/web/message_manage.md new file mode 100644 index 000000000..73594368a --- /dev/null +++ b/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; +} +``` + +### 获取本地会话列表 + +你可以调用 `getLocalConversations` 方法一次性获取本地所有会话的列表。获取会话后，SDK 按照会话活跃时间（最新一条消息的时间戳）的倒序返回会话列表。会话列表数据为 结构。 + +示例代码如下： + +```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) +}) +``` + diff --git a/docs/document/web/message_overview.md b/docs/document/web/message_overview.md index af7b7e7e0..212331d86 100644 --- a/docs/document/web/message_overview.md +++ b/docs/document/web/message_overview.md @@ -26,7 +26,7 @@ ### 消息功能 -#### 管理本地消息数据 +#### 管理本地会话和消息 Web 端暂无相关功能。 diff --git a/docs/document/windows/message_manage.md b/docs/document/windows/message_manage.md index b016feda4..5595e77c9 100644 --- a/docs/document/windows/message_manage.md +++ b/docs/document/windows/message_manage.md @@ -1,8 +1,8 @@ -# 管理本地消息数据 +# 管理本地会话和消息 -本文介绍即时通讯 IM SDK 如何管理本地消息数据。 +本文介绍即时通讯 IM SDK 如何管理本地会话和消息。 除了发送和接收消息外，环信即时通讯 IM SDK 还支持以会话为单位对本地的消息数据进行管理，如获取与管理未读消息、搜索和删除历史消息等。其中，会话是一个单聊、群聊或者聊天室所有消息的集合。用户需在会话中发送消息以及查看或清空历史消息。