HarmonyOS 方法参考

先按 HarmonyOS 接入加入本地模块与根页面。用户、认证、会话目标、未读和错误见 SDK 对象说明。Promise 方法失败时进入 catch；Promise<void> 正常完成没有额外数据。

创建配置：new PopoConfig(...)

参数	类型	必填	说明
serverURL	string	是	部署根地址。
authProvider	() => Promise<PopoAuthInfo>	是	向宿主后端取票，返回用户资料、IM Token 和秒级 expireAt。
webSocketURL	string	否	不传时从部署地址派生 /ws。
onConversationRequested	() => void	否	SDK 请求宿主显示会话根页时调用；宿主切换到自己的消息标签。

返回： PopoConfig 配置对象。

初始化：PopoIM.initialize(context, config)

参数 context: common.Context 为宿主上下文，config: PopoConfig 为配置。

返回： void。配置错误会抛出 PopoError；初始化后再登录。

登录：PopoIM.login()

无参数。

返回： Promise<void>，在认证和首次同步完成后正常完成。

恢复缓存：PopoIM.restoreCachedSession(user)

参数 user: PopoUser 为宿主确认的本机用户。

返回： Promise<boolean>，true 表示恢复到可用缓存，false 表示没有可恢复缓存。此操作不请求网络，之后仍调用 login。

更新资料：PopoIM.updateCurrentUser(user)

参数 user: PopoUser 为当前用户的新资料，不用于切换身份。

返回： Promise<void>。资料由宿主管理时，先保存并同步后端资料，再更新 SDK。

退出：PopoIM.logout()

无参数。

返回： void，退出当前 SDK 会话。宿主同时完成自己的账号退出。

前后台通知：PopoIM.setApplicationActive(active)

参数 active: boolean，前台为 true，后台为 false。

返回： void。跟随 Ability 生命周期调用，不需要重新初始化 SDK。

读取缓存：PopoIM.cacheSize()

无参数。

返回： Promise<number>，媒体缓存字节数。

清理缓存：PopoIM.clearCache()

无参数。

返回： Promise<number>，清理后剩余字节数。不会删除聊天记录、草稿或待发送内容。

添加未读监听：PopoIM.addUnreadListener(listener)

参数 listener: (count: PopoUnreadCount) => void 接收 conversation、contact 两个未读总数。

返回： PopoUnreadObserver，保留对象用于取消监听。

取消未读监听：PopoIM.removeUnreadListener(observer)

参数为添加时返回的 PopoUnreadObserver。

返回： void。

处理消息通知：PopoIM.handleMessageNotification(conversationID)

参数 conversationID: string 为通知中的会话 ID。

返回： void，交给 SDK 处理会话导航。不是在此传对方的用户 ID。

打开会话：PopoUI.openConversation(target)

参数 target: PopoConversationTarget，用 .friend(userID) 或 .group(groupID) 创建。

返回： Promise<void>，正常完成表示已经进入目标会话。

好友二维码内容：PopoUI.friendQRCodePayload(username)

参数 username: string 为完整可搜索账号。

返回： string，可直接编码为二维码的内容。

解析好友二维码：PopoUI.friendUsername(payload)

参数 payload: string 为扫码得到的内容。

返回： string，解析出的账号；无效内容按 SDK 错误处理，不能把任意扫码文本当作账号。

生成二维码：PopoUI.createFriendQRCode(username, size)

参数 username: string 为完整账号，size: number 为 64–4096 的整数像素尺寸。

返回： Promise<image.PixelMap>，二维码图片。

生成二维码卡片：PopoUI.createQRCodeCard(...)

参数 qrCode: image.PixelMap 为二维码，avatar: image.PixelMap | undefined 为可选头像，name: string 为显示名，footer: string 为卡片底部文字。

返回： Promise<image.PixelMap>，合成后的卡片图片。

分享文本：PopoShareItem.text(value)

参数 value: string 为文本。

返回： PopoShareItem，kind=text，text 为输入内容。

分享文件：PopoShareItem.file(...)

参数	类型	必填	说明
kind	PopoShareKind	是	image、video 或 file。
path	string	是	可读取的本地文件路径。
fileName	string	是	展示文件名。
mimeType	string	是	实际 MIME 类型。
thumbnailPath	string	否	本地封面路径。

返回： PopoShareItem，包含 kind、filePath、fileName、mimeType 和可选 thumbnailPath。

打开分享：PopoIM.openShare(items)

参数 items: PopoShareItem[] 为分享项。宿主根页面需承载 PopoSharePage。

返回： void。分享结束由 PopoSharePage.onFinished(error?: PopoError) 通知，无错误时 error 为 undefined。

关闭分享：PopoIM.closeShare()

无参数。

返回： void，关闭 SDK 分享状态。

诊断请求头：PopoIM.clientRequestHeaders(context)

参数 context: common.Context。

返回： Promise<Record<string, string>>，客户端设备与版本诊断请求头，不包含认证 Token。

根页面参数

页面	参数	类型与说明
PopoConversationPage	onNavigationChanged	(insideConversation: boolean) => void；告知宿主是否处于根页内部导航中。
PopoConversationPage	tabBarCoverHeight	可选 number，宿主 TabBar 高度，用于进入聊天过程的界面衔接。
PopoContactPage	active	可选 boolean，当前通讯录根页是否激活。
PopoContactPage	onNavigationChanged	(insideContact: boolean) => void；用于协调宿主底部导航。
PopoSharePage	onFinished	(error?: PopoError) => void；分享流程结束回调。
PopoCallPage	无	承载 SDK 通话界面。

这些 ArkUI 组件渲染界面，不返回业务数据。具体承载方式见接入指南。