开源即时通讯 IM 框架 MobileIMSDK 的鸿蒙 NEXT 端开发快速入门

作者：JackJiang

2024-12-30
江苏
本文字数：4957 字
阅读完需：约 16 分钟

相关链接：

① MobileIMSDK-鸿蒙端的详细介绍
② MobileIMSDK-鸿蒙端的开发手册new（* 精编 PDF 版）

一、理论知识准备

您需要对鸿蒙 Next 和 ArkTS 开发有所了解：

您需要对 WebSocket 技术有所了解：

HTML5 的标准 WebSocket 协议文档、API 手册：

1）WebSocket 的 API 手册
2）WebSocket 的标准文档

鸿蒙 Next 的 WebSocket 文档和手册：

1）鸿蒙Next的WebSocket官方文档

小提示：鸿蒙 Next 中的 WebSocket API 跟标准 HTML5 中的 WebSocket 接口及用法略有不同，但主要 API 都能一一对应，相差不大。

二、开发工具准备

1）DevEco-Studio：

（JackJiang 使用的版本号如上图所示，为了方便直接引用工程，建议你也使用此版或较新版本）

2）一站式下载地址：鸿蒙官网下载地址点此进入。（需要注册成为开发者才能下载哟！）

3）DevEco-Studio 效果预览：

三、SDK 文件用途说明

3.1 文件概览

纯 ArkTS 实现，无任何第 3 方库依赖，更无本地原生代码混编：

MobileIMSDK-鸿蒙端 SDK 本身只是 ets 文件源码的集合，自带的 Demo 代码只是为了方便随时测试 SDK 代码，目的主要是用于演示 SDK 的 API 调用，Demo 代码不属于 SDK 框架的一部分。

大致的目录说明：

3.2 详细说明

SDK 各模块/文件作用说明：

四、主要 API 接口和用途说明

* 主要 API 文档地址是：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/

1）ClientCoreSDK.getInstance().loginHasInit：

用途：是否已经完成过首次登陆。
说明：用户一旦从自已的应用中完成登陆 IM 服务器后，本方法就会一直返回 true（直到退出登陆 IM）。
返回值：{boolean}，true 表示已完成首次成功登陆（即已经成功登陆过 IM 服务端了，后面掉线时不影响此标识），否则表示尚未连接 IM 服务器。

2）ClientCoreSDK.getInstance().connectedToServer：

用途：是否在线。
说明：表示网络连接是否正常。
返回值：{boolean}，true 表示网络连接正常，否则表示已掉线，本字段只在 this._logined=true 时有意义（如果都没有登陆到 IM 服务器，怎么存在在线或掉线的概念呢）。

3）ClientCoreSDK.getInstance().currentLoginInfo：

用途：保存登陆时提交的登陆信息（用户名、密码/token 等）。
说明：格式形如：{loginUserId:'',loginToken:''}，此返回值的内容由调用登陆函数 loginImpl()时传入的内容决定。字段定义详见：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1697l。

4）ClientCoreSDK.getInstance().init(eventHub: common.EventHub): void：

用途：初始化 SDK 核心。
说明：不同于 MobileIMSDK 的 iOS 和 Java 客户端，本方法需要由开发者调用，以确保 MobileIMSDK 核心已被初始化完成。
本方法被调用后， #isInitialed() 将返回 true，否则返回 false。

5）ClientCoreSDK.getInstance().release(): void：

用途：保释放 MobileIMSDK 框架资源统一方法。
说明：本方法建议在退出登陆（或退出 APP 时）时调用。调用时将尝试关闭所有 MobileIMSDK 框架的后台守护线程并同设置核心框架 init=false、loginHasInit=false、connectedToServer=false。

6）LocalDataSender.getInstance().sendLogin(loginInfo: PLoginInfo | undefined): number：

用途：发送登陆(连接)信息给服务端。
说明：不同于其它 IM 框架，本框架的登录和连接高度封装在了一个 sendLogin 方法中，无需单独再去 connect 服务器，大大简化了 SDK 的使用。loginInfo 登陆信息各字段定义见：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1697。

7）LocalDataSender.getInstance().sendLoginout(): number：

用途：发送注销登陆信息。
说明：此方法的调用将被本库理解为退出库的使用，本方法将会额外调用资源释放方法 ClientCoreSDK#release() ，以保证资源释放。本方法调用后，除非再次进行登陆过程，否则核心库将处于初始未初始化状态。

8）LocalDataSender.getInstance().sendCommonDataPlain(dataContentWidthStr: string, to_user_id: string, QoS: boolean = true, fingerPrint: string = '', typeu: number = -1): number：

用途：向某人发送一条消息。
参数 dataContentWidthStr：要发送的数据内容（字符串方式组织）。
参数 to_user_id：要发送到的目标用户 id。
参数 QoS ：true 表示需 QoS 机制支持，否则不需要。
参数 fingerPrint：QoS 机制中要用到的指纹码（即消息包唯一 id），可设为 null，生成方法见 Protocal.genFingerPrint()。
参数 typeu：应用层专用字段——用于应用层存放聊天、推送等场景下的消息类型。注意：此值为-1 时表示未定义。MobileIMSDK 框架中，本字段为保留字段，不参与框架的核心算法，专留作应用层自行定义和使用。
返回值：0 表示数据发出成功，否则返回的是错误码，see ErrorCode。

