当前位置：首页 > article >正文

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

article 2025/1/4 9:15:14

相关链接：

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

一、理论知识准备

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

1）HarmonyOS NEXT星河版零基础入门到实战（B站视频）
2）零基础快速上手HarmonyOS ArkTS开发（系列文章）
3）HarmonyOS 第一课（鸿蒙官方视频教程）

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

1）新手快速入门：WebSocket 简明教程
2）WebSocket 详解（一）：初步认识 WebSocket 技术
3）WebSocket 从入门到精通，半小时就够！
4）从零理解 WebSocket 的通信原理、协议格式、安全性
5）WebSocket详解（二）：技术原理、代码演示和应用案例
6）WebSocket详解（三）：深入WebSocket通信协议细节
7）WebSocket详解（四）：刨根问底HTTP与WebSocket关系(上)
8）WebSocket详解（五）：刨根问底HTTP与WebSocket关系(下)
9）WebSocket详解（六）：刨根问底WebSocket与Socket的关系

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文档地址是：ArkTSDoc

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()时传入的内容决定。字段定义详见：ArkTSDoc。

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登陆信息各字段定义见：ArkTSDoc。

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类定义：ArkTSDoc。

11）SocketEvent.SOCKET_EVENT_ON_LOGIN_RESPONSE事件通知：

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

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}：非空，详见：ArkTSDoc。

16）SocketEvent.SOCKET_EVENT_ON_ERROR_RESPONSE事件通知：

用途：收到服务端反馈的错误信息指令（本回调并非MobileIMSDK-鸿蒙端核心逻辑，开发者可以不需要实现！）。
参数1：{PErrorResponse}：非空，详见：ArkTSDoc。

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是将其标记为”已送达“或”已读“以便提升用户体验。