更新记录

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：支持
• Web：不支持
• 小程序：不支持

主要功能

环境要求

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

导入方式

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

import {
  OpenIMPlatformAndroid,
  OpenIMPlatformIOS,
  initSDK,
  login,
  getLoginStatus,
  onConnectSuccess,
  onUploadFileProgress,
  off,
  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
}

事件订阅

插件提供类型化事件订阅函数。订阅后会返回 OpenIMSDKEventSubscription，可用于取消订阅。

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

off(sub)

常用事件示例：

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
  })
})

文件上传

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 创建消息：

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.