9）LocalDataSender.getInstance().sendCommonData(p: Protocal): number：

用途：通用数据协议包的发送根方法。
参数 p：{Protocal} 要发送的消息协议包对象，Protocal 详情请见“/module/mb_constants.js”下的 createCommonData 函数说明。
返回值：0 表示数据发出成功，否则返回的是错误码，see ErrorCode。

10）SocketEvent.SOCKET_EVENT_ON_RECIEVE_MESSAGE 事件通知：

用途：以便收到聊天消息时在 UI 上展现出来（事件通知于收到 IM 消息时）。
推荐用法：开发者可在此通知中处理收到的各种 IM 消息。
参数 1： {Protocal}：详情请见 Protocal 类定义：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1350。

11）SocketEvent.SOCKET_EVENT_ON_LOGIN_RESPONSE 事件通知：

用途：本地用户的登陆结果回调事件通知（此事件发生时表示客户端已登陆/连接或重连完成）。
推荐用法：开发者可在此事件中处理登录连接和掉线重连响应反馈。
参数 1： {PLoginInfoResponse}：API 文档详见：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1434。

12）SocketEvent.SOCKET_EVENT_ON_LINK_CLOSE 事件通知：

用途：与服务端的通信断开的回调事件通知（此事件发生时表示客户端已掉线）。
该消息只有在客户端连接服务器成功之后网络异常中断之时触发。导致与与服务端的通信断开的原因有（但不限于）：无线网络信号不稳定、WiFi 与 2G/3G/4G/5G 等同开情况下的网络切换、手机系统的省电策略等。
推荐用法：开发者可在此通知中处理掉线时的界面状态更新等，比如设置将界面上的“在线”文字更新成“离线”。

13）SocketEvent.SOCKET_EVENT_PING 事件通知：

用途：本地发出心跳包后的回调通知（本回调并非 MobileIMSDK-鸿蒙端核心逻辑，开发者可以不需要实现！）。
推荐用法：开发者可在此回调中处理底层网络的活动情况。

14）SocketEvent.SOCKET_EVENT_PONG 事件通知：

用途：收到服务端的心跳包反馈的回调通知（本回调并非 MobileIMSDK-鸿蒙端核心逻辑，开发者可以不需要实现！）。
推荐用法：开发者可在此回调中处理底层网络的活动情况。

15）SocketEvent.SOCKET_EVENT_KICKOUT 事件通知：

用途：收到服务端反馈的错误信息指令（本回调并非 MobileIMSDK-鸿蒙端核心逻辑，开发者可以不需要实现！）。
参数 1：{PKickoutInfo}：非空，详见：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1428。

16）SocketEvent.SOCKET_EVENT_ON_ERROR_RESPONSE 事件通知：

用途：收到服务端反馈的错误信息指令（本回调并非 MobileIMSDK-鸿蒙端核心逻辑，开发者可以不需要实现！）。
参数 1：{PErrorResponse}：非空，详见：http://docs.52im.net/extend/docs/api/mobileimsdk/harmony/#1430。

17）SocketEvent.SOCKET_EVENT_RECONNECT_ATTEMPT 事件通知：

用途：“自动重连尝试中”事件（本回调并非 MobileIMSDK-鸿蒙端核心逻辑，开发者可以不需要实现！）。
参数 code ：{numeric}：0：已停止，1：持续运行中，2：单次脉搏

18）SocketEvent.SOCKET_EVENT_MESSAGE_LOST 事件通知：

用途：消息未送达的回调事件通知。
发生场景：比如用户刚发完消息但网络已经断掉了的情况下，表现形式如：就像手机 qq 或微信一样消息气泡边上会出现红色图标以示没有发送成功）。
建议用途：应用层可通过回调中的指纹特征码找到原消息并可以 UI 上将其标记为“发送失败”以便即时告之用户。
参数 1：{Array}：由框架的 QoS 算法判定出来的未送达消息列表。

19）SocketEvent.SOCKET_EVENT_MESSAGE_BE_RECIEVED 事件通知：

用途：消息已被对方收到的回调事件通知。
说明：目前，判定消息被对方收到是有两种可能：1) 对方确实是在线并且实时收到了；2) 对方不在线或者服务端转发过程中出错了，由服务端进行离线存储成功后的反馈（此种情况严格来讲不能算是“已被收到”，但对于应用层来说，离线存储了的消息原则上就是已送达了的消息：因为用户下次登陆时肯定能通过 HTTP 协议取到）。
建议用途：应用层可通过回调中的指纹特征码找到原消息并可以 UI 上将其标记为“发送成功”以便即时告之用户。
参数 1：{String}：已被收到的消息的指纹特征码（唯一 ID），应用层可据此 ID 找到原先已发的消息并可在 UI 是将其标记为”已送达“或”已读“以便提升用户体验。