uni-app 方法参考

从 @/uni_modules/popo-im/js_sdk/index.js 导入 PopoIM。模块、页面和生命周期的接入步骤见 uni-app 接入。用户、认证、会话目标、未读和错误字段见 SDK 对象说明。

Promise<void> 正常完成没有额外数据；失败进入 catch。返回 Unsubscribe 的方法会给出一个函数，调用即可解除本次监听。

初始化：PopoIM.init(config)

参数	类型	必填	说明
config.serverUrl	string	是	部署根地址，例如 https://example.com。
config.webSocketUrl	string 或 null	否	WS/WSS 地址；不传时派生 /ws。
config.authProvider	() => PopoAuthInfo 或 PromiseLike<PopoAuthInfo>	是	从宿主后端获取当前用户的认证结果。

返回： void，只检查并登记配置，不开始网络登录。配置错误同步抛出 PopoError。

登录：PopoIM.login()

无参数。

返回： Promise<void>，在认证和首次同步完成后正常完成。切换账号前先更新宿主 Provider 的身份来源。

恢复缓存：PopoIM.restoreCachedSession(user)

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

返回： Promise<PopoCachedRestoreResult>，包含 restored:boolean（是否恢复到缓存）、user:PopoUser（当前资料）、deviceId:string（本机设备标识）。不取票，不表示已经在线，之后仍调用 login。

恢复离线状态：PopoIM.restoreOfflineSession(user)

参数 user: PopoUser。

返回： Promise<PopoOfflineRestoreResult>，包含 restored:boolean 和 user:PopoUser。需要启动时预热缓存的宿主通常使用 restoreCachedSession，不必把两个恢复入口连续调用一遍。

退出：PopoIM.logout(clearLocalData)

可选参数 clearLocalData:boolean 表示是否清理当前账号本地数据，默认 false。

返回： void。用户明确退出宿主账号时通常传 true。

更新资料：PopoIM.updateCurrentUser(user)

参数 user: PopoUser 为当前账号新资料。

返回： Promise<PopoUser>，更新后的用户资料。字段见 SDK 对象说明，不能用此方法切换账号身份。

读取会话状态：PopoIM.getSessionState()

无参数。

返回： PopoSessionState，字段见本页下方。不要直接修改这个对象。

打开会话：PopoIM.openConversation(target)

参数	类型	必填	说明
target.type	'friend' 或 'group'	是	单聊或群聊。
target.id	string	是	对方外部 user_id 或公开 group_id。
target.messageId	string 或 null	否	正十进制消息 ID，用于定位历史消息；省略打开最新消息。

返回： Promise<void>，完成表示导航成功，不表示对方已读。

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

参数 listener:(count:PopoUnreadCount)=>void，count 包含 conversation、contact 两个当前未读总数。

返回： Unsubscribe。宿主页面卸载时调用返回函数即可解除监听。

移除未读监听：PopoIM.removeUnreadListener(listener)

参数为添加时使用的同一个 listener 函数。

返回： void。也可以调用 addUnreadListener 返回的解除函数，二选一即可。

设置主题：PopoIM.setUiTheme(theme)

参数 theme:'light'|'dark' 为宿主选定的浅色或深色主题。

返回： PopoUiAppearance，包含 theme 和 className，className 为 popo-ui--light 或 popo-ui--dark。

获取主题：PopoIM.getUiAppearance()

无参数。

返回： 当前 PopoUiAppearance，字段同设置主题。

订阅主题：PopoIM.addUiAppearanceListener(listener, options)

参数 listener:(appearance:PopoUiAppearance)=>void；可选 options.emitCurrent:boolean 控制是否立即发送当前值。

返回： Unsubscribe。解除后不再接收变化。

创建好友码内容：PopoIM.createFriendQrPayload(username)

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

返回： string，编码为二维码的内容；不是图片。

解析好友码：PopoIM.parseFriendQrPayload(payload)

参数 payload:string 为扫码内容。

返回： string，解析后的账号；格式无效时抛出错误。

进入前台：PopoIM.onAppForeground()

无参数。

返回： void。在宿主 App.vue 的 onShow 调用一次。

进入后台：PopoIM.onAppBackground()

