更新记录

0.1.1（2026-07-03） 下载此版本

• 事件监听 API 调整：所有 onXxx 类型化订阅函数统一返回 OpenIMSDKUnsubscribe 取消函数，取消单个监听时直接调用返回函数。
• 移除旧的 off(subscription) 单订阅取消方式，保留 offEvent(eventName) 用于清理某一类事件的全部监听。
• 同步更新 Android/iOS 事件监听转发实现、页面示例和插件使用文档，避免长生命周期回调清理不一致。
• 上传进度回调调整：Android/iOS 的 onUploadFileProgress 和 onUploadLogsProgress 对外 payload 统一为 { progress: number }。
• 移除 public UserCommand 事件回调及 Android/iOS 原生 listener 到 UTS 层的转发。

0.1.0（2026-07-01） 下载此版本

为 Android 和 iOS 添加了 Promise 风格的 OpenIM API 以支持 uni-app-x。

平台兼容性

uni-app x(5.07)

Unix OpenIM SDK 使用说明

Unix OpenIM SDK 是面向 uni-app x 的 OpenIM 原生 SDK UTS 插件，提供 Promise 风格 API、类型声明和事件订阅接口。

平台支持

• App Android：支持
• App iOS：支持
• App HarmonyOS：商业版支持，已完成适配；公开插件包不包含 HarmonyOS 源码、HAR 和平台配置
• Web：不支持
• 小程序：不支持

主要功能

环境要求

• HBuilderX 5.7.0 及以上版本
• uni-app x 项目
• App 端需使用自定义基座或正式打包产物验证原生 SDK 能力

导入方式

推荐在页面或业务模块中按需命名导入：

import {
  OpenIMPlatformAndroid,
  OpenIMPlatformIOS,
  initSDK,
  login,
  getLoginStatus,
  onConnectSuccess,
  onUploadFileProgress,
  offEvent,
  createTextMessage,
  createImageMessageFromFullPath,
  createSoundMessageFromFullPath,
  createVideoMessageFromFullPath,
  createFileMessageFromFullPath,
  sendMessage,
  uploadFile
} from '@/uni_modules/unix-openim-sdk'

然后直接调用对应 API：

getLoginStatus()

初始化

调用其他 SDK API 前，需要先初始化：

initSDK({
  apiAddr: 'https://your-api.example.com',
  wsAddr: 'wss://your-ws.example.com',
  platformID: OpenIMPlatformAndroid,
  dataDir: '',
  logLevel: 5,
  isLogStandardOutput: true
})

dataDir 用于配置 OpenIMSDK 的本地数据目录。一般建议传空字符串，让插件和原生 SDK 使用 App 沙盒内的默认可写目录。

• Android：传空字符串即可使用 App 私有可写目录。
• iOS：传空字符串即可，插件会在 iOS 侧归一化为 App 可写目录。
• 不建议传 uni.env.USER_DATA_PATH、unifile://usr 或其他非 POSIX 真实路径给SDK。
• 如果业务必须自定义目录，请传 App 沙盒内真实可写的绝对路径。

平台 ID 可按目标平台选择：

OpenIMPlatformAndroid
OpenIMPlatformIOS

登录

login({
  userID: 'user-id',
  token: 'user-token'
})

Promise 成功时直接返回有效载荷；失败时 reject 的错误对象结构为：

type UnixOpenIMError = {
  errCode: number
  errMsg: string
}

事件订阅

插件提供类型化事件订阅函数。订阅后会返回 OpenIMSDKUnsubscribe 取消函数。

const unsubscribe = onConnectSuccess(() => {
  console.log('OpenIM connected')
})

unsubscribe()

常用事件示例：

onConnectSuccess(() => {})
onConnectFailed((error) => {})
onKickedOffline(() => {})
onRecvNewMessage((message) => {})
onConversationChanged((result) => {})
onFriendAdded((friend) => {})
onGroupInfoChanged((group) => {})
onSendMessageProgress((progress) => {})
onUploadFileProgress((progress) => {})
onUploadLogsProgress((progress) => {})

如需清理某一类事件的所有订阅，可调用：

offEvent('onRecvNewMessage')

发送文本消息

createTextMessage('hello').then((message) => {
  if (message == null) {
    return
  }

  sendMessage({
    message: message,
    recvID: 'receiver-user-id',
    groupID: '',
    offlinePushInfo: null,
    isOnlineOnly: false
  })
})

文件上传

uploadFile.filepath 必须是真实可读的 POSIX 绝对路径，例如 App 沙盒目录中的文件路径。不要传 uni.env.USER_DATA_PATH、unifile://usr/... 或只相对于业务目录的路径；这些路径在原生 OpenIM Core 中可能不可直接访问。

上传文件和上传日志进度回调 payload 统一为 { progress: number }。

onUploadFileProgress((progress) => {
  console.log('upload progress', progress)
})

uploadFile({
  filepath: '/absolute/path/to/file.pdf',
  name: 'file.pdf',
  contentType: 'application/pdf',
  uuid: 'file-uuid',
  cause: 'manual upload'
})

文件类消息

本地文件消息建议使用 FullPath API 创建。filePath、imageFullPath、soundPath、videoPath 和 snapshotPath 都应传真实可读的 POSIX 绝对路径。demo 工程不会内置测试素材，需要业务方自行准备文件并填入页面中的 demoFixed*FullPath 常量。

createFileMessageFromFullPath({
  filePath: '/absolute/path/to/file.pdf',
  fileName: 'file.pdf'
}).then((message) => {
  if (message == null) {
    return
  }

  sendMessage({
    message: message,
    recvID: 'receiver-user-id',
    groupID: '',
    offlinePushInfo: null,
    isOnlineOnly: false
  })
})

其他 FullPath 媒体消息 API：

createImageMessageFromFullPath('/absolute/path/to/image.jpg')
createSoundMessageFromFullPath({ soundPath: '/absolute/path/to/sound.mp3', duration: 10 })
createVideoMessageFromFullPath({ videoPath: '/absolute/path/to/video.mp4', videoType: 'mp4', duration: 10, snapshotPath: '/absolute/path/to/snapshot.jpg' })
createFileMessageFromFullPath({ filePath: '/absolute/path/to/file.pdf', fileName: 'file.pdf' })

常见注意事项

• 原生 SDK 能力必须使用自定义基座或正式包验证，标准基座无法生效原生依赖。
• operationID 为最后一个可选参数，建议业务侧传入可追踪的字符串。
• Promise 成功结果直接返回业务 payload，不返回原生 callback wrapper。
• Promise 失败统一 reject { errCode, errMsg }。
• Android 和 iOS 都建议使用 App 可读写的真实文件系统路径，不要传临时不可访问路径。
• Android typed parsing 可能把缺失的可选消息字段展示为 null，业务判断消息 elem 时应使用显式 null 判断。

License

AGPL-3.0-only.