程序包 @ni-paas-im/harmony
程序包 @ni-paas-im/harmony 是 HarmonyOS IMLib 的公开 API 包。本页列出包内的类、数据结构、枚举与事件监听器，并提供各自的 API 参考入口。
契约预留平台
HarmonyOS 当前为契约预留：本页的类、方法签名、枚举与示例全部来自冻结 IDL 与 sdk-bindings.json，SDK 尚未交付；实现后签名不会变化。
包信息
| 项 | 值 |
|---|---|
| 程序包 | @ni-paas-im/harmony |
| 完整声明 | @ni-paas-im/harmony（预留包名，当前版本未发布） |
| 语言 / 运行时 | ArkTS（TypeScript 超集，HarmonyOS ArkTS 1.1 语法） |
| 源码路径 | src/main/ets/imlib（预留路径，当前版本未创建） |
| 类型声明 | — |
| 异步模型 | Promise<RcResult<T>>（不 reject；错误码在 RcResult.code；返回 null 的 op 用 Promise<RcResult<void>>） |
| 事件 API | addEventListener(event: IMClientEvent, listener: IMClientEventListener): void / removeEventListener(event: IMClientEvent, listener: IMClientEventListener): void |
| 命名约定 | camelCase，方法名与语义 op 同名（camelCase 原样）；init 由静态工厂 getInstance 表达（对齐融云鸿蒙 IMEngine.getInstance() 惯例 + IDL 幂等语义） |
| 平台状态 | 契约预留 |
类摘要
| 类 / 接口 | 类型 | 说明 |
|---|---|---|
| Chatroom | 数据结构 | 聊天室资料：在线态会话，不落离线历史，默认只广播在线成员 |
| ChatroomMember | 数据结构 | 聊天室成员：userId、昵称、在线状态与加入时间 |
| Conversation | 数据结构 | 会话聚合视图：未读数、@ 未读、置顶、草稿、提醒级别与最后一条消息 |
| Friend | 数据结构 | 好友条目：userId、昵称、头像、备注、在线状态与黑名单标记 |
| FriendRequest | 数据结构 | 好友请求：请求 ID、发起/接收双方、附言与处理状态（pending / accepted / rejected） |
| Group | 数据结构 | 群组资料：群名、群主、成员、管理员、禁言映射、公告与成员上限 |
| GroupMember | 数据结构 | 群成员：userId、昵称、角色（群主/管理员/成员）、禁言截止时间与加入时间 |
| IMClient | 类 | IMLib 入口类 |
| IMClientEvent | 监听器 | 事件监听接口 |
| Message | 数据结构 | 消息实体 |
| MessageContent | 数据结构 | 消息内容联合体：按 type 取不同字段，序列化后不超过 5KB |
| ReadReceipt | 数据结构 | 已读回执：会话、读者、已读消息列表、各消息已读人数与会话总人数 |
| UserProfile | 数据结构 | 用户资料：userId、昵称与头像 URL |
枚举摘要
| 枚举 | 取值数 | 说明 |
|---|---|---|
| ChatroomEventKind | 5 | 聊天室事件类型 |
| ConnectionStatus | 4 | 连接状态 |
| ContentType | 9 | 消息内容类型 |
| ConversationType | 5 | 会话类型 |
| Direction | 2 | 消息方向 |
| ErrorCode | 43 | 错误码 |
| EventType | 16 | 事件类型 |
| FriendEventKind | 3 | 好友事件类型 |
| FriendRequestStatus | 3 | 好友请求状态 |
| GroupRole | 3 | 群成员角色 |
| GroupType | 2 | 群组类型 |
| MentionType | 2 | @ 提及类型 |
| NotificationLevel | 3 | 会话提醒级别 |
| SystemType | 8 | 系统通知子类型 |
监听器摘要
| 事件 | 载荷 | 说明 |
|---|---|---|
| CONNECTING | {attempt:int} | 连接建立中：每次建连/重连尝试时触发，载荷含重试次数 attempt。 |
| CONNECTED | {userId:string, sessionId?:string} | 连接建立成功：收到服务端 hello 之后触发，可开始发送请求。 |
| DISCONNECT | {code:int, reason:string} | 连接断开：主动断开、鉴权失败或放弃重连时触发。 |
| SUSPEND | {code:int, reason:string} | 连接挂起：异常断开后 SDK 进入指数退避重连，期间业务请求会失败。 |
| MESSAGES | {messages:Message[]} | 收到消息：在线消息与离线补发消息都通过该事件下发，载荷为 Message 列表。 |
| CONVERSATION | {conversation:Conversation} | 会话变更：未读数、置顶、提醒级别、草稿或最后一条消息变化时触发。 |
| MESSAGE_RECALLED | {message:Message} | 消息被撤回：收到服务端撤回帧，载荷为被撤回的 Message。 |
| READ_RECEIPT | ReadReceipt | 已读回执：收到对方已读上报，载荷为 ReadReceipt。 |
| TYPING | {conversationType:ConversationType,targetId:string,userId:string,typing:bool,timestamp:int64} | 输入状态：收到“正在输入”状态帧。 |
| FRIEND_EVENT | {kind:FriendEventKind,request?:FriendRequest,fromUserId?:string,toUserId?:string,timestamp:int64} | 好友事件：好友请求、接受、拒绝等事件，载荷含 FriendRequest。 |
| CHATROOM_EVENT | {chatroomId:string,kind:ChatroomEventKind,userId?:string,onlineCount?:uint32,chatroom?:Chatroom,timestamp:int64} | 聊天室事件：成员加入/退出/被移出、成员变更、聊天室销毁。 |
| KICKED | {code:int,reason:string} | 被踢下线：多端互踢或账号封禁，SDK 不再自动重连。 |
| MESSAGE_REACTION_CHANGED | {messageId:string,conversationType:ConversationType,targetId:string,reactionId:string,operation:added|removed|cleared,userId:string,reactionTime:int64,totalCount:uint32,users:string[]?} | — |
| MESSAGE_EXPANSION_CHANGED | {messageId:string,conversationType:ConversationType,targetId:string,updated:Record<string,string>?,removed:string[]?,timestamp:int64} | — |
| STREAM_MESSAGE_CHANGED | {streamId:string,messageId:string,conversationType:ConversationType,targetId:string,senderId:string,delta:string,seq:uint32,text:string,status:streaming|ended,complete:bool,timestamp:int64} | — |
| PRESENCE_CHANGED | {userId:string,online:bool,lastSeenAt:int64,timestamp:int64,reason:connect|disconnect|kick|deactivate} | — |
事件载荷
| 事件 | 载荷类型 | 说明 |
|---|---|---|
CONNECTING | {attempt:int} | 连接建立中：每次建连/重连尝试时触发，载荷含重试次数 attempt。 |
CONNECTED | {userId:string, sessionId?:string} | 连接建立成功：收到服务端 hello 之后触发，可开始发送请求。 |
DISCONNECT | {code:int, reason:string} | 连接断开：主动断开、鉴权失败或放弃重连时触发。 |
SUSPEND | {code:int, reason:string} | 连接挂起：异常断开后 SDK 进入指数退避重连，期间业务请求会失败。 |
MESSAGES | {messages:Message[]} | 收到消息：在线消息与离线补发消息都通过该事件下发，载荷为 Message 列表。 |
CONVERSATION | {conversation:Conversation} | 会话变更：未读数、置顶、提醒级别、草稿或最后一条消息变化时触发。 |
MESSAGE_RECALLED | {message:Message} | 消息被撤回：收到服务端撤回帧，载荷为被撤回的 Message。 |
READ_RECEIPT | ReadReceipt | 已读回执：收到对方已读上报，载荷为 ReadReceipt。 |
TYPING | {conversationType:ConversationType,targetId:string,userId:string,typing:bool,timestamp:int64} | 输入状态：收到“正在输入”状态帧。 |
FRIEND_EVENT | {kind:FriendEventKind,request?:FriendRequest,fromUserId?:string,toUserId?:string,timestamp:int64} | 好友事件：好友请求、接受、拒绝等事件，载荷含 FriendRequest。 |
CHATROOM_EVENT | {chatroomId:string,kind:ChatroomEventKind,userId?:string,onlineCount?:uint32,chatroom?:Chatroom,timestamp:int64} | 聊天室事件：成员加入/退出/被移出、成员变更、聊天室销毁。 |
KICKED | {code:int,reason:string} | 被踢下线：多端互踢或账号封禁，SDK 不再自动重连。 |
MESSAGE_REACTION_CHANGED | {messageId:string,conversationType:ConversationType,targetId:string,reactionId:string,operation:added|removed|cleared,userId:string,reactionTime:int64,totalCount:uint32,users:string[]?} | — |
MESSAGE_EXPANSION_CHANGED | {messageId:string,conversationType:ConversationType,targetId:string,updated:Record<string,string>?,removed:string[]?,timestamp:int64} | — |
STREAM_MESSAGE_CHANGED | {streamId:string,messageId:string,conversationType:ConversationType,targetId:string,senderId:string,delta:string,seq:uint32,text:string,status:streaming|ended,complete:bool,timestamp:int64} | — |
PRESENCE_CHANGED | {userId:string,online:bool,lastSeenAt:int64,timestamp:int64,reason:connect|disconnect|kick|deactivate} | — |
使用约定
- 所有公开类型都可以从
@ni-paas-im/harmony直接导入；子包不构成额外 API 面。 - 异步模型：
Promise<RcResult<T>>（不 reject；错误码在 RcResult.code；返回 null 的 op 用 Promise<RcResult<void>>）。 - 事件通过
addEventListener(event: IMClientEvent, listener: IMClientEventListener): void / removeEventListener(event: IMClientEvent, listener: IMClientEventListener): void注册；addEventListener与removeEventListener必须传入同一 handler 引用。 - 文档中的枚举取值与字段名来自 IDL；平台之间的差异只有常量名与调用风格。