无参数。

返回： void。在宿主 App.vue 的 onHide 调用一次。

网络恢复：PopoIM.onNetworkAvailable()

无参数。

返回： void。只在网络从断开恢复为可用时调用，SDK 负责重新连接和同步。

设置通话展示能力：PopoIM.setCallPresentationCapabilities(value)

可选字段 value.audio:boolean、value.video:boolean 表示宿主当前是否已具备对应媒体展示能力。

返回： PopoCallPresentationCapabilities，包含最终的 audio、video 两个布尔值。用于宿主实际媒体接线，不是打开服务器通话开关。

获取通话展示能力：PopoIM.getCallPresentationCapabilities()

无参数。

返回： PopoCallPresentationCapabilities，包含 audio:boolean、video:boolean。

获取通话状态：PopoIM.getCallState()

无参数。

返回： PopoCallState，字段见下方通话对象。

监听通话：PopoIM.addCallListener(listener)

参数 listener:(state:PopoCallState)=>void。

返回： Unsubscribe，后续调用解除本次监听。

移除通话监听：PopoIM.removeCallListener(listener)

参数为添加时的同一个监听函数。

返回： void。

监听媒体凭证：PopoIM.addCallCredentialListener(listener)

参数 listener:(event:PopoCallCredentialEvent)=>void。event.call 为当前通话，event.credentials 为当前设备的临时媒体凭证，字段见下方。

返回： Unsubscribe。凭证只交给当前通话的媒体模块使用。

移除凭证监听：PopoIM.removeCallCredentialListener(listener)

参数为添加时的同一个监听函数。

返回： void。

发起通话：PopoIM.startCall(targetUserId, media, requestId)

参数	类型	必填	说明
targetUserId	string	是	被叫外部 user_id。
media	'audio' 或 'video'	是	语音或视频。
requestId	string 或 null	否	本次发起操作的去重 ID；不传时由 SDK 生成。

返回： Promise<PopoCallState>，发起后的通话状态，不代表已经接通。

接听：PopoIM.acceptCall()

无参数，接听当前来电。

返回： Promise<PopoCallState>，操作后的状态。

拒绝：PopoIM.declineCall()

无参数，被叫拒绝当前来电。

返回： Promise<PopoCallState>，操作后的状态。

取消：PopoIM.cancelCall()

无参数，主叫取消尚未接通的通话。

返回： Promise<PopoCallState>。

挂断：PopoIM.hangupCall()

无参数，结束当前通话。

返回： Promise<PopoCallState>。

读取指定通话：PopoIM.receiveCall(callId)

参数 callId:string，来自推送或通话事件的通话 ID。

返回： Promise<PopoCallState>。根据服务器当前状态决定是否继续展示来电。

报告媒体连接：PopoIM.markCallMediaConnected(callId)

参数 callId:string 为媒体已成功接入的通话 ID。

返回： Promise<PopoCallState>。媒体真正连接后调用，不能用它代替进入媒体房间。

根页导航：setRootNavigationHandler(handler)

此函数直接从模块导入，不在 PopoIM 对象内。

参数 handler:((root:PopoRoot)=>boolean|PromiseLike<boolean>)|null。root 为 conversation 或 contact；宿主成功展示相应根页后返回 true，未接管时返回 false；null 取消宿主处理。

返回： Unsubscribe，移除当前处理器。

根页可见性：markRootVisible(root)

参数 root:'conversation'|'contact'|null。告知 SDK 当前可见的根页面；没有 SDK 根页可见时为 null。

返回： void。仅在自有根容器接入时协调使用，普通 Tab 接入按指南即可。

PopoSessionState 字段

字段	类型	说明
state	string	uninitialized 未初始化、logged_out 未登录、restoring 恢复中、restored 缓存已恢复、offline 离线可读、authenticating 认证中、initial_sync 首次同步中、ready 就绪、failed 失败。
currentUser	PopoUser 或 null	当前账号资料。
foreground	boolean	应用是否在前台。

PopoCallState 字段

字段	类型	说明
call	PopoCall 或 null	当前通话；没有通话时为 null。
isActing	boolean	是否正在提交通话操作。
error	PopoError 或 null	当前错误；没有时为 null。
credentialExpiresAt	number 或 null	当前媒体凭证过期时间，Unix 毫秒。

PopoCall 沿用 HTTP 通话字段：call_id、kind、media、status、version、creator_id、participants、self、ring_deadline_at、lease_expires_at、answer_expires_at、connect_expires_at、started_at、ended_at、end_reason。含义见完整通话说明。uni-app 对参与人只公开 user.user_id、user.nickname、user.avatar、role 和 status；self 公开 role、status、selected_device_id、lease_expires_at。所有通话时间均为 Unix 毫秒，尚未发生时为 null。

PopoCallCredentials 字段

字段	类型	说明
call_id	string 或 null	对应通话 ID。
sdk_app_id	number	TRTC 应用 ID。
room_id	number	TRTC 整数房间号。
user_id	string	TRTC 用户身份，不是宿主 user_id。
user_sig	string	当前设备的临时 UserSig。
private_map_key	string 或 null	可选房间权限票据。
expires_at	number	凭证过期时间，Unix 毫秒。

解析页面颜色：resolvePageChrome(route, theme, override)

这是直接从模块导出的辅助函数，用于宿主需要同步原生导航栏外观的场景。

参数	类型	必填	说明
route	string	是	当前页面路由。
theme	'light' 或 'dark'	否	浅色或深色。
override	object 或 null	否	可覆盖 header、page、footer 三个区域；值可为 chrome、chat、tabbar、editor、surface、page、scanner、dark 或十六进制颜色。statusBarOverlay:boolean 可指定状态栏覆盖模式。

返回： PopoPageChrome：header、page、footer 为各区域颜色文本；frontColor 为 #ffffff 或 #000000；需要状态栏覆盖时带 statusBarOverlay:true。

应用页面颜色：applyPageChrome(runtime, chrome)

参数 runtime:PopoPageChromeRuntime|null|undefined 为提供 setNavigationBarColor、setBackgroundColor 的平台对象，通常传 uni；chrome:PopoPageChrome|null|undefined 为上一个函数的结果。

返回： void。对象为空或平台没有对应能力时跳过相应操作。

底部安全区：resolveBottomSafeAreaInset(runtime)

可选参数 runtime:PopoWindowRuntime|null，提供 getWindowInfo 或 getSystemInfoSync 以读取窗口信息。

返回： number，非负底部安全区高度；无法取得时为 0。宿主布局使用平台返回的同一尺寸单位。

诊断请求头：clientRequestHeaders(runtime, persistence)

可选参数 runtime:PopoDiagnosticsRuntime|null 提供存储、应用和设备信息读取能力；可选 persistence:{getDeviceId():string}|null 提供安装 ID。通常无需传参，使用当前 uni 环境；在宿主隐私同意之后调用。

返回： Record<string,string>，可能包含以下请求头，不包含认证 Token：

字段	说明
X-Popo-Platform	当前为 uniapp。
X-Popo-Sdk-Version	SDK 版本。
X-Client-Trace-ID	本次调用的追踪标识。
X-Popo-Installation-Id	可取得时提供的安装标识，不读取 IMEI 或 MAC。
X-Popo-App-Version	可取得时提供的宿主版本。
X-Popo-Os-Version	可取得时提供的系统名称和版本。
X-Popo-Device-Model	可取得时提供的设备型号。

判断相册保存能力：canSaveToAlbum(runtime, kind)

参数 runtime 提供 saveImageToPhotosAlbum 或 saveVideoToPhotosAlbum；可选 kind 为 image 或 video，省略按图片判断。

返回： boolean，是否存在相应平台能力；H5 为 false。true 不代表已经获得用户相册授权。

判断画布图片：isBrowserCanvasDataUri(path)

参数 path:unknown 为待检查值。

返回： boolean，是否为可识别的浏览器画布图片 data URI。

转为上传文件：browserCanvasUploadFile(path)

参数 path:unknown 为画布图片 data URI，仅用于 H5 辅助处理。

返回： File 或 null。不是画布图片路径时为 null；浏览器不提供 File 能力时抛出错误。此辅助能力不扩大 App SDK 的平台支持范围。